@ids-group-ltd/ids-design-system 0.11.2 → 0.11.3

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.
Files changed (75) hide show
  1. package/CHANGELOG.md +119 -2
  2. package/components.md +27 -12
  3. package/design-system.md +135 -1
  4. package/docs/agent/INDEX.md +98 -0
  5. package/docs/agent/domain/ds-w3w.md +10 -0
  6. package/docs/agent/feedback/ds-alert.md +9 -0
  7. package/docs/agent/feedback/ds-avatar-group.md +7 -0
  8. package/docs/agent/feedback/ds-avatar.md +6 -0
  9. package/docs/agent/feedback/ds-badge.md +7 -0
  10. package/docs/agent/feedback/ds-banner.md +10 -0
  11. package/docs/agent/feedback/ds-empty-state.md +7 -0
  12. package/docs/agent/feedback/ds-progress.md +7 -0
  13. package/docs/agent/feedback/ds-skeleton.md +6 -0
  14. package/docs/agent/feedback/ds-spinner.md +6 -0
  15. package/docs/agent/feedback/ds-stat.md +7 -0
  16. package/docs/agent/feedback/ds-status-dot.md +6 -0
  17. package/docs/agent/feedback/ds-tag.md +8 -0
  18. package/docs/agent/feedback/ds-toast.md +12 -0
  19. package/docs/agent/forms/ds-autocomplete.md +9 -0
  20. package/docs/agent/forms/ds-button.md +14 -0
  21. package/docs/agent/forms/ds-checkbox.md +6 -0
  22. package/docs/agent/forms/ds-date-picker.md +7 -0
  23. package/docs/agent/forms/ds-dropzone.md +10 -0
  24. package/docs/agent/forms/ds-icon-button.md +10 -0
  25. package/docs/agent/forms/ds-input.md +22 -0
  26. package/docs/agent/forms/ds-multi-select.md +6 -0
  27. package/docs/agent/forms/ds-number-stepper.md +8 -0
  28. package/docs/agent/forms/ds-radio.md +6 -0
  29. package/docs/agent/forms/ds-search.md +10 -0
  30. package/docs/agent/forms/ds-select.md +7 -0
  31. package/docs/agent/forms/ds-switch.md +6 -0
  32. package/docs/agent/forms/ds-textarea.md +9 -0
  33. package/docs/agent/forms/the-picker-family-ds-select-ds-multi-select-ds-autocomplete.md +21 -0
  34. package/docs/agent/foundations/global-helper-classes.md +18 -0
  35. package/docs/agent/foundations/grid.md +35 -0
  36. package/docs/agent/foundations/tokens.md +47 -0
  37. package/docs/agent/navigation/ds-app-layout.md +10 -0
  38. package/docs/agent/navigation/ds-auth-layout.md +9 -0
  39. package/docs/agent/navigation/ds-breadcrumbs.md +7 -0
  40. package/docs/agent/navigation/ds-divider.md +9 -0
  41. package/docs/agent/navigation/ds-page-footer.md +7 -0
  42. package/docs/agent/navigation/ds-page-header.md +8 -0
  43. package/docs/agent/navigation/ds-pagination.md +7 -0
  44. package/docs/agent/navigation/ds-sidenav-group.md +8 -0
  45. package/docs/agent/navigation/ds-sidenav-item.md +9 -0
  46. package/docs/agent/navigation/ds-sidenav.md +9 -0
  47. package/docs/agent/navigation/ds-stepper.md +6 -0
  48. package/docs/agent/navigation/ds-tabs.md +9 -0
  49. package/docs/agent/navigation/ds-topbar.md +8 -0
  50. package/docs/agent/overlays/ds-bottom-sheet.md +9 -0
  51. package/docs/agent/overlays/ds-drawer.md +9 -0
  52. package/docs/agent/overlays/ds-menu.md +8 -0
  53. package/docs/agent/overlays/ds-modal-card.md +6 -0
  54. package/docs/agent/overlays/ds-modal.md +8 -0
  55. package/docs/agent/overlays/ds-popover.md +6 -0
  56. package/docs/agent/overlays/ds-tooltip.md +8 -0
  57. package/docs/agent/platform/breadcrumbs-service.md +30 -0
  58. package/docs/agent/platform/ds-config.md +60 -0
  59. package/docs/agent/platform/ds-icon-registry.md +23 -0
  60. package/docs/agent/platform/toast-service.md +19 -0
  61. package/docs/agent/surfaces/ds-accordion.md +8 -0
  62. package/docs/agent/surfaces/ds-card.md +10 -0
  63. package/docs/agent/tables/ds-table.md +15 -0
  64. package/fesm2022/ids-group-ltd-ids-design-system.mjs +262 -338
  65. package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
  66. package/migrations/0.11.3.json +152 -0
  67. package/package.json +1 -1
  68. package/styles/_dropdown-overlay.scss +25 -32
  69. package/styles/_ds-color.scss +31 -12
  70. package/styles/_tokens-charts.scss +2 -3
  71. package/styles/_tokens.scss +158 -321
  72. package/themes/README.md +32 -1
  73. package/themes/_base-palette.scss +35 -76
  74. package/themes/_semantic.scss +5 -2
  75. package/types/ids-group-ltd-ids-design-system.d.ts +115 -190
@@ -1,35 +1,19 @@
1
- /* ============================================================
2
- Design Tokens — Tier 3 component + scale layer.
3
-
4
- Tier 1 colour primitives (ramps + HSL channels) live in
5
- ../themes/light/_palette.scss. Tier 2 semantic role assignments
6
- (surface, border, text, primary/secondary/tertiary, status, focus)
7
- live in ../themes/light/_theme.scss.
8
-
9
- THIS file owns the theme-INDEPENDENT layer:
10
- · scales — spacing, radius, sizes, hit targets, breakpoints
11
- · typography — families, sizes, weights, line-height, tracking
12
- · motion — durations, easings
13
- · elevation — shadows, blur, z-index layers
14
- · opacity — state-overlay alphas
15
- · component — Tier 3 --ds-*-* tokens (per-component geometry)
16
-
17
- Components consume only Tier 2/3 tokens. Direct use of palette
18
- primitives (--blue-600, --neutral-200, …) inside component
19
- styles is a violation — fix by introducing or reusing a role.
20
- ============================================================ */
1
+ /* Design tokens — the theme-INDEPENDENT layer. Tier 1 colour primitives live in
2
+ ../themes/_base-palette.scss and each theme's _palette.scss; Tier 2 semantic
3
+ roles in ../themes/_semantic.scss.
4
+
5
+ Components consume only Tier 2/3 tokens. Reaching for a palette primitive
6
+ (--blue-600, --neutral-200, …) from a component style is a violation — add or
7
+ reuse a role instead. */
21
8
 
