@guildofgleks/ui 21.6.1 → 21.7.0

package/AGENTS.md

@@ -5,12 +5,13 @@ 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.6.1`**. 21.5.0 removed a batch
-of deprecated API — see **Removed in 21.5.0** near the end of this file, which exists so code
-written against 21.4.x can be migrated — and `CHANGELOG.md` has the rest. `README.md` covers the
-same ground at a higher level — install, setup, theming, global configuration — and is accurate;
-this file goes further, into per-component input tables, and is the one to trust for exact names,
-types and defaults.
+Everything below reflects the library's actual source as of **`21.7.0`**. 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
+higher level — install, setup, theming, global configuration — and is accurate; this file goes
+further, into per-component input tables, and is the one to trust for exact names, types and
+defaults.
 
 > **Maintainers:** this file ships inside the npm package and is the API reference an agent reads
 > while writing code against it, so a stale table here becomes wrong code in someone else's app —
@@ -166,30 +167,66 @@ exist.
 
 ## Theming
 
-Full model is in `README.md`'s Theming section and `theming.md`; short version:
+Full model is in `README.md`'s Theming section; short version:
 
 - Every visual value (color, spacing, radius, shadow, duration) is a `--gog-*` CSS custom
   property, layered **foundation** (`--gog-accent-color`, `--gog-space-md`, …, restyles
   everything) → **component** (`--gog-button-primary-bg`, …, one block per component, named after
   the component's own element) → **instance** (`--gog-button-bg`, …, deliberately undeclared
   escape hatch for one element).
+- **Foundation includes a small character layer** (since 21.7.0, `docs/themes.md` iteration 1):
+  `--gog-radius` (corner rounding), `--gog-control-border-*`/`--gog-panel-border-*`/`--gog-border-*`
+  (border weight — form fields, raised surfaces, everything smaller and inline, respectively),
+  `--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.
+- **`--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.
 - **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-*`
-  still resolve and are removed in 21.7.0 — don't write new code with them. The exception is
-  `--gog-input-*`, which is not an abbreviation: it is the shared text-field block that
-  `gog-inputfield` and `gog-textarea` both render, and it keeps that name.
+  were removed in 21.7.0 — if you're reading a codebase or an example that still uses one, rename
+  it; it no longer resolves. The exception is `--gog-input-*`, which is not an abbreviation: it is
+  the shared text-field block that `gog-inputfield` and `gog-textarea` both render, and it keeps
+  that name.
 - **The package does not need the app's `box-sizing` reset** (since 21.6.0): `utilities.css`
   sets `border-box` on every element carrying a `gog-*` class, including the ones the library
   puts on a consumer's own element. Do not add a reset "so the components line up" — they
   already do, and a `* { box-sizing: content-box }` in an app is the only thing that undoes it.
 - Theme switch is a `data-theme` attribute, usually on `<html>`, toggled through the
   `ThemeService` (`inject(ThemeService).setTheme('dark')` / `.toggleTheme()` / `.theme` signal).
