@ids-group-ltd/ids-design-system 0.2.2 → 0.4.0

package/themes/{default/_palette.scss → _base-palette.scss}

@@ -1,19 +1,14 @@
 // =========================================================================
-// Default palette — Tier 1 concrete colour primitives.
+// Base palette — Tier 1 theme-independent 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.
+// Emits at :root. Colour ramps and channels that are identical in every
+// theme: hue ramps (--cool-gray-*, --brand-gray-*, --blue-*, --red-*, …),
+// HSL channels (--blue-h/s/l, --red-h/s/l), shadow substrate h/s (NOT -l —
+// that is per-theme), static anchors, and font families.
 //
-// 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".
+// The --neutral-* FAMILY SLOT (which gray ramp is active) is per-theme and
+// lives in each theme's _palette.scss mixin. Components consume only semantic
+// roles; they never reference this file directly.
 // =========================================================================
 
 :root {
@@ -22,7 +17,7 @@
   // 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-0:   #FFF;
   --cool-gray-50:  #F8FAFC;
   --cool-gray-100: #F1F4F9;
   --cool-gray-150: #E8ECF2;
@@ -44,19 +39,19 @@
   // 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%);
+  --brand-gray-0:   #FFF;
+  --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
@@ -68,16 +63,16 @@
   --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%);
+  --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
@@ -95,6 +90,9 @@
   // -----------------------------------------------------------------------
   // Green — success
   // -----------------------------------------------------------------------
+  // HSL channels (additive — for focus-ring composition + ds-color). The ramp
+  // stops below stay hand-picked hex; these reproduce --green-500 ≈ #22A33A.
+  --green-h: 132; --green-s: 66%; --green-l: 39%;
   --green-50:  #ECFAEE;
   --green-100: #D6F3DB;
   --green-200: #BBE8C2;
@@ -107,6 +105,9 @@
   // -----------------------------------------------------------------------
   // Yellow — attention / warning
   // -----------------------------------------------------------------------
+  // HSL channels (additive — for focus-ring composition + ds-color). Reproduce
+  // --yellow-400 ≈ #F4D43A; ramp stops below stay hand-picked hex.
+  --yellow-h: 47; --yellow-s: 89%; --yellow-l: 59%;
   --yellow-50:  #FFFBEA;
   --yellow-100: #FEF8DC;
   --yellow-200: #FCEFA1;
@@ -124,14 +125,14 @@
   --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%);
+  --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
@@ -148,12 +149,28 @@
   --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 — channel-split substrate h/s only. The lightness (-l) is
+  // per-theme: light uses 7%, dark uses 95% (so the same alphas read as soft
+  // glows over dark surfaces). Each theme's _palette.scss mixin sets -l.
   // -----------------------------------------------------------------------
   --shadow-tint-h: 225;
   --shadow-tint-s: 39%;
-  --shadow-tint-l: 7%;
+
+  // -----------------------------------------------------------------------
+  // Theme-stable contrast anchors — never flip with the theme. On-fill text/
+  // icon roles point here so a dark theme keeps white-on-coloured-fill correct.
+  // -----------------------------------------------------------------------
+  --static-white: #FFF;
+  --static-ink:   #161A28;
+
+  // -----------------------------------------------------------------------
+  // 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);
 }

package/themes/{default/_theme.scss → _semantic.scss}

@@ -1,40 +1,21 @@
 // =========================================================================
-// Default theme — Tier 2 semantic role ASSIGNMENTS (light).
+// Shared role structure — Tier 2 semantic role ASSIGNMENTS.
 //
-// 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.
+// Exposes @mixin roles: the role map whose structure is identical across
+// themes and which resolves through the per-theme palette (surfaces →
+// --neutral-*, text/icon/border → --neutral-*, brand channels, status, focus,
+// semantic→palette bridge). These are the LIGHT-DEFAULT values — dark theme
+// overrides only the deltas in its own _theme.scss mixin body.
 //
-// Tier 3 (component-scoped tokens, geometry, typography, motion) lives in
-// styles/_tokens.scss and is theme-independent.
+// This mixin is an authoring-DRY device. At runtime, exactly one theme block
+// matches (`:not([data-theme='dark'])` vs `[data-theme='dark']`), and that
+// block declares the complete token set itself (palette + roles + overrides).
 // =========================================================================
 