22
9
  :root {
23
- /* ============================================================
24
- Spacing — 4 px base, with named half-steps where atoms need them
25
- ============================================================ */
26
10
  --space-0: 0;
27
11
  --space-px: 1px;
28
- --space-0-5: 2px; /* hairline insets, icon close button pad */
12
+ --space-0-5: 2px;
29
13
  --space-1: 4px;
30
- --space-1-5: 6px; /* badge gap, tag gap, field-label gap */
14
+ --space-1-5: 6px;
31
15
  --space-2: 8px;
32
- --space-2-5: 10px; /* tooltip pad-x, badge pad-x */
16
+ --space-2-5: 10px;
33
17
  --space-3: 12px;
34
18
  --space-4: 16px;
35
19
  --space-5: 20px;
@@ -43,75 +27,46 @@
43
27
  --space-24: 96px;
44
28
  --space-32: 128px;
45
29
 
46
- /* Semantic spacing aliases — default rhythm for the layout primitives
47
- (ds-stack / ds-inline). Components default their gap to these so the
48
- vertical/horizontal rhythm retunes in one place. */
49
- --space-stack: var(--space-4); /* 16px — vertical rhythm between stacked blocks */
50
- --space-inline: var(--space-2); /* 8px — horizontal cluster gap */
51
-
52
- /* ============================================================
53
- Radius — six-stop scale.
54
- Each step is functionally distinct; adjacent steps are
55
- visually distinguishable at standard zoom.
56
- ============================================================ */
30
+ /* Default rhythm for the layout primitives (ds-stack / ds-inline); components
31
+ default their gap here so the rhythm retunes in one place. */
32
+ --space-stack: var(--space-4);
33
+ --space-inline: var(--space-2);
34
+
57
35
  --radius-0: 0;
58
- --radius-sm: 4px; /* kbd, indeterminate-checkbox tick, link focus halo */
59
- --radius-md: 8px; /* buttons, fields, tooltips, search, segmented, tags */
60
- --radius-lg: 12px; /* menus, popovers, dropdowns, cards, modals, drawers, empty-state icons, toasts */
61
- --radius-xl: 16px; /* large containers — viewport/scanner frames, hero cards */
62
- --radius-2xl: 24px; /* heroic surfaces — reserved, no current consumer */
63
-
64
- /* --radius-pill is configurable so themes can override pill-shaped surfaces
65
- (switches, status chips, avatars, segmented thumb) without forking the
66
- full radius scale. A spreadsheet-style client can square pills with:
67
- :root[data-theme="spreadsheet"] { --radius-pill-value: var(--radius-sm); } */
36
+ --radius-sm: 4px;
37
+ --radius-md: 8px;
38
+ --radius-lg: 12px;
39
+ --radius-xl: 16px;
40
+ --radius-2xl: 24px; /* reserved — no current consumer */
41
+
42
+ /* Themes can square every pill-shaped surface (switches, status chips,
43
+ avatars, segmented thumb) without forking the radius scale:
44
+ :root[data-theme="squared"] { --radius-pill-value: var(--radius-sm); } */
68
45
  --radius-pill-value: 999px;
69
46
  --radius-pill: var(--radius-pill-value);
70
47
 
71
- /* Radius ROLES — the layer a consumer retunes. Reading the raw scale directly
72
- meant re-rounding "panels" also re-rounded every control sharing
73
- --radius-md. Each role defaults to the value its members already used, so
74
- nothing moves until one is set. Components resolve
75
- --ds-<comp>-radius -> role -> value, so a per-component override still wins.
76
- No `field` role: fields share --radius-md with buttons, so it would either
77
- duplicate `control` or silently re-round every field. A consumer who wants
78
- them apart scopes the role: `ds-input { --ds-radius-control: 4px; }`. */
48
+ /* Radius ROLES — the layer a consumer retunes. Each defaults to the value its
49
+ members already use, and components resolve --ds-<comp>-radius -> role ->
50
+ value, so a per-component override still wins. No `field` role on purpose:
51
+ fields share --radius-md with buttons, so a consumer who wants them apart
52
+ scopes the role — `ds-input { --ds-radius-control: 4px; }`. */
79
53
  --ds-radius-inner: var(--radius-sm);
80
54
  --ds-radius-control: var(--radius-md);
81
55
  --ds-radius-panel: var(--radius-lg);
82
56
  --ds-radius-pill: var(--radius-pill);
83
57
 
84
- /* Component-scoped radius — kept only when the semantic intent matters
85
- beyond the value itself, OR when the global scale doesn't fit. */
86
- --radius-flat: var(--radius-0); /* explicit "intentionally squared" — middle of btn-group, in-range datepicker */
87
-
88
- /* ============================================================
89
- Border widths — two-stop scale.
90
- Adjacent widths must be visually distinguishable; 1.5/2.5
91
- mid-stops were dropped because they read identically to
92
- 1/2 on standard displays.
93
- ============================================================ */
94
- --border-width-default: 1px; /* every border, divider, field outline */
95
- --border-width-strong: 2px; /* radio dot, slider thumb, tabs underline, focus ring inner band, dropzone dash */
96
-
97
- /* Focus outline-offset — gap between an element edge and its focus ring;
98
- unifies the 2px offset repeated across stepper/table/dropzone/color-picker. */
99
- --focus-ring-offset: 2px;
58
+ --radius-flat: var(--radius-0); /* explicit "intentionally squared", not an unset radius */
100
59
 
101
- /* ============================================================
102
- Elevation
103
- Channel-split substrate so a re-skin can re-tint shadows.
104
- Light theme: cool near-black slate (225 / 39% / 7%).
105
- Dark theme: override --shadow-tint-l to ~95% so the same
106
- alphas render as soft light glows over dark surfaces.
107
- The alpha values stay constant across themes — only the
108
- hue/saturation/lightness become configurable.
109
- ============================================================ */
60
+ /* Two stops only: 1.5/2.5 mid-stops read identically to 1/2 on standard displays. */
61
+ --border-width-default: 1px;
62
+ --border-width-strong: 2px;
110
63
 
111
- /* --shadow-tint-h/s live in themes/_base-palette.scss and -l in each theme's
112
- _palette.scss — palette-level
113
- so dark palettes can override --shadow-tint-l → ~95% for soft light glows. */
64
+ --focus-ring-offset: 2px;
114
65
 
66
+ /* Shadows are composed from a channel-split tint so a theme can re-colour them:
67
+ --shadow-tint-h/s come from ../themes/_base-palette.scss and -l from each
68
+ theme's _palette.scss (light 7%, dark 95%, so the same alphas read as soft
69
+ glows over dark surfaces). The alphas below stay constant across themes. */
115
70
  --shadow-1: 0 1px 2px hsl(var(--shadow-tint-h) var(--shadow-tint-s) var(--shadow-tint-l) / 6%),
116
71
  0 1px 3px hsl(var(--shadow-tint-h) var(--shadow-tint-s) var(--shadow-tint-l) / 8%);
117
72
  --shadow-2: 0 4px 8px hsl(var(--shadow-tint-h) var(--shadow-tint-s) var(--shadow-tint-l) / 6%),
@@ -121,11 +76,9 @@
121
76
  --shadow-4: 0 16px 32px hsl(var(--shadow-tint-h) var(--shadow-tint-s) var(--shadow-tint-l) / 12%),
122
77
  0 24px 48px hsl(var(--shadow-tint-h) var(--shadow-tint-s) var(--shadow-tint-l) / 18%);
123
78
 
124
- /* Elevation ROLES, and the older --shadow-<surface> aliases now point AT them
125
- rather than at a step: setting a role moves every surface at that height,
126
- while an alias still retunes one family. Four roles, not the three first
127
- sketched — the library genuinely uses four heights, and folding toast into
128
- `overlay` would have changed its shadow. */
79
+ /* Elevation ROLES — the --shadow-<surface> aliases below resolve through these,
80
+ so setting a role moves every surface at that height while an alias still
81
+ retunes one family. */
129
82
  --ds-elevation-raised: var(--shadow-1);
130
83
  --ds-elevation-overlay: var(--shadow-2);
131
84
  --ds-elevation-floating: var(--shadow-3);
@@ -136,15 +89,9 @@
136
89
  --shadow-toast: var(--ds-elevation-floating);
137
90
  --shadow-card: var(--ds-elevation-raised);
138
91
 
139
- /* Backdrop blur */
140
92
  --blur-sm: 4px;
141
93
  --blur-md: 8px;
142
94
 
143
- /* ============================================================
144
- Z-index — global stacking scale.
145
- Component-internal stacking (e.g. sticky headers within a
146
- scroll container) uses component-scoped tokens derived from
147
- the global scale so refactors stay local. */
148
95
  --layer-base: 0;
149
96
  --layer-raised: 1;
150
97
  --layer-sticky: 100;
@@ -156,7 +103,6 @@
156
103
  --layer-toast: 1500;
157
104
  --layer-tooltip: 1600;
158
105
 
159
- /* Component-scoped stacking */
160
106
  --table-sticky-header-z: var(--layer-raised);
161
107
  --table-sticky-col-z: var(--layer-raised);
162
108
  --table-sticky-corner-z: 2; /* sticky col header sits over both axes */
@@ -169,40 +115,28 @@
169
115
  --duration-slow: 260ms;
170
116
  --duration-slower: 400ms;
171
117
 
172
- /* Loop durations — for indeterminate spinners, skeletons, progress.
173
- These deliberately sit outside the transition scale because
174
- they describe rhythm, not response. */
118
+ /* Loop durations sit outside the transition scale on purpose — they describe
119
+ rhythm, not response. */
175
120
  --duration-loop-fast: 700ms;
176
121
  --duration-loop-slow: 1400ms;
177
122
 
178
- /* Easing.
179
- - standard: default for transitions; decelerates into rest.
180
- Use for state changes (hover, focus, toggle).
181
- - emphasized: accelerate-decelerate; bigger movements that
182
- "pick up and put down". Use for entries/exits
183
- of overlays, modals, drawers.
184
- - decelerate: incoming-only (out → in). Use when something
185
- appears (toast, tooltip, popover open).
186
- - accelerate: outgoing-only (in → out). Use when something
187
- leaves (toast dismiss, modal close).
188
- - spring: playful overshoot; sparingly. Reserved for
189
- small celebratory feedback. */
123
+ /* Easing — which to pick:
124
+ - standard: state changes (hover, focus, toggle)
125
+ - emphasized: overlay / modal / drawer entries and exits; overshoots
126
+ - decelerate: something appearing (toast, tooltip, popover open)
127
+ - accelerate: something leaving (toast dismiss, modal close)
128
+ - spring: overshoot for small celebratory feedback; sparingly */
190
129
  --ease-standard: cubic-bezier(.2, 0, 0, 1);
191
130
  --ease-emphasized: cubic-bezier(.3, 0, .1, 1.4);
192
131
  --ease-decelerate: cubic-bezier(0, 0, 0, 1);
193
132
  --ease-accelerate: cubic-bezier(.3, 0, 1, 1);
194
133
  --ease-spring: cubic-bezier(.5, 1.5, .5, 1);
195
134
 
196
- /* Motion ROLES — the per-surface --ds-<surface>-enter/leave-* hooks defaulted
197
- straight to the raw scale, so "make every panel entrance snappier" meant
198
- retuning each surface. A role names the intent once and every surface at that
199
- scale follows. Defaults equal the values each surface already used, so nothing
200
- moves until a role is set.
201
- FIVE roles, not the four first sketched: panel LEAVES run at --duration-base,
202
- not fast, so folding them into `exit` would have sped them up. Two resolvers
203
- stay on the raw scale on purpose — ds-loading-overlay and the toast leave use
204
- --ease-standard, which no role carries, and inventing a role for two sites
205
- would be worse than naming the value. */
135
+ /* Motion ROLES — name the intent once and every surface at that scale follows.
136
+ Defaults equal the values each surface already used, so nothing moves until a
137
+ role is set. `exit` and `exit-large` stay separate because panel LEAVES run at
138
+ --duration-base, not fast. A few resolvers stay on the raw scale on purpose:
139
+ ds-loading-overlay and the toast leave use --ease-standard, which no role carries. */
206
140
  --ds-motion-enter-panel-duration: var(--duration-fast);
207
141
  --ds-motion-enter-panel-easing: var(--ease-decelerate);
208
142
  --ds-motion-enter-surface-duration: var(--duration-base);
@@ -214,32 +148,23 @@
214
148
  --ds-motion-exit-large-duration: var(--duration-base);
215
149
  --ds-motion-exit-large-easing: var(--ease-accelerate);
216
150
 
217
- /* Opacity — semantic, purpose-named (Material/Carbon/Polaris convention).
218
- Each token has a real consumer in the codebase; symmetric "unused"
219
- numeric stops are deliberately omitted. */
220
- --opacity-disabled: 0.5; /* full disabled state on interactive components */
221
- --opacity-text-disabled: 0.38; /* disabled text alpha (WCAG-derived) */
222
- --opacity-scrim: 0.55; /* modal/drawer backdrop overlay (light theme) */
223
- --opacity-state-hover: 0.08; /* hover layer over surface (overlay vs surface swap) */
224
- --opacity-state-pressed: 0.16; /* active/pressed layer */
225
- --opacity-state-active: 0.24; /* deepest pressed layer (e.g. tag close on :active) */
226
-
227
- /* ============================================================
228
- Breakpoints — $bp-* Sass aliases + up()/down() mixins live in
229
- _breakpoints.scss (pure); the --bp-* custom properties come from
230
- its emit-vars mixin, included once by styles/ds.
231
- ============================================================ */
232
-
233
- /* ============================================================
234
- Page grid — tier-specific gutters + margins.
235
- Consumed by `.page-grid` in _page-grid.scss; one column-count
236
- per tier (4 / 8 / 12 / 12) with `--page-gutter` and
237
- `--page-margin` swapping at the matching min-width breakpoint.
238
- ============================================================ */
239
- --page-gutter-mobile: var(--space-3); /* 12px — <= 640px, 4-col tier */
240
- --page-gutter-tablet: var(--space-4); /* 16px — 641–1024px, 8-col tier */
241
- --page-gutter-desktop: var(--space-5); /* 20px — 1025–1440px, 12-col tier */
242
- --page-gutter-wide: var(--space-6); /* 24px — >= 1441px, 12-col tier, container caps */
151
+ --opacity-disabled: 0.5;
152
+ --opacity-text-disabled: 0.38; /* WCAG-derived */
153
+ --opacity-scrim: 0.55;
154
+ --opacity-state-hover: 0.08;
155
+ --opacity-state-pressed: 0.16;
156
+ --opacity-state-active: 0.24; /* deeper than -pressed, for a third press level */
157
+
158
+ /* Breakpoints: the $bp-* Sass aliases and up()/down() mixins live in
159
+ _breakpoints.scss; the --bp-* runtime mirror comes from its emit-vars mixin,
160
+ included once by styles/ds. */
161
+
162
+ /* Tier gutters and margins for `.page-grid`; _page-grid.scss owns the tier
163
+ table and swaps these at the matching min-width breakpoint. */
164
+ --page-gutter-mobile: var(--space-3); /* 12px */
165
+ --page-gutter-tablet: var(--space-4); /* 16px */
166
+ --page-gutter-desktop: var(--space-5); /* 20px */
167
+ --page-gutter-wide: var(--space-6); /* 24px */
243
168
  --page-margin-mobile: var(--space-4); /* 16px */
244
169
  --page-margin-tablet: var(--space-6); /* 24px */
245
170
  --page-margin-desktop: var(--space-8); /* 32px */
@@ -253,12 +178,8 @@
253
178
  --col-cap-text: 720px;
254
179
  --col-cap-content: 1280px;
255
180
 
256
- /* ============================================================
257
- Typography scale (theme-independent). Font FAMILIES are a theme
258
- choice and live in themes/light/_theme.scss (--font-sans/mono/
259
- display/heading); the size/weight/leading/tracking scale below is
260
- constant across themes.
261
- ============================================================ */
181
+ /* Font FAMILIES are a theme choice and live in ../themes/_base-palette.scss;
182
+ the size/weight/leading/tracking scale below is constant across themes. */
262
183
  --font-weight-regular: 400;
263
184
  --font-weight-medium: 500;
264
185
  --font-weight-semibold: 600;
@@ -271,21 +192,21 @@
271
192
  --font-size-h3: 28px;
272
193
  --font-size-h4: 22px;
273
194
  --font-size-h5: 18px;
274
- --font-size-h5-strong: 20px; /* modal titles, condensed headers */
195
+ --font-size-h5-strong: 20px;
275
196
  --font-size-l: 18px;
276
197
  --font-size-m: 16px;
277
198
  --font-size-s: 14px;
278
199
  --font-size-xs: 12px;
279
200
  --font-size-2xs: 11px;
280
- --font-size-3xs: 10px; /* avatar-sm font */
281
- --font-size-4xs: 9px; /* avatar-xs font */
201
+ --font-size-3xs: 10px;
202
+ --font-size-4xs: 9px;
282
203
  --font-size-mono: 13px;
283
204
 
284
205
  --line-height-tight: 1.1;
285
206
  --line-height-snug: 1.25;
286
207
  --line-height-base: 1.4;
287
208
  --line-height-loose: 1.6;
288
- --line-height-flat: 1; /* button labels, single-line UI */
209
+ --line-height-flat: 1;
289
210
 
290
211
  --letter-spacing-tight: -.02em;
291
212
  --letter-spacing-snug: -.01em;
@@ -293,16 +214,13 @@
293
214
  --letter-spacing-wide: .02em;
294
215
  --letter-spacing-wider: .08em;
295
216
 
296
- /* ============================================================
297
- Hit targets — the canonical size scale for interactive height
298
- ============================================================ */
299
- --hit-xs: 24px; /* btn-s, datepicker nav, modal close */
300
- --hit-sm: 28px; /* segmented btn, stepper node */
301
- --hit-md: 36px; /* search, pagination, tag-input rows */
302
- --hit-min: 32px; /* dense desktop default (alias of --hit-cozy-tier-0) */
303
- --hit-cozy: 40px; /* default control height */
304
- --hit-comfy: 44px; /* WCAG min for touch */
305
- --hit-touch: 48px; /* mobile-friendly */
217
+ --hit-xs: 24px;
218
+ --hit-sm: 28px;
219
+ --hit-md: 36px;
220
+ --hit-min: 32px; /* dense desktop default */
221
+ --hit-cozy: 40px; /* default control height; retuned by every density tier */
222
+ --hit-comfy: 44px; /* WCAG 2.5.5 minimum for touch */
223
+ --hit-touch: 48px;
306
224
 
307
225
  --icon-2xs: 10px;
308
226
  --icon-xs: 12px;
@@ -310,32 +228,21 @@
310
228
  --icon-md: 16px;
311
229
  --icon-lg: 20px;
312
230
 
313
- /* ============================================================
314
- 3 · COMPONENT-SCOPED dimensions
315
- Atom-level geometry that doesn't fit cleanly in a global
316
- scale. Density Tweaks override these at :root.
317
- ============================================================ */
318
-
319
- /* Field padding — density-aware, consumed by input, search and
320
- textarea controls. Tokenised so the ultra-compact tier can
321
- compress without component edits. */
322
231
  --field-pad-x: var(--space-3);
323
232
  --field-pad-y: 0;
324
233
 
325
- /* Shared inner padding for surface containers (card, stat, …). Components
326
- default their own --ds-*-pad to this, so a consumer retunes all at once. */
234
+ /* Components default their own --ds-*-pad to this, so a consumer retunes every
235
+ surface container (card, stat, …) at once. */
327
236
  --ds-container-pad: var(--space-6);
328
237
 
329
- /* Shared focus indicators — components default their own --ds-*-focus-shadow
330
- to these, so a consumer retunes focus per-group at once (field vs control)
331
- or per-component. Two families: fields get the soft halo, interactive
332
- controls/nav get the crisp ring (see themes/light/_theme.scss). */
238
+ /* Two focus families: fields get the soft halo, interactive controls and nav
239
+ the crisp ring. Components default their own --ds-*-focus-shadow to these,
240
+ so a consumer can retune a whole family or a single component. */
333
241
  --ds-field-focus-shadow: var(--focus-field);
334
242
  --ds-field-focus-shadow-error: var(--focus-field-error);
335
243
  --ds-control-focus-shadow: var(--focus-ring);
336
244
  --ds-control-focus-shadow-error: var(--focus-ring-error);
337
245
 
338
- /* Table cell padding — density-aware, consumed by .tbl td/th. */
339
246
  --table-cell-pad-x: var(--space-4);
340
247
  --table-cell-pad-y: var(--space-3);
341
248
  --table-head-pad-y: var(--space-3);
@@ -346,34 +253,29 @@
346
253
  --check-indet-h: 2px;
347
254
  --radio-dot-size: 10px;
348
255
  --radio-bw-checked: var(--border-width-strong);
349
- --check-glyph-sm: 14px; /* .size-sm / .size-lg control box — fixed, not density-scaled */
256
+ --check-glyph-sm: 14px; /* size-sm / size-lg boxes — fixed, not density-scaled like --check-size */
350
257
  --check-glyph-lg: 24px;
351
258
  --radio-glyph-sm: 14px;
352
259
  --radio-glyph-lg: 24px;
353
260
 
354
- /* Switch */
355
261
  --switch-track-w: 36px;
356
262
  --switch-track-h: 20px;
357
263
  --switch-thumb-size: 16px;
358
264
  --switch-thumb-pad: 2px;
359
265
  --switch-thumb-travel: 16px; /* track-w − thumb − 2*pad */
360
266
 
361
- /* Slider */
362
267
  --slider-track-h: 4px;
363
268
  --slider-thumb-size: 18px;
364
269
  --slider-thumb-bw: var(--border-width-strong);
365
270
 
366
- /* Status dot, badge dot */
367
271
  --status-dot-size: 8px;
368
272
  --badge-dot-size: 6px;
369
273
 
370
- /* Badge */
371
274
  --badge-pad-y: 4px;
372
275
  --badge-pad-x: 10px;
373
276
  --badge-gap: var(--space-1-5);
374
277
  --badge-count-size: 20px;
375
278
 
376
- /* Tag */
377
279
  --tag-pad-y: 6px;
378
280
  --tag-pad-x: 10px;
379
281
  --tag-pad-x-close: 6px;
@@ -381,37 +283,30 @@
381
283
  --tag-close-size: 14px;
382
284
  --tag-close-pad: 2px;
383
285
 
384
- /* Avatar */
385
286
  --avatar-xs: 20px;
386
287
  --avatar-sm: 24px;
387
288
  --avatar-md: 32px;
388
289
  --avatar-lg: 40px;
389
290
  --avatar-bw-group: var(--border-width-strong);
390
291
 
391
- /* Spinner */
392
292
  --spinner-sm: 12px;
393
293
  --spinner-md: 16px;
394
294
  --spinner-lg: 24px;
395
295
  --spinner-bw: var(--border-width-strong);
396
296
 
397
- /* Progress */
398
297
  --progress-h: 6px;
399
298
 
400
- /* Stepper */
401
299
  --stepper-node-size: 28px; /* === --hit-sm */
402
300
  --stepper-bar-w: 56px;
403
301
  --stepper-bar-h: 2px;
404
302
 
405
- /* Segmented control */
406
303
  --segmented-btn-h: var(--hit-sm);
407
304
  --segmented-r-inner: var(--radius-md);
408
305
  --segmented-pad: 2px;
409
306
 
410
- /* Sidenav */
411
307
  --sidenav-w: 240px;
412
308
  --sidenav-w-collapsed: 64px;
413
309
 
414
- /* Modal */
415
310
  --modal-w-sm: 480px;
416
311
  --modal-w-md: 640px;
417
312
  --modal-w-lg: 800px;
@@ -419,19 +314,15 @@
419
314
  --modal-w-fullscreen: calc(100vw - var(--space-6));
420
315
  --modal-h-fullscreen: calc(100vh - var(--space-6));
421
316
 
422
- /* Auth layout */
423
317
  --auth-card-w: 420px;
424
318
 
425
- /* Drawer */
426
319
  --drawer-w-sm: 320px;
427
320
  --drawer-w-md: 480px;
428
321
  --drawer-w-lg: 640px;
429
322
 
430
- /* Popover / cmdk */
431
323
  --popover-maxh: 360px;
432
324
 
433
- /* Field */
434
- --field-label-gap: var(--space-1-5); /* field vertical rhythm: label↔control & control↔hint */
325
+ --field-label-gap: var(--space-1-5); /* both label↔control and control↔hint */
435
326
  --field-gap-req: var(--space-1); /* label↔asterisk */
436
327
  --field-h-sm: var(--hit-min);
437
328
  --field-h-md: var(--hit-cozy);
@@ -439,195 +330,150 @@
439
330
  --field-textarea-min: 96px;
440
331
  --field-num-stepper-w: var(--space-8);
441
332
 
442
- /* OTP / PIN input — one box per digit. */
443
333
  --otp-cell-w: var(--space-12); /* 48px */
444
334
  --otp-cell-h: var(--space-14); /* 56px */
445
- --otp-gap: var(--space-2); /* 8px between cells */
335
+ --otp-gap: var(--space-2); /* 8px */
446
336
 
447
- /* Color picker */
448
- --color-picker-swatch: var(--space-6); /* 24px preset swatch */
449
- --color-picker-preview: var(--space-10); /* 40px panel preview */
450
- --color-picker-panel-w: 240px; /* picker overlay width */
337
+ --color-picker-swatch: var(--space-6); /* 24px */
338
+ --color-picker-preview: var(--space-10); /* 40px */
339
+ --color-picker-panel-w: 240px;
451
340
  --color-picker-sv-h: 160px; /* saturation/value plane height */
452
- --color-picker-hue-h: var(--space-3); /* 12px hue slider height */
453
- --color-picker-thumb: 14px; /* draggable thumb diameter */
454
-
455
- /* ============================================================
456
- 3b · COMPONENT-SCOPED dimensions (Phase 4 additions)
457
- Tokens for atom geometries that previously lived as literals
458
- inside component CSS. Grouped by component for readability.
459
- ============================================================ */
460
-
461
- /* Top bar / app layout */
462
- --topbar-h: var(--space-14); /* 56px — global app bar height */
463
-
464
- /* Sidenav internals — w / w-collapsed defined above */
465
- --sidenav-pad-brand-y: var(--space-2); /* logo top padding */
466
- --sidenav-pad-brand-b: var(--space-6); /* logo bottom padding */
467
- --sidenav-logo-size: var(--hit-sm); /* 28px — square brand mark */
468
- --sidenav-collapsed-item: var(--hit-cozy); /* 40px — collapsed nav-item hit area */
469
- --sidenav-collapsed-glyph: var(--icon-lg); /* 20px — matches the size the item template renders its icon at */
470
- --sidenav-section-pad-b: var(--space-1-5); /* nav-section bottom padding */
471
- --sidenav-item-rail-width: 3px; /* active-item left rail */
472
-
473
- /* Form section grid */
474
- --form-section-label-w: 280px; /* labels column width */
475
-
476
- /* Page header */
477
- --page-header-sub-mt: var(--space-1); /* subtitle top margin */
478
-
479
- /* Bottom sheet */
480
- --bottom-sheet-handle-w: 36px; /* drag-handle bar */
341
+ --color-picker-hue-h: var(--space-3); /* 12px */
342
+ --color-picker-thumb: 14px;
343
+
344
+ --topbar-h: var(--space-14); /* 56px */
345
+
346
+ --sidenav-pad-brand-y: var(--space-2);
347
+ --sidenav-pad-brand-b: var(--space-6);
348
+ --sidenav-logo-size: var(--hit-sm); /* 28px */
349
+ --sidenav-collapsed-item: var(--hit-cozy); /* 40px */
350
+ --sidenav-collapsed-glyph: var(--icon-lg); /* 20px — must match the size the item template renders its icon at */
351
+ --sidenav-section-pad-b: var(--space-1-5);
352
+ --sidenav-item-rail-width: 3px;
353
+
354
+ --form-section-label-w: 280px;
355
+
356
+ --page-header-sub-mt: var(--space-1);
357
+
358
+ --bottom-sheet-handle-w: 36px;
481
359
  --bottom-sheet-handle-h: 4px;
482
360
 
483
- /* Field internals */
484
- --field-textarea-rows-min: 60px; /* min-h for inline textarea inside the field wrapper */
485
- --field-select-pad-r: var(--space-6); /* select chevron clearance */
486
- --field-affix-overlap: var(--border-width-default); /* affix bleed over field border */
361
+ --field-textarea-rows-min: 60px; /* the inline textarea inside the field wrapper, not --field-textarea-min */
362
+ --field-select-pad-r: var(--space-6); /* chevron clearance */
363
+ --field-affix-overlap: var(--border-width-default);
487
364
 
488
- /* Button group */
489
- --btn-group-overlap: calc(var(--border-width-default) * -1); /* -1px — collapses adjacent borders */
490
- --btn-link-uloff: 3px; /* underline-offset on link buttons */
491
- --breadcrumbs-link-uloff: 2px; /* underline-offset on breadcrumb links */
365
+ --btn-group-overlap: calc(var(--border-width-default) * -1); /* collapses adjacent borders */
366
+ --btn-link-uloff: 3px; /* underline-offset */
367
+ --breadcrumbs-link-uloff: 2px;
492
368
 
493
- /* Card */
494
- --card-hover-lift: 1px; /* translateY on .card--hover */
369
+ --card-hover-lift: 1px;
495
370
  --card-title-fs: var(--font-size-h4);
496
371
 
497
- /* Sort icon (table headers) */
498
372
  --sort-ic-size: var(--icon-xs); /* 12px */
499
373
  --sort-ic-gap: var(--space-1-5); /* 6px */
500
- --sort-ic-opacity-idle: 0.4; /* unsorted column icon */
374
+ --sort-ic-opacity-idle: 0.4;
501
375
 
502
- /* Tag close glyph (when literal svg sits inside .tag .x) */
376
+ /* The literal svg inside .tag .x, not the button box (--tag-close-size). */
503
377
  --tag-close-glyph: var(--icon-xs); /* 12px */
504
378
 
505
- /* Bulk action toolbar */
506
- --bulk-bar-offset: var(--space-4); /* sticky offset from container bottom */
379
+ --bulk-bar-offset: var(--space-4); /* sticky offset from the container bottom */
507
380
 
508
- /* Menu */
509
- --menu-minw: 200px; /* dropdown menu min width */
381
+ --menu-minw: 200px;
510
382
  --menu-sep-h: var(--border-width-default);
511
383
 
512
- /* List / list-item — density-aware row padding + leading/trailing gap. */
513
384
  --list-item-pad-y: var(--space-3); /* 12px */
514
385
  --list-item-pad-x: var(--space-4); /* 16px */
515
386
  --list-item-gap: var(--space-3); /* 12px leading↔body↔trailing */
516
387
 
517
- /* Tooltip */
518
388
  --tooltip-maxw: 240px;
519
389
  --tooltip-arrow: var(--space-2); /* 8px — caret edge length, halved for offset */
520
390
 
521
- /* Popover */
522
391
  --popover-maxw: 320px;
523
392
 
524
- /* Toast */
525
393
  --toast-minw: 320px;
526
394
  --toast-maxw: 480px;
527
- --toast-bar-w: 3px; /* left accent bar */
528
- --toast-enter-y: var(--space-1); /* slide-in distance */
395
+ --toast-bar-w: 3px;
396
+ --toast-enter-y: var(--space-1);
529
397
 
530
- /* Banner / Alert */
531
- --banner-bar-w: 4px; /* left accent bar */
532
- --banner-ic-mt: var(--border-width-default); /* optical bump for icon alignment */
398
+ --banner-bar-w: 4px;
533
399
 
534
- /* Empty state */
535
400
  --empty-icon-size: var(--space-16); /* 64px */
536
401
  --empty-body-maxw: 360px;
537
402
 
538
403
  /* Pickers — the listbox panel shared by select, autocomplete and multi-select. */
539
- --picker-offset: var(--space-1); /* gap below trigger */
540
- --picker-maxh: 280px; /* listbox max height */
404
+ --picker-offset: var(--space-1); /* gap below the trigger */
405
+ --picker-maxh: 280px;
541
406
 
542
- /* Command palette (cmdk) */
543
407
  --cmdk-w: 560px;
544
- --cmdk-list-maxh: var(--popover-maxh); /* alias — keeps cmdk + popover synced */
408
+ --cmdk-list-maxh: var(--popover-maxh); /* alias — keeps cmdk and popover in step */
545
409
 
546
- /* Datepicker */
547
410
  --date-picker-w: 280px;
548
- --date-picker-cell-gap: var(--space-0-5); /* 2px — grid gap between day cells */
549
- --date-picker-nav-size: var(--hit-xs); /* 24px — month-step buttons */
411
+ --date-picker-cell-gap: var(--space-0-5); /* 2px */
412
+ --date-picker-nav-size: var(--hit-xs); /* 24px */
550
413
 
551
- /* Modal close button */
552
414
  --modal-close-size: var(--hit-xs); /* 24px */
553
- --modal-enter-y: var(--space-2); /* 8px slide-in */
415
+ --modal-enter-y: var(--space-2); /* 8px */
554
416
 
555
- /* Error page */
556
417
  --errorpage-body-maxw: 520px;
557
418
 
558
- /* Wizard (extras) */
559
419
  --wizard-body-minh: 200px;
560
- --wizard-step-bar-w: var(--space-8); /* 32px connector */
420
+ --wizard-step-bar-w: var(--space-8); /* 32px */
561
421
 
562
- /* Inline edit */
563
422
  --inline-edit-input-minw: var(--space-20); /* 80px */
564
423
  --inline-edit-btn-size: var(--hit-xs); /* 24px */
565
424
 
566
- /* Settings */
567
425
  --settings-nav-w: 220px;
568
426
  --settings-row-label-w: 240px;
569
- --settings-row-label-gap: var(--space-0-5); /* 2px between strong + helper */
427
+ --settings-row-label-gap: var(--space-0-5); /* 2px */
570
428
 
571
- /* Matrix */
572
- --matrix-maxh: 360px; /* shares optical with --popover-maxh by intent */
429
+ --matrix-maxh: 360px; /* deliberately the same optic as --popover-maxh, not an alias */
573
430
  --matrix-cell-pad-y: var(--space-2); /* 8px */
574
431
  --matrix-cell-pad-x: var(--space-2-5); /* 10px */
575
432
  --matrix-cell-minw: var(--space-16); /* 64px */
576
433
  --matrix-rowhdr-minw: 160px;
577
434
 
578
- /* Calendar / timeline */
579
435
  --calendar-rowlabel-w: 160px;
580
436
  --calendar-row-h: var(--hit-touch); /* 48px */
581
- --calendar-cell-min: var(--hit-cozy); /* 40px minimum column width */
582
- --calendar-cell-pad: var(--space-1); /* 4px inner padding */
437
+ --calendar-cell-min: var(--hit-cozy); /* 40px */
438
+ --calendar-cell-pad: var(--space-1); /* 4px */
583
439
  --calendar-bar-h: var(--space-8); /* 32px */
584
- --calendar-bar-inset-y: var(--space-2); /* 8px from top of cell */
440
+ --calendar-bar-inset-y: var(--space-2); /* 8px */
585
441
 
586
- /* Timeline / activity feed */
587
- --timeline-node-size: var(--hit-sm); /* 28px event node */
588
- --timeline-spine-w: var(--border-width-strong); /* 2px connector spine */
589
- --timeline-gap: var(--space-5); /* vertical gap between events */
442
+ --timeline-node-size: var(--hit-sm); /* 28px */
443
+ --timeline-spine-w: var(--border-width-strong); /* 2px */
444
+ --timeline-gap: var(--space-5);
590
445
 
591
- /* Tree-view */
592
446
  --tree-indent: var(--space-5); /* 20px per nesting level */
593
447
  --tree-row-pad-y: var(--space-1-5); /* 6px */
594
- --tree-row-pad-x: var(--space-3); /* 12px base inset */
448
+ --tree-row-pad-x: var(--space-3); /* 12px */
595
449
 
596
- /* Bin pack visualisation */
597
450
  --binpack-bay-h: var(--hit-touch); /* 48px */
598
451
 
599
- /* Map placeholder chip */
600
452
  --map-chip-pad-y: var(--space-1-5); /* 6px */
601
453
  --map-chip-pad-x: var(--space-2-5); /* 10px */
602
- --map-chip-inset: var(--space-3); /* 12px from top-left */
454
+ --map-chip-inset: var(--space-3); /* 12px */
603
455
 
604
- /* KBD badge */
605
456
  --kbd-pad-y: var(--space-0-5); /* 2px */
606
457
  --kbd-pad-x: var(--space-1-5); /* 6px */
607
458
 
608
- /* Chart */
609
459
  --chart-empty-h: 160px;
610
460
  --chart-skeleton-h: 160px;
611
461
  --chart-legend-dot: var(--icon-2xs); /* 10px */
612
462
 
613
- /* Compare layout */
614
463
  --compare-dt-w: 90px;
615
464
 
616
- /* Do/Don't stage */
617
465
  --dodont-stage-minh: 100px;
618
466
 
619
- /* Statemap arrow */
620
467
  --statemap-arrow-w: var(--space-8); /* 32px */
621
- --statemap-arrow-cap: var(--space-1); /* 4px caret border-width */
468
+ --statemap-arrow-cap: var(--space-1); /* 4px — caret border-width */
622
469
 
623
- /* Page composition (extras) */
624
- --grid-table-min: 220px; /* auto-fit minmax */
470
+ --grid-table-min: 220px; /* auto-fit minmax floor */
625
471
  --grid-cols-card-minh: 120px;
626
472
  --grid-cols-card-thumb: 80px;
627
473
  --dl-spec-label-w: 120px;
628
474
  --scroll-spec-h: 220px;
629
475
  --tab-spec-maxw: 220px;
630
- --tab-spec-dot-offset: var(--border-width-strong); /* -2px notification offset (negated inline) */
476
+ --tab-spec-dot-offset: var(--border-width-strong); /* negated at the use site */
631
477
  }