-  Ships `light` and `dark`. Three more importable presets: `slate`, `one-dark`, `one-light`
-  (`@guildofgleks/ui/styles/presets/<name>.css`).
+  Ships `light` and `dark`, plus nine importable presets at
+  `@guildofgleks/ui/styles/presets/<name>.css`. **All nine set palette and character** (since
+  21.7.0 — before it, three were palette-only, which made them recoloured defaults):
+
+  | Preset                 | Radius | Density | Identity                                         |
+  | ---------------------- | ------ | ------- | ------------------------------------------------ |
+  | `slate`                | 12px   | 1.05    | soft modern — hairline borders, roomy            |
+  | `one-dark`/`one-light` | 4px    | 0.9     | editor chrome; identical character, two tones    |
+  | `material`             | 4px    | 1.1     | Material Design 3, pill buttons                  |
+  | `primeng`              | 6px    | 0.95    | PrimeNG Aura                                     |
+  | `ledger`               | 0      | 0.9     | administrative — hard offset shadow, no motion   |
+  | `terminal`             | 0      | 0.85    | green phosphor, monospaced throughout, no motion |
+  | `bevel`                | 0      | 0.9     | early-web desktop — `outset`/`inset` borders     |
+  | `parchment`            | 0      | 1.1     | ink on paper — old-style serif, oxblood          |
+
+  `material`, `primeng` and `bevel` also set a few genuinely per-component things the character
+  layer has no vocabulary for (a pill button, a table's header font, a button bevel that has to
+  disagree with a field's); see their own file headers.
+
+- **A preset never makes a network request.** Each sets a font _stack_ resolving to a real system
+  face. Where a webfont is worth offering, it is a separate opt-in file — `terminal.fonts.css`
+  (IBM Plex Mono), `parchment.fonts.css` (EB Garamond) — imported **after** the preset, since it
+  re-points the same tokens and later wins. Do not add an `@import url(…)` to a preset itself; put
+  it in a companion file, or the import becomes a download nobody asked for.
 - Restyle one instance without touching a theme: `<gog-button style="--gog-button-bg: #ff4edb">`.
-- Build a custom theme by declaring a palette against a new `data-theme` value (see
-  `theming.md` for the full worked example) — component tokens re-derive automatically, you
-  don't restate them.
+- Build a custom theme by declaring a palette **and a character** against a new `data-theme`
+  value (see `README.md`'s Theming section for the full worked example) — component tokens
+  re-derive automatically, you don't restate them.
 
 ## Right-to-left
 
@@ -253,40 +290,39 @@ in English sets these once rather than on every control:
 ```ts
 provideGogConfig({
   labels: {
-    clear: 'Очистить', // inputfield / textarea clear button
-    clearSelection: 'Очистить выбор', // select / multiselect / autocomplete
-    clearDate: 'Очистить дату', // datepicker
-    selectAll: 'Выбрать все', // multiselect panel
-    clearAll: 'Очистить', // multiselect panel
-    increment: 'Увеличить', // number spin buttons
-    decrement: 'Уменьшить',
-    showPassword: 'Показать пароль',
-    hidePassword: 'Скрыть пароль',
-    closeDialog: 'Закрыть',
-    closeToast: 'Закрыть',
-    pagination: 'Навигация по страницам',
-    previousPage: 'Предыдущая страница',
-    nextPage: 'Следующая страница',
-    openCalendar: 'Открыть календарь',
-    togglePanel: 'Свернуть раздел', // gog-panel's toggle, only when it has no heading
-    rowsPerPage: 'Строк на странице', // gog-paginator's size select
-    total: 'Всего', // gog-table's row-count label
-    tablePagination: 'Навигация по таблице',
-    selectRow: 'Выбрать строку',
-    selectAllRows: 'Выбрать все строки на странице',
-    today: 'Сегодня',
-    thisMonth: 'Текущий месяц',
-    previousMonth: 'Предыдущий месяц',
-    nextMonth: 'Следующий месяц',
-    previousYear: 'Предыдущий год',
-    nextYear: 'Следующий год',
-    hours: 'Часы',
-    minutes: 'Минуты',
-    seconds: 'Секунды',
+    clear: 'Löschen', // inputfield / textarea clear button
+    clearSelection: 'Auswahl löschen', // select / multiselect / autocomplete
+    clearDate: 'Datum löschen', // datepicker
+    selectAll: 'Alle auswählen', // multiselect panel
+    clearAll: 'Alle löschen', // multiselect panel
+    increment: 'Erhöhen', // number spin buttons
+    decrement: 'Verringern',
+    showPassword: 'Passwort anzeigen',
+    hidePassword: 'Passwort verbergen',
+    closeDialog: 'Schließen',
+    closeToast: 'Schließen',
+    pagination: 'Seitennavigation',
+    previousPage: 'Vorherige Seite',
+    nextPage: 'Nächste Seite',
+    openCalendar: 'Kalender öffnen',
+    togglePanel: 'Bereich umschalten', // gog-panel's toggle, only when it has no heading
+    rowsPerPage: 'Zeilen pro Seite', // gog-paginator's size select
+    total: 'Gesamt', // gog-table's row-count label
+    tablePagination: 'Tabellennavigation',
+    selectRow: 'Zeile auswählen',
+    selectAllRows: 'Alle Zeilen auswählen',
+    today: 'Heute',
+    thisMonth: 'Aktueller Monat',
+    previousMonth: 'Vorheriger Monat',
+    nextMonth: 'Nächster Monat',
+    previousYear: 'Vorheriges Jahr',
+    nextYear: 'Nächstes Jahr',
+    hours: 'Stunden',
+    minutes: 'Minuten',
+    seconds: 'Sekunden',
     // The one non-string field: it interpolates the page number, and word order and
     // agreement around a number vary by language, so it takes a formatter.
-    page: (page, isCurrent) =>
-      isCurrent ? `Страница ${page}, текущая` : `Перейти на страницу ${page}`,
+    page: (page, isCurrent) => (isCurrent ? `Seite ${page}, aktuell` : `Zu Seite ${page} wechseln`),
   },
 });
 ```
@@ -322,7 +358,7 @@ provideGogConfig({
     followSystem: true, // open in the OS prefers-color-scheme, and keep following it
     // until the app calls setTheme/toggleTheme
     lightTheme: 'light', // the two names followSystem maps to and toggleTheme alternates
-    darkTheme: 'cyberpunk', // between
+    darkTheme: 'one-dark', // between
     defaultTheme: 'light', // used when nothing else decides
   },
 });
@@ -370,10 +406,31 @@ async confirmDelete(): Promise<void> {
 }
 ```
 
-`DialogConfig`: `{ title?, component, data?, modal? (default true), closable?, draggable?, closeIconName?, closeIconTemplate?, width?, maxWidth?, role? ('dialog' default | 'alertdialog'), zIndex? }`.
-`open()` returns `{ close(result?), afterClosed: Promise<TResult | undefined> }`. Also:
+`DialogConfig<TData>`: `{ title?, component, data?: TData, modal? (default true), closable?, draggable?, closeIconName?, closeIconTemplate?, width?, maxWidth?, role? ('dialog' default | 'alertdialog'), zIndex? }`.
+`open<TResult, TData>()` returns `{ close(result?), afterClosed: Promise<TResult | undefined> }`. Also:
 `closeAll(result?)`, `updatePosition(id, offsetX, offsetY)` (for `draggable` dialogs).
 
+**`open<TResult, TData>()` type-checks `data` against `TData` when you supply both type
+arguments** — supplying only `TResult` (the common case above) leaves `TData` as `unknown`,
+exactly as before:
+
+```ts
+interface EditUserData {
+  userId: string;
+}
+
+const handle = this.dialogService.open<{ saved: boolean }, EditUserData>({
+  component: EditDialogComponent,
+  data: { userId: user.id }, // checked against EditUserData here
+});
+```
+
+This checks only the call site. `EditDialogComponent` still reads its data via `inject(DIALOG_DATA)`
+— an `InjectionToken<unknown>` shared by every dialog, so it still needs its own cast
+(`inject<EditUserData>(DIALOG_DATA)`, shown below). Angular's DI has no way to carry a
+per-call-site type through one shared token, so the receiving half of the round trip is still on
+trust — this closes only the half that can be closed.
+
 The library ships a ready-made `ConfirmationDialogComponent` for yes/no prompts — pass it as
 `component` with `data: { title, description, confirmText, cancelText }`; it resolves the
 dialog's result to `true`/`false`.
@@ -424,6 +481,13 @@ Outputs: `gogClick: MouseEvent`.
 **`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.
 
+**Use `(gogClick)`, never `(click)`, on `gog-button`.** The click handler that drives `debounce`
+and emits `gogClick` is bound on the `<button>` inside the component's own template, not on the
+host — a native click still bubbles up through `<gog-button>`, so a `(click)` listener written
+there fires on every press, silently bypassing the debounce entirely. This is specific to the
+component: `[gogButton]` on your own `<a>`/`<button>` has no debounce to bypass, so `(click)` on
+it works exactly as written.
+
 ```html
 <gog-button variant="primary" [loading]="saving()" (gogClick)="save()">Save</gog-button>
 <gog-button variant="ghost" ariaLabel="Close" (gogClick)="close()"
@@ -1626,17 +1690,33 @@ Everything the package currently deprecates, as data:
 ```ts
 import { GOG_DEPRECATIONS, type GogDeprecation } from '@guildofgleks/ui';
 
-GOG_DEPRECATIONS.filter((entry) => entry.removedIn === '21.7.0');
-// { kind: 'token', name: '--gog-btn-bg', replacement: '--gog-button-bg',
-//   since: '21.5.0', sinceDate: '2026-08-19', removedIn: '21.7.0' }
+GOG_DEPRECATIONS; // []
 ```
 
 `kind` is `'symbol'` for an export or input and `'token'` for a `--gog-*` custom property. The
 list is generated from the library's source — tags for symbols, stylesheets for tokens — so it
 matches what actually still resolves in the version you installed.
 
-**In 21.5.0 it holds 154 tokens and no symbols.** Nothing in the TypeScript API is deprecated
-right now; the three abbreviated token prefixes are, until 21.7.0.
+**As of 21.7.0 the list is empty on both halves.** Nothing in the TypeScript API is deprecated, and
+the three abbreviated token prefixes that used to fill the token half are gone rather than
+deprecated — see the removal table below. An empty list here means exactly that: nothing to
+migrate away from right now.
+
+## Removed in 21.7.0
+
+**Nothing in this table exists any more.** Three CSS custom-property prefixes, abbreviations of a
+component's own name, are gone — each was honoured only as a fallback the spelled-out token wrapped
+(`--gog-button-x: var(--gog-btn-x, value)`), never declared on its own.
+
+| Removed           | Replacement                   |
+| ----------------- | ----------------------------- |
+| `--gog-btn-*`     | `--gog-button-*`              |
+| `--gog-ms-*`      | `--gog-multiselect-*`         |
+| `--gog-confirm-*` | `--gog-confirmation-dialog-*` |
+
+A consumer's CSS that still sets one of the left-hand names doesn't fail their build — an
+unresolved `var()` just stops matching anything, silently. If a themed surface stopped picking up
+an override after upgrading to 21.7.0, this table is the first thing to check.
 
 ## Removed in 21.5.0
 

package/CHANGELOG.md

@@ -4,6 +4,165 @@ 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.7.0] - 29.08.2026
+
+### Added
+
+- **Every shipped theme now meets WCAG AA, and the check runs in CI.** Nine gated failures across
+  five palettes were fixed: muted text in `slate`, `one-dark` and `one-light`; the filled button's
+  label, at rest and on hover, in `light`, `primeng`, `one-light` and `slate`. `check:contrast` is
+  now a CI step — it was deliberately kept out while any finding was open, because a permanently
+  red step over a known condition teaches everyone to ignore CI.
+
+  **`one-dark` and `one-light` changed colour, and that is a trade you may notice.** They
+  reproduce a named editor palette; `#5c6370` is One Dark's own comment colour and reads at 2.32:1
+  on its own background — fine for code, well under AA for UI text. Muted text is now `#9099a8`
+  (dark) and `#6e6f77` (light). If you depended on the exact original hues, set
+  `--gog-muted-text-color` back in your own theme block.
+
+- **Tokens read from TypeScript now resolve `calc()` instead of silently falling back.**
+  `--gog-scroll-thumb-min-size`, `--gog-tooltip-gap`, `--gog-tooltip-z` and `--gog-dropdown-z` were
+  read with `parseFloat`, which returns `NaN` for `calc(...)` — and every caller turned that into
+  its default without a word. **This is a consumer-facing fix:** writing
+  `--gog-scroll-thumb-min-size: calc(2rem + 4px)` in your own theme now works, where before it
+  quietly became 32px. `rem`, `em` and `%` work too.
+
+- **Two WCAG AA contrast fixes, both on a filled button's own label.** The library's own `light`
+  theme: `--gog-accent-color` `#9e6f00` → `#926600` (white on the old value was 4.44:1, under
+  AA's 4.5), and its hover fill `#c88e00` → `#7a5500` — the hover is now _darker_ than the rest
+  state rather than brighter, because gold light enough to read as "a brighter gleam" cannot
+  carry white text at all (the old hover was 2.87:1, worse than the rest state everyone had
+  noticed). `primeng`: moved one step down Aura's own blue ramp, `#3b82f6` → `#2563eb`
+  (500 → 600), rather than inventing a colour outside the palette it reproduces; 3.68:1 → 5.17:1.
+
+  **If you were overriding either token, nothing breaks** — but a theme built on top of `light`'s
+  gold may want to re-check its own derived shades. `check:contrast` now also tests the hover
+  fill, which was never checked before; `one-dark`, `one-light` and `slate` keep their known
+  findings on purpose (see `docs/backlog.md`).
+
+- **Three new presets complete the catalogue: `terminal`, `bevel` and `parchment`.** Retro and
+  Historical, the two families `docs/themes.md` had left unbuilt. `terminal` is green phosphor on
+  an unlit screen, monospaced throughout, square, no motion. `bevel` is the early-web desktop —
+  grey panels, raised buttons, sunken fields, navy — and is the first theme to use
+  `--gog-border-style: outset`/`inset`, which is what the character layer carries a border _style_
+  for. `parchment` is ink on laid paper: old-style serif, oxblood accent, roomy margins. Each is
+  `@import '@guildofgleks/ui/styles/presets/<name>.css'`, then `data-theme="<name>"`. All three
+  pass `check:contrast` on every gated pair.
+
+- **Optional webfont files, and the rule they exist to keep: a preset never makes a network
+  request.** Each preset sets a font stack that resolves to a real system face. Where a webfont
+  is worth offering, it is a separate file the consumer imports _after_ the preset —
+  `presets/terminal.fonts.css` (IBM Plex Mono) and `presets/parchment.fonts.css` (EB Garamond).
+  Import the preset alone and nothing is downloaded.
+
+- **`slate`, `one-dark` and `one-light` now set a character, not just a palette** — so every
+  shipped preset does. They were palette-only, which made them recoloured defaults: they wore another product's
+  colours on this library's shape. Each now sets the character layer and a density —
+  `slate` becomes the catalogue's _soft modern_ entry (12px corners, hairline borders, roomier at
+  `1.05`), and `one-dark`/`one-light` become editor chrome (4px corners, compact at `0.9`,
+  sentence-case labels), deliberately identical to each other so a toggle between them changes
+  tone and nothing else. **Palettes are unchanged**; `check:contrast` reports the same eight
+  findings as before. See `docs/themes.md` iteration 4.
+
+- **`--gog-density`: one number that sets the spacing of the whole library.** A theme makes
+  every component tighter or roomier with `--gog-density: 0.9` — no component tokens named, no
+  list to keep up to date as components are added. It multiplies a new fourteen-step spacing
+  scale (`--gog-space-2` … `--gog-space-48`, named for their pixel value at density 1), and
+  every padding and gap in `theme.css` now derives from that scale. The three shipped presets
+  that carry a character layer use it: `ledger` at `0.9` (administrative software packed a
+  screen), `primeng` at `0.95`, `material` at `1.1` (M3's posture is generous by design).
+
+  The five existing `--gog-space-xs|sm|md|lg|2xl` names are kept as aliases with their exact
+  previous values, so no existing theme or consumer stylesheet changes. **Nothing moves at
+  density 1** except thirteen paddings that were never on a grid to begin with — five of them
+  fractional `rem` values computing to 3.6px, 4.4px, 4.8px, 7.2px and 9.6px — which now round
+  to the nearest 2px step. The largest single change is 4px, on `--gog-panel-slg-padding-x`.
+  See `docs/themes.md` iteration 6.
+
+- **A new shipped preset: `ledger`** — the square-cornered, hard-shadowed, system-font
+  administrative-software identity. Beige and grey, a muted navy accent, uniform 1px borders,
+  zero corner radius, a hard offset shadow with no blur, and every transition duration set to
+  `0s`. `@import '@guildofgleks/ui/styles/presets/ledger.css'`, then `data-theme="ledger"`.
+  Palette-plus-character-layer only, like `material`/`primeng` below but with no per-component
+  overrides needed at all — see `docs/themes.md` iteration 4. Named `ledger`, not the plan's own
+  "Classic" (that names the catalogue _family_, not this preset) — `ui-showcase` already uses
+  "Classic" as the display label for `data-theme="light"`.
+
+- **Two new shipped presets: `material` and `primeng`** — full visual identities (Material
+  Design 3 baseline and PrimeNG's Aura), not just palettes, ported from `gleks-ui-lab`'s
+  compare page. `@import '@guildofgleks/ui/styles/presets/material.css'` /
+  `.../presets/primeng.css'`, then `data-theme="material"` / `"primeng"`. Unlike `slate`/
+  `one-dark`/`one-light`, both set the character layer (corner rounding, border weight, casing,
+  tracking) plus a handful of settings the character layer has no vocabulary for yet (a pill
+  button, a table's header font). See each file's own header comment for what's per-component
+  and why.
+
+- **Four new foundation tokens give a theme somewhere to set corner rounding, border weight and
+  emphasis casing/tracking once, instead of per component:** `--gog-text-transform` (default
+  `uppercase`), `--gog-letter-spacing` (default `1px`), `--gog-border-width` and `--gog-border-style`
+  (default `1px solid` — a third tier alongside the existing `--gog-control-border-*` for form
+  fields and `--gog-panel-border-*` for raised surfaces, covering everything smaller and inline:
+  chips, tags, badges, toggles, table rows, tabs, calendar cells). 40 component tokens across
+  `theme.css` now derive from these plus the pre-existing `--gog-radius` — no default changed;
+  every conversion was checked to render the identical pixel value before and after. Not
+  converted, on purpose: pill/circle radii and deliberately-flat corners (a rounding axis
+  shouldn't reshape a shape choice), and per-component values with no shared pattern to extract.
+  `docs/themes.md` has the full audit. Setting any of the four in a `[data-theme]` block now
+  restyles every component that reads it, with no per-component overrides to list.
+
+- **`DialogService.open()` and `DialogConfig` gain an optional `TData` generic**, checked against
+  `data` at the call site: `dialogService.open<TResult, TData>({ data: /* checked against TData */ })`.
+  Supplying only `TResult` — the existing, common form — leaves `TData` as `unknown`, exactly as
+  before; nothing about an existing call changes. This closes only the sending half of the round
+  trip: the component you open still reads its data via `inject(DIALOG_DATA)`, one
+  `InjectionToken<unknown>` shared by every dialog, so it still needs its own cast
+  (`inject<TData>(DIALOG_DATA)`) — Angular's DI has no way to carry a per-call-site type through a
+  single shared token. See `AGENTS.md`'s `DialogService` section for the full example.
+
+### Removed
+
+- **The three abbreviated token prefixes deprecated in 21.5.0 (21.3.0 for `--gog-ms-*`) are gone.**
+  Each had been declared nowhere, honoured only as a fallback the spelled-out token wrapped:
+  `--gog-button-x: var(--gog-btn-x, value)`. The fallback layer is deleted; the spelled-out name is
+  now the plain declaration, with the same final value as before. Rename any of the following you
+  still set, in your own stylesheet — a `var()` reference to a name nothing declares does not fail
+  a build, it just silently stops matching anything:
+
+  | Old               | New                           |
+  | ----------------- | ----------------------------- |
+  | `--gog-btn-*`     | `--gog-button-*`              |
+  | `--gog-ms-*`      | `--gog-multiselect-*`         |
+  | `--gog-confirm-*` | `--gog-confirmation-dialog-*` |
+
+  `GogTokenName` (the exported type listing every `--gog-*` custom property) drops the 20 old
+  spellings it used to include — a compile error on a variable annotated with one of them is the
+  one part of this change your build will actually catch.
+
+### Fixed
+
+- **Four tokens that resolved to nothing, found while surveying this release's removal below.**
+  Each was a `var(--gog-…)` with no fallback, naming a custom property nothing declares — which
+  makes the token holding it guaranteed-invalid, so the declaration reading it silently computes to
+  nothing. No build error, nothing to see except the missing style:
+
+  - **`gog-multiselect`'s focus glow never rendered.** Its default read the deprecated
+    `--gog-ms-focus-ring`, declared nowhere — now reads its own `--gog-multiselect-focus-ring`,
+    matching `gog-input` and `gog-select`.
+  - **The filter box inside `gog-select` and `gog-multiselect` had no border and the wrong text
+    colour.** Both read a `--gog-{select,multiselect}-control-*` pair that was never declared
+    anywhere in the library — now read `--gog-{select,multiselect}-field-*`, the tokens that were
+    actually meant. The border loss was total (`border` is a shorthand, so one invalid part drops
+    the whole declaration); the colour loss was invisible, because `color` just inherited instead.
+  - **`gog-multiselect`'s JS-computed panel height silently used hardcoded defaults instead of the
+    themed metrics.** Its `GogDropdownBase` token overrides named the deprecated `--gog-ms-*`
+    prefix, which `theme.css` has never declared as a real property — so
+    `getComputedStyle().getPropertyValue()` always read `''`. Now reads `--gog-multiselect-*`,
+    matching the pattern `gog-select` already used correctly.
+
+  A consumer who set `--gog-multiselect-focus-glow`, `--gog-select-filter-input-color/-border` or
+  their `gog-multiselect` counterparts directly, to work around any of the first two being missing,
+  keeps working exactly as before — an explicit override still wins over the (now real) default.
+
 ## [21.6.1] - 26.08.2026
 
 ### Added

package/README.md

@@ -81,6 +81,13 @@ export class ExampleComponent {}
 Outputs are prefixed `gog` (`gogClick`, `gogToggle`) so they never collide with native DOM
 events. Inputs keep their natural names.
 
+> **Don't write `(click)` on `gog-button`.** Its click handler is bound on the `<button>` inside
+> its own template, not on the host — a native click still bubbles up through the host element, so
+> a `(click)` listener there fires on every press, silently bypassing `debounce`'s throttling.
+> `(gogClick)` is the one that only emits once the debounce window has passed; use it instead. This
+> is specific to the `gog-button` component — `[gogButton]` on your own `<a>`/`<button>` has no
+> debounce to bypass, so your own `(click)` on it works exactly as written.
+
 **3. If you use dialogs or toasts, place their hosts once.** `DialogService.open()` and
 `ToastService.show()` update state but render nothing without them:
 
@@ -116,8 +123,12 @@ want for a toast.
 
 Every value the components paint with lives in `styles/theme.css`, in three layers:
 
-**Foundation** — palette, type scale, spacing, motion. Override these to restyle everything at
-once; component tokens derive from them, so a palette swap carries through on its own.
+**Foundation** — palette, type scale, spacing, motion, and a small _character_ layer: corner
+rounding (`--gog-radius`), border weight (`--gog-control-border-*` for form fields,
+`--gog-panel-border-*` for raised surfaces, `--gog-border-*` for everything smaller and inline),
+and emphasis casing/tracking (`--gog-text-transform`, `--gog-letter-spacing`). Override these to
+restyle everything at once; component tokens derive from them, so a palette or character change
+carries through on its own, with nothing to re-list per component.
 
 **Component** — `--gog-<component>-*`, one block per component, named after the component you
 write in markup (`gog-button` → `--gog-button-*`), to restyle a single component app-wide:
@@ -139,11 +150,11 @@ variant and size classes:
 }
 ```
 
-> **Renamed in 21.5.0.** Three prefixes were abbreviated and are now spelled out:
-> `--gog-btn-*` → `--gog-button-*`, `--gog-confirm-*` → `--gog-confirmation-dialog-*`, and
-> `--gog-ms-*` → `--gog-multiselect-*` (that one since 21.3.0). **The old spellings still work**
-> — every new name derives from its old twin — and are **removed in 21.7.0**. A CSS override that
-> stops being read fails silently, which is why the window is two minors rather than one.
+> **Renamed in 21.5.0, removed in 21.7.0.** Three prefixes were abbreviated and are now spelled
+> out: `--gog-btn-*` → `--gog-button-*`, `--gog-confirm-*` → `--gog-confirmation-dialog-*`, and
+> `--gog-ms-*` → `--gog-multiselect-*` (that one since 21.3.0). **The old spellings no longer
+> resolve.** If you set one of them, rename it — a `var()` reference to a name nothing declares
+> doesn't fail your build, it just silently stops matching anything.
 >
 > One prefix that looks abbreviated and is not: **`--gog-input-*`**. It names the shared
 > text-field block that both `gog-inputfield` and `gog-textarea` render (`.gog-input__field`), not
@@ -167,7 +178,7 @@ The active theme is a `data-theme` attribute on `:root`, managed by `ThemeServic
 ```ts
 private readonly theme = inject(ThemeService);
 this.theme.toggleTheme(); // light ⇄ dark
-this.theme.setTheme('cyberpunk'); // any name you declared in CSS
+this.theme.setTheme('one-dark'); // any preset you imported, or any name you declared in CSS
 ```
 
 Out of the box it adopts whatever `data-theme` is already on the document, or `light`.
@@ -175,19 +186,64 @@ Persisting the choice and following the OS setting are opt-in:
 
 ```ts
 provideGogConfig({
-  theme: { storageKey: 'app-theme', followSystem: true, darkTheme: 'cyberpunk' },
+  theme: { storageKey: 'app-theme', followSystem: true, darkTheme: 'one-dark' },
 });
 ```
 
-A theme only declares what it changes — the derived layer re-resolves against whatever palette is
-in scope, so a new palette restyles every component without listing any of them. The `slate`
-preset is the worked example, palette-only:
+A theme only declares what it changes — the derived layer re-resolves against whatever is in
+scope, so a theme restyles every component without listing any of them. **Eleven declarations
+are a whole visual identity**, not a recolour:
 
 ```css
-@import '@guildofgleks/ui/styles/index.css';
-@import '@guildofgleks/ui/styles/presets/slate.css';
+[data-theme='compact'] {
+  /* Palette: every colour in the library re-derives from these. */
+  --gog-background-color: #f4f6f8;
+  --gog-surface-color: #ffffff;
+  --gog-text-color: #1e293b;
+  --gog-accent-color: #4f46e5;
+
+  /* Character: every corner, border, label and gap in the library re-derives from these. */
+  --gog-radius: 2px;
+  --gog-density: 0.85; /* one number = every padding and gap at once */
+  --gog-control-border-width: 1px;
+  --gog-text-transform: none;
+  --gog-letter-spacing: normal;
+}
 ```
 
+The palette half has always worked this way. The **character layer** (`--gog-radius`,
+`--gog-density`, the border and casing tokens — all since 21.7.0) is the other half: it is what
+lets a theme change the library's _shape_ — square or generous corners, thin borders,
+sentence-case labels, tight or roomy spacing — still without naming a single component.
+
+Nine presets ship alongside the built-in `light` and `dark`, each at `styles/presets/<name>.css`
+and activated by `data-theme="<name>"`. All nine set palette **and** character:
+
+| Preset                  | The identity                                                            |
+| ----------------------- | ----------------------------------------------------------------------- |
+| `slate`                 | soft modern — 12px corners, hairline borders, roomier than the default  |
+| `one-dark`, `one-light` | editor chrome — 4px corners, compact, sentence case; one UI, two tones  |
+| `material`, `primeng`   | Material Design 3 and PrimeNG Aura, including their shape and density   |
+| `ledger`                | administrative software — square corners, hard offset shadow, no motion |
+| `terminal`              | green phosphor — monospaced throughout, square, no motion               |
+| `bevel`                 | the early-web desktop — raised buttons, sunken fields, grey and navy    |
+| `parchment`             | ink on laid paper — old-style serif, oxblood accent, roomy              |
+
+**No preset downloads a font.** Each sets a stack that resolves to a real system face — the
+platform's own monospace for `terminal`, Tahoma/Verdana for `bevel`, Iowan Old Style/Palatino for
+`parchment` — so importing a preset never adds a network request. Where a webfont makes a visible
+difference, it lives in a separate opt-in file you import _after_ the preset:
+
+```css
+@import '@guildofgleks/ui/styles/presets/parchment.css';
+@import '@guildofgleks/ui/styles/presets/parchment.fonts.css'; /* optional: EB Garamond */
+```
+
+`terminal.fonts.css` (IBM Plex Mono) is the other one. `material` and `primeng` additionally set
+a few things the character layer has no vocabulary for (a pill button, a table's header font), and
+`bevel` sets one (a button's bevel must disagree with a field's). `AGENTS.md` has the per-preset
+detail and the full token list.
+
 Fonts are left alone on purpose (system stacks, no webfont download). Add
 `@guildofgleks/ui/styles/fonts.css` for the showcase's typography.
 
@@ -202,7 +258,7 @@ provideGogConfig({
   dropdown: { appendToBody: true },
   datepicker: { locale: 'de-DE', format: 'dd.MM.yyyy' },
   ripple: { enabled: true }, // press feedback on every interactive surface at once
-  labels: { clear: 'Очистить', selectAll: 'Выбрать все' }, // translate the library once
+  labels: { clear: 'Löschen', selectAll: 'Alle auswählen' }, // translate the library once
 });
 ```