-: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);
-
+@mixin roles {
   /* Surfaces — six-stop scale.
      · canvas    : page background
-     · default   : cards, sheets, toolbars (the “paper”)
+     · 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)
@@ -54,12 +35,12 @@
 
   /* 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);
+  --surface-scrim:     hsl(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);
+  --btn-split-divider: hsl(0deg 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
@@ -81,35 +62,28 @@
   --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-on-media:        var(--static-white);
+  --text-on-media-shadow: 0 1px 3px hsl(0deg 0% 0% / 70%);
   --text-link:         var(--blue-700);
-  --text-on-primary:     var(--neutral-0);
-  --text-on-success:   var(--neutral-0);
+  --text-on-primary:     var(--static-white);
+  --text-on-success:   var(--static-white);
+
   /* 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);
+  --text-on-warning:   var(--static-ink);
+  --text-on-error:     var(--static-white);
 
   /* 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);
+  --icon-on-primary:     var(--static-white);
 
   /* Semantic → palette bridge. The lib knows colours by PURPOSE; the theme
-     (themes/default/_theme.scss) ships the concrete ramps + HSL channels. This
+     (themes/light/_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.
@@ -120,6 +94,12 @@
   --error-h:    var(--red-h);
   --error-s:    var(--red-s);
   --error-l:    var(--red-l);
+  --success-h:  var(--green-h);
+  --success-s:  var(--green-s);
+  --success-l:  var(--green-l);
+  --warning-h:  var(--yellow-h);
+  --warning-s:  var(--yellow-s);
+  --warning-l:  var(--yellow-l);
 
   /* Primary roles.
      Hover / pressed / selected-hover are DERIVED from --primary at runtime via
@@ -135,7 +115,7 @@
   --primary-muted:           var(--blue-100);
   --primary-muted-strong:    var(--blue-200);
   --primary-strong:          var(--blue-700);
-  --primary-on:              var(--neutral-0);
+  --primary-on:              var(--static-white);
 
   /* Accent / secondary role — composed from --secondary-h/s/l channels.
      Channels default to brand values so unbranded apps render identical to
@@ -146,12 +126,13 @@
   --secondary-s:       var(--primary-s);
   --secondary-l:       var(--primary-l);
 
-  --secondary:         hsl(var(--secondary-h), var(--secondary-s), var(--secondary-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-subtitle:  hsl(var(--secondary-h), 100%, 97%);
-  --secondary-muted:   hsl(var(--secondary-h), 95%, 94%);
+  --secondary-strong:  hsl(var(--secondary-h) var(--secondary-s) calc(var(--secondary-l) - 11%));
+  --secondary-subtitle:  hsl(var(--secondary-h) 100% 97%);
+  --secondary-muted:   hsl(var(--secondary-h) 95% 94%);
+  --secondary-muted-strong: hsl(var(--secondary-h) 95% 89%);
   --secondary-on:      var(--primary-on);
 
   /* Tertiary — third brand hue. Used by the tertiary button variant and
@@ -165,12 +146,13 @@
   --tertiary-s:       var(--primary-s);
   --tertiary-l:       var(--primary-l);
 
-  --tertiary:         hsl(var(--tertiary-h), var(--tertiary-s), var(--tertiary-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-subtitle:  hsl(var(--tertiary-h), 100%, 97%);
-  --tertiary-muted:   hsl(var(--tertiary-h), 95%, 94%);
+  --tertiary-strong:  hsl(var(--tertiary-h) var(--tertiary-s) calc(var(--tertiary-l) - 11%));
+  --tertiary-subtitle:  hsl(var(--tertiary-h) 100% 97%);
+  --tertiary-muted:   hsl(var(--tertiary-h) 95% 94%);
+  --tertiary-muted-strong: hsl(var(--tertiary-h) 95% 89%);
   --tertiary-on:      var(--primary-on);
 
   /* Status roles.
@@ -182,6 +164,7 @@
   --success-hover:     color-mix(in srgb, var(--success) 88%, black);
   --success-subtitle:    var(--green-50);
   --success-muted:     var(--green-100);
+  --success-muted-strong: var(--green-200);
   --success-border:    var(--green-200);
   --success-text:      var(--green-700);
 
@@ -189,6 +172,7 @@
   --warning-hover:     color-mix(in srgb, var(--warning) 88%, black);
   --warning-subtitle:    var(--yellow-50);
   --warning-muted:     var(--yellow-100);
+  --warning-muted-strong: var(--yellow-200);
   --warning-border:    var(--yellow-200);
   --warning-text:      var(--yellow-700);
 
@@ -197,9 +181,18 @@
   --error-pressed:    color-mix(in srgb, var(--error) 76%, black);
   --error-subtitle:     var(--red-50);
   --error-muted:      var(--red-100);
+  --error-muted-strong: var(--red-200);
   --error-border:     var(--red-200);
   --error-text:       var(--red-600);
 
+  /* -pressed (success/warning) + -on aliases — added for the --accent-* pointer
+     family so every ds-color family resolves --accent-pressed / --accent-on. */
+  --success-pressed:  color-mix(in srgb, var(--success) 76%, black);
+  --warning-pressed:  color-mix(in srgb, var(--warning) 76%, black);
+  --error-on:         var(--text-on-error);
+  --success-on:       var(--text-on-success);
+  --warning-on:       var(--text-on-warning);
+
   --info:              var(--sky-500);
   --info-hover:        color-mix(in srgb, var(--info) 88%, black);
   --info-subtitle:       var(--sky-50);
@@ -212,17 +205,18 @@
      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-subtitle);
