@ids-group-ltd/ids-design-system 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/themes/README.md CHANGED
@@ -1,97 +1,110 @@
1
- # Themes — palette + role assignments
1
+ # Themes — base palette · sibling themes · brands
2
2
 
3
- 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`).
3
+ 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`).
4
4
 
5
- ## Architecture: three tiers
5
+ ## Architecture: three layers
6
6
 
7
- | Tier | Lives in | Examples | Consumers |
8
- | -------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
9
- | **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 |
10
- | **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 |
11
- | **Tier 3 — Component / scale** | `styles/_tokens.scss` and inside `*.component.scss` | `--space-*`, `--radius-*`, `--ds-button-bg-color`, `--duration-fast`, `--layer-modal` | Components (their own) |
7
+ | Layer | Lives in | Examples | Applied at |
8
+ | ------------------------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------- |
9
+ | **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) |
10
+ | **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']` |
11
+ | **Component / scale** | `styles/_tokens.scss`, `*.component.scss` | `--space-*`, `--radius-*`, `--ds-button-bg-color`, `--duration-fast` | `:root` (theme-independent) |
12
12
 
13
- **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.
13
+ **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.
14
14
 
15
- **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.
15
+ ## Files
16
16
 
17
- ## Available palette + theme
17
+ - **`_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.
18
+ - **`_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.
19
+ - **`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.
20
+ - **`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).
21
+ - **`../styles/_theme-activation.scss`** — applies light at `:root` and dark at `:root[data-theme='dark']`, plus the light-context `data-neutrals='brand'` switch.
18
22
 
19
- - **`default/_palette.scss`** — Blue + slate ramps (the concrete colours).
20
- - **`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.
23
+ `styles/ds.scss` forwards `_base-palette` then `theme-activation` (before `tokens`), so `@use 'styles/ds';` renders light out of the box.
21
24
 
22
- Future (each a `themes/<name>/` folder with `_palette.scss` + `_theme.scss`):
25
+ **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.
23
26
 
24
- - `themes/dark/` — Dark-mode flip (`--shadow-tint-l` → ~95%, neutrals inverted, etc.).
25
- - `themes/high-contrast/` — A11y boost.
27
+ ## Theme switching
28
+
29
+ **Light is the default — no attribute needed.** Dark is opt-in:
30
+
31
+ - (nothing) — light
32
+ - `<html data-theme="dark">` — dark
33
+ - `<html data-theme="light">` — also light (explicit; same as the default)
34
+
35
+ ```scss
36
+ :root { @include light.theme; } // default
37
+ :root[data-theme='dark'] { @include dark.theme; } // opt-in (complete set → fully wins)
38
+ ```
39
+
40
+ 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`:
41
+
42
+ ```ts
43
+ // app.config.ts
44
+ import { provideDsTheme } from '@ids-group-ltd/ids-design-system';
45
+
46
+ export const appConfig: ApplicationConfig = {
47
+ providers: [provideDsTheme({ followSystem: true })],
48
+ };
49
+ ```
50
+
51
+ 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.
52
+
53
+ On-fill text uses theme-stable `--static-white` / `--static-ink` so it doesn't flip with the neutrals.
54
+
55
+ **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.)
26
56
 
27
57
  ## How a consumer picks a theme
28
58
 
29
- ### Option A — out-of-the-box default
59
+ ### Option A — out of the box (light)
30
60
 
31
61
  ```scss
32
- // Consumer styles.scss
33
- @use 'styles/ds'; // bundles default palette + theme + tokens + reset + ...
62
+ @use 'styles/ds'; // base palette + light/dark activation + tokens + reset + …
34
63
  ```
35
64
 
36
- ### Option B — explicit theme choice
65
+ ### Option B — à la carte (advanced, opt-in global side-effects)
37
66
 
38
67
  ```scss
39
- // Consumer styles.scss
40
- @use 'themes/dark/palette'; // pick a non-default theme: palette …
41
- @use 'themes/dark/theme'; // … then its role map
68
+ @use 'themes/base-palette';
69
+ @use 'styles/theme-activation'; // light at :root + dark at [data-theme='dark']
42
70
  @use 'styles/tokens';
71
+ @use 'styles/fonts';
43
72
  @use 'styles/reset';
44
- @use 'styles/typography';
45
- @use 'styles/scrollbar';
46
- @use 'styles/icon-base';
47
- @use 'styles/dropdown-overlay';
73
+ // …
48
74
  ```
