@guildofgleks/ui 21.6.0 → 21.7.0

package/CHANGELOG.md

@@ -4,6 +4,273 @@ 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
+
+- **`gog-card` — a surface for one self-contained thing.** A product tile, a summary, a search
+  result. It paints a background, a border and a radius, which a CSS class of your own could also
+  do; what it adds is what a class cannot:
+
+  - **It names itself.** The heading you project as `gogCardHeader` becomes the card's accessible
+    name — the card takes that element's id (minting one if it has none), points its own
+    `aria-labelledby` at it and announces itself as a group. `role="group"` rather than `region`
+    on purpose: a grid of twenty cards would put twenty landmarks in a screen reader's landmark
+    list, which is worse than none.
+  - **The whole surface can activate a link, without the card inventing a control.** There is no
+    `interactive` input and no `gogClick` output. Put `gogCardLink` on the `<a>` the card is about
+    — usually the one in its heading — and its hit area stretches over the card, with the focus
+    ring drawn around the surface. The link stays yours, so `routerLink`, `href`, `target`,
+    middle-click, "open in new tab" and Enter all keep working, and anything else focusable in the
+    card still receives its own clicks. A card rendering its own `<button>` instead could hold no
+    other control (a button may not contain one), could not navigate the way an app navigates, and
+    would announce the card's entire text as its name.
+  - **`loading` and `disabled` are folded in**, including `aria-busy`, the placeholder shaped like
+    a title and body copy, and taking the card's link out of the tab order.
+
+  Slots: `gogCardHeader`, `gogCardMedia` (full-bleed, rounds into the top corners), `gogCardFooter`.
+  Tokens: `--gog-card-*`, with `--gog-card-bg`, `--gog-card-border-color`, `--gog-card-shadow`,
+  `--gog-card-padding-y`, `--gog-card-padding-x` and `--gog-card-gap` left undeclared as the
+  per-instance escape hatch.
+
+- **`gog-panel` — a titled region of a page.** A settings section, a dashboard area, a form group.
+  It differs from `gog-card` in behaviour, not only in size: it is a real landmark
+  (`role="region"` named by its `gogPanelHeader` heading), it can **collapse**, and its surface is
+  never itself a link, because controls live inside a panel.
+
+  Collapsing **composes `gog-collapsible`** rather than repeating it, so the open/close state, the
+  id wiring and the animation are the ones the rest of the library already uses. The heading stays
+  a heading: the toggle is a separate `<button>` named by it through `aria-labelledby`, with its
+  hit area stretched across the header row — so the pointer still gets "click the title to
+  collapse", while a screen reader gets a heading _and_ a named expandable button instead of a
+  heading swallowed by `role="button"`. A panel that cannot collapse undoes the collapse geometry
+  it inherits, `overflow` included, so a dropdown opened inside one is not clipped.
+
+  `loading` keeps the heading and the footer and replaces only the body — a page section is titled
+  before its content arrives. Slots: `gogPanelHeader`, `gogPanelFooter`. New label:
+  `GOG_CONFIG.labels.togglePanel`, used only by a collapsible panel with no heading to be named by.
+
+  **`--gog-panel-*` now means two things, deliberately.** `--gog-panel-radius`,
+  `--gog-panel-shadow`, `--gog-panel-border-width` and `--gog-panel-border-style` were already the
+  foundation surface tier that dialogs, dropdown panels and tooltips read; the component adopts
+  them instead of owning a fourth definition of "raised surface", so a theme's house radius and
+  shadow reach it for free. The rest of `--gog-panel-*` is the component's own. Nothing was
+  renamed and no existing override changes meaning.
+
+- **`gogRipple` — a press wash for any element.** `<button gogRipple>`, `<div gogRipple>`, a
+  `gog-*` host tag: a directive, so it adds no wrapper and changes no layout. Built from scratch —
+  there is no `@angular/cdk` in this package and there will not be.
+
+  The interesting part is not the animation. A ripple normally clips its host, and `gogBadge`
+  pins its badge **outside** the host's box on purpose — so the first ordinary pairing anyone
+  tries, a badged button, loses its badge the moment the ripple is installed. This one never
+  clips the host: the wash lives in its own layer that clips itself, and that layer takes the
+  host's corner radius through `border-radius: inherit`, per instance and per theme, with no
+  token to set. The one thing to know follows from it — **put the directive on the element that
+  paints the surface**, since a wrapper whose child paints the rounded background passes on the
+  wrapper's radius (usually `0`) and the wash squares off.
+
+  Inputs: `rippleDisabled`, `rippleCentred`. Suppressed with no wiring on a host that is
+  `disabled` or `aria-disabled="true"`, and under `prefers-reduced-motion: reduce` — suppressed
+  outright there, not merely shortened. Keyboard activation is centred, since `Enter` and `Space`
+  carry no coordinates. Tokens: `--gog-ripple-color` (defaults to `currentColor`, so one value
+  works on a filled surface and a ghost one), `--gog-ripple-opacity`,
+  `--gog-ripple-enter-duration`, `--gog-ripple-exit-duration`, `--gog-ripple-easing`.
+
+- **Every interactive surface in the library can ripple, from one switch.**
+  `provideGogConfig({ ripple: { enabled: true } })` turns it on for `gog-button`, `[gogButton]`,
+  `gog-button-toggle-group`, `gog-chip`, `gog-tabs` headers, `gog-accordion` headers,
+  `gogCollapsibleTrigger`, `gogMenuItem` and the options inside `gog-select`, `gog-multiselect`
+  and `gog-autocomplete` — `gog-paginator` follows, because its page buttons are `gog-button`s.
+
+  **Off by default**, so this release changes the appearance of nothing. Each of those components
+  also takes a **`ripple`** input that beats the app-wide setting in both directions:
+  `[ripple]="false"` opts one control out of an app that turned it on, `[ripple]="true"` opts one
+  in without switching the app over.
+
+  `ripple` is the first visual default in `GOG_CONFIG` rather than in `theme.css`, and the
+  exception is deliberate: `--gog-ripple-opacity: 0` hides the wash but still pays for the DOM
+  node, the pointer listeners and the animation frames. A real off has to reach the TypeScript —
+  and it does: a disabled ripple attaches no listeners and adds no class to its host.
+
+  Two surfaces are deliberately left out, with `gogRipple` available if you disagree: **`gog-table`
+  rows** and **`gogCardLink`**. Both are hundreds of pixels wide, so the wave has to cross the
+  whole surface and reads as a flash rather than as feedback where you pressed — and a table
+  installs one directive per row, with no virtualization in the library yet. A `gog-chip` that is
+  not `clickable`, or is `disabled`, never ripples whatever the config says.
+
+- **`GogSurfaceVariant`** (`'outlined' | 'elevated' | 'filled'`), shared by both, so the two agree
+  on what each word looks like.
+
+### Fixed
+
+- **A loading `gog-table` and `gog-autocomplete` announce themselves.** Both now set
+  `aria-busy="true"` while `loading` is on, which every component with a `loading` input is
+  supposed to do. A loading table replaces its rows with a single spinner cell and dims its
+  header; the autocomplete's spinner sits in its actions slot and is `aria-hidden`. Neither had
+  anything to tell a screen reader that a wait was in progress — the table read as a table with
+  no rows, and the field as idle. The autocomplete is the worse of the two, because unlike a
+  button the user pressed, that wait is not something they started.
+
 ## [21.6.0] - 23.08.2026
 
 ### Fixed
