Density tokens for control sizes, and a compact preset via data-density="compact"

CHANGELOG.md

@@ -7,6 +7,42 @@ GlassKit uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [Unreleased]
+
+### Added
+
+- **Density tokens for the control sizes, and a compact preset: `data-density="compact"`.** The heights of fields, buttons, toggles, checkboxes, radios, list rows and modal actions were px literals in the component rules, so a denser layout — an admin screen, a desktop form, a narrow column — had to override a dozen selectors and keep the toggle's thumb, its travel and the first-line alignment of the labels in step by hand. They are tokens now, declared next to the spacing tokens with the values GlassKit has always drawn and read with that value as fallback, as `--gl-modal-max-width` is; `data-density="compact"` on `<html>`, next to `data-theme`, swaps in a denser set, at load or at runtime:
+
+  | Token | Default | Compact |
+  |---|---|---|
+  | `--gl-control-height` (input, select, search) | `52px` | `40px` |
+  | `--gl-control-padding-x` (input, select, textarea) | unset → `var(--gl-space-md)` | `var(--gl-space-sm)` |
+  | `--gl-btn-height` / `-sm` / `-lg` | `56px` / `44px` / `64px` | `40px` / `32px` / `48px` |
+  | `--gl-textarea-min-height` | `120px` | `88px` |
+  | `--gl-list-item-min-height` | `56px` | `48px` |
+  | `--gl-list-item-padding-y` | unset → `var(--gl-space-md)` | `10px` |
+  | `--gl-toggle-width` × `--gl-toggle-height` | `52px` × `30px` | `44px` × `26px` |
+  | `--gl-toggle-thumb-size` | `22px` | `18px` |
+  | `--gl-check-size` (checkbox, radio) | `24px` | `20px` |
+  | `--gl-modal-action-height` | `52px` | `44px` |
+
+  Only these tokens change; colours, type and spacing stay, so nothing outside the controls moves. The toggle's thumb sits `(height − thumb) / 2 − 1px` inside the track — 3 px at 52 × 30, where it has always sat — and travels `width − height`, from the right and to the left under `dir="rtl"`; the invisible inputs that lie on top of the controls since 1.20.0 take the same sizes, and the first-line offsets of toggle, checkbox and radio are computed from them. Any value a project sets therefore stays aligned. Two paddings join the heights because the heights alone would not have shown: a list row's 16 px top and bottom padding already makes a plain row 50 px tall, so a 48 px minimum needs `--gl-list-item-padding-y`; and a 40 px field reads better with 12 px inside (`--gl-control-padding-x`, which the textarea follows too, so stacked fields keep one text edge). Both are left unset by default, like `--gl-toast-top`: the rules fall back to `--gl-space-md` as before, so a spacing override still reaches them wherever it is declared. The select keeps its padding pair under `:dir(rtl)`: the token takes the text side, left to right on the left and right to left on the right, and the chevron's room stays with the chevron. The chevron, the search icon and the check and radio glyphs keep their sizes.
+
+  The preset is a bare attribute selector, like `[data-theme="light"]`, placed after the theme blocks, and the build puts it into `tokensCss` / `tokensSheet` with them. GlassKit Elements adopts only `componentsSheet` in its shadow roots and places the tokens on the document, so the compact values reach every element by inheritance — and so does a project's own `[data-density="compact"] { --gl-btn-height: 36px; }`, which a preset inside `componentsSheet` would have overridden in every shadow root. A `glassSheet` consumer whose shadow root holds an element with `data-theme` has to mirror `data-density` onto it as well, as GlassKit Elements does with its theme wrapper.
+
+  Measured in Chromium and WebKit (Playwright 1.63) against 1.20.0: without the attribute every one of these controls has the same size, padding, thumb position, input box, label offset and first-line centre as before, left to right and right to left, and full-page screenshots — a test page in both themes, this repository's index, showcase and docs in English and German — are pixel-identical, apart from regions that also differ between two renders of 1.20.0. With `data-density="compact"` on `<html>`, at load and switched at runtime: input, select and search 40 px with 12 px inner padding, buttons 40 / 32 / 48 px, the textarea 88 px, list rows 48 px with or without a 28 px icon (about 56 px with title and subtitle), the toggle 44 × 26 px with an 18 px thumb and the same gap at either end in both directions, checkbox and radio 20 px with their inputs on top, modal actions 44 px, every label still centred on its first line; under `dir="rtl"` the select's 12 px move to the right with the chevron on the left. Removing the attribute restores every value.
+
+### Changed
+
+- `build-styles-js.mjs` splits three token blocks off instead of two — `:root, [data-theme="dark"]`, `[data-theme="light"]` and `[data-density="compact"]` — and fails if `tokensCss` lacks the preset or `componentsCss` declares a density token.
+
+### Compatibility
+
+- Without `data-density` nothing changes, and a stylesheet that lacks the new tokens — an older `tokensCss` next to this `componentsSheet` — gets the old sizes from the fallbacks.
+- Like every token of the dark block, the size defaults are declared again by an element below `<html>` that carries `data-theme="dark"`; keep `data-density` on `<html>`, next to `data-theme`.
+
+---
+
 ## [1.20.0] – 2026-10-05
 
 The first batch of findings filed as GitHub issues, from a product that is adopting GlassKit at full depth; GlassKit Elements 1.20.0 ships the matching element changes.

