@guildofgleks/ui 21.8.0 → 21.9.0

package/AGENTS.md

@@ -5,8 +5,8 @@ an app that **consumes** the published `@guildofgleks/ui` npm package. It is not
 authoring the library — if you are working inside the `gleks_web_ui` monorepo itself, read
 `.github/instructions/*.md` instead.
 
-Everything below reflects the library's actual source as of **`21.8.0`** (in progress — the
-released version is 21.7.2; see `CHANGELOG.md` for what 21.8.0 adds). 21.7.0 removed the three
+Everything below reflects the library's actual source as of **`21.9.0`** (in progress — the
+released version is 21.8.0; see `CHANGELOG.md` for what 21.9.0 adds). 21.7.0 removed the three
 abbreviated token prefixes and 21.5.0 removed a batch of deprecated API — see **Removed in 21.7.0**
 and **Removed in 21.5.0** near the end of this file, which exist so code written against an older
 version can be migrated — and `CHANGELOG.md` has the rest. `README.md` covers the same ground at a
@@ -181,13 +181,30 @@ Full model is in `README.md`'s Theming section; short version:
   `--gog-text-transform`/`--gog-letter-spacing` (emphasis casing/tracking). Component tokens in
   the categories these cover derive from them by default; setting one in a `[data-theme]` block
   restyles every component that reads it, with nothing to re-list per component.
+- **The type scale is `--gog-text-xs | sm | md | lg | slg | xl | 2xl | 3xl`.** `slg` (1.25rem)
+  fills the gap between `lg` and `xl` and is named for the control size that needed it. Every
+  component font size that is one of these reads the token, so retuning the scale retunes the
+  library; the handful that do not are off-scale on purpose (an 11px chip, the accordion
+  chevron's px ramp, the toggle's own micro-ramp).
+
+- **Weight is `--gog-font-weight-medium | semibold | bold | heavy`** (500/600/700/900). Every
+  component weight reads one of them, so a lighter or heavier house style is four declarations.
+
+- **`--gog-z-base` moves the whole stacking order.** Badge `+1`, toast `+100`, dropdowns, dialogs
+  and menus `+300`, tooltip `+400`, the blocking spinner overlay `+8000`. Set the base to lift
+  the library above your own chrome without disturbing its internal order.
+
 - **`--gog-density` is the character layer for spacing** (since 21.7.0, `docs/themes.md`
   iteration 6). It multiplies the fourteen-step scale `--gog-space-2` … `--gog-space-48`, named
   for their pixel value at density 1, and every padding and gap in the library derives from a
   step. `--gog-density: 0.9` in a `[data-theme]` block makes the whole library tighter; nothing
   else needs to be named. `--gog-space-xs|sm|md|lg|2xl` are aliases for steps 4/8/16/24/48 and
-  still work. Icon offsets follow density; the glyph box, focus-ring offset and float-label
-  reserve deliberately do not — they are legibility, not spacing.
+  still work. Icon offsets, dropdown panel gaps, error-line offsets and the badge's overhang
+  follow density; the glyph box, the focus-ring offset, the float-label reserve and the
+  scrollbar/toggle thumb insets deliberately do not — those are legibility or geometry fitted to
+  a fixed-width track, not spacing. Since 21.9.0 the split is enforced rather than trusted:
+  `check-tokens` rule H fails the build on a length token that restates a scale step's value as
+  a bare literal, with the three exceptions named in the script.
 - **Component prefixes are spelled out** since 21.5.0: `--gog-button-*`, `--gog-multiselect-*`,
   `--gog-confirmation-dialog-*`. The abbreviated `--gog-btn-*`, `--gog-ms-*` and `--gog-confirm-*`
   were removed in 21.7.0 — if you're reading a codebase or an example that still uses one, rename
@@ -271,7 +288,8 @@ parent's config**, one level deep per key — it does not replace it.
 | `datepicker`   | `locale`, `firstDayOfWeek`, `format`                                    | `gog-datepicker`, `gog-calendar`.                                                                                                                                                                                                                                                                                                                                                                            |
 | `autocomplete` | `searchDebounce`, `minLength`, `openOnFocus`                            | `gog-autocomplete`.                                                                                                                                                                                                                                                                                                                                                                                          |
 | `tooltip`      | `position`, `showDelay`, `hideDelay`                                    | the `gogTooltip` directive.                                                                                                                                                                                                                                                                                                                                                                                  |
-| `scroll`       | `autoHide`, `hideDelay`, `size`, `overscrollBehavior`, `showTrack`      | `gog-scroll` (and every component that uses one internally).                                                                                                                                                                                                                                                                                                                                                 |
+| `spinner`      | `component`, `variant`                                                  | every spinner the library draws — `gog-spinner`, `gog-spinner-overlay`, and the ones inside `gog-button` and `gog-autocomplete`, which have no input of their own. `component` takes **your** component and renders it in place of the built-in look. |
+| `scroll`       | `autoHide`, `hideDelay`, `size`, `overscrollBehavior`, `showTrack`, `horizontalWheel` | `gog-scroll` (and every component that uses one internally).                                                                                                                                                                                                                                                                                                                                                 |
 | `button`       | `debounce`                                                              | `gog-button`.                                                                                                                                                                                                                                                                                                                                                                                                |
 | `ripple`       | `enabled`                                                               | the press ripple on `gog-button`, `[gogButton]`, `gog-button-toggle-group`, `gog-chip`, `gog-tabs`, `gog-accordion`, `gogCollapsibleTrigger`, `gogMenuItem` and the `gog-select`/`gog-multiselect`/`gog-autocomplete` options. **Off by default.** Each of those takes a `ripple` input that wins over it. Not the `gogRipple` directive — writing that attribute is already the per-element decision.       |
 | `inputfield`   | `showSpinButtons`                                                       | `gog-inputfield`.                                                                                                                                                                                                                                                                                                                                                                                            |
