@ids-group-ltd/ids-design-system 0.1.0

package/themes/README.md

@@ -0,0 +1,96 @@
+# Themes — palette + role assignments
+
+Colour lives in two files here: a **palette** (defines the concrete colours) and a **theme** (assigns them to semantic roles). The geometry/component layer is separate (`../styles/_tokens.scss`).
+
+## Architecture: three tiers
+
+| Tier | Lives in | Examples | Consumers |
+|---|---|---|---|
+| **Tier 1 — Palette** (defines colours) | `themes/<name>/_palette.scss` | `--blue-600`, `--cool-gray-0`, `--brand-gray-500`, `--red-500`, `--blue-h/s/l`, `--shadow-tint-h/s/l` | Only the theme file |
+| **Tier 2 — Theme** (sets roles) | `themes/<name>/_theme.scss` | `--primary: var(--blue-600)`, `--text-primary`, `--surface-default`, `--success`, `--focus-ring`, `--primary-h: var(--blue-h)`, font families; the `--neutral-*` family slot (cool-gray by default, brand-gray via `[data-neutrals="brand"]`) | Components |
+| **Tier 3 — Component / scale** | `styles/_tokens.scss` and inside `*.component.scss` | `--space-*`, `--radius-*`, `--ds-button-bg`, `--duration-fast`, `--layer-modal` | Components (their own) |
+
+**Hard rule:** components NEVER consume Tier 1 palette directly. If you write `var(--blue-600)` inside `button.component.scss`, that's a bug — introduce or reuse a Tier 2 role.
+
+**Why split palette from theme:** the palette says *what colours exist*; the theme says *what each role is*. A dark theme ships a different palette (different ramp values) + a theme map that re-points roles. Swapping either re-skins the system without touching components.
+
+## Available palette + theme
+
+- **`default/_palette.scss`** — Blue + slate ramps (the concrete colours).
+- **`default/_theme.scss`** — Light role map onto the default palette. Both are bundled into `styles/ds.scss` (palette → theme → tokens) so `@use 'styles/ds';` works out of the box.
+
+Future (each a `themes/<name>/` folder with `_palette.scss` + `_theme.scss`):
+- `themes/dark/` — Dark-mode flip (`--shadow-tint-l` → ~95%, neutrals inverted, etc.).
+- `themes/high-contrast/` — A11y boost.
+
+## How a consumer picks a theme
+
+### Option A — out-of-the-box default
+
+```scss
+// Consumer styles.scss
+@use 'styles/ds';   // bundles default palette + theme + tokens + reset + ...
+```
+
+### Option B — explicit theme choice
+
+```scss
+// Consumer styles.scss
+@use 'themes/dark/palette';      // pick a non-default theme: palette …
+@use 'themes/dark/theme';        // … then its role map
+@use 'styles/tokens';
+@use 'styles/reset';
+@use 'styles/typography';
+@use 'styles/scrollbar';
+@use 'styles/icon-base';
+@use 'styles/dropdown-overlay';
+```
+
+Palette + theme must come BEFORE `tokens` so role aliases resolve.
+
+### Option C — brand layer on top of default theme
+
+```scss
+// Consumer styles.scss
+@use 'styles/ds';                        // default theme + DS
+@use './app/styles/brand-manage-my';     // overrides palette/roles via [data-brand]
+```
+
+This is the mm-broker pattern: load DS (default theme included), then overlay a brand at a more-specific selector (`[data-brand="manage-my"]`).
+
+## Brand vs theme — what's the difference?
+
+- **Theme** swaps the entire Tier 1 palette. Affects EVERY semantic role downstream.
+- **Brand** is a thin overlay scoped via attribute selector (`[data-brand="X"]`). Usually overrides a smaller subset (key palette stops + maybe a few roles).
+
+Same mechanism (CSS custom properties + cascade), different scope.
+
+## Adding a new theme
+
+1. Create a `themes/<name>/` folder with `_palette.scss` (ramps + HSL channels) and `_theme.scss` (role map), mirroring `themes/default/`.
+2. Optionally add it to `styles/ds.scss` if it should be a default-bundled option.
+3. Or let consumers `@use 'themes/<name>/palette'; @use 'themes/<name>/theme';` directly.
+
+Components don't need any change — they consume semantic roles which automatically pick up the new palette.
+
+## Adding a new brand override
+
+1. Create `<consumer-app>/src/app/styles/_brand-X.scss`.
+2. Open with `[data-brand="X"] { ... }`.
+3. Override:
+   - **Palette HSL channels** (`--blue-h/s/l`) — for focus rings and halos that compose hsla() from channels (the theme bridges `--primary-h: var(--blue-h)`).
+   - **Blue ramp** (`--blue-50..900`) — single source of truth. All brand-derived roles (`--primary`, `--primary-strong`, `--primary-subtle`, `--primary-muted-strong`, `--text-link`, `--surface-tint`) automatically retint. **Do NOT also override the `--primary-*` roles directly — that's redundant.**
+   - Other roles you want to retint independently (surfaces, borders, text, success/danger ramps, secondary, etc.).
+4. Apply via `<html data-brand="X">` on the host app.
+
+## Rules summary
+
+- Components NEVER reference `var(--blue-600)` / `var(--neutral-200)` / `var(--red-500)` directly. Use a Tier 2 role (`--primary`, `--text-secondary`) or a Tier 3 component token.
+- Themes own palette. Brands overlay on top via `[data-brand]`.
+- Theme switching = swap one `@use 'themes/X'`. No component changes.
+- `--primary-hover`, `--primary-pressed` are auto-derived via `color-mix()`. Don't override unless brand needs non-derived hover.
+- Audit guard (suggested pre-commit hook):
+  ```bash
+  grep -nE 'var\(--(violet|neutral|red|green|yellow|blue|orange|cyan|magenta)-[0-9]+\)' \
+    prototype/ds/src/lib/components/**/*.scss && exit 1
+  ```

