@ids-group-ltd/ids-design-system 0.3.0 → 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 {
@@ -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;
@@ -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)
@@ -84,34 +65,25 @@
 
   /* 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:        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.
@@ -122,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
@@ -137,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
@@ -154,6 +132,7 @@
   --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
@@ -173,6 +152,7 @@
   --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.
@@ -184,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);
 
@@ -191,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);
 
@@ -199,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);
@@ -256,22 +247,44 @@
     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 hsl(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);
+  /* 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));
+
+  /* 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%);
+}

package/themes/light/_palette.scss

@@ -0,0 +1,34 @@
+// =========================================================================
+// Light palette — Tier 1b per-theme primitives.
+//
+// Exposes @mixin palette with ONLY the light-specific primitives:
+//   · --neutral-* slot pointed at the cool-gray ramp
+//   · --shadow-tint-l: 7%  (light shadow substrate lightness)
+//
+// Theme-independent ramps (--cool-gray-*, --brand-gray-*, --blue-*, etc.)
+// and HSL channels live in themes/_base-palette.scss and emit at :root.
+// =========================================================================
+
+@mixin palette {
+  /* 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);
+
+  // Shadow substrate lightness for light theme.
+  --shadow-tint-l: 7%;
+}

package/themes/light/_theme.scss

@@ -0,0 +1,15 @@
+// =========================================================================
+// Light theme — Tier 2 role assignments (light).
+//
+// Composes the light-specific palette (neutral slot + shadow-l) with the
+// shared role structure. Light needs no extra role overrides — _roles.scss
+// already holds the light-default values.
+// =========================================================================
+
+@use 'palette';
+@use '../semantic';
+
+@mixin theme {
+  @include palette.palette;
+  @include semantic.roles;
+}