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

package/styles/_tokens.scss

@@ -2,9 +2,9 @@
    Design Tokens — Tier 3 component + scale layer.
 
    Tier 1 colour primitives (ramps + HSL channels) live in
-   ../themes/default/_palette.scss. Tier 2 semantic role assignments
+   ../themes/light/_palette.scss. Tier 2 semantic role assignments
    (surface, border, text, primary/secondary/tertiary, status, focus)
-   live in ../themes/default/_theme.scss.
+   live in ../themes/light/_theme.scss.
 
    THIS file owns the theme-INDEPENDENT layer:
      · scales      — spacing, radius, sizes, hit targets, breakpoints
@@ -43,6 +43,12 @@
   --space-24:  96px;
   --space-32: 128px;
 
+  /* Semantic spacing aliases — default rhythm for the layout primitives
+     (ds-stack / ds-inline). Components default their gap to these so the
+     vertical/horizontal rhythm retunes in one place. */
+  --space-stack:  var(--space-4);   /* 16px — vertical rhythm between stacked blocks */
+  --space-inline: var(--space-2);   /*  8px — horizontal cluster gap */
+
   /* ============================================================
      Radius — six-stop scale.
      Each step is functionally distinct; adjacent steps are
@@ -84,17 +90,18 @@
      The alpha values stay constant across themes — only the
      hue/saturation/lightness become configurable.
      ============================================================ */
-  /* --shadow-tint-h/s/l live in themes/default/_palette.scss — palette-level
+
+  /* --shadow-tint-h/s/l live in themes/light/_palette.scss — palette-level
      so dark palettes can override --shadow-tint-l → ~95% for soft light glows. */
 
-  --shadow-1: 0 1px 2px  hsla(var(--shadow-tint-h), var(--shadow-tint-s), var(--shadow-tint-l), .06),
-              0 1px 3px  hsla(var(--shadow-tint-h), var(--shadow-tint-s), var(--shadow-tint-l), .08);
-  --shadow-2: 0 4px 8px  hsla(var(--shadow-tint-h), var(--shadow-tint-s), var(--shadow-tint-l), .06),
-              0 4px 16px hsla(var(--shadow-tint-h), var(--shadow-tint-s), var(--shadow-tint-l), .10);
-  --shadow-3: 0 8px 16px hsla(var(--shadow-tint-h), var(--shadow-tint-s), var(--shadow-tint-l), .08),
-              0 16px 32px hsla(var(--shadow-tint-h), var(--shadow-tint-s), var(--shadow-tint-l), .14);
-  --shadow-4: 0 16px 32px hsla(var(--shadow-tint-h), var(--shadow-tint-s), var(--shadow-tint-l), .12),
-              0 24px 48px hsla(var(--shadow-tint-h), var(--shadow-tint-s), var(--shadow-tint-l), .18);
+  --shadow-1: 0 1px 2px  hsl(var(--shadow-tint-h) var(--shadow-tint-s) var(--shadow-tint-l) / 6%),
+              0 1px 3px  hsl(var(--shadow-tint-h) var(--shadow-tint-s) var(--shadow-tint-l) / 8%);
+  --shadow-2: 0 4px 8px  hsl(var(--shadow-tint-h) var(--shadow-tint-s) var(--shadow-tint-l) / 6%),
+              0 4px 16px hsl(var(--shadow-tint-h) var(--shadow-tint-s) var(--shadow-tint-l) / 10%);
+  --shadow-3: 0 8px 16px hsl(var(--shadow-tint-h) var(--shadow-tint-s) var(--shadow-tint-l) / 8%),
+              0 16px 32px hsl(var(--shadow-tint-h) var(--shadow-tint-s) var(--shadow-tint-l) / 14%);
+  --shadow-4: 0 16px 32px hsl(var(--shadow-tint-h) var(--shadow-tint-s) var(--shadow-tint-l) / 12%),
+              0 24px 48px hsl(var(--shadow-tint-h) var(--shadow-tint-s) var(--shadow-tint-l) / 18%);
   --shadow-popover: var(--shadow-2);
   --shadow-modal:   var(--shadow-4);
   --shadow-toast:   var(--shadow-3);