632
478
 
633
479
  @media (prefers-reduced-motion: reduce) {
@@ -638,32 +484,26 @@
638
484
  --duration-slow: 0ms;
639
485
  --duration-slower: 0ms;
640
486
 
641
- /* Looping status indicators (spinners, indeterminate progress) stay
642
- visible but calmer — slowed, never frozen: a stopped spinner reads as
643
- "hung", not "loading". The one large motion we DO halt is the page-wide
644
- skeleton sweep, which stops itself in _skeleton-shimmer.scss. */
487
+ /* Loops are slowed, never frozen: a stopped spinner reads as "hung", not
488
+ "loading". The one large motion that does halt is the page-wide skeleton
489
+ sweep, which stops itself in _skeleton-shimmer.scss. */
645
490
  --duration-loop-fast: 1400ms;
646
491
  --duration-loop-slow: 2800ms;
647
492
  }
648
493
 
649
- /* Kill one-shot motion only. Every entrance/transition animation is
650
- token-driven, so zeroing the one-shot durations above already makes them
651
- instant — loops must NOT be blanket-zeroed here or they freeze. */
494
+ /* One-shot motion only. Every entrance/transition is token-driven, so zeroing
495
+ the durations above already makes them instant — loops must NOT be
496
+ blanket-zeroed here or they freeze. */
652
497
  *, *::before, *::after {
653
498
  transition-duration: 0ms !important;
654
499
  }