README.md

@@ -280,6 +280,44 @@ The `theme-override.css` template comes with **4 example themes**:
 - 🌹 Rose
 - 🎨 Custom (empty, ready to fill)
 
+### Density
+
+Admin screens, desktop layouts and narrow forms want denser controls. Set `data-density="compact"` on `<html>`, next to `data-theme`:
+
+```html
+<html data-theme="dark" data-density="compact">
+```
+
+```js
+// Switch at runtime
+document.documentElement.setAttribute('data-density', 'compact');
+document.documentElement.removeAttribute('data-density');   // back to the default
+```
+
+Since **1.21.0** the control sizes are tokens, and the attribute swaps in a denser set. Without it every control keeps the size it has always had. Colours, type and spacing stay as they are, so nothing outside the controls moves:
+
+| Token | Default | Compact |
+|---|---|---|
+| `--gl-control-height` (input, select, search) | `52px` | `40px` |
+| `--gl-control-padding-x` (input, select, textarea) | unset → `var(--gl-space-md)` | `var(--gl-space-sm)` |
+| `--gl-btn-height` / `-sm` / `-lg` | `56px` / `44px` / `64px` | `40px` / `32px` / `48px` |
+| `--gl-textarea-min-height` | `120px` | `88px` |
+| `--gl-list-item-min-height` | `56px` | `48px` |
+| `--gl-list-item-padding-y` | unset → `var(--gl-space-md)` | `10px` |
+| `--gl-toggle-width` × `--gl-toggle-height` | `52px` × `30px` | `44px` × `26px` |
+| `--gl-toggle-thumb-size` | `22px` | `18px` |
+| `--gl-check-size` (checkbox, radio) | `24px` | `20px` |
+| `--gl-modal-action-height` | `52px` | `44px` |
+
+Every token can also be set on its own, for one density or both — the toggle's thumb and the first-line alignment of toggle, checkbox and radio follow whatever size you give:
+
+```css
+:root                    { --gl-btn-height: 48px; }   /* default density */
+[data-density='compact'] { --gl-btn-height: 36px; }   /* compact only */
+```
+
+Like `data-theme`, keep `data-density` on `<html>`: an element further down that carries `data-theme="dark"` re-declares the dark block, the default sizes included.
+
 ---
 
 ## 🎛️ Design Tokens
@@ -308,6 +346,12 @@ All visual values are controlled via CSS Custom Properties:
 /* Spacing */
 --gl-space-xs … --gl-space-4xl
 
+/* Density – control sizes, denser with data-density="compact" */
+--gl-control-height       /* 52px – input, select */
+--gl-btn-height           /* 56px; -sm 44px, -lg 64px */
+--gl-check-size           /* 24px – checkbox, radio */
+--gl-toggle-width … --gl-modal-action-height
+
 /* Shadows & Insets */
 --gl-shadow-card
 --gl-inset-strong
