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

package/styles/ds.scss

@@ -1,27 +1,27 @@
-// Public DS stylesheet entry. Consumers import once at the top of their styles.scss:
-//   @use 'styles/ds';
-//
-// Bundles the default palette + theme for out-of-the-box rendering. Layers:
-//   default/palette — Tier 1 concrete colours (ramps + HSL channels)
-//   default/theme   — Tier 2 semantic role → palette assignments + font families
-//   tokens          — Tier 3 geometry / typography scale / motion / component tokens
-// Advanced consumers can swap the palette/theme and keep tokens — global
-// side-effects (fonts, link) are then opt-in:
-//   @use 'themes/X/palette'; @use 'themes/X/theme'; @use 'styles/tokens';
-//   @use 'styles/fonts'; @use 'styles/link'; …
-
-@forward '../themes/default/palette';
-@forward '../themes/default/theme';
-@forward 'tokens';
-@forward 'tokens-charts';
-@forward 'fonts';
-@forward 'reset';
-@forward 'typography';
-@forward 'link';
-@forward 'layout-utils';
-@forward 'page-grid';
-@forward 'scrollbar';
-@forward 'icon-base';
-@forward 'dropdown-overlay';
-@forward 'toast-overlay';
-@forward 'skeleton-shimmer';
+// Public DS stylesheet entry. Consumers import once at the top of their styles.scss:
+//   @use 'styles/ds';
+//
+// Bundles the default palette + theme for out-of-the-box rendering. Layers:
+//   default/palette — Tier 1 concrete colours (ramps + HSL channels)
+//   default/theme   — Tier 2 semantic role → palette assignments + font families
+//   tokens          — Tier 3 geometry / typography scale / motion / component tokens
+// Advanced consumers can swap the palette/theme and keep tokens — global
+// side-effects (fonts, link) are then opt-in:
+//   @use 'themes/X/palette'; @use 'themes/X/theme'; @use 'styles/tokens';
+//   @use 'styles/fonts'; @use 'styles/link'; …
+
+@forward '../themes/default/palette';
+@forward '../themes/default/theme';
+@forward 'tokens';
+@forward 'tokens-charts';
+@forward 'fonts';
+@forward 'reset';
+@forward 'typography';
+@forward 'link';
+@forward 'layout-utils';
+@forward 'page-grid';
+@forward 'scrollbar';
+@forward 'icon-base';
+@forward 'dropdown-overlay';
+@forward 'toast-overlay';
+@forward 'skeleton-shimmer';

package/themes/README.md

@@ -1,96 +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
-  ```
+# 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`) — the simplest re-skin lever. All brand-derived roles (`--primary`, `--primary-strong`, `--primary-subtitle`, `--primary-muted-strong`, `--text-link`, `--surface-tint`) retint automatically from it. For a fully calibrated brand you MAY also set the `--primary-*` roles directly to hand-picked hex (when ramp derivation doesn't hit the exact stop) — see `_brand-manage-my.scss`. Leave `--primary-hover`/`--primary-pressed` to the DS `color-mix()` derivation.
+   - 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

@@ -1,159 +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%;
-}
+// =========================================================================
+// 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%;
+}