@@ -40,7 +307,7 @@ reached 1.0, so breaking changes may land in minor versions.
   rendering under it. The rule is a single class in specificity, so your own styles still win.
 
 - **Disabled and focus styling can no longer be lost to an ordinary app stylesheet.** `[gogButton]`
-  and `gogMenuItem` are applied to *your* element, which is the element you style — and a plain
+  and `gogMenuItem` are applied to _your_ element, which is the element you style — and a plain
   `.my-button { cursor: pointer }` in an Angular component stylesheet is the same specificity as
   the library's `.gog-btn:disabled` once `[_ngcontent-…]` is stamped on it, so it won on source
   order. Measured: a disabled button reading `cursor: pointer` at full opacity — enabled-looking
@@ -189,7 +456,7 @@ a version bump with nothing to migrate.
   **`npm run check:logical-properties` now fails the build** on a `padding`, `margin`,
   `border-width` or `border-radius` shorthand that sets the two horizontal sides differently.
   21.5.0 converted 16 stylesheets to logical properties and still missed these four, because the
-  sidedness lives in a value's *position inside a shorthand* rather than in a `left`/`right`
+  sidedness lives in a value's _position inside a shorthand_ rather than in a `left`/`right`
   keyword — invisible to a grep, and invisible to a unit test with no style engine.
 
 - **Documented the `position: fixed` containing-block caveat**, in one place plus a line on each

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,16 +150,23 @@ 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
 > the `gog-inputfield` component — the two are meant to restyle together from one token set, so
 > there is no `--gog-inputfield-*` and there will not be one.