@@ -468,6 +486,7 @@ Every component below is exported from `@guildofgleks/ui`'s root — `import { X
 | Input       | Type                              | Default     | Notes                                                 |
 | ----------- | --------------------------------- | ----------- | ----------------------------------------------------- |
 | `variant`   | `GogVariant`                      | `'primary'` |                                                       |
+| `severity`  | `GogSeverity`                     | `'accent'`  | what the action means; orthogonal to `variant` — see below |
 | `size`      | `GogSize \| undefined`            | `'md'`      | via `GOG_CONFIG.control.size`                         |
 | `disabled`  | `boolean`                         | `false`     |                                                       |
 | `fullWidth` | `boolean`                         | `false`     |                                                       |
@@ -483,6 +502,29 @@ Every component below is exported from `@guildofgleks/ui`'s root — `import { X
 
 Outputs: `gogClick: MouseEvent`.
 
+**`severity` says what the action means; `variant` says how loudly it is drawn** (21.9.0). The
+two are orthogonal, so this is not a fifth variant — it re-points the colours all four are built
+from, and every combination is real: `variant="ghost" severity="danger"` is a quiet delete,
+`variant="primary" severity="danger"` a loud one. `'accent'` is the default and the absence of a
+claim, so nothing has to opt out of a severity it does not have. `GogSeverity` is shared with
+`gog-progressbar`, whose `GogProgressbarVariant` is now an alias of it.
+
+```html
+<gog-button severity="danger" (gogClick)="deleteAccount()">Delete account</gog-button>
+<gog-button variant="outline" severity="warning">Discard draft</gog-button>
+<a gogButton severity="success" routerLink="/done">Finish</a>
+```
+
+Two colour rules are worth knowing before you override anything. A **filled** severity button's
+label is `--gog-<status>-text-color`, which each theme states for its own hue — `material` and
+`primeng` put near-black on their bright ones, the rest white — and hover and press deepen the
+fill *away* from that label (`--gog-<status>-shade`), so a state always makes the label easier to
+read rather than harder. A **transparent** one's label is `--gog-button-<status>-ink`: the status
+hue mixed halfway toward the page's ink, because the raw hue is legible body text in only five of
+the eleven shipped themes. Override `--gog-button-<status>-ink` if your own theme wants more
+colour there, and check it: all four severities across all four variants and all their states are
+gated by `npm run check:contrast`.
+
 **Every ARIA attribute this button needs has an input, and a raw attribute is not a
 substitute.** `<gog-button [attr.aria-pressed]="on()">` compiles, throws nothing, and does
 nothing: the attribute lands on the `<gog-button>` custom element, which has no role, while the
@@ -494,6 +536,13 @@ simply not a toggle to a screen reader. Use `[ariaPressed]`, `[ariaExpanded]`, `
 `aria-pressed="false"` / `aria-expanded="false"`, which is what an off toggle or a closed
 disclosure has to say — a button with no `aria-pressed` at all is not a toggle button.
 
+**A toggle button now looks toggled** (21.9.0). `aria-pressed="true"` (or `"mixed"`) draws an
+inset ring — `--gog-button-<variant>-toggled-shadow`, overridable per instance with
+`--gog-button-toggled-shadow`. A ring rather than a fill because hover and press already own the
+background: the state has to survive both, and until 21.9.0 it did not exist at all, so a button
+could announce itself as on to a screen reader and look identical to an off one. `[gogButton]`
+gets the same look from the attribute you write on your own element.
+
 **`[gogButton]` needs none of these inputs.** It styles an element you own, so write the ARIA
 attributes on your own `<button>`/`<a>` directly. Same for `[gogMenuTrigger]`, which sets
 `aria-haspopup`/`aria-expanded`/`aria-controls` on its host — put it on your own `<button
@@ -506,6 +555,19 @@ gogButton>`, as its own example shows, not on a `<gog-button>`.
             (gogClick)="open.set(!open())">Filters</gog-button>
 ```
 
+**The press is a colour, not only a movement.** `:active` deepens the button's background (and
+the label where the fill demands it) as well as scaling it by `--gog-button-active-scale`. Under
+`prefers-reduced-motion: reduce` the scale is dropped and the colour stays, so the press is still
+visible to a reader who has switched animations off — before 21.9.0 that reader got no feedback at
+all, since the ripple is off by default and is itself suppressed under reduced motion. Override
+per instance with `--gog-button-press-bg` / `--gog-button-press-color`, or per theme with
+`--gog-button-<variant>-active-bg`.
+
+Every other pressable surface in the library does the same thing since 21.9.0 — menu items,
+chips, tab and accordion headers, button-toggle options and the three dropdowns' option rows —
+each through its own `--gog-<block>-press-bg`. `gogCollapsibleTrigger` is the exception: the
+library paints nothing on that element in any state, because it is yours.
+
 **`debounce` is a spam guard, not a delay before the first click.** The first click in a window
 fires immediately (leading edge); further clicks within `debounce` ms are silently dropped.
 
@@ -956,6 +1018,7 @@ the element stays yours and the directive only gives it the look.
 | Input       | Type                     | Default                                  |
 | ----------- | ------------------------ | ---------------------------------------- |
 | `variant`   | `GogVariant`             | `'primary'`                              |
