ng-hub-ui-ds 22.9.0 → 22.9.1

package/CHANGELOG.md

@@ -5,6 +5,48 @@ All notable changes to `ng-hub-ui-ds` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [22.9.1] - 2026-09-06
+
+### Fixed
+
+- **The README stopped promising a token that resolves to nothing.** Its colour table still listed
+  `--hub-sys-color-{variant}-dark` as the fifth member of the family — retired in 22.4.0 — and never
+  mentioned `-on`, the member that replaced it and that forms, buttons and badges consume today. The
+  "SCSS functions" section described a closed `$hub-variants` list and a `-dark` back-compat alias,
+  a mechanism the package left behind in that same release: it now shows the open `$hub-accents` map,
+  `$hub-accents-extra` and the real derivation loop, so a reader who copies it gets working code.
+  Also restores the seven libraries missing from the family list and drops the two that are not in it:
+  `ng-hub-ui-accordion`, retired in favour of panels, and `ng-hub-ui-dropdown`, which is a directive
+  inside `ng-hub-ui-buttons` and never a package. `focus-ring-color()` joins the mixin catalogue.
+  Both languages.
+- **`BREAKING_CHANGES.md` records the 22.4.0 removal of `--hub-sys-color-{variant}-dark`.** It shipped
+  with a changelog line and no entry here; in this repository the major tracks Angular and can never
+  signal a break, so this file is the only warning a consumer gets — and a CSS variable that resolves
+  to nothing fails silently, at paint time, with no build error.
+- **The terminal-theme comment no longer points at a file the package does not ship.** It sent the
+  reader to `styles/themes/terminal.scss`, which lives in the documentation app, not here. The
+  compiled `hub-tokens.css` carries the same correction.
+- **Docs site** — the family gallery on the design-system page claimed `avatar`, `milestones` and
+  `utils` were still pending after they had been wired to `--hub-sys-*`, and listed none of
+  `action-sheet`, `badges`, `buttons`, `icons`, `loading`, `metrics` or `signature`. Its cards also
+  linked to unprefixed URLs, which only resolve through a legacy redirect table `action-sheet` is
+  absent from, and which drop a reader of the Spanish page into the English docs; they are relative
+  now. Nothing in the published package changes.
+
+### Added
+
+- **`FUNCTIONALITIES.md`**, the coverage table the rest of the family carries: which tokens, mixins
+  and utilities exist and which of them the documentation actually demonstrates. Every mixin is
+  marked uncovered on purpose — the page's demos consume the utility classes, as it says itself.
+
+### Removed
+
+- **Docs site** — the orphan `app-topbar` component. The site's top navigation moved into the app
+  shell's sidebar slots and nothing mounts the component any more, but its stylesheet stayed behind
+  as the last place in the repository still reading `--hub-sys-color-primary-dark`, the alias this
+  package retired in 22.4.0. A component nobody renders is still a component somebody copies styles
+  from, which is the only reason this was worth a line. Nothing in the published package changes.
+
 ## [22.9.0] - 2026-09-03
 
 ### Removed
@@ -14,7 +56,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   selector covered `:root` and every theme. With Bootstrap present it silently handed that
   package control of this one's semantic tokens; without it, every declaration resolved to its
   fallback and the block did nothing. It is gone, and with it the package's last dependency on
-  another framework's variables: **0** `--bs-*` references remain.
+  another framework's variables: the emitted tokens carry **0** `--bs-*` references. The
+  only ones left in the package are inside `bridge-bootstrap()`, which emits nothing unless
+  you call it.
 
 ### Changed
 

package/README.es.md

@@ -27,25 +27,30 @@ librerías de componentes Angular para aplicaciones standalone.
 Este paquete es la base de design tokens de la que lee el resto del ecosistema
 **ng-hub-ui**:
 