49
75
 
50
- Palette + theme must come BEFORE `tokens` so role aliases resolve.
76
+ `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.
51
77
 
52
- ### Option C — brand layer on top of default theme
78
+ ### Option C — brand layer on top
53
79
 
54
80
  ```scss
55
- // Consumer styles.scss
56
- @use 'styles/ds'; // default theme + DS
57
- @use './app/styles/brand-manage-my'; // overrides palette/roles via [data-brand]
81
+ @use 'styles/ds';
82
+ @use './app/styles/brand-manage-my'; // [data-brand="manage-my"] overrides (light-authored)
58
83
  ```
59
84
 
60
- This is the mm-broker pattern: load DS (default theme included), then overlay a brand at a more-specific selector (`[data-brand="manage-my"]`).
61
-
62
- ## Brand vs theme — what's the difference?
63
-
64
- - **Theme** swaps the entire Tier 1 palette. Affects EVERY semantic role downstream.
65
- - **Brand** is a thin overlay scoped via attribute selector (`[data-brand="X"]`). Usually overrides a smaller subset (key palette stops + maybe a few roles).
85
+ ## Brand vs theme
66
86
 
67
- Same mechanism (CSS custom properties + cascade), different scope.
87
+ - **Theme** swaps the whole role map (light ↔ dark). Light is the default; dark is opt-in and, when active, fully replaces light.
88
+ - **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.
68
89
 
69
90
  ## Adding a new theme
70
91
 
71
- 1. Create a `themes/<name>/` folder with `_palette.scss` (ramps + HSL channels) and `_theme.scss` (role map), mirroring `themes/default/`.
72
- 2. Optionally add it to `styles/ds.scss` if it should be a default-bundled option.
73
- 3. Or let consumers `@use 'themes/<name>/palette'; @use 'themes/<name>/theme';` directly.
92
+ 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).
93
+ 2. Add a selector block in `styles/_theme-activation.scss` (`:root[data-theme='<name>'] { @include <name>.theme; }`), after the light default.
74
94
 
75
- Components don't need any change — they consume semantic roles which automatically pick up the new palette.
95
+ Components never change — they consume semantic roles, which the active theme block defines.
76
96
 
77
97
  ## Adding a new brand override
78
98
 
79
99
  1. Create `<consumer-app>/src/app/styles/_brand-X.scss`.
80
- 2. Open with `[data-brand="X"] { ... }`.
81
- 3. Override:
82
- - **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)`).
83
- - **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.
84
- - Other roles you want to retint independently (surfaces, borders, text, success/danger ramps, secondary, etc.).
85
- 4. Apply via `<html data-brand="X">` on the host app.
100
+ 2. Open with `[data-brand="X"] { … }` (authored on light — the default theme).
101
+ 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.
102
+ 4. Apply via `<html data-brand="X">`.
86
103
 
87
104
  ## Rules summary
88
105
 
89
- - 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.
90
- - Themes own palette. Brands overlay on top via `[data-brand]`.
91
- - Theme switching = swap one `@use 'themes/X'`. No component changes.
92
- - `--primary-hover`, `--primary-pressed` are auto-derived via `color-mix()`. Don't override unless brand needs non-derived hover.
93
- - Audit guard (suggested pre-commit hook):
94
- ```bash
95
- grep -nE 'var\(--(violet|neutral|red|green|yellow|blue|orange|cyan|magenta)-[0-9]+\)' \
96
- prototype/ds/src/lib/components/**/*.scss && exit 1
97
- ```
106
+ - Components never reference base-palette primitives (`--blue-600`, `--neutral-200`) directly — use a Tier-2 role.
107
+ - Light is the default; dark is opt-in (`data-theme="dark"`); OS-follow is a consumer opt-in. No `prefers-color-scheme` by default.
108
+ - Themes are sibling and self-contained; `_semantic.scss`'s `@mixin roles` holds the light-default values, dark overrides the deltas.
109
+ - Brands are theme-authored overlays. `manage-my` is light.
110
+ - `--primary-hover`/`--primary-pressed` are auto-derived via `color-mix()` (toward black in light, toward white in dark).
@@ -1,19 +1,14 @@
1
1
  // =========================================================================