+| `severity`  | `GogSeverity`            | `'accent'`; same as `gog-button`         |
 | `size`      | `GogSize \| undefined`   | `'md'`; via `GOG_CONFIG.control.size`    |
 | `fullWidth` | `boolean` (bare attr ok) | `false`                                  |
 | `ripple`    | `boolean \| undefined`   | `false`; via `GOG_CONFIG.ripple.enabled` |
@@ -1004,6 +1067,7 @@ are impossible by design.
 | `size`                         | `GogSize`                           | `'md'`                                   |
 | `shape`                        | `GogTagShape` (`'rounded'\|'pill'`) | `'rounded'`                              |
 | `disabled`, `clickable`        | `boolean`                           | `false`, `true`                          |
+| `selected`                     | `boolean \| null` (two-way)         | `null` — see below                       |
 | `removable`                    | `boolean`                           | `false`                                  |
 | `fullWidth`                    | `boolean`                           | `false`                                  |
 | `ariaLabel`, `removeAriaLabel` | `string`                            | `''`, `'Remove chip'`                    |
@@ -1019,6 +1083,29 @@ Outputs: `gogClick: MouseEvent | KeyboardEvent`, `gogRemove: void`.
 >
 ```
 
+**`selected` makes it a filter chip** (21.9.0) — a chip you toggle on and off rather than press.
+It is tri-state, and `null` is the default so nothing about an existing chip changes: no
+`aria-pressed`, no selected look, activation only emits `gogClick`. Set it to `false` and the chip
+is a toggle that is off (`aria-pressed="false"` — a chip with no `aria-pressed` at all is not a
+toggle to a screen reader, so "off" has to be stated); `true` and it is on, which draws an inset
+ring from `--gog-chip-selected-shadow`. A ring rather than a fill because `:hover` and `:active`
+already own the chip's background and the selection has to survive both.
+
+It is a two-way `model`, so the chip flips it on click, Enter and Space — a row of filters needs
+no click handler:
+
+```html
+@for (f of filters; track f.label) {
+<gog-chip [(selected)]="f.on">{{ f.label }}</gog-chip>
+}
+```
+
+`gogClick` still fires, **after** the flip, so a handler reading `selected()` sees the new value.
+Drive the state from that handler instead and you want a one-way `[selected]`, or the two writes
+cancel out. A `disabled` chip keeps the ring but drops `aria-pressed`, which needs the
+`role="button"` a disabled chip does not carry — "selected, and currently unavailable" is a real
+state and hiding it would leave it announced and invisible.
+
 #### `gog-tag`
 
 | Input       | Type                  | Default     |
@@ -1048,6 +1135,19 @@ Slot: `<ng-template gogTagIcon>` for custom icon markup.
 `variant="custom"` renders your own projected markup, still inheriting the size wrapper and
 `--gog-spinner-color` theming.
 
+**To replace the spinner everywhere at once, pass a component to `GOG_CONFIG`** — including the
+two places you cannot reach with an input, `gog-button`'s and `gog-autocomplete`'s loading
+states:
+
+```ts
+provideGogConfig({ spinner: { component: HouseLoaderComponent } });
+```
+
+It renders inside the same size wrapper as the built-ins, so it keeps the sizing, the overlay
+behaviour, `role="status"` and the accessible name — only the visual is yours. An instance's own
+`variant` still wins over it, so `<gog-spinner variant="ring">` is a ring in an app that has set
+a component: a default does not overrule something asked for explicitly.
+
 ```html
 <gog-spinner-overlay [loading]="isLoading()">
   <app-content-that-loads />
@@ -1588,6 +1688,21 @@ region — the library's official recommendation over a raw `overflow-x`/`overfl
 | `ariaLabel`          | `string`                                                                 | `''`                                                                                    |
 | `overscrollBehavior` | `GogScrollOverscrollBehavior \| undefined` (`'auto'\|'contain'\|'none'`) | `'auto'`; via `GOG_CONFIG.scroll.overscrollBehavior`                                    |
 | `showTrack`          | `boolean \| undefined`                                                   | `true`; via `GOG_CONFIG.scroll.showTrack`                                               |
+| `horizontalWheel`    | `boolean \| undefined`                                                   | `false`; via `GOG_CONFIG.scroll.horizontalWheel`                                        |
+
+**`horizontalWheel` turns a vertical wheel into horizontal scrolling** (21.9.0), for the case a
+consumer hits first: hover a horizontal-only row, turn the wheel, and the *page* moves. That is
+the browser's own behaviour and the component deliberately did nothing about it until now.
+
+It is off by default because it changes what an existing instance does with a gesture it
+currently passes on; `provideGogConfig({ scroll: { horizontalWheel: true } })` turns it on
+app-wide. It only acts when the viewport cannot scroll vertically (checked against live
+geometry, so `axis="both"` scrolls down while there is down to go), the event carries no
+horizontal delta of its own (a trackpad swipe and `Shift`+wheel already work), `ctrlKey` is
+clear (pinch-zoom), and there is room left in the direction of the turn. **That last condition is
+the point:** at the content's end the event is left alone and the page picks it up, so the wheel
+never goes dead over a scrolled-to-the-end region. `overscrollBehavior: 'contain'` still
+contains — that boundary is the browser's and this never reaches past it.
 
 Outputs: `gogScroll: GogScrollMetrics`, `gogReachStart`/`gogReachEnd: 'vertical'|'horizontal'`.
 Methods (via template ref): `scrollTo(options)`, `scrollToTop()`, `scrollToBottom()`,

package/CHANGELOG.md

@@ -4,6 +4,383 @@ All notable changes to `@guildofgleks/ui` are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project has not yet
 reached 1.0, so breaking changes may land in minor versions.
 