-- [**ng-hub-ui-accordion**](https://www.npmjs.com/package/ng-hub-ui-accordion) (obsoleta — usa ng-hub-ui-panels)
 - [**ng-hub-ui-action-sheet**](https://www.npmjs.com/package/ng-hub-ui-action-sheet)
 - [**ng-hub-ui-avatar**](https://www.npmjs.com/package/ng-hub-ui-avatar)
+- [**ng-hub-ui-badges**](https://www.npmjs.com/package/ng-hub-ui-badges)
 - [**ng-hub-ui-board**](https://www.npmjs.com/package/ng-hub-ui-board)
 - [**ng-hub-ui-breadcrumbs**](https://www.npmjs.com/package/ng-hub-ui-breadcrumbs)
+- [**ng-hub-ui-buttons**](https://www.npmjs.com/package/ng-hub-ui-buttons)
 - [**ng-hub-ui-calendar**](https://www.npmjs.com/package/ng-hub-ui-calendar)
-- [**ng-hub-ui-dropdown**](https://www.npmjs.com/package/ng-hub-ui-dropdown)
 - [**ng-hub-ui-ds**](https://www.npmjs.com/package/ng-hub-ui-ds) ← Estás aquí
 - [**ng-hub-ui-forms**](https://www.npmjs.com/package/ng-hub-ui-forms)
 - [**ng-hub-ui-history**](https://www.npmjs.com/package/ng-hub-ui-history)
+- [**ng-hub-ui-icons**](https://www.npmjs.com/package/ng-hub-ui-icons)
+- [**ng-hub-ui-loading**](https://www.npmjs.com/package/ng-hub-ui-loading)
+- [**ng-hub-ui-metrics**](https://www.npmjs.com/package/ng-hub-ui-metrics)
 - [**ng-hub-ui-milestones**](https://www.npmjs.com/package/ng-hub-ui-milestones)
 - [**ng-hub-ui-modal**](https://www.npmjs.com/package/ng-hub-ui-modal)
 - [**ng-hub-ui-nav**](https://www.npmjs.com/package/ng-hub-ui-nav)
 - [**ng-hub-ui-paginable**](https://www.npmjs.com/package/ng-hub-ui-paginable)
 - [**ng-hub-ui-panels**](https://www.npmjs.com/package/ng-hub-ui-panels)
 - [**ng-hub-ui-portal**](https://www.npmjs.com/package/ng-hub-ui-portal)
+- [**ng-hub-ui-signature**](https://www.npmjs.com/package/ng-hub-ui-signature)
 - [**ng-hub-ui-skeleton**](https://www.npmjs.com/package/ng-hub-ui-skeleton)
 - [**ng-hub-ui-sortable**](https://www.npmjs.com/package/ng-hub-ui-sortable)
 - [**ng-hub-ui-stepper**](https://www.npmjs.com/package/ng-hub-ui-stepper)
+- [**ng-hub-ui-toast**](https://www.npmjs.com/package/ng-hub-ui-toast)
 - [**ng-hub-ui-utils**](https://www.npmjs.com/package/ng-hub-ui-utils)
 
 ---
@@ -178,8 +183,10 @@ espaciado direccional `-x` / `-y`.
 
 ## 🎨 Los colores semánticos
 
-Cada color semántico (`primary` · `success` · `danger` · `warning` · `info`)
-expone una **familia uniforme** de cinco tokens:
+Cada variante semántica expone una **familia uniforme** de cinco tokens. El conjunto por
+defecto es `primary` · `secondary` · `success` · `danger` · `warning` · `info` · `neutral` ·
+`light` · `dark`, y es **abierto**: cada variante que añadas obtiene la misma familia (ver
+[Cómo modificarlo](#️-cómo-modificarlo)).
 
 | Token                               | Uso típico                                     |
 | ----------------------------------- | ---------------------------------------------- |
@@ -187,7 +194,7 @@ expone una **familia uniforme** de cinco tokens:
 | `--hub-sys-color-<v>-subtle`        | Fondo tenue (banners, alertas)                 |
 | `--hub-sys-color-<v>-border-subtle` | Borde tenue sobre el fondo subtle              |
 | `--hub-sys-color-<v>-emphasis`      | Texto legible sobre el fondo subtle            |
-| `--hub-sys-color-<v>-dark`          | Variante oscura del color                      |
+| `--hub-sys-color-<v>-on`            | Color de texto/icono con contraste **sobre** el acento |
 
 Ejemplo de uso (un aviso a juego con el resto de la familia):
 
@@ -248,7 +255,7 @@ Los únicos nombres fuera de Bootstrap son los primitivos de layout que reflejan
 .sr-label    { @include hub.visually-hidden(); }
 ```
 
-Grupos: **tema** (`theme()` — tematización parcial en una llamada: pásale solo las escalas/acentos cambiados como mapas), **breakpoints** (`media-breakpoint-up/down` sobre el mapa `$hub-breakpoints` — de él se generan las variantes responsive `.d-md-*`, `.col-lg-*`, `.p-sm-*`…), **layout** (`stack`, `cluster`, `grid`, `grid-fixed`, `row`, `col`, `offset`, `center`), **tipografía** (`font-family`, `font-size`, `font-weight`, `line-height`, `text-color`, `link-color`, `text-truncate`, `text-break`), **superficies** (`bg`, `text-bg`, `border`, `border-color`, `radius`, `shadow`), **helpers** (`focus-ring`, `visually-hidden`, `stretched-link`, `ratio`, `clearfix`) y los **puentes** (`bridge-bootstrap` / `bridge-material` / `bridge-tailwind` / `bridge-open-props`).
+Grupos: **tema** (`theme()` — tematización parcial en una llamada: pásale solo las escalas/acentos cambiados como mapas), **breakpoints** (`media-breakpoint-up/down` sobre el mapa `$hub-breakpoints` — de él se generan las variantes responsive `.d-md-*`, `.col-lg-*`, `.p-sm-*`…), **layout** (`stack`, `cluster`, `grid`, `grid-fixed`, `row`, `col`, `offset`, `center`), **tipografía** (`font-family`, `font-size`, `font-weight`, `line-height`, `text-color`, `link-color`, `text-truncate`, `text-break`), **superficies** (`bg`, `text-bg`, `border`, `border-color`, `radius`, `shadow`), **helpers** (`focus-ring`, `focus-ring-color`, `visually-hidden`, `stretched-link`, `ratio`, `clearfix`) y los **puentes** (`bridge-bootstrap` / `bridge-material` / `bridge-tailwind` / `bridge-open-props`).
 
 El catálogo completo con demos en vivo está documentado en [hubui.dev/design-system](https://hubui.dev/en/design-system/).
 
@@ -311,43 +318,55 @@ Reúne tus overrides bajo un atributo de tema y actívalo cuando quieras:
 ## 🧩 Funciones SCSS (cómo se genera por dentro)
 
 Las familias de color semántico **no se escriben a mano**, y un tema solo fija el
-**acento** de cada variante — `-subtle`, `-border-subtle` y `-emphasis` se derivan
-**una sola vez** en `:root` con `color-mix()` a partir del acento, la superficie y
-el _ink_ vivos. Así, añadir un color o un tema es uniforme y sin _boilerplate_.
+**acento** de cada variante — `-subtle`, `-border-subtle`, `-emphasis` y `-on` se
+derivan **una sola vez** en `:root` a partir del acento, la superficie y el _ink_
+vivos. Los nombres de las variantes viven en un único mapa Sass **abierto**, así
+que añadir un color o un tema es uniforme y sin _boilerplate_.
 
 ```scss
-$hub-variants: primary, success, danger, warning, info;
-
-// Un acento por variante, por tema — solo el color base.
-$hub-accents-light: (
+// El ÚNICO sitio que enumera los nombres de variante. Es `!default`, así que puedes
+// reemplazarlo entero antes del import — o, mejor, fusionar con $hub-accents-extra.
+$hub-accents: (
 	primary: var(--hub-ref-color-blue-500, #0d6efd),
+	secondary: var(--hub-ref-color-gray-600, #6c757d),
 	success: var(--hub-ref-color-green-500, #198754),
 	danger:  var(--hub-ref-color-red-500, #dc3545),
 	warning: var(--hub-ref-color-yellow-500, #ffc107),
-	info:    var(--hub-ref-color-cyan-500, #0dcaf0)
-);
-
-// Fija SOLO --hub-sys-color-<variante> (el acento). Se llama en cada tema.
+	info:    var(--hub-ref-color-cyan-500, #0dcaf0),
+	neutral: var(--hub-ref-color-gray-600, #6c757d),
+	light:   var(--hub-ref-color-gray-100, #f8f9fa),
+	dark:    var(--hub-ref-color-gray-900, #212529)
+) !default;
+
+// Override aditivo — pasa SOLO las variantes que añades o retocas, conserva las demás.
+$hub-accents-extra: () !default;
+$hub-accents: map.merge($hub-accents, $hub-accents-extra);
+
+// Fija SOLO --hub-sys-color-<variante> (el acento). Se llama en cada bloque de tema
+// con el mapa propio del tema, así que un tema emite justo las variantes que retinta.
 @mixin hub-color-accents($accents) {
-	@each $name in $hub-variants {
-		--hub-sys-color-#{$name}: #{map.get($accents, $name)};
+	@each $name, $color in $accents {
+		--hub-sys-color-#{$name}: #{$color};
 	}
 }
 
-// Deriva la familia de roles del acento + superficie + ink vivos. Se emite UNA
-// vez en :root; los temas solo cambian las entradas y la familia se recalcula.
+// Deriva la familia de roles del acento + superficie + ink vivos. Se emite UNA vez
+// en :root sobre el conjunto abierto, así que cada variante — incluidas las tuyas —
+// obtiene su familia completa gratis.
 @mixin hub-color-derive() {
-	@each $name in $hub-variants {
+	@each $name in map.keys($hub-accents) {
 		--hub-sys-color-#{$name}-subtle:        color-mix(in oklch, var(--hub-sys-color-#{$name}) 12%, var(--hub-sys-surface-page, #fff));
 		--hub-sys-color-#{$name}-border-subtle: color-mix(in oklch, var(--hub-sys-color-#{$name}) 35%, var(--hub-sys-surface-page, #fff));
 		--hub-sys-color-#{$name}-emphasis:      color-mix(in oklch, var(--hub-sys-color-#{$name}) 80%, var(--hub-sys-color-ink, #212529));
-		--hub-sys-color-#{$name}-dark:          var(--hub-sys-color-#{$name}-emphasis); // alias retrocompatible
+		// Volteo de contraste en escala de grises según la luminosidad del propio acento:
+		// los acentos oscuros (L < .62) resuelven a texto blanco; los claros, a casi negro.
+		--hub-sys-color-#{$name}-on:            oklch(from var(--hub-sys-color-#{$name}) clamp(0, (0.62 - l) * 1000, 1) 0 h);
 	}
 }
 
 :root,
 [data-theme='light'] {
-	@include hub-color-accents($hub-accents-light);
+	@include hub-color-accents($hub-accents);
 	@include hub-color-derive();
 }
 ```
@@ -355,8 +374,8 @@ $hub-accents-light: (
 > Casi nunca necesitas tocar el SCSS: como la familia se deriva del **acento
 > único** en tiempo de ejecución, sobrescribir `--hub-sys-color-<variante>` en CSS
 > plano — incluso en un subárbol — recalcula `-subtle` / `-border-subtle` /
-> `-emphasis` automáticamente. Los mapas + mixins son solo la mecánica interna,
-> útil si contribuyes al paquete o compilas tu propia variante de la paleta.
+> `-emphasis` / `-on` automáticamente. Los mapas + mixins son solo la mecánica
+> interna, útil si contribuyes al paquete o compilas tu propia variante de la paleta.
 
 ---
 

package/README.md

@@ -27,25 +27,30 @@ component libraries for standalone apps.
 This package is the design-token foundation the rest of the **ng-hub-ui**
 ecosystem reads from:
 
-- [**ng-hub-ui-accordion**](https://www.npmjs.com/package/ng-hub-ui-accordion) (deprecated — use ng-hub-ui-panels)
 - [**ng-hub-ui-action-sheet**](https://www.npmjs.com/package/ng-hub-ui-action-sheet)
 - [**ng-hub-ui-avatar**](https://www.npmjs.com/package/ng-hub-ui-avatar)
+- [**ng-hub-ui-badges**](https://www.npmjs.com/package/ng-hub-ui-badges)
 - [**ng-hub-ui-board**](https://www.npmjs.com/package/ng-hub-ui-board)
 - [**ng-hub-ui-breadcrumbs**](https://www.npmjs.com/package/ng-hub-ui-breadcrumbs)
+- [**ng-hub-ui-buttons**](https://www.npmjs.com/package/ng-hub-ui-buttons)
 - [**ng-hub-ui-calendar**](https://www.npmjs.com/package/ng-hub-ui-calendar)
-- [**ng-hub-ui-dropdown**](https://www.npmjs.com/package/ng-hub-ui-dropdown)
 - [**ng-hub-ui-ds**](https://www.npmjs.com/package/ng-hub-ui-ds) ← You are here
 - [**ng-hub-ui-forms**](https://www.npmjs.com/package/ng-hub-ui-forms)
 - [**ng-hub-ui-history**](https://www.npmjs.com/package/ng-hub-ui-history)
+- [**ng-hub-ui-icons**](https://www.npmjs.com/package/ng-hub-ui-icons)
+- [**ng-hub-ui-loading**](https://www.npmjs.com/package/ng-hub-ui-loading)
+- [**ng-hub-ui-metrics**](https://www.npmjs.com/package/ng-hub-ui-metrics)
 - [**ng-hub-ui-milestones**](https://www.npmjs.com/package/ng-hub-ui-milestones)
 - [**ng-hub-ui-modal**](https://www.npmjs.com/package/ng-hub-ui-modal)
 - [**ng-hub-ui-nav**](https://www.npmjs.com/package/ng-hub-ui-nav)
 - [**ng-hub-ui-paginable**](https://www.npmjs.com/package/ng-hub-ui-paginable)
 - [**ng-hub-ui-panels**](https://www.npmjs.com/package/ng-hub-ui-panels)
 - [**ng-hub-ui-portal**](https://www.npmjs.com/package/ng-hub-ui-portal)
+- [**ng-hub-ui-signature**](https://www.npmjs.com/package/ng-hub-ui-signature)
 - [**ng-hub-ui-skeleton**](https://www.npmjs.com/package/ng-hub-ui-skeleton)
 - [**ng-hub-ui-sortable**](https://www.npmjs.com/package/ng-hub-ui-sortable)
 - [**ng-hub-ui-stepper**](https://www.npmjs.com/package/ng-hub-ui-stepper)
+- [**ng-hub-ui-toast**](https://www.npmjs.com/package/ng-hub-ui-toast)
 - [**ng-hub-ui-utils**](https://www.npmjs.com/package/ng-hub-ui-utils)
 
 ---
@@ -179,8 +184,10 @@ These are live, re-basable CSS variables too, using the same directional
 
 ## 🎨 Semantic colours
 
-Each semantic colour (`primary` · `success` · `danger` · `warning` · `info`)
-exposes a **uniform family** of five tokens:
+Each semantic variant exposes a **uniform family** of five tokens. The default set is
+`primary` · `secondary` · `success` · `danger` · `warning` · `info` · `neutral` · `light` ·
+`dark`, and it is **open**: every variant you add gets the same family (see
+[How to customise it](#️-how-to-customise-it)).
 
 | Token                               | Typical use                                    |
 | ----------------------------------- | ---------------------------------------------- |
@@ -188,7 +195,7 @@ exposes a **uniform family** of five tokens:
 | `--hub-sys-color-<v>-subtle`        | Faint background (banners, alerts)             |
 | `--hub-sys-color-<v>-border-subtle` | Faint border over the subtle background        |
 | `--hub-sys-color-<v>-emphasis`      | Legible text over the subtle background        |
-| `--hub-sys-color-<v>-dark`          | Dark variant of the colour                     |
+| `--hub-sys-color-<v>-on`            | Contrast text/icon colour laid **on** the accent |
 
 Usage example (a callout that matches the rest of the family):
 
@@ -250,7 +257,7 @@ The only non-Bootstrap names are the layout primitives that mirror the mixins: `
 .sr-label    { @include hub.visually-hidden(); }
 ```
 
-Groups: **theme** (`theme()` — partial theming in one call: pass only the changed scales/accents as maps), **breakpoints** (`media-breakpoint-up/down` over the `$hub-breakpoints` map — the responsive variants `.d-md-*`, `.col-lg-*`, `.p-sm-*`… are generated from it), **layout** (`stack`, `cluster`, `grid`, `grid-fixed`, `row`, `col`, `offset`, `center`), **typography** (`font-family`, `font-size`, `font-weight`, `line-height`, `text-color`, `link-color`, `text-truncate`, `text-break`), **surfaces** (`bg`, `text-bg`, `border`, `border-color`, `radius`, `shadow`), **helpers** (`focus-ring`, `visually-hidden`, `stretched-link`, `ratio`, `clearfix`) and the **bridges** (`bridge-bootstrap` / `bridge-material` / `bridge-tailwind` / `bridge-open-props`).
+Groups: **theme** (`theme()` — partial theming in one call: pass only the changed scales/accents as maps), **breakpoints** (`media-breakpoint-up/down` over the `$hub-breakpoints` map — the responsive variants `.d-md-*`, `.col-lg-*`, `.p-sm-*`… are generated from it), **layout** (`stack`, `cluster`, `grid`, `grid-fixed`, `row`, `col`, `offset`, `center`), **typography** (`font-family`, `font-size`, `font-weight`, `line-height`, `text-color`, `link-color`, `text-truncate`, `text-break`), **surfaces** (`bg`, `text-bg`, `border`, `border-color`, `radius`, `shadow`), **helpers** (`focus-ring`, `focus-ring-color`, `visually-hidden`, `stretched-link`, `ratio`, `clearfix`) and the **bridges** (`bridge-bootstrap` / `bridge-material` / `bridge-tailwind` / `bridge-open-props`).
 
 The full catalogue with live demos is documented at [hubui.dev/design-system](https://hubui.dev/en/design-system/).
 
@@ -313,52 +320,64 @@ Group your overrides under a theme attribute and activate it whenever you want:
 ## 🧩 SCSS functions (how it is generated internally)
 
 The semantic colour families are **not written by hand**, and a theme only ever
-sets the **accent** of each variant — `-subtle`, `-border-subtle` and `-emphasis`
-are derived **once** in `:root` with `color-mix()` from the live accent, surface
-and ink CSS variables. Adding a colour or a theme is uniform and boilerplate-free.
+sets the **accent** of each variant — `-subtle`, `-border-subtle`, `-emphasis` and
+`-on` are derived **once** in `:root` from the live accent, surface and ink CSS
+variables. The variant names live in a single **open** Sass map, so adding a colour
+or a theme is uniform and boilerplate-free.
 
 ```scss
-$hub-variants: primary, success, danger, warning, info;
-
-// One accent per variant, per theme — just the base colour.
-$hub-accents-light: (
+// The ONE place that enumerates variant names. `!default`, so you can replace it
+// wholesale before the import — or, better, merge into it with $hub-accents-extra.
+$hub-accents: (
 	primary: var(--hub-ref-color-blue-500, #0d6efd),
+	secondary: var(--hub-ref-color-gray-600, #6c757d),
 	success: var(--hub-ref-color-green-500, #198754),
 	danger:  var(--hub-ref-color-red-500, #dc3545),
 	warning: var(--hub-ref-color-yellow-500, #ffc107),
-	info:    var(--hub-ref-color-cyan-500, #0dcaf0)
-);
-
-// Sets ONLY --hub-sys-color-<variant> (the accent). Called in every theme block.
+	info:    var(--hub-ref-color-cyan-500, #0dcaf0),
+	neutral: var(--hub-ref-color-gray-600, #6c757d),
+	light:   var(--hub-ref-color-gray-100, #f8f9fa),
+	dark:    var(--hub-ref-color-gray-900, #212529)
+) !default;
+
+// Additive override — pass ONLY the variants you add or retune, keep the defaults.
+$hub-accents-extra: () !default;
+$hub-accents: map.merge($hub-accents, $hub-accents-extra);
+
+// Sets ONLY --hub-sys-color-<variant> (the accent). Called in every theme block
+// with that theme's own map, so a theme emits exactly the variants it re-tints.
 @mixin hub-color-accents($accents) {
-	@each $name in $hub-variants {
-		--hub-sys-color-#{$name}: #{map.get($accents, $name)};
+	@each $name, $color in $accents {
+		--hub-sys-color-#{$name}: #{$color};
 	}
 }
 
 // Derives the role family from the live accent + surface + ink. Emitted ONCE in
-// :root; themes only override the inputs, so the family recomputes contextually.
+// :root over the open set, so every variant — including the ones you added — gets
+// its full family for free.
 @mixin hub-color-derive() {
-	@each $name in $hub-variants {
+	@each $name in map.keys($hub-accents) {
 		--hub-sys-color-#{$name}-subtle:        color-mix(in oklch, var(--hub-sys-color-#{$name}) 12%, var(--hub-sys-surface-page, #fff));
 		--hub-sys-color-#{$name}-border-subtle: color-mix(in oklch, var(--hub-sys-color-#{$name}) 35%, var(--hub-sys-surface-page, #fff));
 		--hub-sys-color-#{$name}-emphasis:      color-mix(in oklch, var(--hub-sys-color-#{$name}) 80%, var(--hub-sys-color-ink, #212529));
-		--hub-sys-color-#{$name}-dark:          var(--hub-sys-color-#{$name}-emphasis); // back-compat alias
+		// Grayscale contrast flip driven by the accent's own lightness: dark accents
+		// (L < .62) resolve to white text, light accents to near-black.
+		--hub-sys-color-#{$name}-on:            oklch(from var(--hub-sys-color-#{$name}) clamp(0, (0.62 - l) * 1000, 1) 0 h);
 	}
 }
 
 :root,
 [data-theme='light'] {
-	@include hub-color-accents($hub-accents-light);
+	@include hub-color-accents($hub-accents);
 	@include hub-color-derive();
 }
 ```
 
 > You almost never need to touch the SCSS: because the family is derived from the
 > **single accent** at runtime, overriding `--hub-sys-color-<variant>` in plain CSS
-> — even on a subtree — recomputes `-subtle` / `-border-subtle` / `-emphasis`
-> automatically. The maps + mixins are just the internal mechanism, useful if you
-> contribute to the package or compile your own palette variant.
+> — even on a subtree — recomputes `-subtle` / `-border-subtle` / `-emphasis` /
+> `-on` automatically. The maps + mixins are just the internal mechanism, useful if
+> you contribute to the package or compile your own palette variant.
 
 ---