package/themes/default/_palette.scss

@@ -0,0 +1,159 @@
+// =========================================================================
+// Default palette — Tier 1 concrete colour primitives.
+//
+// This file DEFINES the colours: raw ramps (--cool-gray-*, --brand-gray-*,
+// --blue-*, --red-*, --green-*, --yellow-*, --sky-*, --orange-*) + the HSL
+// channels (--blue-h/s/l, --red-h/s/l, --shadow-tint-h/s/l) they compose from.
+// Tokens are named by the COLOUR itself — the palette does not know what a
+// colour is "for". The --neutral-* FAMILY SLOT (which gray ramp is active)
+// is semantic, so it lives in the theme (_theme.scss), not here.
+//
+// The companion theme (themes/default/_theme.scss) SETS these onto semantic
+// roles (--primary → --blue-600, --error → --red-500, …). Components consume
+// only those roles, never this palette directly.
+//
+// A sibling palette (e.g. _palette-dark.scss) ships different ramp values; pair
+// it with a matching theme file. Default = "Blue + Slate baseline".
+// =========================================================================
+
+:root {
+  // -----------------------------------------------------------------------
+  // Cool gray ramp (13 stops) — hand-drawn slate-family gray. The hue drifts
+  // 210 → 227 toward the brand hue (229) as it darkens; chroma follows a
+  // designed U-curve (S 40% → 12% → 37%). Appearance name, Carbon-style.
+  // -----------------------------------------------------------------------
+  --cool-gray-0:   #FFFFFF;
+  --cool-gray-50:  #F8FAFC;
+  --cool-gray-100: #F1F4F9;
+  --cool-gray-150: #E8ECF2;
+  --cool-gray-200: #DCE1EA;
+  --cool-gray-300: #C2C9D6;
+  --cool-gray-400: #9BA3B4;
+  --cool-gray-500: #6B7388;
+  --cool-gray-600: #4D5468;
+  --cool-gray-700: #353B4D;
+  --cool-gray-800: #232838;
+  --cool-gray-900: #161A28;
+  --cool-gray-950: #0B0E18;
+
+  // -----------------------------------------------------------------------
+  // Brand gray ramp (13 stops) — derived, M3-style: the cool-gray S/L curve
+  // and hue drift are kept, but the hue source is --neutral-h (defaults to
+  // the brand hue). Re-skinning --primary-h re-tints these grays to match
+  // the brand automatically. With the default blue brand this ramp matches
+  // cool-gray to within rounding.
+  // -----------------------------------------------------------------------
+  --neutral-h: var(--primary-h, var(--blue-h));
+  --brand-gray-0:   #FFFFFF;
+  --brand-gray-50:  hsl(calc(var(--neutral-h) - 19), 40.0%, 98.0%);
+  --brand-gray-100: hsl(calc(var(--neutral-h) - 12), 40.0%, 96.1%);
+  --brand-gray-150: hsl(calc(var(--neutral-h) - 13), 27.8%, 92.9%);
+  --brand-gray-200: hsl(calc(var(--neutral-h) - 10), 25.0%, 89.0%);
+  --brand-gray-300: hsl(calc(var(--neutral-h) - 10), 19.6%, 80.0%);
+  --brand-gray-400: hsl(calc(var(--neutral-h) - 8),  14.3%, 65.7%);
+  --brand-gray-500: hsl(calc(var(--neutral-h) - 6),  11.9%, 47.6%);
+  --brand-gray-600: hsl(calc(var(--neutral-h) - 5),  14.9%, 35.5%);
+  --brand-gray-700: hsl(calc(var(--neutral-h) - 4),  18.5%, 25.5%);
+  --brand-gray-800: hsl(calc(var(--neutral-h) - 3),  23.1%, 17.8%);
+  --brand-gray-900: hsl(calc(var(--neutral-h) - 2),  29.0%, 12.2%);
+  --brand-gray-950: hsl(calc(var(--neutral-h) - 3),  37.1%, 6.9%);
+
+  // -----------------------------------------------------------------------
+  // Blue — defined as HSL channels so we can compose hsla() halos and tints
+  // from the same source. #2F54FF ≈ hsl(229, 100%, 59%). This is the ramp the
+  // default theme maps --primary onto (see styles/_tokens.scss). Naming is
+  // concrete (the colour) — the semantic --primary mapping lives in the lib.
+  // -----------------------------------------------------------------------
+  --blue-h: 229;
+  --blue-s: 100%;
+  --blue-l: 59%;
+
+  --blue-50:  hsl(var(--blue-h), 100%, 97%);
+  --blue-100: hsl(var(--blue-h),  95%, 94%);
+  --blue-200: hsl(var(--blue-h),  95%, 89%);
+  --blue-300: hsl(var(--blue-h),  98%, 82%);
+  --blue-400: hsl(var(--blue-h), 100%, 75%);
+  --blue-500: hsl(var(--blue-h), 100%, 66%);
+  --blue-600: hsl(var(--blue-h), var(--blue-s), var(--blue-l));
+  --blue-700: hsl(var(--blue-h),  85%, 52%);
+  --blue-800: hsl(var(--blue-h),  79%, 40%);
+  --blue-900: hsl(var(--blue-h),  77%, 30%);
+
+  // -----------------------------------------------------------------------
+  // Orange — focus / secondary signal
+  // -----------------------------------------------------------------------
+  --orange-50:  #FFF7F0;
+  --orange-100: #FFEEDF;
+  --orange-200: #FFD9B8;
+  --orange-300: #FFC59C;
+  --orange-400: #FF9755;
+  --orange-500: #FF7A2E;
+  --orange-600: #E8631A;
+  --orange-700: #B84812;
+  --orange-800: #8A340A;
+
+  // -----------------------------------------------------------------------
+  // Green — success
+  // -----------------------------------------------------------------------
+  --green-50:  #ECFAEE;
+  --green-100: #D6F3DB;
+  --green-200: #BBE8C2;
+  --green-300: #8EDA9A;
+  --green-400: #4FC368;
+  --green-500: #22A33A;
+  --green-600: #1B8A2E;
+  --green-700: #156822;
+
+  // -----------------------------------------------------------------------
+  // Yellow — attention / warning
+  // -----------------------------------------------------------------------
+  --yellow-50:  #FFFBEA;
+  --yellow-100: #FEF8DC;
+  --yellow-200: #FCEFA1;
+  --yellow-300: #F9E25F;
+  --yellow-400: #F4D43A;
+  --yellow-500: #E0BE00;
+  --yellow-600: #B89B00;
+  --yellow-700: #8A7400;
+
+  // -----------------------------------------------------------------------
+  // Red — HSL-channel-split for halo derivation. #D81F1F ≈ hsl(0, 75%, 49%).
+  // The default theme maps --error onto this ramp (see styles/_tokens.scss).
+  // -----------------------------------------------------------------------
+  --red-h: 0;
+  --red-s: 75%;
+  --red-l: 49%;
+
+  --red-50:  hsl(var(--red-h), 86%, 97%);
+  --red-100: hsl(var(--red-h), 86%, 95%);
+  --red-200: hsl(var(--red-h), 86%, 88%);
+  --red-300: hsl(var(--red-h), 84%, 76%);
+  --red-400: hsl(var(--red-h), 87%, 57%);
+  --red-500: hsl(var(--red-h), var(--red-s), var(--red-l));
+  --red-600: hsl(var(--red-h), 78%, 41%);
+  --red-700: hsl(var(--red-h), 78%, 31%);
+
+  // -----------------------------------------------------------------------
+  // Sky — info role ramp. A brighter, cooler blue (#3B82F6) kept distinct
+  // from the primary --blue ramp (#2F54FF) so "informational" reads apart
+  // from "primary action".
+  // -----------------------------------------------------------------------
+  --sky-50:  #EFF6FF;
+  --sky-100: #DBEAFE;
+  --sky-200: #BFDBFE;
+  --sky-300: #93C5FD;
+  --sky-400: #60A5FA;
+  --sky-500: #3B82F6;
+  --sky-600: #2563EB;
+  --sky-700: #1D4ED8;
+
+  // -----------------------------------------------------------------------
+  // Shadow tint — channel-split substrate. Light theme uses a cool
+  // near-black slate (225 / 39% / 7%). A dark theme would override
+  // --shadow-tint-l to ~95% so the same alphas render as soft light
+  // glows over dark surfaces.
+  // -----------------------------------------------------------------------
+  --shadow-tint-h: 225;
+  --shadow-tint-s: 39%;
+  --shadow-tint-l: 7%;
+}