2
- // Default palette — Tier 1 concrete colour primitives.
2
+ // Base palette — Tier 1 theme-independent primitives.
3
3
  //
4
- // This file DEFINES the colours: raw ramps (--cool-gray-*, --brand-gray-*,
5
- // --blue-*, --red-*, --green-*, --yellow-*, --sky-*, --orange-*) + the HSL
6
- // channels (--blue-h/s/l, --red-h/s/l, --shadow-tint-h/s/l) they compose from.
7
- // Tokens are named by the COLOUR itself — the palette does not know what a
8
- // colour is "for". The --neutral-* FAMILY SLOT (which gray ramp is active)
9
- // is semantic, so it lives in the theme (_theme.scss), not here.
4
+ // Emits at :root. Colour ramps and channels that are identical in every
5
+ // theme: hue ramps (--cool-gray-*, --brand-gray-*, --blue-*, --red-*, …),
6
+ // HSL channels (--blue-h/s/l, --red-h/s/l), shadow substrate h/s (NOT -l —
7
+ // that is per-theme), static anchors, and font families.
10
8
  //
11
- // The companion theme (themes/default/_theme.scss) SETS these onto semantic
12
- // roles (--primary → --blue-600, --error → --red-500, …). Components consume
13
- // only those roles, never this palette directly.
14
- //
15
- // A sibling palette (e.g. _palette-dark.scss) ships different ramp values; pair
16
- // it with a matching theme file. Default = "Blue + Slate baseline".
9
+ // The --neutral-* FAMILY SLOT (which gray ramp is active) is per-theme and
10
+ // lives in each theme's _palette.scss mixin. Components consume only semantic
11
+ // roles; they never reference this file directly.
17
12
  // =========================================================================
18
13
 
19
14
  :root {
@@ -95,6 +90,9 @@
95
90
  // -----------------------------------------------------------------------
96
91
  // Green — success
97
92
  // -----------------------------------------------------------------------
93
+ // HSL channels (additive — for focus-ring composition + ds-color). The ramp
94
+ // stops below stay hand-picked hex; these reproduce --green-500 ≈ #22A33A.
95
+ --green-h: 132; --green-s: 66%; --green-l: 39%;
98
96
  --green-50: #ECFAEE;
99
97
  --green-100: #D6F3DB;
100
98
  --green-200: #BBE8C2;
@@ -107,6 +105,9 @@
107
105
  // -----------------------------------------------------------------------
108
106
  // Yellow — attention / warning
109
107
  // -----------------------------------------------------------------------
108
+ // HSL channels (additive — for focus-ring composition + ds-color). Reproduce
109
+ // --yellow-400 ≈ #F4D43A; ramp stops below stay hand-picked hex.
110
+ --yellow-h: 47; --yellow-s: 89%; --yellow-l: 59%;
110
111
  --yellow-50: #FFFBEA;
111
112
  --yellow-100: #FEF8DC;
112
113
  --yellow-200: #FCEFA1;
@@ -148,12 +149,28 @@
148
149
  --sky-700: #1D4ED8;
149
150
 
150
151
  // -----------------------------------------------------------------------
151
- // Shadow tint — channel-split substrate. Light theme uses a cool
152
- // near-black slate (225 / 39% / 7%). A dark theme would override
153
- // --shadow-tint-l to ~95% so the same alphas render as soft light
154
- // glows over dark surfaces.
152
+ // Shadow tint — channel-split substrate h/s only. The lightness (-l) is
153
+ // per-theme: light uses 7%, dark uses 95% (so the same alphas read as soft
154
+ // glows over dark surfaces). Each theme's _palette.scss mixin sets -l.
155
155
  // -----------------------------------------------------------------------
156
156
  --shadow-tint-h: 225;
157
157
  --shadow-tint-s: 39%;
158
- --shadow-tint-l: 7%;
158
+
159
+ // -----------------------------------------------------------------------
160
+ // Theme-stable contrast anchors — never flip with the theme. On-fill text/
161
+ // icon roles point here so a dark theme keeps white-on-coloured-fill correct.
162
+ // -----------------------------------------------------------------------
163
+ --static-white: #FFF;
164
+ --static-ink: #161A28;
165
+
166
+ // -----------------------------------------------------------------------
167
+ // Font families — a theme/brand choice (the size/weight/leading SCALE is
168
+ // theme-independent and lives in styles/_tokens.scss). Display + heading
169
+ // default to body sans; a brand can mix a serif/display family here without
170
+ // touching component code.
171
+ // -----------------------------------------------------------------------
172
+ --font-sans: "Mulish", -apple-system, blinkmacsystemfont, "Segoe UI", roboto, sans-serif;
173
+ --font-mono: "JetBrains Mono", ui-monospace, sfmono-regular, menlo, monospace;
174
+ --font-display: var(--font-sans);
175
+ --font-heading: var(--font-sans);
159
176
  }