@@ -437,6 +481,8 @@ Since CSS Custom Properties penetrate the shadow boundary, **theme switching wor
 document.documentElement.setAttribute('data-theme', 'light');
 ```
 
+`data-density="compact"` reaches the shadow roots the same way: the preset only sets tokens, and tokens cross the shadow boundary by inheritance.
+
 > **Tip:** For maximum performance with many component instances, import `glassSheet` once and share it across all components. The browser keeps the stylesheet in memory only once.
 
 ---
@@ -547,6 +593,10 @@ A few refinements arrive later and fall back quietly where they are missing:
 ## 📋 States & Modifiers – Cheat Sheet
 
 ```
+Page Attributes (on <html>):
+  data-theme="dark" / "light"
+  data-density="compact"          (denser controls)
+
 Interactive States:
   .is-active          → Tab Bar item, Modal Overlay
   .is-open            → Accordion item, Popover

SKILL.md

@@ -89,6 +89,16 @@ and prose mirror. Pairs that must move together — the select's chevron and its
 toggle's thumb and its travel, the progress fill's gradient — are under `:dir(rtl)`
 (Chrome 120+); an older browser keeps them left to right rather than splitting them.
 
+### Density
+
+Denser controls for admin screens, desktop layouts and narrow forms: `data-density="compact"` on `<html>`, next to `data-theme` (since 1.21.0).
+
+```html
+<html data-theme="dark" data-density="compact">
+```
+
+Fields and buttons are 40px high instead of 52 and 56px; toggles, checkboxes, radios, list rows and modal actions shrink with them. Colours, type and spacing stay. Without the attribute nothing changes; `removeAttribute('data-density')` switches back at runtime. The values are the density tokens in section 2 — never shrink controls by overriding their `height`. It combines with `dir="rtl"`: the toggle's thumb and the select's padding mirror at either density.
+
 ---
 
 ## 2. Design Tokens
@@ -215,6 +225,28 @@ fully-translucent pre-1.7.0 chip.
 | `--gl-space-3xl` | `40px` |
 | `--gl-space-4xl` | `56px` |
 
+### Density (since 1.21.0)
+
+The control sizes. `data-density="compact"` on `<html>` switches to the second value column.
+
+| Token | Default | Compact | Used by |
+|---|---|---|---|
+| `--gl-control-height` | `52px` | `40px` | `.glass-input`, `.glass-select` (and the search field) |
+| `--gl-control-padding-x` | unset → `var(--gl-space-md)` | `var(--gl-space-sm)` | Inner left/right padding of input, select, textarea |
+| `--gl-btn-height` | `56px` | `40px` | `.glass-btn` |
+| `--gl-btn-height-sm` | `44px` | `32px` | `.glass-btn--sm` |
+| `--gl-btn-height-lg` | `64px` | `48px` | `.glass-btn--lg` |
+| `--gl-textarea-min-height` | `120px` | `88px` | `.glass-textarea` |
+| `--gl-list-item-min-height` | `56px` | `48px` | `.glass-list__item` |
+| `--gl-list-item-padding-y` | unset → `var(--gl-space-md)` | `10px` | `.glass-list__item`, top and bottom |
+| `--gl-toggle-width` | `52px` | `44px` | `.glass-toggle__track` |
+| `--gl-toggle-height` | `30px` | `26px` | `.glass-toggle__track` |
+| `--gl-toggle-thumb-size` | `22px` | `18px` | `.glass-toggle__thumb` |
+| `--gl-check-size` | `24px` | `20px` | `.glass-checkbox__box`, `.glass-radio__circle` |
+| `--gl-modal-action-height` | `52px` | `44px` | `.glass-modal__action` |
+
+The rules read each size with its default as fallback, like `--gl-modal-max-width`. The toggle's thumb inset and travel (in both directions) and the first-line alignment of toggle, checkbox and radio are derived from these, so any value stays aligned. The two paddings are unset by default and fall back to `--gl-space-md`, so a spacing override still reaches them. Set any token on `:root` for both densities, or on `[data-density="compact"]` for compact only.
+
 ### Shadows
 
 | Token | Usage |