@@ -169,16 +176,13 @@
   --opacity-scrim:           0.55;  /* modal/drawer backdrop overlay (light theme) */
   --opacity-state-hover:     0.08;  /* hover layer over surface (overlay vs surface swap) */
   --opacity-state-pressed:   0.16;  /* active/pressed layer */
+  --opacity-state-active:    0.24;  /* deepest pressed layer (e.g. tag close on :active) */
 
   /* ============================================================
-     Breakpoints
+     Breakpoints — moved to _breakpoints.scss, the single source for both
+     the --bp-* custom properties (still emitted, now from that partial)
+     AND the $bp-* Sass aliases usable inside @media.
      ============================================================ */
-  --bp-xs:  480px;
-  --bp-sm:  640px;
-  --bp-md:  768px;
-  --bp-lg: 1024px;
-  --bp-xl: 1441px;   /* Page-grid wide-tier threshold (12 cols, container caps at --col-cap-content). */
-  --bp-2xl:1536px;
 
   /* ============================================================
      Page grid — tier-specific gutters + margins.
@@ -202,13 +206,13 @@
   --scrollbar-thumb:        var(--neutral-300);
   --scrollbar-thumb-hover:  var(--neutral-400);
   --scrollbar-thumb-active: var(--neutral-500);
-  --select-bg: color-mix(in srgb, var(--primary) 22%, transparent);
+  --select-bg-color: color-mix(in srgb, var(--primary) 22%, transparent);
   --col-cap-text:    720px;
   --col-cap-content: 1280px;
 
   /* ============================================================
      Typography scale (theme-independent). Font FAMILIES are a theme
-     choice and live in themes/default/_theme.scss (--font-sans/mono/
+     choice and live in themes/light/_theme.scss (--font-sans/mono/
      display/heading); the size/weight/leading/tracking scale below is
      constant across themes.
      ============================================================ */
@@ -282,6 +286,15 @@
      default their own --ds-*-pad to this, so a consumer retunes all at once. */
   --ds-container-pad:  var(--space-6);
 
+  /* Shared focus indicators — components default their own --ds-*-focus-shadow
+     to these, so a consumer retunes focus per-group at once (field vs control)
+     or per-component. Two families: fields get the soft halo, interactive
+     controls/nav get the crisp ring (see themes/light/_theme.scss). */
+  --ds-field-focus-shadow:         var(--focus-field);
+  --ds-field-focus-shadow-error:   var(--focus-field-error);
+  --ds-control-focus-shadow:       var(--focus-ring);
+  --ds-control-focus-shadow-error: var(--focus-ring-error);
+
   /* Table cell padding — density-aware, consumed by .tbl td/th. */
   --table-cell-pad-x:  var(--space-4);
   --table-cell-pad-y:  var(--space-3);
@@ -367,7 +380,7 @@
   --popover-maxh: 360px;
 
   /* Field */
-  --field-gap-label:   var(--space-1-5);   /* label↔control */
+  --field-label-gap:   var(--space-1-5);   /* field vertical rhythm: label↔control & control↔hint */
   --field-gap-req:     var(--space-1);     /* label↔asterisk */
   --field-h-sm:        var(--hit-min);
   --field-h-md:        var(--hit-cozy);
@@ -383,6 +396,19 @@
   --search-h: var(--hit-md);
   --search-maxw: 320px;
 
+  /* OTP / PIN input — one box per digit. */
+  --otp-cell-w: var(--space-12);   /* 48px */
+  --otp-cell-h: var(--space-14);   /* 56px */
+  --otp-gap:    var(--space-2);    /*  8px between cells */
+
+  /* Color picker */
+  --color-picker-swatch:  var(--space-6);    /* 24px preset swatch */
+  --color-picker-preview: var(--space-10);   /* 40px panel preview */
+  --color-picker-panel-w: 240px;             /* picker overlay width */
+  --color-picker-sv-h:    160px;             /* saturation/value plane height */
+  --color-picker-hue-h:   var(--space-3);    /* 12px hue slider height */
+  --color-picker-thumb:   14px;              /* draggable thumb diameter */
+
   /* ============================================================
      3b · COMPONENT-SCOPED dimensions (Phase 4 additions)
      Tokens for atom geometries that previously lived as literals
@@ -433,6 +459,11 @@
   --menu-minw:               200px;                  /* dropdown menu min width */
   --menu-sep-h:              var(--border-width-default);
 