-  --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);
+  --status-planning-bg-color:   var(--neutral-150);
+  --status-planning-text-color:   var(--neutral-700);
+  --status-confirmed-bg-color:  var(--primary-subtitle);
+  --status-confirmed-text-color:  var(--primary-strong);
+  --status-active-bg-color:     var(--green-50);
+  --status-active-text-color:     var(--green-700);
+  --status-completed-bg-color:  var(--neutral-900);
+  --status-completed-text-color:  var(--neutral-0);
 
   /* Focus rings.
      Outer halos use hsla() composed from brand/danger HSL channels
@@ -237,38 +231,60 @@
 
   --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));
+    0 0 0 4px hsl(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);
+    0 0 0 4px hsl(var(--error-h) var(--error-s) var(--error-l) / 100%);
 
   /* 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));
+    0 0 0 3px hsl(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));
-}
+    0 0 0 3px hsl(var(--error-h) var(--error-s) var(--error-l) / var(--focus-field-alpha));
+
+  /* Per-family focus rings/fields — pre-composed once from each family's
+     channels so ds-color flips a single --accent-focus-* pointer (no :root
+     composite re-declaration in the scope). --focus-ring-error exists above. */
+  --focus-ring-secondary:
+    0 0 0 2px var(--focus-ring-inner),
+    0 0 0 4px hsl(var(--secondary-h) var(--secondary-s) var(--secondary-l) / 100%);
+  --focus-ring-tertiary:
+    0 0 0 2px var(--focus-ring-inner),
+    0 0 0 4px hsl(var(--tertiary-h) var(--tertiary-s) var(--tertiary-l) / 100%);
+  --focus-ring-success:
+    0 0 0 2px var(--focus-ring-inner),
+    0 0 0 4px hsl(var(--success-h) var(--success-s) var(--success-l) / 100%);
+  --focus-ring-warning:
+    0 0 0 2px var(--focus-ring-inner),
+    0 0 0 4px hsl(var(--warning-h) var(--warning-s) var(--warning-l) / 100%);
+  --focus-field-secondary:
+    0 0 0 3px hsl(var(--secondary-h) var(--secondary-s) var(--secondary-l) / var(--focus-field-alpha));
+  --focus-field-tertiary:
+    0 0 0 3px hsl(var(--tertiary-h) var(--tertiary-s) var(--tertiary-l) / var(--focus-field-alpha));
+  --focus-field-success:
+    0 0 0 3px hsl(var(--success-h) var(--success-s) var(--success-l) / var(--focus-field-alpha));
+  --focus-field-warning:
+    0 0 0 3px hsl(var(--warning-h) var(--warning-s) var(--warning-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);
+  /* Accent pointer layer — the single indirection ds-color flips. Defaults to
+     the primary family (+ existing focus/tint tokens) so the unbranded theme is
+     pixel-identical. Components read these for their accent instead of
+     --primary* / --focus-* / --surface-tint. */
+  --accent:               var(--primary);
+  --accent-hover:         var(--primary-hover);
+  --accent-pressed:       var(--primary-pressed);
+  --accent-strong:        var(--primary-strong);
+  --accent-subtitle:      var(--primary-subtitle);
+  --accent-muted:         var(--primary-muted);
+  --accent-muted-strong:  var(--primary-muted-strong);
+  --accent-on:            var(--primary-on);
+  --accent-focus-ring:    var(--focus-ring);
+  --accent-focus-field:   var(--focus-field);
+  --accent-surface-tint:  var(--surface-tint);
 }

package/themes/dark/_palette.scss