+>
+> And one prefix that means two things on purpose: **`--gog-panel-*`**. Four of them —
+> `--gog-panel-radius`, `--gog-panel-shadow`, `--gog-panel-border-width`,
+> `--gog-panel-border-style` — are the _foundation_ surface tier that dialogs, dropdown panels and
+> tooltips read, and the `gog-panel` component reads them too rather than owning a fourth copy of
+> "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.
 
 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`.
@@ -160,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`.
@@ -168,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.
 
@@ -194,14 +257,20 @@ provideGogConfig({
   control: { size: 'sm', errorDisplay: 'auto', clearable: true },
   dropdown: { appendToBody: true },
   datepicker: { locale: 'de-DE', format: 'dd.MM.yyyy' },
-  labels: { clear: 'Очистить', selectAll: 'Выбрать все' }, // translate the library once
+  ripple: { enabled: true }, // press feedback on every interactive surface at once
+  labels: { clear: 'Löschen', selectAll: 'Alle auswählen' }, // translate the library once
 });
 ```
 
 Keys: `control`, `dropdown`, `floatLabel`, `datepicker`, `autocomplete`, `inputfield`, `textarea`,
-`tooltip`, `scroll`, `button`, `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`, `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.
+
+`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
+the animation frames, so a real off has to reach the TypeScript. It is **off by default**, and
+every rippling component takes a `ripple` input that beats it in both directions.
 
 Icons work the same way — 41 Lucide glyphs ship with the package, and your own register by name:
 
@@ -243,13 +312,14 @@ dropdowns, always for the menu.
 | Form controls       | `gog-inputfield`, `gog-textarea`, `gog-select`, `gog-multiselect`, `gog-autocomplete`, `gog-checkbox`, `gog-radio-group`, `gog-toggle`, `gog-slider`, `gog-datepicker`, `gog-calendar`, `gog-button-toggle-group` |
 | Actions             | `gog-button`, `gog-chip`                                                                                                                                                                                          |
 | Data                | `gog-table` (+ `gog-column`), `gog-paginator`, `gog-tag`                                                                                                                                                          |
-| Layout & disclosure | `gog-accordion`, `gog-tabs` (+ `gog-tab`), `gog-collapsible`, `gog-divider`, `gog-scroll`                                                                                                                         |
+| Layout & disclosure | `gog-accordion`, `gog-tabs` (+ `gog-tab`), `gog-collapsible`, `gog-card`, `gog-panel`, `gog-divider`, `gog-scroll`                                                                                                |
 | Overlays            | `gog-dialog`, `gog-confirmation-dialog`, `gog-toast` (+ `gog-toast-container`), `gog-menu` (+ `gogMenuTrigger` / `gogMenuItem`)                                                                                   |
 | Feedback            | `gog-spinner`, `gog-spinner-overlay`, `gog-progressbar`, `gog-skeleton`                                                                                                                                           |
 | Content             | `gog-icon`                                                                                                                                                                                                        |
 
 **Directives:** `gogButton` (a link that looks like a button), `gogTooltip`, `gogBadge`,
-`gogCollapsibleTrigger`, `gogCollapsibleContent`.
+`gogRipple` (a press wash on any element), `gogCollapsibleTrigger`, `gogCollapsibleContent`,
+`gogCardLink` (a link the whole card activates).
 **Services:** `DialogService`, `ToastService`, `ThemeService`.
 
 Seventeen more directives go on markup you own rather than configuring a component through an
@@ -270,6 +340,14 @@ A few things worth knowing before you reach for a workaround:
   They also generate their own `id`, so labels and error messages are wired up without `inputId`.
 - **`gog-collapsible` is headless** — no markup of its own. Project any element as the trigger and
   any element as the panel.
+- **A clickable `gog-card` has no `interactive` input.** Put `gogCardLink` on the `<a>` the card is
+  about — usually the one in its heading — and the whole surface activates that link, keyboard,
+  middle-click and `routerLink` included. Same reasoning as `gog-button` above: the element stays
+  yours. Anything else focusable in the card keeps receiving its own clicks.
+- **`gog-panel` shares the `--gog-panel-*` prefix with the foundation surface tier.**
+  `--gog-panel-radius`, `--gog-panel-shadow` and the border pair are the tokens dialogs and
+  dropdown panels already read, so a theme's idea of a raised surface reaches the component for
+  free. Its own family (background, padding, heading, toggle, footer) sits alongside them.
 - **`[(ngModel)]` is untested.** The library never imports `FormsModule`; use Reactive Forms.
 
 ## Documentation