+  /* List / list-item — density-aware row padding + leading/trailing gap. */
+  --list-item-pad-y:         var(--space-3);             /* 12px */
+  --list-item-pad-x:         var(--space-4);             /* 16px */
+  --list-item-gap:           var(--space-3);             /* 12px leading↔body↔trailing */
+
   /* Tooltip */
   --tooltip-maxw:            240px;
   --tooltip-arrow:           var(--space-2);             /* 8px — caret edge length, halved for offset */
@@ -502,6 +533,16 @@
   --calendar-bar-h:          var(--space-8);             /* 32px */
   --calendar-bar-inset-y:    var(--space-2);             /* 8px from top of cell */
 
+  /* Timeline / activity feed */
+  --timeline-node-size:      var(--hit-sm);              /* 28px event node */
+  --timeline-spine-w:        var(--border-width-strong); /* 2px connector spine */
+  --timeline-gap:            var(--space-5);             /* vertical gap between events */
+
+  /* Tree-view */
+  --tree-indent:             var(--space-5);             /* 20px per nesting level */
+  --tree-row-pad-y:          var(--space-1-5);           /* 6px */
+  --tree-row-pad-x:          var(--space-3);             /* 12px base inset */
+
   /* Bin pack visualisation */
   --binpack-bay-h:           var(--hit-touch);       /* 48px */
 
@@ -549,13 +590,20 @@
     --duration-base:    0ms;
     --duration-slow:    0ms;
     --duration-slower:  0ms;
-    --duration-loop-fast: 0ms;
-    --duration-loop-slow: 0ms;
+
+    /* Looping status indicators (spinners, indeterminate progress) stay
+       visible but calmer — slowed, never frozen: a stopped spinner reads as
+       "hung", not "loading". The one large motion we DO halt is the page-wide
+       skeleton sweep, which stops itself in _skeleton-shimmer.scss. */
+    --duration-loop-fast: 1400ms;
+    --duration-loop-slow: 2800ms;
   }
+
+  /* Kill one-shot motion only. Every entrance/transition animation is
+     token-driven, so zeroing the one-shot durations above already makes them
+     instant — loops must NOT be blanket-zeroed here or they freeze. */
   *, *::before, *::after {
     transition-duration: 0ms !important;
-    animation-duration:  0ms !important;
-    animation-iteration-count: 1 !important;
   }
 }
 