+## [21.9.0] - 04.09.2026
+
+### Added
+
+- **`gog-button` and `[gogButton]` gain `severity`.** `severity` says what the action means;
+  `variant` says how loudly it is drawn. The two are orthogonal, which is the whole design: this
+  is not a fifth variant but a re-pointing of the colours all four are built from, so
+  `variant="ghost" severity="danger"` is a quiet delete and `variant="primary" severity="danger"`
+  a loud one. `'accent'` is the default and the absence of a claim — an existing button emits no
+  new class and renders byte-for-byte as before. The `GogSeverity` union is shared with
+  `gog-progressbar`, whose `GogProgressbarVariant` is now an alias of it.
+
+  Two colour rules came out of measuring rather than choosing. A **filled** severity button's
+  label is `--gog-<status>-text-color`, and hover and press deepen the fill *away* from it via
+  `--gog-<status>-shade`, so every state makes the label easier to read rather than harder — the
+  first attempt deepened toward the page's ink unconditionally and cost `primeng`'s info button
+  6.44:1 down to 4.23:1 on press, because there the label *is* the ink. A **transparent** one's
+  label is `--gog-button-<status>-ink`, the status hue mixed halfway toward the ink, because the
+  raw hue is legible body text in only five of the eleven shipped themes; the 50% is the binding
+  case (`material`'s amber) rather than a round number. All four severities, four variants and
+  every state are gated by `check:contrast` — 1155 pairs across 11 themes, all passing.
+
+- **A status colour is three tokens now, not one.** `--gog-<status>-color` is the fill;
+  `--gog-<status>-text-color` is the label that reads on it, the way `--gog-accent-text-color`
+  already did for the accent; and `--gog-<status>-shade` is the direction hover and press deepen
+  in. Both new ones default to the accent's answer, so a theme states them only where its own hue
+  disagrees — and the defaults are what nine of the eleven shipped presets still use. If you write
+  a theme, this is the contract to know: setting a status colour alone is how a bright amber ends
+  up under white text, which is exactly the defect in the Fixed section below.
+
+- **`gog-scroll` gains `horizontalWheel`, so a vertical wheel can scroll a horizontal row.**
+  Hover a horizontal-only region, turn the wheel, and the page moves instead — the browser's own
+  behaviour, and the thing consumers report about this component most. The component draws an
+  overlay thumb over native scrolling and had deliberately never touched wheel handling; this is
+  the narrow exception, opt-in.
+
+  It acts only when all of this holds: the viewport cannot scroll vertically (checked against
+  live geometry, not the `axis` input, so `axis="both"` still scrolls down while there is down to
+  go), the event carries no horizontal delta of its own (a trackpad swipe and `Shift`+wheel
+  already work and translating on top would double them), `ctrlKey` is clear (pinch-zoom), and
+  there is room left in the direction of the turn. **The last one is most of the feature:** at the
+  content's end the event is left alone, so the page picks it up exactly as before. A region that
+  swallowed the wheel at its own end would leave the page feeling stuck, which is a worse bug than
+  the one being fixed. `overscrollBehavior: 'contain'` still contains — that boundary is the
+  browser's and this never reaches past it.
+
+  Off by default, because it changes what an existing instance does with a gesture it currently
+  passes on; `GOG_CONFIG.scroll.horizontalWheel` turns it on app-wide. A line-mode delta (what
+  Firefox sends) is scaled rather than applied raw, which would have moved the content three
+  pixels per notch.
+
+- **`gog-chip` gains `selected` — the filter chip.** A row of chips you toggle on and off could
+  not be built from this component: it had `clickable` and `removable`, so a chip could be pressed
+  or dismissed, but nothing said "this one is on". `[(selected)]` is that, and it is tri-state
+  because the alternative would have changed every chip that already ships. `null`, the default,
+  is not a toggle at all — no `aria-pressed`, no selected look, activation emits `gogClick` and
+  nothing else. `false` is a toggle that is off, and states it: a chip with no `aria-pressed` is
+  not a toggle to a screen reader, so "off" has to be said rather than left absent. `true` draws
+  an inset ring, `--gog-chip-selected-shadow`.
+
+  The look and the semantics ship together on purpose, which is the whole reason this waited:
+  forwarding `aria-pressed` alone would have let a chip announce itself as on while looking
+  identical to an off one — WCAG 1.4.1 from the other side, and the exact trap `gog-button` was
+  in between 21.8.0 and 21.9.0. A ring rather than a fill for the same reason as the button's:
+  `:hover` and `:active` already own this surface's background, so a selected chip painted with a
+  fill would lose the one thing saying it is on the moment the pointer arrived.
+
+  It is a `model`, so the chip flips it on click, Enter and Space and a filter row needs no click
+  handler. `gogClick` still fires, after the flip, so a handler reading `selected()` sees the new
+  value. A `disabled` chip keeps the ring and drops `aria-pressed`, which needs the `role="button"`
+  a disabled chip does not carry — "on, and currently unavailable" is a real state, and hiding it
+  would leave it announced and invisible. `check:contrast` gained the ring against both the hover
+  and the press background, at 3:1 (WCAG 1.4.11, a boundary rather than text); all 11 themes pass.
+
+- **`GOG_CONFIG.spinner.component` — one line replaces every loading indicator in the library.**
+  Passing a component, not a value: it is rendered through `NgComponentOutlet` in place of the
+  built-in look, wherever the library draws a spinner. That includes the two places a consumer
+  could not reach at all — `gog-button` and `gog-autocomplete` render `<gog-spinner>` from their
+  own templates and expose no input for it, so a house loader had no way in. It sits inside the
+  same size wrapper as the built-ins, keeping the sizing, the overlay behaviour, `role="status"`
+  and the accessible name; only the visual changes.
+
+  Precedence is the library's usual instance-then-config-then-default, and the wrinkle is stated
+  because it is the one people will ask about: an instance's own `variant` outranks both config
+  keys, so `<gog-spinner variant="ring">` stays a ring in an app that has set a component.
+  `spinner.variant` is there for an app that only wants to switch between the two built-ins.
+
+  `variant` is therefore `GogSpinnerVariant | undefined` now, resolving through the same
+  `resolveConfigured` chain as every other configurable input. `variant="custom"` with projected
+  content is unaffected.
+
+### Fixed
+
+- **Leading is a character axis too: `--gog-line-height-none|tight|snug|normal|relaxed|loose`.**
+  Twenty component tokens held a bare number — seven of them the same `1.4` — so roomier text
+  meant finding and re-listing every one. Same values, nothing moves. `gog-panel`'s heading keeps
+  its own `1.25`, off the scale on purpose the way an 11px chip is off the type scale, and rule G
+  covers the family so the next bare number fails the build.
+
+- **`--gog-control-clear-icon-ratio`: one number, not five.** The clear (×) button's glyph is the
+  same part in `gog-autocomplete`, `gog-datepicker`, `gog-inputfield`, `gog-multiselect` and
+  `gog-select`, and each carried its own `0.7`. `gog-textarea` keeps its own `1`: its clear
+  button sits in a corner rather than in the field's icon row, which is a different problem and
+  a different number.
+
+- **Weight is a character axis now: `--gog-font-weight-medium|semibold|bold|heavy`.** Fifteen
+  component tokens held a bare `500`/`600`/`700`/`900`, so a house style that wanted lighter
+  chrome had to find and re-list every one — 21.7.0's character layer unified casing and tracking
+  and stopped short of this. Same values, nothing moves; what changes is that four tokens now
+  reach all fifteen. Four steps because four are used: no `normal`, since nothing in the library
+  paints 400 and an unused token is API nobody asked for. `check-tokens` rule G covers the family,
+  so the next bare number fails the build.
+
+- **`--gog-z-base`: the whole stacking order moves as one.** `badge`, `toast`, `dropdown`
+  (which dialogs and menus read), `tooltip` and the blocking `spinner-overlay` were five
+  unrelated literals — 1, 100, 300, 400, 8000 — so an app that had to lift the library above its
+  own chrome edited five tokens and hoped it had found them all. Each is `calc(var(--gog-z-base) +
+  N)` now: the numbers are unchanged at `--gog-z-base: 0`, and setting it to 10000 gives
+  10001/10100/10300/10400/18000 — the same order, one number. The gaps are deliberate, so an app
+  can still slot its own element between two library layers.
+
+- **One disabled level, not four.** `--gog-disabled-opacity` (0.4) is read by nine components,
+  while `gog-accordion`, the `gog-select` and `gog-multiselect` option rows (0.5) and `gog-chip`
+  (0.55) each carried their own. One state should not have four opinions, and the three
+  stragglers were invisible to rule G by construction — it flags a literal only when the value
+  *matches* the token's. **This is a visual change**: those four fade slightly further now.
+
+- **The type scale gained the step it was missing: `--gog-text-slg` (1.25rem).** `gog-button` and
+  the field controls both needed a size for their `slg` variant, the scale went straight from
+  1.125rem to 1.5rem, and both wrote `1.25rem` as a literal — the same value chosen twice,
+  independently, which is a missing rung rather than two opinions. Both read the token now, and
+  rule G lists it, so the next component that wants 20px type cannot re-invent it. Named for the
+  control size it serves rather than continuing the t-shirt run, because that is what asked for
+  it.
+
+- **Sixteen component font sizes now read the type scale, and rule G covers it.** A theme that
+  retuned `--gog-text-*` moved most of the library and left `gog-button`, `gog-chip`, `gog-tag`,
+  the dialog's close button, the toast's action and close, and the toggle's `lg` state label
+  behind — each held a literal that was byte-for-byte a scale step (`--gog-button-md-font-size:
+  1rem` sitting beside `--gog-text-md: 1rem`). Same values, so nothing moves in any theme; the
+  difference is that retuning the scale now reaches them.
+
+  `check-tokens` rule G covered radii, strokes, casing and tracking but **not** font size, which
+  is how sixteen of them accumulated. It does now, and the thirteen remaining literals are right
+  to be literals: five are the accordion chevron's px ramp, and eight are off the scale on
+  purpose — `slg` is 1.25rem in two components because the scale has no step between 1.125 and
+  1.5, an 11px chip sits deliberately below `xs`, and the toggle's state label has its own
+  four-step micro-ramp. Rule G flags only an exact match, which is precisely what keeps those
+  out of it.
+
+- **Three clear buttons ignored the theme's corner radius.** `--gog-input-clear-radius`,
+  `--gog-select-clear-radius` and `--gog-multiselect-clear-radius` were a flat `2px`, so a theme
+  that set `--gog-radius` moved every corner in the library except these. They are
+  `calc(var(--gog-radius) / 4)` now: identical at the default 8px, so nothing moves in `light` or
+  `dark` — but `bevel`, whose whole identity is square corners (`--gog-radius: 0`), had three
+  quietly rounded controls and now does not.
+
+  Found by counting rather than by looking: of 47 radius tokens, 30 already derived from
+  `--gog-radius`, 8 are pills or circles (a shape, not a corner size), 5 are deliberately flat,
+  and these 3 were the remainder. `check-tokens` rule G could not have caught them — it flags a
+  literal only when its value *equals* a character token's, which is what keeps a pill's `999px`
+  from being called drift, and is exactly why a small arbitrary number is the shape of drift it
+  cannot see. `gog-toast` and `gog-accordion` keep their flat corners, on the user's call: those
+  are a chosen shape.
+
+- **Error text was below WCAG AA in four themes.** `--gog-danger-color` is what every
+  `--gog-<block>-error-color` resolves to, so it is the colour a validation message is printed in
+  — text, needing 4.5:1, not the 3:1 a status accent gets away with. It cleared neither ground in
+  `one-light` (3.51:1 / 3.67:1), `primeng` (3.60 / 3.76), `one-dark` (4.38) or `slate` (4.46).
+  Each preset's red moves the smallest distance that clears 4.6:1 on both the page and a card:
+  `#e45649`→`#c2493e`, `#ef4444`→`#ce3a3a`, `#e06c75`→`#e2737c`, `#dc2626`→`#d82525`.
+  `check:contrast` gained the pair in the same change — it had none for `danger` at all, which is
+  why a field error nobody could read was invisible to it. Found by pointing the new
+  `check:app-contrast` at `ui-showcase`, which renders the library from source.
+
+- **A toggle button now looks toggled.** 21.8.0 taught `gog-button` to forward `aria-pressed`,
+  and nothing in the library styled it — so a toggle could announce itself as on to a screen
+  reader while looking identical to an off one, which is WCAG 1.4.1 from the other side and
+  exactly the reason `docs/backlog.md` gives for *not* forwarding `aria-pressed` to `gog-chip`.
+  `aria-pressed="true"` (and `"mixed"`) now draws an inset ring: new
+  `--gog-button-<variant>-toggled-shadow`, with `--gog-button-toggled-shadow` as the per-instance
+  override. A ring rather than a fill because `:hover` and `:active` already own the background —
+  a toggled button that lost its state the moment the pointer arrived would be the same bug one
+  layer down. It keys off the attribute, not an input, so `[gogButton]` on your own element gets
+  it from the `aria-pressed` you already wrote there.
+
+- **A button pressed with animations off now shows that it was pressed.** `:active` was a
+  `transform: scale()` and nothing else, and the `prefers-reduced-motion: reduce` block switched
+  that transform off — so the reader most likely to need the feedback got none at all. The ripple
+  did not cover it either: it is off by default, and it is deliberately suppressed under reduced
+  motion because it genuinely is decoration. `:active` now also deepens the button's background,
+  one step past its own hover so a press is distinguishable while hovering, and reduced motion
+  drops only the movement. New per-variant `--gog-button-<variant>-press-bg`/`-press-color`
+  tokens and the usual `--gog-button-press-bg`/`-press-color` instance overrides. **Ghost presses
+  to a filled `--gog-accent-dim`, like outline, rather than to a wash** — checked across all 11
+  themes, and a wash cannot work there: ghost's own *label* is the accent, so tinting its ground
+  with the accent walks the two together, and a 24% wash put the label under 4.5:1 in seven
+  themes. A filled press moves the label to `--gog-accent-text-color`, the pair `check:contrast`
+  already gates, so no future theme can quietly break it. Reduced motion must remove the animation, not the
+  information — the same rule the toast countdown was fixed under in 21.7.1.
+
+  The family is spelled `press`, not `active`, because `active` already means two different
+  things in this library — `--gog-tabs-active-color` is the *selected* tab, while
+  `--gog-scroll-thumb-active-bg` is the thumb being dragged. One name, one meaning. The shipped
+  `--gog-button-active-scale` keeps its spelling: renaming a token consumers already override
+  needs a deprecation cycle, and this is a patch.
+
+- **`check:contrast` now measures composited washes, and found 24 more failures.** The script
+  compared palette hexes, so any pair where one side was a `color-mix()` wash was invisible to it
+  — which is both of the button failures above, found by hand instead. New `scripts/token-color.mjs`
+  resolves a component token the way a browser does (the theme's own block, then the `@supports`
+  mixed layer, then the derived layer, then the literals), composites it over the ground that
+  component actually sits on, and the check measures the label against that. 385 pairs across the
+  11 themes, up from 143.
+
+  It then grew a second half that needs no table at all: `collectStatePairs` reads the compiled
+  stylesheets and checks every label/ground pair the rules themselves state, so a component added
+  later is covered without anyone remembering to list it. **627 pairs** in total now. That sweep
+  found one further real failure across the whole library — `gog-autocomplete`'s **selected
+  option** label, `--gog-accent-color` on its own tint, 4.12:1 in light (and `--gog-accent-dim` is
+  worse again, 3.77:1 in one-dark). It is `--gog-text-color` now; the tint and `aria-selected`
+  still mark the row, and `gog-select` keeps its accent label because its selected option has no
+  tint behind it. Icons are held to 3:1 rather than 4.5:1, which is what keeps a spin-button glyph
+  and a panel chevron — 4.35:1 and 4.40:1, both correct — from being "fixed" into near-black.
+
+  Its first run failed 24 of them, all real, and all fixed here:
+
+  - **A pressed tab's label leaves the muted tone.** A resting tab is deliberately
+    `--gog-muted-text-color`, which has no headroom to spend on a tinted ground: 3.24:1 in
+    one-dark and under 4.5 in six more. New `--gog-tabs-press-color`, the full text colour — which
+    is what pressing a tab is about to make it anyway.
+  - **An accordion header's label stops turning accent while hovered or held.** It took
+    `--gog-accordion-accent-color` on an accent-tinted strip: 3.61:1 in light, 3.79:1 in one-light,
+    4.09:1 in ledger, and worse once the press deepened the tint. New `--gog-accordion-hover-color`,
+    defaulting to the header's own text colour; the lift is carried by the background alone. The
+    same trade as the ghost button's hover, for the same reason.
+  - **The press wash is 20%, not 22%.** Measured rather than chosen: at 21% one-dark's mid-grey
+    text falls under 4.5:1 on three of the surfaces. 20% is the strongest wash that clears AA in
+    every theme, and it is still a clear step past the 10-12% hover.
+
+- **A ghost button's label was under WCAG AA on its own hover, in three themes.** `light`
+  3.94:1, `primeng` 4.18:1, `one-light` 4.22:1. The variant's resting label *is*
+  `--gog-accent-color` and its hover tints the ground with the same accent, so the two walked
+  toward each other. **No background fixes it**, which is why this took a sweep rather than a
+  nudge: a half-strength wash (4.28), a neutral `--gog-hover-color` (4.15), a text scrim (3.91)
+  and an accent-dim wash (3.96) were all measured across the 11 themes, and `light` fails every
+  one — `--gog-accent-color` as *text* on that theme's background is 4.60:1 to begin with, so
+  there is no headroom to spend on any ground at all. The label now becomes `--gog-text-color`
+  while hovered, which clears 5.29:1 at worst (one-dark) and leaves the wash untouched, so the
+  hover stays the subtle one this variant is documented to have. Ghost's three states now read
+  transparent → tinted → filled, with a label chosen for each ground rather than one label
+  hoping to survive three.
+
+- **`bevel` had no accent ramp, so its buttons could not show a press.** That preset declared
+  `--gog-accent-dim: #000080`, byte-identical to its `--gog-accent-color`. Harmless while `dim`
+  was only a field border; once it became the pressed fill, a pressed button in `bevel` painted
+  itself the colour it already was. Nothing failed — the token existed, resolved and passed every
+  contrast pair. It is now `#00005c`, and **`check-tokens` rule I was widened from the surface
+  tiers to any ramp**, so a theme whose rest/hover/press tones collapse into each other fails the
+  build instead of shipping a state nobody can see. Found by sweeping all 11 themes rather than by
+  the check that now catches it.
+
+- **The other nine pressable surfaces had no press feedback either — now eight of them do.**
+  `.gog-btn:active` turned out to be the *only* `:active` rule in the library. `gogMenuItem`,
+  `gog-chip`, `gog-tabs` headers, `gog-accordion` headers, `gog-button-toggle-group` options and
+  the `gog-select` / `gog-multiselect` / `gog-autocomplete` option rows all acknowledged a press
+  through the ripple alone — which is off by default and suppressed under reduced motion — so a
+  default-configured app confirmed a press nowhere at all. Each now paints
+  `--gog-<block>-press-bg`: a wash roughly double the 10-12% one its own hover uses, in the same
+  ingredient, with a flat `--gog-border-color` for browsers without `color-mix()`. Two of them
+  are not that shape and say so in place: a `gog-tabs` header paints no background in any other
+  state (its hover moves the label colour only), and a *selected* button-toggle option is already
+  filled, so it deepens to `--gog-accent-dim` the way the filled button variants do.
+
+  **`gogCollapsibleTrigger` is deliberately not in that list.** It is the consumer's own element
+  and the library paints nothing on it — no background at rest, none on hover, only a cursor and
+  a disabled state. A press colour there would be the library inventing a look for markup it does
+  not own, and inventing it for one state out of three. The same reasoning `docs/ripple.md`
+  records for `gogCardLink` and `gog-table` rows.
+
+  The three option rows' press rules are guarded against the disabled modifier; their **hover**
+  rules are not, and were left alone — a disabled option lighting up under the pointer is a
+  separate decision from this one, and it is filed rather than folded in.
+
+- **A disabled option no longer lights up under the pointer, and no longer ripples.** Two
+  separate holes in the same place. `.gog-select__option:hover` and `.gog-ms__option:hover`
+  carried no disabled guard, so a row that cannot be chosen took the same hover background as one
+  that can — only its opacity and its cursor disagreed, and neither is what a hover is read for.
+  `gog-autocomplete` already had this right (`:not([aria-disabled='true'])`), which is where the
+  fix was copied from. And all **three** wired `gogRipple` with `[rippleDisabled]="!rippleEnabled()"`,
+  taking no account of the option's own state: with the ripple switched on app-wide, a disabled
+  row answered a press with a wave. The options are rendered `aria-disabled`, not `disabled`, so
+  nothing else was stopping it. Same argument the library already applied to a non-interactive
+  `gog-chip`: a wave is a promise, and these rows cannot keep it.
+
+- **The outline button's label was unreadable while hovered, in every shipped theme.**
+  `--gog-button-outline-hover-color` resolved to `--gog-primary-color`, the colour of text on the
+  *page*, while the hover fill is the accent — pale parchment on bright amber in `dark` (1.41:1),
+  light grey on blue in `one-dark` (1.11:1), and failing WCAG AA in all 11 themes, the best of
+  them `light` at 3.65:1. It now resolves to `--gog-accent-text-color`, the token that means "text
+  on an accent fill" and the one both filled variants already used. Found while adding the state
+  above, which would have copied the same mistake into `:active`.
+
+- **`check:contrast` gained the pair that hid both.** The script had no pair for a label on the
+  accent *fill* other than `accentText/accent`, so neither the outline label nor the new held
+  state was covered. `accentText/accentDim(active)` is now checked at 4.5:1, and it immediately
+  failed one theme: `one-dark`'s `--gog-accent-dim` moved from `#4b8fca` to `#5399d6` (4.05:1 →
+  4.59:1). That token had only ever been a field border, which is gated at 3:1; making it a fill
+  under a label is what raised the bar. The nudge moves it toward this palette's own `#61afef`,
+  so unlike 21.7.0's two comment-colour corrections it costs no fidelity.
+
+- **Ten pieces of geometry ignored `--gog-density`, and nine of the eleven themes set it.**
+  `terminal` runs at 0.85, `one-dark`/`one-light`/`bevel`/`ledger` at 0.9, `primeng` at 0.95,
+  `slate` at 1.05, `material`/`parchment` at 1.1 — so in every one of them these ten stayed at
+  the pixel they were typed as while everything around them moved. The clearest case is the gap
+  between a dropdown and its panel: `gog-autocomplete` and `gog-datepicker` read `--gog-space-2`,
+  while `gog-select` and `gog-multiselect` restated `2px`, so in `terminal` two of the four
+  panels drew closer to their field and two did not. Also converted: `--gog-menu-offset` (which
+  sat between `--gog-menu-padding` and `--gog-menu-gap`, both already reading the scale),
+  `--gog-input-clear-inset` (the textarea's clear button — the other four clearable fields place
+  their chrome from `--gog-control-icon-offset`), the two error-line offsets, the toggle's
+  in-track wording clearance, the badge's overhang, and the calendar's header and time-row
+  margins. Each now reads its scale step, so all ten render exactly as before at the default
+  density and follow the theme everywhere else.
+
+- **Four focus rings did not follow `--gog-focus-ring-offset`.** `gog-button-toggle` restated
+  its `2px` on the line directly after reading `--gog-focus-ring-width` from the foundation;
+  `gog-button` used `3px`; `gog-calendar` and `gog-tabs` used `-2px` to sit the ring inside a
+  cell, because both pack their cells edge to edge and an outward ring lands on the neighbour.
+  All four now derive from the foundation token — `var(…)`, `calc(… + 1px)` and `calc(… * -1)` —
+  so a theme that moves the ring moves them with it, and the two negative values now say in the
+  file why they are negative. No rendered value changes.
+
+- **`check-tokens` rule H only covered two of the six families that hold a spacing number.**
+  The density check was written for `-padding` and `-gap`, the two the density work had just
+  converted, and `-offset`, `-inset` and `-margin` went unwatched for three releases — which is
+  where all ten literals above were hiding. The name filter now covers all six, and exempts the
+  lengths that match a scale step by coincidence rather than by meaning: every
+  `*-focus-ring-offset` (an accessibility affordance, which a compact theme must not shrink, and
+  which a component should answer by reading the foundation ring rather than a spacing step),
+  plus the scrollbar and toggle thumb insets, both fitted to a track whose own width is a fixed
+  pixel value. The script's header now also lists rules H and I, which had been in it unlisted
+  since they were added.
+
+- **`gogBadge`'s status variants failed WCAG AA in four themes, and had since they shipped.** A
+  status badge paints `--gog-<status>-color` and labelled it `--gog-accent-text-color`, which on
+  a light theme is white: `material`'s amber measured **1.97:1**, `primeng`'s green 2.28:1, and
+  `slate` and `one-light` failed on all three of success/warning/info — 11 pairs in total.
+  `danger` passed everywhere, which is the tell: a danger pair was added to `check:contrast` on
+  2026-09-03 and the palettes were tuned to it, while the other three statuses had never been
+  measured against anything.
+
+  Half the fix costs no fidelity: `material` puts near-black on its amber (8.69:1) and `primeng`
+  does the same on all three of Aura's bright hues (6.44–8.31:1), which is what both design
+  systems do themselves. The other half had no label to pick — neither white nor the theme's own
+  ink reached AA — so the hue moved instead, one step down each theme's own ramp: `slate`'s three
+  to Tailwind's 700s, `material`'s blue to Light Blue 800, and `one-light`'s three darkened, the
+  same trade that theme already made on its accent and muted tokens in 21.7.0.
+
+  **The reason no check caught it generalises past the badge.** `check:contrast`'s automatic
+  sweep pairs a rule that sets `color` with the `background-color` beside it; a variant class
+  sets neither, only `--gog-badge-variant-bg`/`-color` for the base rule to read. Every variant
+  of every component is written that way, so the sweep had been reporting ~180 passing states
+  without looking at one of them. Four explicit badge pairs close it for this component; the
+  general fix is filed in `docs/backlog.md`.
+
+- **Two fields put their error line 2px lower than the other six.** Every control that renders an
+  error — `gog-inputfield`, `gog-textarea`, `gog-select`, `gog-multiselect`, `gog-autocomplete`,
+  `gog-datepicker`, `gog-radio-group`, `gog-slider` — is a flex column whose own gap already
+  separates the error from the field, the same gap that separates the label from it. Two of them
+  then added `margin-top: 2px` on top: measured in a browser, `gog-inputfield` and
+  `gog-multiselect` sat at 6px while `gog-select`, `gog-autocomplete` and `gog-datepicker` sat at
+  4px from the identical gap. In one form, side by side, the six did not line up.
+  `--gog-input-error-offset` and `--gog-multiselect-error-offset` now default to `0`, so one
+  mechanism spaces the error line everywhere; both tokens stay, and setting one still pushes that
+  field's error further than the rest.
+
 ## [21.8.0] - 03.09.2026
 
 ### Added