package/themes/default/_theme.scss

@@ -0,0 +1,274 @@
+// =========================================================================
+// Default theme — Tier 2 semantic role ASSIGNMENTS (light).
+//
+// The palette (themes/default/_palette.scss) DEFINES the concrete colours
+// (--blue-*, --red-*, --neutral-*, … + HSL channels). THIS file SETS them
+// onto semantic roles (--primary → --blue-600, --surface-canvas → --neutral-50,
+// --error → --red-500, …). Components consume only these roles, never the
+// palette directly — so swapping the palette, or re-mapping here, re-skins the
+// whole system. A sibling theme (e.g. dark) ships its own palette + this map.
+//
+// Tier 3 (component-scoped tokens, geometry, typography, motion) lives in
+// styles/_tokens.scss and is theme-independent.
+// =========================================================================
+
+:root {
+  /* Neutral family slot — semantic pointer at the active gray ramp from the
+     palette. Default: hand-drawn cool-gray. <html data-neutrals="brand">
+     (ds-docs tweaks panel) repoints it at the brand-derived brand-gray ramp,
+     where --primary-h re-tints every gray. Roles below consume --neutral-*
+     so the family switch never touches them. */
+  --neutral-0:   var(--cool-gray-0);
+  --neutral-50:  var(--cool-gray-50);
+  --neutral-100: var(--cool-gray-100);
+  --neutral-150: var(--cool-gray-150);
+  --neutral-200: var(--cool-gray-200);
+  --neutral-300: var(--cool-gray-300);
+  --neutral-400: var(--cool-gray-400);
+  --neutral-500: var(--cool-gray-500);
+  --neutral-600: var(--cool-gray-600);
+  --neutral-700: var(--cool-gray-700);
+  --neutral-800: var(--cool-gray-800);
+  --neutral-900: var(--cool-gray-900);
+  --neutral-950: var(--cool-gray-950);
+
+  /* Surfaces — six-stop scale.
+     · canvas    : page background
+     · default   : cards, sheets, toolbars (the “paper”)
+     · secondary : hover lanes, table heads, addons, code blocks
+     · overlay   : modals, drawers, popovers (paired with scrim)
+     · tint      : brand-tinted (active rows, sidenav active item)
+     · inverted  : dark-on-light callouts, toasts
+     Conceptual elevation is communicated by SHADOW tokens,
+     not by surface tokens. Hover/pressed states use
+     --opacity-state-* overlays on top of the underlying surface. */
+  --surface-canvas:         var(--neutral-50);
+  --surface-default:        var(--neutral-0);
+  --surface-secondary:      var(--neutral-100);
+  --surface-overlay:        var(--neutral-0);
+  --surface-inverted:       var(--neutral-900);
+  --surface-inverted-hover: var(--neutral-800);
+  --surface-tint:           var(--blue-50);
+  --surface-disabled:       var(--neutral-100);
+  --surface-muted:          var(--neutral-150);
+
+  /* Scrim — modal/drawer backdrop. Derived from inverted surface
+     so dark-mode override flips automatically. */
+  --surface-scrim:     hsla(var(--shadow-tint-h), var(--shadow-tint-s), var(--shadow-tint-l), .55);
+
+  /* Visible-on-coloured-fill divider. The split-button right-hand chevron
+     sits ON the brand fill, so a transparent white hairline reads correctly
+     across any brand hue. Override per theme if the brand is too light. */
+  --btn-split-divider: hsla(0, 0%, 100%, .25);
+
+  /* Visited link — derives from --primary-muted by default so it sympathetically
+     shifts with the brand hue. Override (e.g. for financial dashboards that
+     want neutral-grey visited links) by setting this token directly. */
+  --link-visited:      hsl(var(--primary-h) calc(var(--primary-s) * 0.6) 45%);
+
+  /* Borders */
+  --border-default:    var(--neutral-200);
+  --border-strong:     var(--neutral-300);
+  --border-subtle:     var(--neutral-150);
+  --border-divider:    var(--neutral-150);
+  --border-inverted:   var(--neutral-700);
+  --border-disabled:   var(--neutral-150);
+
+  /* Text */
+  --text-primary:      var(--neutral-900);
+  --text-secondary:    var(--neutral-700);
+  --text-tertiary:     var(--neutral-500);
+  --text-muted:        var(--neutral-400);
+  --text-disabled:     var(--neutral-400);
+  --text-inverted:     var(--neutral-0);
+  /* Text overlaid on arbitrary imagery (camera feeds, photos) — pairs a
+     guaranteed-light colour with a contrast shadow. */
+  --text-on-media:        var(--neutral-0);
+  --text-on-media-shadow: 0 1px 3px hsla(0, 0%, 0%, .7);
+  --text-link:         var(--blue-700);
+  --text-on-primary:     var(--neutral-0);
+  --text-on-success:   var(--neutral-0);
+  /* Warning fill is yellow (--yellow-400 #F4D43A) — white text on it is only
+     ~1.5:1 (fails WCAG). On-warning text is the darkest neutral (~10:1). */
+  --text-on-warning:   var(--neutral-900);
+  --text-on-error:     var(--neutral-0);
+
+  /* Icons */
+  --icon-default:      var(--neutral-500);
+  --icon-strong:       var(--neutral-700);
+  --icon-muted:        var(--neutral-400);
+  --icon-on-primary:     var(--neutral-0);
+
+  /* Font families — a theme/brand choice (the size/weight/leading SCALE is
+     theme-independent and lives in styles/_tokens.scss). Display + heading
+     default to body sans; a brand can mix a serif/display family here without
+     touching component code. */
+  --font-sans:    "Mulish", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  --font-mono:    "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
+  --font-display: var(--font-sans);
+  --font-heading: var(--font-sans);
+
+  /* Semantic → palette bridge. The lib knows colours by PURPOSE; the theme
+     (themes/default/_theme.scss) ships the concrete ramps + HSL channels. This
+     is the one place that maps semantic roles onto a concrete palette. A brand
+     re-skins by overriding either the palette (--blue-*, --red-*) or these
+     role tokens directly.
+     Channel mappings let hsla() halos/tints compose from the same hue source. */
+  --primary-h:  var(--blue-h);
+  --primary-s:  var(--blue-s);
+  --primary-l:  var(--blue-l);
+  --error-h:    var(--red-h);
+  --error-s:    var(--red-s);
+  --error-l:    var(--red-l);
+
+  /* Primary roles.
+     Hover / pressed / selected-hover are DERIVED from --primary at runtime via
+     color-mix() so a brand swap (overriding only --primary) propagates to every
+     interaction state automatically. A brand that wants a non-derived hover
+     hue can still override these tokens directly.
+     Step sizes (12% / 24% darker) mirror the blue 600→700→800 ramp. */
+  --primary:                 var(--blue-600);
+  --primary-hover:           color-mix(in srgb, var(--primary) 88%, black);
+  --primary-pressed:         color-mix(in srgb, var(--primary) 76%, black);
+  --primary-selected-hover:  color-mix(in srgb, var(--primary) 88%, black);
+  --primary-subtle:          var(--blue-50);
+  --primary-muted:           var(--blue-100);
+  --primary-muted-strong:    var(--blue-200);
+  --primary-strong:          var(--blue-700);
+  --primary-on:              var(--neutral-0);
+
+  /* Accent / secondary role — composed from --secondary-h/s/l channels.
+     Channels default to brand values so unbranded apps render identical to
+     --primary. Override --secondary-h/s/l per-brand (or via the tweaks panel)
+     to introduce a true secondary hue — --secondary recomposes automatically.
+     Hover/pressed derive from --secondary so any hue change propagates. */
+  --secondary-h:       var(--primary-h);
+  --secondary-s:       var(--primary-s);
+  --secondary-l:       var(--primary-l);
+
+  --secondary:         hsl(var(--secondary-h), var(--secondary-s), var(--secondary-l));
+  --secondary-hover:   color-mix(in srgb, var(--secondary) 88%, black);
+  --secondary-pressed: color-mix(in srgb, var(--secondary) 76%, black);
+  --secondary-strong:  hsl(var(--secondary-h), var(--secondary-s), calc(var(--secondary-l) - 11%));
+  --secondary-subtle:  hsl(var(--secondary-h), 100%, 97%);
+  --secondary-muted:   hsl(var(--secondary-h), 95%, 94%);
+  --secondary-on:      var(--primary-on);
+
+  /* Tertiary — third brand hue. Used by the tertiary button variant and
+     tonal accents (decorative chips, hierarchy tones, indicators). Mirrors
+     the --primary / --secondary token-family shape: HSL channels for halo
+     composition, hover/pressed via color-mix, subtle/muted ramps for tonal
+     surfaces. Defaults to --primary channels so single-hue themes render
+     identical to primary. Multi-hue brands override --tertiary-h/s/l (or
+     --tertiary directly for non-HSL values). */
+  --tertiary-h:       var(--primary-h);
+  --tertiary-s:       var(--primary-s);
+  --tertiary-l:       var(--primary-l);
+
+  --tertiary:         hsl(var(--tertiary-h), var(--tertiary-s), var(--tertiary-l));
+  --tertiary-hover:   color-mix(in srgb, var(--tertiary) 88%, black);
+  --tertiary-pressed: color-mix(in srgb, var(--tertiary) 76%, black);
+  --tertiary-strong:  hsl(var(--tertiary-h), var(--tertiary-s), calc(var(--tertiary-l) - 11%));
+  --tertiary-subtle:  hsl(var(--tertiary-h), 100%, 97%);
+  --tertiary-muted:   hsl(var(--tertiary-h), 95%, 94%);
+  --tertiary-on:      var(--primary-on);
+
+  /* Status roles.
+     -hover / -pressed are derived from the base role via the same color-mix()
+     rule as --primary-hover. Override per role if a brand needs a non-derived
+     hue. -text / -border / -subtle / -muted stay as ramp picks because their
+     contrast targets are tuned, not procedural. */
+  --success:           var(--green-500);
+  --success-hover:     color-mix(in srgb, var(--success) 88%, black);
+  --success-subtle:    var(--green-50);
+  --success-muted:     var(--green-100);
+  --success-border:    var(--green-200);
+  --success-text:      var(--green-700);
+
+  --warning:           var(--yellow-400);
+  --warning-hover:     color-mix(in srgb, var(--warning) 88%, black);
+  --warning-subtle:    var(--yellow-50);
+  --warning-muted:     var(--yellow-100);
+  --warning-border:    var(--yellow-200);
+  --warning-text:      var(--yellow-700);
+
+  --error:            var(--red-500);
+  --error-hover:      color-mix(in srgb, var(--error) 88%, black);
+  --error-pressed:    color-mix(in srgb, var(--error) 76%, black);
+  --error-subtle:     var(--red-50);
+  --error-muted:      var(--red-100);
+  --error-border:     var(--red-200);
+  --error-text:       var(--red-600);
+
+  --info:              var(--sky-500);
+  --info-hover:        color-mix(in srgb, var(--info) 88%, black);
+  --info-subtle:       var(--sky-50);
+  --info-muted:        var(--sky-100);
+  --info-border:       var(--sky-200);
+  --info-text:         var(--sky-700);
+
+  /* Status pills (event lifecycle).
+     DECISION: --status-confirmed-* chains through --primary-* so a
+     brand re-skin moves Confirmed with it. The other lifecycle
+     stages are deliberately neutral/green/dark to keep semantic
+     distance from brand. */
+  /* Status pills — canonical (single system).
+     Legacy classes `.badge--active` (single) and ad-hoc semantic
+     pills are unified in the Badge component to consume these tokens. */
+  --status-planning-bg:   var(--neutral-150);
+  --status-planning-fg:   var(--neutral-700);
+  --status-confirmed-bg:  var(--primary-subtle);
+  --status-confirmed-fg:  var(--primary-strong);
+  --status-active-bg:     var(--green-50);
+  --status-active-fg:     var(--green-700);
+  --status-completed-bg:  var(--neutral-900);
+  --status-completed-fg:  var(--neutral-0);
+
+  /* Focus rings.
+     Outer halos use hsla() composed from brand/danger HSL channels
+     so re-skinning --primary-h propagates into focus state.
+     The inner halo reads --surface-canvas so the ring stays visible
+     in both light and dark themes (canvas flips, ring adapts). */
+  --focus-ring-inner:        var(--surface-canvas);
+  --focus-ring-outer-h:      var(--primary-h);
+  --focus-ring-outer-s:      var(--primary-s);
+  --focus-ring-outer-l:      var(--primary-l);
+  --focus-ring-outer-alpha:  1;
+
+  --focus-ring:
+    0 0 0 2px var(--focus-ring-inner),
+    0 0 0 4px hsla(var(--focus-ring-outer-h), var(--focus-ring-outer-s), var(--focus-ring-outer-l), var(--focus-ring-outer-alpha));
+  --focus-ring-inverted:
+    0 0 0 2px var(--neutral-900),
+    0 0 0 4px var(--blue-300);
+  --focus-ring-error:
+    0 0 0 2px var(--focus-ring-inner),
+    0 0 0 4px hsla(var(--error-h), var(--error-s), var(--error-l), 1);
+
+  /* Field focus — coloured halo only (no double-ring). Derived from
+     brand HSL so it tracks rebrand. Alpha is a token so dark themes
+     can boost it for legibility. */
+  --focus-field-alpha: .22;
+  --focus-field:
+    0 0 0 3px hsla(var(--primary-h), var(--primary-s), var(--primary-l), var(--focus-field-alpha));
+  --focus-field-error:
+    0 0 0 3px hsla(var(--error-h), var(--error-s), var(--error-l), var(--focus-field-alpha));
+}
+
+/* Brand-derived neutrals — opt-in family switch (ds-docs tweaks panel sets
+   the attribute). Repoints the --neutral-* slot at the brand-gray ramp. */
+:root[data-neutrals='brand'] {
+  --neutral-0:   var(--brand-gray-0);
+  --neutral-50:  var(--brand-gray-50);
+  --neutral-100: var(--brand-gray-100);
+  --neutral-150: var(--brand-gray-150);
+  --neutral-200: var(--brand-gray-200);
+  --neutral-300: var(--brand-gray-300);
+  --neutral-400: var(--brand-gray-400);
+  --neutral-500: var(--brand-gray-500);
+  --neutral-600: var(--brand-gray-600);
+  --neutral-700: var(--brand-gray-700);
+  --neutral-800: var(--brand-gray-800);
+  --neutral-900: var(--brand-gray-900);
+  --neutral-950: var(--brand-gray-950);
+}