@@ -597,6 +645,7 @@
 }
 [data-density="cozy"] {
   --hit-cozy:  40px;
+
   /* defaults */
 }
 [data-density="comfy"] {

package/styles/_typography.scss

@@ -1,31 +1,31 @@
 // Type utility classes — ported from CLAUDE_DESIGN_DS/tokens.css §Type utilities.
 // These are GLOBAL by design — consumers apply them via class.
 
-.t-display    { font: var(--font-weight-extrabold) var(--font-size-display)/var(--line-height-tight) var(--font-display); letter-spacing: var(--letter-spacing-tight); }
-.t-h1         { font: var(--font-weight-extrabold) var(--font-size-h1)/var(--line-height-tight) var(--font-heading); letter-spacing: var(--letter-spacing-tight); }
-.t-h2         { font: var(--font-weight-extrabold) var(--font-size-h2)/var(--line-height-snug) var(--font-heading); letter-spacing: var(--letter-spacing-snug); }
-.t-h3         { font: var(--font-weight-extrabold) var(--font-size-h3)/var(--line-height-snug) var(--font-heading); letter-spacing: var(--letter-spacing-snug); }
-.t-h4         { font: var(--font-weight-bold) var(--font-size-h4)/var(--line-height-snug) var(--font-heading); }
-.t-h5         { font: var(--font-weight-bold) var(--font-size-h5)/var(--line-height-snug) var(--font-heading); }
-.t-card-title { font: var(--font-weight-bold) var(--card-title-fs)/var(--line-height-snug) var(--font-heading); margin: 0; color: var(--text-primary); }
-.t-l          { font: var(--font-weight-regular) var(--font-size-l)/var(--line-height-base) var(--font-sans); }
-.t-l-bold     { font: var(--font-weight-bold) var(--font-size-l)/var(--line-height-base) var(--font-sans); }
-.t-m          { font: var(--font-weight-regular) var(--font-size-m)/var(--line-height-base) var(--font-sans); }
-.t-m-bold     { font: var(--font-weight-bold) var(--font-size-m)/var(--line-height-base) var(--font-sans); }
-.t-s          { font: var(--font-weight-regular) var(--font-size-s)/var(--line-height-base) var(--font-sans); }
-.t-s-bold     { font: var(--font-weight-bold) var(--font-size-s)/var(--line-height-base) var(--font-sans); }
-.t-xs         { font: var(--font-weight-regular) var(--font-size-xs)/var(--line-height-base) var(--font-sans); }
-.t-xs-bold    { font: var(--font-weight-bold) var(--font-size-xs)/var(--line-height-base) var(--font-sans); }
-.t-overline   { font: var(--font-weight-bold) var(--font-size-2xs)/var(--line-height-base) var(--font-sans); letter-spacing: var(--letter-spacing-wider); text-transform: uppercase; color: var(--text-tertiary); }
-.t-caption    { font: var(--font-weight-regular) var(--font-size-xs)/var(--line-height-base) var(--font-sans); color: var(--text-tertiary); }
-.t-mono        { font: var(--font-weight-medium) var(--font-size-mono)/var(--line-height-base) var(--font-mono); }
-.t-mono-inline { font: var(--font-weight-regular) var(--font-size-mono)/1 var(--font-mono); background: var(--surface-secondary); color: var(--text-primary); padding: 1px var(--space-1); border-radius: var(--radius-sm); }
-.t-mono-block  { font: var(--font-weight-regular) var(--font-size-mono)/var(--line-height-loose) var(--font-mono); background: var(--surface-secondary); border: var(--border-width-default) solid var(--border-divider); border-radius: var(--radius-md); padding: var(--space-3) var(--space-4); }
+.t-display    { font: var(--font-weight-extrabold) var(--font-size-display) / var(--line-height-tight) var(--font-display); letter-spacing: var(--letter-spacing-tight); }
+.t-h1         { font: var(--font-weight-extrabold) var(--font-size-h1) / var(--line-height-tight) var(--font-heading); letter-spacing: var(--letter-spacing-tight); }
+.t-h2         { font: var(--font-weight-extrabold) var(--font-size-h2) / var(--line-height-snug) var(--font-heading); letter-spacing: var(--letter-spacing-snug); }
+.t-h3         { font: var(--font-weight-extrabold) var(--font-size-h3) / var(--line-height-snug) var(--font-heading); letter-spacing: var(--letter-spacing-snug); }
+.t-h4         { font: var(--font-weight-bold) var(--font-size-h4) / var(--line-height-snug) var(--font-heading); }
+.t-h5         { font: var(--font-weight-bold) var(--font-size-h5) / var(--line-height-snug) var(--font-heading); }
+.t-card-title { font: var(--font-weight-bold) var(--card-title-fs) / var(--line-height-snug) var(--font-heading); margin: 0; color: var(--text-primary); }
+.t-l          { font: var(--font-weight-regular) var(--font-size-l) / var(--line-height-base) var(--font-sans); }
+.t-l-bold     { font: var(--font-weight-bold) var(--font-size-l) / var(--line-height-base) var(--font-sans); }
+.t-m          { font: var(--font-weight-regular) var(--font-size-m) / var(--line-height-base) var(--font-sans); }
+.t-m-bold     { font: var(--font-weight-bold) var(--font-size-m) / var(--line-height-base) var(--font-sans); }
+.t-s          { font: var(--font-weight-regular) var(--font-size-s) / var(--line-height-base) var(--font-sans); }
+.t-s-bold     { font: var(--font-weight-bold) var(--font-size-s) / var(--line-height-base) var(--font-sans); }
+.t-xs         { font: var(--font-weight-regular) var(--font-size-xs) / var(--line-height-base) var(--font-sans); }
+.t-xs-bold    { font: var(--font-weight-bold) var(--font-size-xs) / var(--line-height-base) var(--font-sans); }
+.t-overline   { font: var(--font-weight-bold) var(--font-size-2xs) / var(--line-height-base) var(--font-sans); letter-spacing: var(--letter-spacing-wider); text-transform: uppercase; color: var(--text-tertiary); }
+.t-caption    { font: var(--font-weight-regular) var(--font-size-xs) / var(--line-height-base) var(--font-sans); color: var(--text-tertiary); }
+.t-mono        { font: var(--font-weight-medium) var(--font-size-mono) / var(--line-height-base) var(--font-mono); }
+.t-mono-inline { font: var(--font-weight-regular) var(--font-size-mono) / 1 var(--font-mono); background: var(--surface-secondary); color: var(--text-primary); padding: 1px var(--space-1); border-radius: var(--radius-sm); }
+.t-mono-block  { font: var(--font-weight-regular) var(--font-size-mono) / var(--line-height-loose) var(--font-mono); background: var(--surface-secondary); border: var(--border-width-default) solid var(--border-divider); border-radius: var(--radius-md); padding: var(--space-3) var(--space-4); }
 
 .sr-only {
   position: absolute !important;
   width: 1px; height: 1px;
   padding: 0; margin: -1px;
-  overflow: hidden; clip: rect(0,0,0,0);
+  overflow: hidden; clip-path: inset(50%);
   white-space: nowrap; border: 0;
 }

package/styles/ds.scss

@@ -1,27 +1,33 @@
 // 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';
+// Bundles the base palette (theme-independent ramps + channels + statics + fonts)
+// and the theme activation (light + dark, sibling themes + OS-default media rule).
+// Layers:
+//   base-palette      — Tier 1a theme-independent primitives (ramps, channels,
+//                       statics, shadow h/s, font families) emitted at :root
+//   theme-activation  — Tier 1b + Tier 2: per-theme palette + role assignments,
+//                       scoped to mutually-exclusive :root selectors
+//   tokens            — Tier 3 geometry / typography scale / motion / component tokens
+// Advanced consumers can compose themes individually instead of using ds:
+//   @use 'themes/base-palette'; @use 'styles/theme-activation'; @use 'styles/tokens';
 //   @use 'styles/fonts'; @use 'styles/link'; …
 
-@forward '../themes/default/palette';
-@forward '../themes/default/theme';
+@forward '../themes/base-palette';
+@forward 'theme-activation';
 @forward 'tokens';
+@forward 'breakpoints';
 @forward 'tokens-charts';
 @forward 'fonts';
 @forward 'reset';
 @forward 'typography';
 @forward 'link';
+@forward 'ds-color';
 @forward 'layout-utils';
 @forward 'page-grid';
 @forward 'scrollbar';
 @forward 'icon-base';
 @forward 'dropdown-overlay';
 @forward 'toast-overlay';
+@forward 'overlay-motion';
 @forward 'skeleton-shimmer';

package/themes/README.md

@@ -1,96 +1,110 @@
-# Themes — palette + role assignments
+# Themes — base palette · sibling themes · brands
 
-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`).
+Colour is layered in three concerns: a **base palette** (theme-independent primitives), **themes** (light / dark — sibling role maps; light is the default, dark is opt-in), and **brands** (optional overlays authored on a theme). The geometry/component layer is separate (`../styles/_tokens.scss`).
 
-## Architecture: three tiers
+## Architecture: three layers
 
-| 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) |
+| Layer                          | Lives in                                       | Examples                                                                                              | Applied at                          |
+| ------------------------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| **Base palette** (primitives)  | `themes/_base-palette.scss`                    | `--blue-600`, `--cool-gray-*`, `--brand-gray-*`, `--red-h/s/l`, `--static-white`, fonts, `--shadow-tint-h/s` | `:root` (theme-independent)         |
+| **Theme** (role map)           | `themes/_semantic.scss` + `themes/<t>/_*.scss` | `--primary`, `--surface-canvas`, `--text-primary`, the `--neutral-*` slot, `--focus-ring`              | `:root` (light) / `:root[data-theme='dark']` |
+| **Component / scale**          | `styles/_tokens.scss`, `*.component.scss`      | `--space-*`, `--radius-*`, `--ds-button-bg-color`, `--duration-fast`                                   | `:root` (theme-independent)         |
 
-**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.
+**Hard rule:** components NEVER consume base-palette primitives directly. `var(--blue-600)` inside `button.component.scss` is a bug — use a Tier-2 role (`--primary`, `--text-secondary`) or a component token.
 
-**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.
+## Files
 
-## Available palette + theme
+- **`_base-palette.scss`** — theme-independent primitives at `:root`: hue ramps (`--blue/red/green/yellow/sky/orange-*`) + HSL channels, `--cool-gray-*` / `--brand-gray-*` ramps, `--static-white` / `--static-ink` (never flip), `--shadow-tint-h/s`, font families. Shared by every theme.
+- **`_semantic.scss`** — `@mixin roles`: the semantic role map (surfaces, text, icons, borders, primary/secondary/tertiary families, status, status-pills, focus). Structure is identical across themes; values resolve through each theme's own `--neutral-*` ramp. Holds the **light-default** values.
+- **`light/_palette.scss` + `light/_theme.scss`** — `@mixin palette` (the `--neutral-*` slot = cool-gray + `--shadow-tint-l: 7%`) and `@mixin theme` (`palette` + `semantic.roles`). Light is the **default** skin and needs no extra overrides.
+- **`dark/_palette.scss` + `dark/_theme.scss`** — `@mixin palette` (dark neutral ramp + `--shadow-tint-l: 95%`) and `@mixin theme` (`palette` + `semantic.roles` + the value overrides that genuinely differ on dark: tint surfaces, on-tint text, hover/pressed mixed toward white, scrim, focus-halo alpha, chart tokens).
+- **`../styles/_theme-activation.scss`** — applies light at `:root` and dark at `:root[data-theme='dark']`, plus the light-context `data-neutrals='brand'` switch.
 
-- **`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.
+`styles/ds.scss` forwards `_base-palette` then `theme-activation` (before `tokens`), so `@use 'styles/ds';` renders light 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.
+**Why sibling themes (not a dark "patch"):** the dark block declares the COMPLETE token set (`@include palette` + `@include semantic.roles` + its own overrides), so `:root[data-theme='dark']` fully replaces light rather than delta-patching it. The `@mixin roles` in `_semantic.scss` is an authoring-DRY device (the light-default structure both themes share), not a runtime cross-theme dependency.
+
+## Theme switching
+
+**Light is the default — no attribute needed.** Dark is opt-in:
+
+- (nothing) — light
+- `<html data-theme="dark">` — dark
+- `<html data-theme="light">` — also light (explicit; same as the default)
+
+```scss
+:root                    { @include light.theme; }   // default
+:root[data-theme='dark'] { @include dark.theme; }     // opt-in (complete set → fully wins)
+```
+
+There is **no automatic `prefers-color-scheme` switch** — light is deterministic by default. To follow the OS, opt in at the app root with `provideDsTheme`:
+
+```ts
+// app.config.ts
+import { provideDsTheme } from '@ids-group-ltd/ids-design-system';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideDsTheme({ followSystem: true })],
+};
+```
+
+It sets `data-theme` from `prefers-color-scheme` at startup and keeps it in sync as the OS changes; a manual `data-theme="dark"` still wins.
+
+On-fill text uses theme-stable `--static-white` / `--static-ink` so it doesn't flip with the neutrals.
+
+**Known limitation — `data-neutrals="brand"` + dark:** the brand-gray (hue-derived) neutral switch is a **light-theme feature**. The dark block ships its own neutral ramp and is declared last, so on `data-theme="dark"` the dark neutrals win and the brand-gray tint is ignored. (Benign — renders correct dark, just not brand-tinted neutrals.)
 
 ## How a consumer picks a theme
 
-### Option A — out-of-the-box default
+### Option A — out of the box (light)
 
 ```scss
-// Consumer styles.scss
-@use 'styles/ds';   // bundles default palette + theme + tokens + reset + ...
+@use 'styles/ds'; // base palette + light/dark activation + tokens + reset + …
 ```
 
-### Option B — explicit theme choice
+### Option B — à la carte (advanced, opt-in global side-effects)
 
 ```scss
-// Consumer styles.scss
-@use 'themes/dark/palette';      // pick a non-default theme: palette …
-@use 'themes/dark/theme';        // … then its role map
+@use 'themes/base-palette';
+@use 'styles/theme-activation'; // light at :root + dark at [data-theme='dark']
 @use 'styles/tokens';
+@use 'styles/fonts';
 @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.
+`base-palette` + `theme-activation` must come BEFORE `tokens` so role aliases resolve. The theme `_palette` / `_theme` files expose **mixins** — don't `@use` them directly; `theme-activation` applies them.
 
-### Option C — brand layer on top of default theme
+### Option C — brand layer on top
 
 ```scss
-// Consumer styles.scss
-@use 'styles/ds';                        // default theme + DS
-@use './app/styles/brand-manage-my';     // overrides palette/roles via [data-brand]
+@use 'styles/ds';
+@use './app/styles/brand-manage-my'; // [data-brand="manage-my"] overrides (light-authored)
 ```
 
-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).
+## Brand vs theme
 
-Same mechanism (CSS custom properties + cascade), different scope.
+- **Theme** swaps the whole role map (light ↔ dark). Light is the default; dark is opt-in and, when active, fully replaces light.
+- **Brand** is a thin overlay scoped via attribute (`[data-brand="X"]`), authored on a theme. `manage-my` is authored on **light** — pair it with the default (light) theme. A brand that wants dark adds a separate `[data-theme='dark'][data-brand="X"]` layer.
 
 ## 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.
+1. Create `themes/<name>/_palette.scss` (`@mixin palette` — its `--neutral-*` ramp + `--shadow-tint-l`) and `themes/<name>/_theme.scss` (`@mixin theme` — `@include palette` + `@include semantic.roles` + only the role values that differ for this theme).
+2. Add a selector block in `styles/_theme-activation.scss` (`:root[data-theme='<name>'] { @include <name>.theme; }`), after the light default.
 
-Components don't need any change — they consume semantic roles which automatically pick up the new palette.
+Components never change — they consume semantic roles, which the active theme block defines.
 
 ## 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.
+2. Open with `[data-brand="X"] { … }` (authored on light — the default theme).
+3. Override the brand hue (`--blue-*` ramp and/or `--primary` + channels), and any roles you want to retint (surfaces, text, secondary, status). Leave `--primary-hover`/`--primary-pressed` to the DS `color-mix()` derivation.
+4. Apply via `<html data-brand="X">`.
 
 ## 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
-  ```
+- Components never reference base-palette primitives (`--blue-600`, `--neutral-200`) directly — use a Tier-2 role.
+- Light is the default; dark is opt-in (`data-theme="dark"`); OS-follow is a consumer opt-in. No `prefers-color-scheme` by default.
+- Themes are sibling and self-contained; `_semantic.scss`'s `@mixin roles` holds the light-default values, dark overrides the deltas.
+- Brands are theme-authored overlays. `manage-my` is light.
+- `--primary-hover`/`--primary-pressed` are auto-derived via `color-mix()` (toward black in light, toward white in dark).