@@ -0,0 +1,39 @@
+// =========================================================================
+// Dark palette — Tier 1b per-theme primitives.
+//
+// Exposes @mixin palette with ONLY the dark-specific primitives:
+//   · --neutral-* slot: hand-tuned dark neutrals (NOT a linear inverse —
+//     note --neutral-0 is an ELEVATED card surface, LIGHTER than the
+//     --neutral-50 canvas — the opposite of light, where 0 (#FFF) is the
+//     brightest stop). Brand/status ramps are left to the role layer.
+//   · --shadow-tint-l: 95%  (flipped so same alphas read as soft glows)
+//
+// Theme-independent ramps (--cool-gray-*, --brand-gray-*, --blue-*, etc.)
+// and HSL channels live in themes/_base-palette.scss and emit at :root.
+//
+// KNOWN LIMITATION — data-neutrals="brand" + dark: this ramp overrides
+// --neutral-* directly, so when both `[data-neutrals='brand']` and
+// `[data-theme='dark']` are set (equal specificity) dark wins by source order —
+// the brand-gray hue-tint is dropped and these fixed dark neutrals apply. Benign
+// (renders correctly dark, just not brand-hue-tinted); a dark brand-gray ramp is
+// a future follow-up, not v1.
+// =========================================================================
+
+@mixin palette {
+  --neutral-0:   #171B24; // surface-default / overlay (cards) — elevated
+  --neutral-50:  #0F131A; // surface-canvas — darkest (page bg)
+  --neutral-100: #1E2330; // surface-secondary / disabled
+  --neutral-150: #242A38; // surface-muted, border-subtitle/divider/disabled
+  --neutral-200: #2A3040; // border-default
+  --neutral-300: #3A4252; // border-strong
+  --neutral-400: #6B7388; // text-muted/disabled, icon-muted
+  --neutral-500: #8A93A6; // text-tertiary, icon-default
+  --neutral-600: #9BA3B4;
+  --neutral-700: #B7BFD0; // text-secondary, icon-strong, border-inverted
+  --neutral-800: #CDD3E0;
+  --neutral-900: #E7EAF2; // text-primary, surface-inverted
+  --neutral-950: #F4F6FA;
+
+  // Shadow substrate flips light so the same alphas read as soft glows on dark.
+  --shadow-tint-l: 95%;
+}

package/themes/dark/_theme.scss