655
500
  }
656
501
 
657
- /* ============================================================
658
- Density tiers — set [data-density] on <html> or any container
659
- ============================================================ */
660
502
  [data-density="ultra-compact"] {
661
- /* Power-user / tradesperson tier: financial dashboards, log viewers,
662
- dense data grids. 24px hits sit BELOW WCAG 2.5.5 (44px enhanced)
663
- and WCAG 2.5.8 (24px minimum) margins — acceptable only when:
664
- (a) the screen is keyboard-first, (b) input is mouse/keys not
665
- touch, (c) accidental-tap risk is low, (d) the user opted in.
666
- Do not enable for mobile or touch-first layouts. */
503
+ /* 24px hits sit BELOW WCAG 2.5.5 (44px enhanced) and WCAG 2.5.8 (24px
504
+ minimum) margins — acceptable only when: (a) the screen is keyboard-first,
505
+ (b) input is mouse/keys not touch, (c) accidental-tap risk is low, (d) the
506
+ user opted in. Do not enable for mobile or touch-first layouts. */
667
507
  --hit-cozy: 24px;
668
508
  --hit-min: 24px;
669
509
  --check-size: 14px;
@@ -677,14 +517,13 @@
677
517
  --sidenav-w: 200px;
678
518
  --segmented-btn-h: 20px;
679
519
 
680
- /* Ultra also compresses field + table padding (tighter than compact/comfy). */
681
520
  --field-pad-x: var(--space-2);
682
521
  --field-pad-y: var(--space-1);
683
522
  --table-cell-pad-x: var(--space-2);
684
523
  --table-cell-pad-y: var(--space-1);
685
524
  --table-head-pad-y: var(--space-1);
686
525
 
687
- /* One rung, not two: a card's frame reads as padding lost long before its cells
526
+ /* One rung only — a card's frame reads as padding lost long before its cells
688
527
  do, so 24 → 16 while the cells inside it go 16 → 8. */
689
528
  --ds-container-pad: var(--space-4);
690
529
  }
@@ -703,8 +542,6 @@
703
542
  }
704
543
  [data-density="cozy"] {
705
544
  --hit-cozy: 40px;
706
-
707
- /* defaults */
708
545
  }
709
546
  [data-density="comfy"] {
710
547
  --hit-cozy: 48px;