@guildofgleks/ui 21.7.2 → 21.9.0

package/CHANGELOG.md

@@ -4,6 +4,413 @@ 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
+
+- **`gog-button` forwards ARIA state and relationships: `ariaPressed`, `ariaExpanded`,
+  `ariaControls`, `ariaHasPopup`.** The component hides the real `<button>`, so
+  `<gog-button [attr.aria-pressed]="on()">` puts the attribute on the custom element host —
+  which has no role — and assistive tech never sees it. It compiles, throws nothing, looks
+  right, and silently ships a toggle button that is not a toggle button; `ariaLabel` already
+  existed for exactly this reason and was the only one. `null` (the default) omits the
+  attribute, while `false` is forwarded as `aria-pressed="false"`/`aria-expanded="false"`,
+  which is what an off toggle or a closed disclosure must say. New exported type
+  `GogAriaHasPopup`. The `[gogButton]` directive needs none of this — it styles an element you
+  own, so write the attributes there directly.
+
+### Fixed
+
+- **`GOG_CONFIG`'s own documentation now names every component that reads each key.** The
+  `GogGlobalConfig` JSDoc — the closest thing the library has to a source of truth for which
+  component honours which setting, and what your editor shows you on hover — under-reported four
+  keys. `control.size` did not mention `gog-button-toggle-group`, `gog-toggle`, `gog-autocomplete`
+  or `gog-datepicker`; `control.errorDisplay`, `control.clearable` and `floatLabel` did not
+  mention `gog-autocomplete` or `gog-datepicker`; and `dropdown` claimed to apply to
+  `gog-select`/`gog-multiselect` as a block, when `appendToBody`/`direction` also reach
+  `gog-autocomplete` and `gog-datepicker` while `filter`/`filterPosition` genuinely do not.
+  `AGENTS.md`'s config table was closer but stated outright that `gog-toggle` does **not** take
+  `control.size`, which it does. No behaviour change — every one of these components already
+  honoured the setting; only the documentation was wrong, in the direction of telling you a
+  setting would not work when it does.
+
 ## [21.7.2] - 30.08.2026
 
 ### Fixed

package/README.md

@@ -168,6 +168,16 @@ variant and size classes:
 > "what a raised surface looks like here". Change one and every raised surface follows, which is
 > the intent; the rest of `--gog-panel-*` belongs to the component alone.
 
+**A status colour is three tokens, not one.** `--gog-danger-color` and its three siblings are
+fills, and a fill needs a label that reads on it and a direction to deepen in — so each also has
+`--gog-<status>-text-color` (the label; defaults to the accent's, state it only when your hue
+disagrees) and `--gog-<status>-shade` (which way hover and press move; defaults to the page's ink,
+and should be the opposite when your label *is* the ink). Setting a status colour alone and
+leaving those at their defaults is how a bright amber ends up under white text: it measured 1.97:1
+in one of this package's own presets before 21.9.0. `gogBadge` and `gog-button`'s `severity` read
+the label; the button also reads the shade. `gog-tag` derives its own pair by mixing and
+`gog-progressbar` paints no label on its bar, so neither needs them.
+
 Every group and token name is in **[`TOKENS.md`](./TOKENS.md)**, generated from `theme.css` so it
 cannot drift, and available at runtime as `GOG_TOKEN_GROUPS`.
 
@@ -263,9 +273,20 @@ provideGogConfig({
 ```
 
 Keys: `control`, `dropdown`, `floatLabel`, `datepicker`, `autocomplete`, `inputfield`, `textarea`,
-`tooltip`, `scroll`, `button`, `ripple`, `paginator`, `toast`, `theme`, `labels`. An instance's own
-input always wins, and providing the config again lower in the injector tree layers onto the
-parent rather than replacing it.
+`tooltip`, `scroll`, `button`, `ripple`, `spinner`, `paginator`, `toast`, `theme`, `labels`. An
+instance's own input always wins, and providing the config again lower in the injector tree layers
+onto the parent rather than replacing it.
+
+`spinner` is the one key that takes a **component** rather than a value:
+
+```ts
+provideGogConfig({ spinner: { component: HouseLoader } });
+```
+
+That renders your loader wherever the library draws a spinner — including the two places no input
+could reach, since `gog-button` and `gog-autocomplete` render their own and expose nothing for it.
+It keeps the library's sizing, overlay behaviour, `role="status"` and accessible name; only the
+visual is yours.
 
 `ripple` is the one visual default that is not a token, and the exception is deliberate:
 `--gog-ripple-opacity: 0` would hide the wash but still pay for the DOM node, the listeners and