@jungherz-de/glasskit 1.19.1 → 1.21.0

package/CHANGELOG.md

@@ -7,6 +7,74 @@ GlassKit uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.21.0] – 2026-10-05
+
+Contributed as pull request [#5](https://github.com/JUNGHERZ/GlassKit/pull/5) by the product that is adopting GlassKit at full depth; GlassKit Elements 1.21.0 follows the attribute.
+
+### 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.
+
+### Fixed
+
+- **The select's chevron shows in the light theme.** It was an SVG with a fixed white stroke (`rgba(255,255,255,0.6)`) in both themes, so on light glass the arrow all but disappeared and the select no longer read as one. It is now the token `--gl-select-chevron`, set per theme: the dark theme keeps the same white stroke, the light theme draws it in its muted text colour, `rgba(26,42,54,0.55)`. The rule reads `var(--gl-select-chevron, …)` with the old image as fallback; a page replaces the arrow by setting the token to its own `url(…)`. Measured: docs and showcase render pixel-identical in the dark theme; in the light theme the chevron's 28 pixels are all that changes. ([#1](https://github.com/JUNGHERZ/GlassKit/issues/1))
+- **A hidden list slot takes no room.** `.glass-list__leading { display: flex }` beat the user-agent rule for `[hidden]`, so a `<glk-list-item>` without an icon, which hides its empty leading slot, kept the 28 px box and its gap: title at 60 px instead of 20, row 60 px instead of 56. `.glass-list__leading[hidden]` and `.glass-list__trailing[hidden]` are now `display: none` — the same fix 1.16.0 made for `.glass-btn[hidden]` — and the divider rules look for a *visible* leading slot, so such a row's divider starts at 20 px like that of a row built without the slot. Measured in Chromium and WebKit: title 20 px, row 56 px, divider from 20 px. ([#4](https://github.com/JUNGHERZ/GlassKit/issues/4))
+- **Toggle, checkbox and radio: the invisible input lies on top of its control.** With `pointer-events: none`, and painted below the track, box or circle, the input was covered — a test tool that clicks the control by its role (`getByRole('switch').click()`, `check()` in Playwright) found something else at the spot and timed out, and a pointer reached the input only by way of the label. It now has `z-index: 1` and takes the click itself. It covers exactly the track (52 × 30) or the box and circle (24 × 24), left to right, right to left and next to large text alike (measured offset: 0 px in Chromium and WebKit), and lines up with their first-line offset through the same `lh` margin; without `lh` support it keeps `margin: 0`, as the visuals do. The label text — a link in a consent label included — stays the label's: the link follows and the box stays unticked. Nothing changes visually; docs and showcase render pixel-identical. Found while moving `<glk-toggle>`'s switch role onto its input. (GlassKit Elements [#6](https://github.com/JUNGHERZ/glasskit-elements/issues/6))
+- **An empty control label takes no room.** `.glass-toggle__label`, `.glass-checkbox__label` and `.glass-radio__label` are `display: none` while `:empty`, so a switch without text keeps no 12 px gap for one: 52 px wide instead of 64. (GlassKit Elements [#8](https://github.com/JUNGHERZ/glasskit-elements/issues/8))
+
+### Added
+
+- **Right to left.** With `dir="rtl"` on `<html>` or a container, the components mirror. Paddings, insets and borders are logical properties now: label and hint padding, the search icon and the room kept for it, the toast's ×, the tab bar badge, the list dividers, the popover's `--start` and `--end` anchors, the line between modal actions, and the prose list indent and blockquote rule; accordion triggers, list rows, table headers and prose align to the start, `.glass-table__num` to the end. Pairs that must move together sit under `:dir(rtl)` — the select's chevron and its 40 px padding, the toggle's thumb and its travel, the popover's transform origin, the progress fill's gradient (turned with `scale: -1 1`, so its darker end still leads) — so a browser without `:dir()` (Chrome before 120) keeps them left to right instead of splitting them. Left to right nothing moves: docs and showcase render pixel-identical in both themes, apart from the light chevron above. Checked under `dir="rtl"` in Chromium and WebKit: chevron at 16 px from the left with the padding on its side, label and hint padding on the right, search icon on the right, thumb starting right and travelling left, rows without icon with title and divider at 20 px from the right, fill growing from the right. ([#2](https://github.com/JUNGHERZ/GlassKit/issues/2))
+- **`--gl-modal-max-width`.** `.glass-modal` was capped by a literal 340 px, so a dialog with a form or a table could not grow on tablet or desktop without overriding the component rule. It reads `var(--gl-modal-max-width, 340px)` now, with the token in the `:root` block: `.settings-dialog { --gl-modal-max-width: 560px; }`. ([#3](https://github.com/JUNGHERZ/GlassKit/issues/3))
+- **The modal overlay may be a native `<dialog>`.** Opened with `showModal()`, it lies in the top layer, the page behind it is inert for pointer, keyboard and screen readers, focus moves in and goes back to where it came from, and Escape closes it. `dialog.glass-modal-overlay` undoes the dialog's own box — size, margin, border, colour — keeps a closed dialog hidden (the overlay's `display: flex` would beat the user-agent rule) and makes its `::backdrop` transparent, because the overlay paints the dimmed, blurred layer itself; the `.is-active` fade works as before. While such a dialog is open, everything outside it is inert, a toast included: it is neither clickable nor announced. GlassKit Elements 1.20.0 builds `<glk-modal>` on it. (GlassKit Elements [#5](https://github.com/JUNGHERZ/glasskit-elements/issues/5))
+
+### Documentation
+
+- **Browser support in the README.** It still named Firefox 103 and "full" support elsewhere, but the token derivations use `color-mix()` since 1.11.0: the floor is Chrome and Edge 111, Safari 16.4, Firefox 113, Samsung Internet 22. Three refinements come later and fall back quietly — first-line alignment of toggle, checkbox and radio (`lh`, Firefox 120), the divider of rows without icon (`:has()`, Firefox 121), the right-to-left pairs (`:dir()`, Chrome 120). (GlassKit Elements [#9](https://github.com/JUNGHERZ/glasskit-elements/issues/9) asked for the check.)
+- The docs pages counted 31 components and the package description 24; README, SKILL.md and the landing pages say 34, and now all of them do. Docs (English and German) and SKILL.md describe right to left, the dialog overlay, both tokens and the control inputs; `theme-override.css` has an example for the two tokens.
+
+### Compatibility
+
+- Pages under `dir="rtl"` that mirrored GlassKit with their own rules can drop them.
+- A pointer click on a toggle, checkbox or radio now targets the input: listeners above it see one `click` (from the input) where they saw two (one from the track, box or circle, one from the input that the label then activated).
+- A page that gave the select its own chevron through `background-image` keeps it; setting `--gl-select-chevron` is the simpler way now.
+
+---
+
 ## [1.19.1] – 2026-09-26
 
 ### Fixed
@@ -944,6 +1012,8 @@ during development. Version 1.3 is the first public open-source release.
 
 ---
 
+[1.21.0]: https://github.com/JUNGHERZ/GlassKit/releases/tag/v1.21.0
+[1.20.0]: https://github.com/JUNGHERZ/GlassKit/releases/tag/v1.20.0
 [1.19.1]: https://github.com/JUNGHERZ/GlassKit/releases/tag/v1.19.1
 [1.19.0]: https://github.com/JUNGHERZ/GlassKit/releases/tag/v1.19.0
 [1.18.0]: https://github.com/JUNGHERZ/GlassKit/releases/tag/v1.18.0
@@ -971,4 +1041,4 @@ during development. Version 1.3 is the first public open-source release.
 [1.3.2]: https://github.com/JUNGHERZ/GlassKit/releases/tag/v1.3.2
 [1.3.1]: https://github.com/JUNGHERZ/GlassKit/releases/tag/v1.3.1
 [1.3.0]: https://github.com/JUNGHERZ/GlassKit/releases/tag/v1.3.0
-[Unreleased]: https://github.com/JUNGHERZ/GlassKit/compare/v1.19.1...HEAD
+[Unreleased]: https://github.com/JUNGHERZ/GlassKit/compare/v1.21.0...HEAD

package/README.md

@@ -1,9 +1,9 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/version-1.19.1-orange?style=flat-square" alt="Version">
+  <img src="https://img.shields.io/badge/version-1.21.0-orange?style=flat-square" alt="Version">
   <img src="https://img.shields.io/badge/CSS-only-blue?style=flat-square" alt="CSS only">
   <img src="https://img.shields.io/badge/components-34-green?style=flat-square" alt="Components">
   <img src="https://img.shields.io/badge/license-MIT-lightgrey?style=flat-square" alt="License">
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/changelog-v1.19.1-f5a623?style=flat-square" alt="Changelog"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/changelog-v1.21.0-f5a623?style=flat-square" alt="Changelog"></a>
   <a href="https://www.npmjs.com/package/@jungherz-de/glasskit"><img src="https://img.shields.io/npm/v/@jungherz-de/glasskit?style=flat-square&color=cb3837&label=npm" alt="npm"></a>
   <a href="https://cdn.jsdelivr.net/npm/@jungherz-de/glasskit/"><img src="https://img.shields.io/badge/CDN-jsDelivr-blue?style=flat-square" alt="jsDelivr"></a>
 </p>
@@ -72,16 +72,16 @@ No download, no build tool – just include and go:
 
 ```html
 <!-- jsDelivr – Minified -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/glasskit@1.19/glasskit.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/glasskit@1.21/glasskit.min.css">
 
 <!-- jsDelivr – Unminified (for reading/debugging) -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/glasskit@1.19/glasskit.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/glasskit@1.21/glasskit.css">
 
 <!-- unpkg – Alternative -->
-<link rel="stylesheet" href="https://unpkg.com/@jungherz-de/glasskit@1.19/glasskit.min.css">
+<link rel="stylesheet" href="https://unpkg.com/@jungherz-de/glasskit@1.21/glasskit.min.css">
 ```
 
-> **Tip:** Replace `@1.19` with `@latest` for the newest version – or pin to a specific version for maximum stability.
+> **Tip:** Replace `@1.21` with `@latest` for the newest version – or pin to a specific version for maximum stability.
 
 ### npm / yarn / pnpm
 
@@ -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,9 +346,20 @@ 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
+
+/* Component hooks */
+--gl-modal-max-width      /* 340px */
+--gl-select-chevron       /* url(…) per theme */
+--gl-toast-top            /* distance of the toast from the top */
 ```
 
 The full token reference can be found in the [Documentation](docs.html).
@@ -432,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.
 
 ---
@@ -520,14 +571,20 @@ Attach or reference `SKILL.md` when asking an AI to generate GlassKit HTML. It p
 
 ## 🌐 Browser Compatibility
 
-GlassKit uses `backdrop-filter` for glass effects. Support:
+The floor is set by `color-mix()`, which derives the brand, state and focus tokens on `:root` (since 1.11.0):
 
-| Browser | Support |
+| Browser | Version |
 |---|---|
-| Safari (iOS/macOS) | ✅ Full |
-| Chrome / Edge | ✅ Full |
-| Firefox | ✅ From version 103 |
-| Samsung Internet | ✅ Full |
+| Chrome / Edge | 111+ |
+| Safari (iOS/macOS) | 16.4+ |
+| Firefox | 113+ |
+| Samsung Internet | 22+ |
+
+A few refinements arrive later and fall back quietly where they are missing:
+
+- The first-line alignment of toggle, checkbox and radio uses the `lh` unit (Firefox 120); without it the control sits at the top of its label.
+- List rows without a leading icon move their divider in with `:has()` (Firefox 121); without it the divider keeps the icon inset.
+- Right to left, the pairs that must move together — select chevron and padding, toggle thumb and travel, progress gradient — sit under `:dir(rtl)` (Chrome 120); without it they stay left to right.
 
 > **Note:** In browsers without `backdrop-filter` support, elements will be rendered with the defined background colors – the UI remains usable, just without the blur effect.
 
@@ -536,6 +593,10 @@ GlassKit uses `backdrop-filter` for glass effects. Support:
 ## 📋 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
@@ -567,8 +628,13 @@ Toast Modifiers:
   .glass-toast__action / __close   (offer with a button)
   --gl-toast-top                   (distance from the top)
 
-Modal Action Modifiers:
+Modal:
   .glass-modal__action--primary / --danger
+  dialog.glass-modal-overlay       (native <dialog>, opened with showModal())
+  --gl-modal-max-width             (panel width, 340px unless set)
+
+Select:
+  --gl-select-chevron              (the chevron, per theme)
 
 List Modifiers:
   .glass-list--flush / --bare
@@ -616,6 +682,9 @@ Tab Bar – Floating:
   .glass-tab-bar--floating
   .glass-tab-bar__accessory
   .glass-tab-bar__accessory--accent / --success / --error
+
+Right to left:
+  dir="rtl" on <html> or a container – the components mirror
 ```
 
 ---

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: glasskit-css
-description: GlassKit is a pure CSS glassmorphism component library (v1.19.1) with 34 components, Dark & Light mode, design tokens, and BEM-like naming. Use this reference whenever generating HTML that uses GlassKit classes to ensure correct structure, nesting, modifiers, and token usage.
+description: GlassKit is a pure CSS glassmorphism component library (v1.21.0) with 34 components, Dark & Light mode, design tokens, and BEM-like naming. Use this reference whenever generating HTML that uses GlassKit classes to ensure correct structure, nesting, modifiers, and token usage.
 ---
 
 # GlassKit CSS – AI Component Reference
@@ -80,6 +80,25 @@ function toggleTheme() {
 }
 ```
 
+### Right to Left (since 1.20.0)
+
+Set `dir="rtl"` on `<html>` or on any container; nothing else. Paddings, insets and borders
+are logical properties, so labels, hints, the search icon, list dividers, popover anchors,
+tab badges, modal actions, the toast's × and the text alignment of accordion, list, table
+and prose mirror. Pairs that must move together — the select's chevron and its padding, the
+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
@@ -206,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 |
@@ -469,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>`.
@@ -598,7 +641,8 @@ Danger variant:
 |---|---|
 | `.glass-modal-overlay` | Fullscreen container with blur |
 | `.glass-modal-overlay.is-active` | Visible + animated |
-| `.glass-modal` | Dialog box |
+| `dialog.glass-modal-overlay` | The overlay as a native `<dialog>`, opened with `showModal()` (since 1.20.0) |
+| `.glass-modal` | Dialog box, at most `--gl-modal-max-width` wide (340px unless set; since 1.20.0) |
 | `.glass-modal__header` | Header area |
 | `.glass-modal__title` | Title (20px, bold) |
 | `.glass-modal__body` | Content area |
@@ -618,6 +662,43 @@ document.querySelector('.glass-modal-overlay').classList.add('is-active');
 document.querySelector('.glass-modal-overlay').classList.remove('is-active');
 ```
 
+**Prefer a native `<dialog>` (since 1.20.0).** Opened with `showModal()` it lies in the top
+layer, the page behind it is inert (pointer, keyboard, screen readers), focus moves in and
+returns on close, and Escape closes it. GlassKit resets the dialog's own box and backdrop:
+
+```html
+<dialog class="glass-modal-overlay" id="confirm" aria-labelledby="confirm-title">
+  <div class="glass-modal">
+    <div class="glass-modal__header">
+      <h2 class="glass-modal__title" id="confirm-title">Delete contract?</h2>
+    </div>
+    <div class="glass-modal__body"><p>This action cannot be undone.</p></div>
+    <div class="glass-modal__footer">
+      <button class="glass-modal__action" onclick="closeDialog()">Cancel</button>
+      <button class="glass-modal__action glass-modal__action--danger">Delete</button>
+    </div>
+  </div>
+</dialog>
+```
+
+```js
+const dialog = document.getElementById('confirm');
+function openDialog() {
+  dialog.showModal();
+  void dialog.offsetHeight;            // compute the closed state first,
+  dialog.classList.add('is-active');   // so the fade runs
+}
+function closeDialog() {
+  dialog.classList.remove('is-active');
+  setTimeout(() => dialog.close(), 300);   // after the fade
+}
+dialog.addEventListener('cancel', (e) => { e.preventDefault(); closeDialog(); }); // Escape fades too
+```
+
+While a modal dialog is open everything outside it is inert — a toast shown then is neither
+clickable nor announced; give feedback inside the dialog. Wider dialogs (forms, tables):
+`.my-dialog { --gl-modal-max-width: 560px; }`.
+
 ---
 
 ### 3.13 Toast
@@ -734,6 +815,10 @@ Dropdown with glass styling and custom chevron.
 |---|---|
 | `.glass-select` | Styled dropdown |
 
+The chevron is the token `--gl-select-chevron` — an SVG `url(…)` in each theme's muted text
+colour (since 1.20.0; before, it stayed white in the light theme). Override it with your own
+`url(…)`. Right to left, chevron and padding move to the left.
+
 ---
 
 ### 3.17 Search
@@ -753,7 +838,7 @@ Search field with embedded search icon.
 | Class | Description |
 |---|---|
 | `.glass-search` | Wrapper (position: relative) |
-| `.glass-search__icon` | Positioned search icon (left) |
+| `.glass-search__icon` | Positioned search icon (inline start — left, or right under `dir="rtl"`) |
 
 **Important:** The input inside `.glass-search` uses the regular `.glass-input` class.
 
@@ -783,6 +868,12 @@ iOS-style switch.
 
 **State:** `:checked` on the input activates the toggle visually.
 
+The input is invisible but lies **on top of** the track and takes the click itself (since
+1.20.0) — a test tool clicking the switch by role (`getByRole('switch')` with
+`role="switch"` on the input) reaches it. It covers only the track; label text, links in it
+included, stays the label's. An empty `__label` takes no room (no 12px gap). Both apply to
+checkbox and radio as well.
+
 ---
 
 ### 3.19 Checkbox
@@ -1050,7 +1141,8 @@ iOS-style grouped settings list. Items can carry a leading icon, a title with op
 
 **Notes:**
 - Dividers are auto-rendered via `::after`. The last item never has a divider.
-- Items **with** a `__leading` slot get an icon-aligned divider inset; items **without** a leading slot get a standard left/right padding inset (handled via `:has()`). Large leading (`--lg`) adjusts the divider inset automatically.
+- Items **with** a `__leading` slot get an icon-aligned divider inset; items **without** one — or with a `__leading` that carries the `hidden` attribute (since 1.20.0) — get the standard padding inset (handled via `:has()`). Large leading (`--lg`) adjusts the divider inset automatically.
+- A `__leading` or `__trailing` with `hidden` takes no room (since 1.20.0; `display: flex` used to beat the attribute).
 - SVG icon convention: `24px` for leading (32px for `--lg`), `18px` for trailing, `stroke: currentColor`, `stroke-width: 2`.
 - Use `<ul>` + `<li>` for semantic lists. For interactive rows wrap in `<a>` or `<button>` instead of `<li>` if a single-row list is needed.
 - `.glass-list__section-header` sits **outside** the `.glass-list` container, directly above it.
@@ -1826,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
 
@@ -1842,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` |
 
 ---
 
@@ -1919,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
@@ -1930,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:
@@ -2002,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