@@ -1,40 +1,21 @@
1
1
  // =========================================================================
2
- // Default theme — Tier 2 semantic role ASSIGNMENTS (light).
2
+ // Shared role structure — Tier 2 semantic role ASSIGNMENTS.
3
3
  //
4
- // The palette (themes/default/_palette.scss) DEFINES the concrete colours
5
- // (--blue-*, --red-*, --neutral-*, … + HSL channels). THIS file SETS them
6
- // onto semantic roles (--primary → --blue-600, --surface-canvas → --neutral-50,
7
- // --error → --red-500, …). Components consume only these roles, never the
8
- // palette directly — so swapping the palette, or re-mapping here, re-skins the
9
- // whole system. A sibling theme (e.g. dark) ships its own palette + this map.
4
+ // Exposes @mixin roles: the role map whose structure is identical across
5
+ // themes and which resolves through the per-theme palette (surfaces →
6
+ // --neutral-*, text/icon/border → --neutral-*, brand channels, status, focus,
7
+ // semantic→palette bridge). These are the LIGHT-DEFAULT values — dark theme
8
+ // overrides only the deltas in its own _theme.scss mixin body.
10
9
  //
11
- // Tier 3 (component-scoped tokens, geometry, typography, motion) lives in
12
- // styles/_tokens.scss and is theme-independent.
10
+ // This mixin is an authoring-DRY device. At runtime, exactly one theme block
11
+ // matches (`:not([data-theme='dark'])` vs `[data-theme='dark']`), and that
12
+ // block declares the complete token set itself (palette + roles + overrides).
13
13
  // =========================================================================
14
14
 