@@ -478,6 +510,8 @@ Full-width buttons (56px height) with three variants and size modifiers.
 
 **Important:** Buttons default to `width: 100%`. Use `--auto` for inline/auto-width buttons.
 
+**Heights** are density tokens: `--gl-btn-height`, `-sm`, `-lg` — 56 / 44 / 64px, or 40 / 32 / 48px with `data-density="compact"` on `<html>` (since 1.21.0).
+
 **Icons:** Button SVGs need **no inline `fill`/`stroke` attributes** – GlassKit styles them automatically: outline style (`fill: none; stroke: currentColor; stroke-width: 2`, round caps/joins) as the default, `--secondary`/`--tertiary` use their icon tokens, `--primary` renders icons filled. For deliberately filled icons (e.g. brand logos like the GitHub mark) add `glass-icon--fill` to the `<svg>`.
 
 **Links as buttons:** `.glass-btn` also works on `<a>` elements – anchors render as `inline-flex` with `text-decoration: none`, so `--auto` shrink-wraps exactly like on a real `<button>`.
@@ -1884,6 +1918,7 @@ Key points in this composition:
 7. **`data-theme`** – Always set on `<html>`, never on `<body>` or deeper elements.
 8. **List dividers are automatic** – Never add a `<hr>` or divider element between `.glass-list__item`s. The divider is rendered via `::after` and respects `:has(.glass-list__leading)` for the inset.
 9. **Popover toggle naming** – Never name your popover toggle JS function `togglePopover`. It collides with the native `HTMLElement.togglePopover()` method. Use a prefix like `gkTogglePopover`.
+10. **`data-density`** – Like `data-theme`, on `<html>`: `compact` or absent. For a denser UI set the attribute or a density token, never `height` on the components.
 
 ### ❌ Common Mistakes
 
@@ -1900,6 +1935,7 @@ Key points in this composition:
 | Putting `glass-list` inside `glass-popover` without `--bare` | Add `.glass-list--bare` to strip the double glass surface |
 | JS function named `togglePopover()` | Rename to `gkTogglePopover()` or similar to avoid native API clash |
 | Putting `.is-open` on the trigger button instead of `.glass-popover` | The state class belongs on the popover element |
+| Overriding `height` of `.glass-btn`, `.glass-input` etc. for a denser UI | `data-density="compact"` on `<html>`, or set a density token — toggle thumb and label alignment follow the tokens, not a hand-set `height` |
 
 ---
 
@@ -1977,7 +2013,7 @@ customElements.define('my-card', MyCard);
 | `css` | `string` | The same, as a string |
 | `componentsSheet` | `CSSStyleSheet` | Component rules only, no token declarations (since 1.9.0) |
 | `componentsCss` | `string` | The same, as a string |
-| `tokensSheet` | `CSSStyleSheet` | Only the two `[data-theme]` blocks that declare `--gl-*` (since 1.9.0) |
+| `tokensSheet` | `CSSStyleSheet` | Only the blocks that declare `--gl-*`: the two `[data-theme]` blocks (since 1.9.0) and the `[data-density="compact"]` preset (since 1.21.0) |
 | `tokensCss` | `string` | The same, as a string |
 
 CSS Custom Properties (`--gl-*`) cross the shadow boundary by inheritance, so the example
@@ -1988,6 +2024,7 @@ above picks up whatever the document defines and theme switching works globally.
 > element carrying `data-theme`, that selector matches it and re-declares every token
 > locally — and a matching rule always beats an inherited value. A project's
 > `:root { --gl-color-primary: … }` then silently stops arriving inside your component.
+> The dark block declares the default control sizes too, so `<html data-density="compact">` stops arriving as well — unless that element carries `data-density` mirrored from `<html>`, which lets the compact preset (also in the full sheet) match it.
 >
 > If you need a themed element inside the shadow root, adopt `componentsSheet` instead
 > and make sure the tokens are present on the document:
@@ -2060,6 +2097,13 @@ Overriding `--gl-color-success` / `--gl-color-error` is enough on its own: fill,
 text and glow of every state component are derived from those tokens. Only if you want
 a different ink than the derived one do you need to touch `--gl-color-{state}-on-surface`.
 
+The density tokens (section 2) are overridden the same way, for both densities or for compact only:
+
+```css
+:root                    { --gl-btn-height: 48px; }
+[data-density='compact'] { --gl-btn-height: 36px; }
+```
+
 Included theme templates in `theme-override.css`:
 - 🔵 Ocean Blue
 - 🟢 Emerald Green

build-styles-js.mjs

@@ -7,7 +7,8 @@
 //
 // The CSS is additionally emitted split in two:
 //
-//   tokensCss      – the two [data-theme] blocks that declare --gl-*
+//   tokensCss      – the blocks that declare --gl-*: the two [data-theme]
+//                    blocks and the [data-density=compact] preset
 //   componentsCss  – everything else
 //
 // Why: a shadow root that adopts the *whole* sheet re-declares every token
@@ -30,10 +31,13 @@ const pkg = JSON.parse(readFileSync('package.json', 'utf-8'));
 const css = readFileSync('glasskit.min.css', 'utf-8').replace(/\/\*# sourceMappingURL=.*?\*\/\s*$/, '');
 
 // ---- Split off the token blocks -------------------------------------------
-// Both selectors appear exactly once in the minified output. The light block
+// Each selector appears exactly once in the minified output. The light block
 // is matched with its brace attached so the `[data-theme=light] .glass-*`
-// component rules are not mistaken for it.
-const TOKEN_BLOCK_STARTS = [':root,[data-theme=dark]{', '[data-theme=light]{'];
+// component rules are not mistaken for it; the density preset the same way.
+// The preset belongs with the tokens: in componentsCss it would re-declare
+// the density tokens inside every shadow root that carries the attribute,
+// and a project's own density values would stop arriving there.
+const TOKEN_BLOCK_STARTS = [':root,[data-theme=dark]{', '[data-theme=light]{', '[data-density=compact]{'];
 
 /** Returns [start, end) of the rule block beginning at `open`. */
 function blockRange(source, open) {
@@ -71,7 +75,9 @@ componentsCss += css.slice(cursor);
 const checks = [
   [tokensCss.includes('--gl-color-primary:'), 'tokensCss is missing --gl-color-primary'],
   [tokensCss.includes('--gl-state-scrim:'), 'tokensCss is missing --gl-state-scrim'],
+  [tokensCss.includes('--gl-control-height:40px'), 'tokensCss is missing the compact density preset'],
   [!componentsCss.includes('--gl-color-primary:'), 'componentsCss still declares tokens'],
+  [!componentsCss.includes('--gl-control-height:'), 'componentsCss still declares density tokens'],
   [!css.includes('sourceMappingURL'), 'the embedded CSS still names a source map'],
   [componentsCss.includes('.glass-btn--primary'), 'componentsCss is missing component rules'],
   [componentsCss.includes('.glass-theme-toggle'), 'componentsCss lost the theme-toggle rules'],
@@ -81,7 +87,7 @@ for (const [ok, message] of checks) {
   if (!ok) throw new Error(`Split check failed: ${message}`);
 }
 
-// The two token blocks sit next to each other, so the full sheet is exactly
+// The token blocks sit next to each other, so the full sheet is exactly
 // head + tokens + tail. Emitting the parts and re-joining them at runtime keeps
 // the module from carrying the CSS twice.
 const head = css.slice(0, ranges[0][0]);
@@ -94,7 +100,7 @@ const output = [
   `// GlassKit v${pkg.version} – Constructable Stylesheet`,
   '// Auto-generated by build-styles-js.mjs – do not edit manually.',
   '',
-  '// The [data-theme] blocks that declare --gl-* …',
+  '// The [data-theme] and [data-density] blocks that declare --gl-* …',
   `const tokensCss = ${JSON.stringify(tokensCss)};`,
   '',
   '// … and everything else, in two pieces around where they were.',