@@ -0,0 +1,122 @@
+// =========================================================================
+// Dark theme — Tier 2 role overrides.
+//
+// Composes the dark palette (neutral ramp + shadow-l 95%) with the shared
+// role structure, then overrides only the roles whose VALUES differ from
+// the light defaults. The activation selector (:root[data-theme='dark'])
+// lives in styles/_theme-activation.scss. Dark is opt-in — light is the
+// default; there is no automatic prefers-color-scheme switch.
+//
+// Most roles follow the inverted --neutral-* ramp automatically (custom
+// props resolve at use-time). This file overrides ONLY roles that can't
+// follow the flip: tint/subtle surfaces (near-white *-50 picks → dark hue
+// tints), on-tint text (*-text / *-strong → lighter stops), hover/pressed
+// direction, scrim (must stay dark), focus halo alpha, and charts.
+// On-fill text already points at theme-stable --static-white/--static-ink.
+// =========================================================================
+
+@use 'palette';
+@use '../semantic';
+
+@mixin theme {
+  @include palette.palette;
+  @include semantic.roles;
+
+  // Interaction states: on dark, hover/pressed must LIGHTEN. The default theme
+  // derives them as color-mix toward black (darkens) — wrong direction here.
+  // Mirror the light recipe's 88% / 76% steps, mixed toward white instead.
+  --primary-hover:          color-mix(in srgb, var(--primary) 88%, white);
+  --primary-pressed:        color-mix(in srgb, var(--primary) 76%, white);
+  --primary-selected-hover: color-mix(in srgb, var(--primary) 88%, white);
+  --secondary-hover:        color-mix(in srgb, var(--secondary) 88%, white);
+  --secondary-pressed:      color-mix(in srgb, var(--secondary) 76%, white);
+  --tertiary-hover:         color-mix(in srgb, var(--tertiary) 88%, white);
+  --tertiary-pressed:       color-mix(in srgb, var(--tertiary) 76%, white);
+  --success-hover:          color-mix(in srgb, var(--success) 88%, white);
+  --warning-hover:          color-mix(in srgb, var(--warning) 88%, white);
+  --error-hover:            color-mix(in srgb, var(--error) 88%, white);
+  --error-pressed:          color-mix(in srgb, var(--error) 76%, white);
+  --success-pressed:        color-mix(in srgb, var(--success) 76%, white);
+  --warning-pressed:        color-mix(in srgb, var(--warning) 76%, white);
+  --info-hover:             color-mix(in srgb, var(--info) 88%, white);
+
+  // Brand tint surfaces + on-tint text (channel-derived → track rebrand).
+  --surface-tint:         hsl(var(--primary-h) 45% 16%);
+  --primary-subtitle:     hsl(var(--primary-h) 45% 18%);
+  --primary-muted:        hsl(var(--primary-h) 40% 26%);
+  --primary-muted-strong: hsl(var(--primary-h) 42% 32%);
+  --primary-strong:       hsl(var(--primary-h) 90% 72%);
+
+  --secondary-subtitle:   hsl(var(--secondary-h) 45% 18%);
+  --secondary-muted:      hsl(var(--secondary-h) 40% 26%);
+  --secondary-muted-strong: hsl(var(--secondary-h) 42% 32%);
+  --secondary-strong:     hsl(var(--secondary-h) 90% 72%);
+
+  --tertiary-subtitle:    hsl(var(--tertiary-h) 45% 18%);
+  --tertiary-muted:       hsl(var(--tertiary-h) 40% 26%);
+  --tertiary-muted-strong: hsl(var(--tertiary-h) 42% 32%);
+  --tertiary-strong:      hsl(var(--tertiary-h) 90% 72%);
+
+  --text-link:            hsl(var(--primary-h) 90% 74%);
+  --link-visited:         hsl(var(--primary-h) 50% 70%);
+
+  // Status families: dark tint bg + border, lighter text.
+  --success-subtitle:     hsl(132deg 38% 14%);
+  --success-muted:        hsl(132deg 34% 20%);
+  --success-muted-strong: hsl(132deg 30% 28%);
+  --success-border:       hsl(132deg 30% 28%);
+  --success-text:         hsl(132deg 55% 62%);
+
+  --warning-subtitle:     hsl(45deg 42% 14%);
+  --warning-muted:        hsl(45deg 38% 22%);
+  --warning-muted-strong: hsl(45deg 35% 30%);
+  --warning-border:       hsl(45deg 35% 30%);
+  --warning-text:         hsl(45deg 90% 62%);
+
+  --error-subtitle:       hsl(0deg 45% 16%);
+  --error-muted:          hsl(0deg 40% 24%);
+  --error-muted-strong:   hsl(0deg 38% 32%);
+  --error-border:         hsl(0deg 38% 32%);
+  --error-text:           hsl(0deg 85% 74%);
+
+  --info-subtitle:        hsl(217deg 45% 16%);
+  --info-muted:           hsl(217deg 40% 24%);
+  --info-border:          hsl(217deg 38% 32%);
+  --info-text:            hsl(217deg 90% 74%);
+
+  // Status pills that referenced palette stops directly (green-50/700) — repoint
+  // to the dark status roles so the lifecycle pill reads on dark. (planning →
+  // neutral, confirmed → primary-*, completed → neutral all follow flips.)
+  --status-active-bg-color:   var(--success-subtitle);
+  --status-active-text-color: var(--success-text);
+
+  // Scrim stays dark — must NOT follow --shadow-tint-l: 95%.
+  --surface-scrim: hsl(225deg 39% 4% / 70%);
+
+  // Field focus halo — boost alpha for legibility on dark.
+  --focus-field-alpha: .35;
+
+  // Chart / dataviz overrides. Axis/grid/label/title/cursor already flip via the
+  // --neutral-* / --text-* roles; only the light-bg-tuned bits move here.
+  --chart-hover-bg-color:     hsl(0deg 0% 100% / 6%); // light wash (default dark wash is invisible on dark)
+  --chart-tooltip-bg-color:   var(--surface-overlay);  // native dark tooltip, not an inverted light box
+  --chart-tooltip-text-color: var(--text-primary);
+  --chart-tooltip-border:     var(--border-strong);
+
+  // Sequential — flip so low → high reads dark → bright on a dark canvas.
+  --chart-seq-1: var(--blue-800);
+  --chart-seq-2: var(--blue-700);
+  --chart-seq-3: var(--blue-600);
+  --chart-seq-4: var(--blue-500);
+  --chart-seq-5: var(--blue-400);
+  --chart-seq-6: var(--blue-300);
+
+  // Divergent — bright red ← dark-neutral zero → bright green (|value| → brightness).
+  --chart-div--3: hsl(0deg 70% 62%);
+  --chart-div--2: hsl(0deg 55% 46%);
+  --chart-div--1: hsl(0deg 45% 32%);
+  --chart-div-0:  var(--neutral-150);
+  --chart-div-1:  hsl(140deg 40% 32%);
+  --chart-div-2:  hsl(140deg 48% 46%);
+  --chart-div-3:  hsl(140deg 55% 60%);
+}