15
- :root {
16
- /* Neutral family slot — semantic pointer at the active gray ramp from the
17
- palette. Default: hand-drawn cool-gray. <html data-neutrals="brand">
18
- (ds-docs tweaks panel) repoints it at the brand-derived brand-gray ramp,
19
- where --primary-h re-tints every gray. Roles below consume --neutral-*
20
- so the family switch never touches them. */
21
- --neutral-0: var(--cool-gray-0);
22
- --neutral-50: var(--cool-gray-50);
23
- --neutral-100: var(--cool-gray-100);
24
- --neutral-150: var(--cool-gray-150);
25
- --neutral-200: var(--cool-gray-200);
26
- --neutral-300: var(--cool-gray-300);
27
- --neutral-400: var(--cool-gray-400);
28
- --neutral-500: var(--cool-gray-500);
29
- --neutral-600: var(--cool-gray-600);
30
- --neutral-700: var(--cool-gray-700);
31
- --neutral-800: var(--cool-gray-800);
32
- --neutral-900: var(--cool-gray-900);
33
- --neutral-950: var(--cool-gray-950);
34
-
15
+ @mixin roles {
35
16
  /* Surfaces — six-stop scale.
36
17
  · canvas : page background
37
- · default : cards, sheets, toolbars (the “paper”)
18
+ · default : cards, sheets, toolbars (the "paper")
38
19
  · secondary : hover lanes, table heads, addons, code blocks
39
20
  · overlay : modals, drawers, popovers (paired with scrim)
40
21
  · tint : brand-tinted (active rows, sidenav active item)
@@ -84,34 +65,25 @@
84
65
 
85
66
  /* Text overlaid on arbitrary imagery (camera feeds, photos) — pairs a
86
67
  guaranteed-light colour with a contrast shadow. */
87
- --text-on-media: var(--neutral-0);
68
+ --text-on-media: var(--static-white);
88
69
  --text-on-media-shadow: 0 1px 3px hsl(0deg 0% 0% / 70%);
89
70
  --text-link: var(--blue-700);
90
- --text-on-primary: var(--neutral-0);
91
- --text-on-success: var(--neutral-0);
71
+ --text-on-primary: var(--static-white);
72
+ --text-on-success: var(--static-white);
92
73
 
93
74
  /* Warning fill is yellow (--yellow-400 #F4D43A) — white text on it is only
94
75
  ~1.5:1 (fails WCAG). On-warning text is the darkest neutral (~10:1). */
95
- --text-on-warning: var(--neutral-900);
96
- --text-on-error: var(--neutral-0);
76
+ --text-on-warning: var(--static-ink);
77
+ --text-on-error: var(--static-white);
97
78
 
98
79
  /* Icons */
99
80
  --icon-default: var(--neutral-500);
100
81
  --icon-strong: var(--neutral-700);
101
82
  --icon-muted: var(--neutral-400);
102
- --icon-on-primary: var(--neutral-0);
103
-
104
- /* Font families — a theme/brand choice (the size/weight/leading SCALE is
105
- theme-independent and lives in styles/_tokens.scss). Display + heading
106
- default to body sans; a brand can mix a serif/display family here without
107
- touching component code. */
108
- --font-sans: "Mulish", -apple-system, blinkmacsystemfont, "Segoe UI", roboto, sans-serif;
109
- --font-mono: "JetBrains Mono", ui-monospace, sfmono-regular, menlo, monospace;
110
- --font-display: var(--font-sans);
111
- --font-heading: var(--font-sans);
83
+ --icon-on-primary: var(--static-white);
112
84
 
113
85
  /* Semantic → palette bridge. The lib knows colours by PURPOSE; the theme
114
- (themes/default/_theme.scss) ships the concrete ramps + HSL channels. This
86
+ (themes/light/_theme.scss) ships the concrete ramps + HSL channels. This
115
87
  is the one place that maps semantic roles onto a concrete palette. A brand
116
88
  re-skins by overriding either the palette (--blue-*, --red-*) or these
117
89
  role tokens directly.
@@ -122,6 +94,12 @@
122
94
  --error-h: var(--red-h);
123
95
  --error-s: var(--red-s);
124
96
  --error-l: var(--red-l);
97
+ --success-h: var(--green-h);
98
+ --success-s: var(--green-s);
99
+ --success-l: var(--green-l);
100
+ --warning-h: var(--yellow-h);
101
+ --warning-s: var(--yellow-s);
102
+ --warning-l: var(--yellow-l);
125
103
 
126
104
  /* Primary roles.
127
105
  Hover / pressed / selected-hover are DERIVED from --primary at runtime via
@@ -137,7 +115,7 @@
137
115
  --primary-muted: var(--blue-100);
138
116
  --primary-muted-strong: var(--blue-200);
139
117
  --primary-strong: var(--blue-700);
140
- --primary-on: var(--neutral-0);
118
+ --primary-on: var(--static-white);
141
119
 
142
120
  /* Accent / secondary role — composed from --secondary-h/s/l channels.
143
121
  Channels default to brand values so unbranded apps render identical to
@@ -154,6 +132,7 @@
154
132
  --secondary-strong: hsl(var(--secondary-h) var(--secondary-s) calc(var(--secondary-l) - 11%));
155
133
  --secondary-subtitle: hsl(var(--secondary-h) 100% 97%);
156
134
  --secondary-muted: hsl(var(--secondary-h) 95% 94%);
135
+ --secondary-muted-strong: hsl(var(--secondary-h) 95% 89%);
157
136
  --secondary-on: var(--primary-on);
158
137
 
159
138
  /* Tertiary — third brand hue. Used by the tertiary button variant and
@@ -173,6 +152,7 @@
173
152
  --tertiary-strong: hsl(var(--tertiary-h) var(--tertiary-s) calc(var(--tertiary-l) - 11%));
174
153
  --tertiary-subtitle: hsl(var(--tertiary-h) 100% 97%);
175
154
  --tertiary-muted: hsl(var(--tertiary-h) 95% 94%);
155
+ --tertiary-muted-strong: hsl(var(--tertiary-h) 95% 89%);
176
156
  --tertiary-on: var(--primary-on);
177
157
 
178
158
  /* Status roles.
@@ -184,6 +164,7 @@
184
164
  --success-hover: color-mix(in srgb, var(--success) 88%, black);
185
165
  --success-subtitle: var(--green-50);
186
166
  --success-muted: var(--green-100);
167
+ --success-muted-strong: var(--green-200);
187
168
  --success-border: var(--green-200);
188
169
  --success-text: var(--green-700);
189
170
 
@@ -191,6 +172,7 @@
191
172
  --warning-hover: color-mix(in srgb, var(--warning) 88%, black);
192
173
  --warning-subtitle: var(--yellow-50);
193
174
  --warning-muted: var(--yellow-100);
175
+ --warning-muted-strong: var(--yellow-200);
194
176
  --warning-border: var(--yellow-200);
195
177
  --warning-text: var(--yellow-700);
196
178
 
@@ -199,9 +181,18 @@
199
181
  --error-pressed: color-mix(in srgb, var(--error) 76%, black);
200
182
  --error-subtitle: var(--red-50);
201
183
  --error-muted: var(--red-100);
184
+ --error-muted-strong: var(--red-200);
202
185
  --error-border: var(--red-200);
203
186
  --error-text: var(--red-600);
204
187
 
188
+ /* -pressed (success/warning) + -on aliases — added for the --accent-* pointer
189
+ family so every ds-color family resolves --accent-pressed / --accent-on. */
190
+ --success-pressed: color-mix(in srgb, var(--success) 76%, black);
191
+ --warning-pressed: color-mix(in srgb, var(--warning) 76%, black);
192
+ --error-on: var(--text-on-error);
193
+ --success-on: var(--text-on-success);
194
+ --warning-on: var(--text-on-warning);
195
+
205
196
  --info: var(--sky-500);
206
197
  --info-hover: color-mix(in srgb, var(--info) 88%, black);
207
198
  --info-subtitle: var(--sky-50);
@@ -256,22 +247,44 @@
256
247
  0 0 0 3px hsl(var(--primary-h) var(--primary-s) var(--primary-l) / var(--focus-field-alpha));
257
248
  --focus-field-error:
258
249
  0 0 0 3px hsl(var(--error-h) var(--error-s) var(--error-l) / var(--focus-field-alpha));
259
- }
260
250
 
261
- /* Brand-derived neutrals — opt-in family switch (ds-docs tweaks panel sets
262
- the attribute). Repoints the --neutral-* slot at the brand-gray ramp. */
263
- :root[data-neutrals='brand'] {
264
- --neutral-0: var(--brand-gray-0);
265
- --neutral-50: var(--brand-gray-50);
266
- --neutral-100: var(--brand-gray-100);
267
- --neutral-150: var(--brand-gray-150);
268
- --neutral-200: var(--brand-gray-200);
269
- --neutral-300: var(--brand-gray-300);
270
- --neutral-400: var(--brand-gray-400);
271
- --neutral-500: var(--brand-gray-500);
272
- --neutral-600: var(--brand-gray-600);
273
- --neutral-700: var(--brand-gray-700);
274
- --neutral-800: var(--brand-gray-800);
275
- --neutral-900: var(--brand-gray-900);
276
- --neutral-950: var(--brand-gray-950);
251
+ /* Per-family focus rings/fields — pre-composed once from each family's
252
+ channels so ds-color flips a single --accent-focus-* pointer (no :root
253
+ composite re-declaration in the scope). --focus-ring-error exists above. */
254
+ --focus-ring-secondary:
255
+ 0 0 0 2px var(--focus-ring-inner),
256
+ 0 0 0 4px hsl(var(--secondary-h) var(--secondary-s) var(--secondary-l) / 100%);
257
+ --focus-ring-tertiary:
258
+ 0 0 0 2px var(--focus-ring-inner),
259
+ 0 0 0 4px hsl(var(--tertiary-h) var(--tertiary-s) var(--tertiary-l) / 100%);
260
+ --focus-ring-success:
261
+ 0 0 0 2px var(--focus-ring-inner),
262
+ 0 0 0 4px hsl(var(--success-h) var(--success-s) var(--success-l) / 100%);
263
+ --focus-ring-warning:
264
+ 0 0 0 2px var(--focus-ring-inner),
265
+ 0 0 0 4px hsl(var(--warning-h) var(--warning-s) var(--warning-l) / 100%);
266
+ --focus-field-secondary:
267
+ 0 0 0 3px hsl(var(--secondary-h) var(--secondary-s) var(--secondary-l) / var(--focus-field-alpha));
268
+ --focus-field-tertiary:
269
+ 0 0 0 3px hsl(var(--tertiary-h) var(--tertiary-s) var(--tertiary-l) / var(--focus-field-alpha));
270
+ --focus-field-success:
271
+ 0 0 0 3px hsl(var(--success-h) var(--success-s) var(--success-l) / var(--focus-field-alpha));
272
+ --focus-field-warning:
273
+ 0 0 0 3px hsl(var(--warning-h) var(--warning-s) var(--warning-l) / var(--focus-field-alpha));
274
+
275
+ /* Accent pointer layer — the single indirection ds-color flips. Defaults to
276
+ the primary family (+ existing focus/tint tokens) so the unbranded theme is
277
+ pixel-identical. Components read these for their accent instead of
278
+ --primary* / --focus-* / --surface-tint. */
279
+ --accent: var(--primary);
280
+ --accent-hover: var(--primary-hover);
281
+ --accent-pressed: var(--primary-pressed);
282
+ --accent-strong: var(--primary-strong);
283
+ --accent-subtitle: var(--primary-subtitle);
284
+ --accent-muted: var(--primary-muted);
285
+ --accent-muted-strong: var(--primary-muted-strong);
286
+ --accent-on: var(--primary-on);
287
+ --accent-focus-ring: var(--focus-ring);
288
+ --accent-focus-field: var(--focus-field);
289
+ --accent-surface-tint: var(--surface-tint);
277
290
  }
@@ -0,0 +1,39 @@
1
+ // =========================================================================
2
+ // Dark palette — Tier 1b per-theme primitives.
3
+ //
4
+ // Exposes @mixin palette with ONLY the dark-specific primitives:
5
+ // · --neutral-* slot: hand-tuned dark neutrals (NOT a linear inverse —
6
+ // note --neutral-0 is an ELEVATED card surface, LIGHTER than the
7
+ // --neutral-50 canvas — the opposite of light, where 0 (#FFF) is the
8
+ // brightest stop). Brand/status ramps are left to the role layer.
9
+ // · --shadow-tint-l: 95% (flipped so same alphas read as soft glows)
10
+ //
11
+ // Theme-independent ramps (--cool-gray-*, --brand-gray-*, --blue-*, etc.)
12
+ // and HSL channels live in themes/_base-palette.scss and emit at :root.
13
+ //
14
+ // KNOWN LIMITATION — data-neutrals="brand" + dark: this ramp overrides
15
+ // --neutral-* directly, so when both `[data-neutrals='brand']` and
16
+ // `[data-theme='dark']` are set (equal specificity) dark wins by source order —
17
+ // the brand-gray hue-tint is dropped and these fixed dark neutrals apply. Benign
18
+ // (renders correctly dark, just not brand-hue-tinted); a dark brand-gray ramp is
19
+ // a future follow-up, not v1.
20
+ // =========================================================================
21
+
22
+ @mixin palette {
23
+ --neutral-0: #171B24; // surface-default / overlay (cards) — elevated
24
+ --neutral-50: #0F131A; // surface-canvas — darkest (page bg)
25
+ --neutral-100: #1E2330; // surface-secondary / disabled
26
+ --neutral-150: #242A38; // surface-muted, border-subtitle/divider/disabled
27
+ --neutral-200: #2A3040; // border-default
28
+ --neutral-300: #3A4252; // border-strong
29
+ --neutral-400: #6B7388; // text-muted/disabled, icon-muted
30
+ --neutral-500: #8A93A6; // text-tertiary, icon-default
31
+ --neutral-600: #9BA3B4;
32
+ --neutral-700: #B7BFD0; // text-secondary, icon-strong, border-inverted
33
+ --neutral-800: #CDD3E0;
34
+ --neutral-900: #E7EAF2; // text-primary, surface-inverted
35
+ --neutral-950: #F4F6FA;
36
+
37
+ // Shadow substrate flips light so the same alphas read as soft glows on dark.
38
+ --shadow-tint-l: 95%;
39
+ }