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

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 (81) hide show
  1. package/CHANGELOG.md +319 -12
  2. package/components.md +35 -12
  3. package/design-system.md +135 -1
  4. package/docs/agent/INDEX.md +99 -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/body-scroll-lock-service.md +12 -0
  58. package/docs/agent/platform/breadcrumbs-service.md +30 -0
  59. package/docs/agent/platform/ds-config.md +60 -0
  60. package/docs/agent/platform/ds-icon-registry.md +23 -0
  61. package/docs/agent/platform/toast-service.md +17 -0
  62. package/docs/agent/surfaces/ds-accordion.md +8 -0
  63. package/docs/agent/surfaces/ds-card.md +10 -0
  64. package/docs/agent/tables/ds-table.md +15 -0
  65. package/fesm2022/ids-group-ltd-ids-design-system.mjs +924 -763
  66. package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
  67. package/migrations/0.11.3.json +152 -0
  68. package/migrations/0.11.4.json +241 -0
  69. package/migrations/0.8.0.json +6 -5
  70. package/package.json +1 -1
  71. package/styles/_control-label.scss +18 -0
  72. package/styles/_dropdown-overlay.scss +25 -32
  73. package/styles/_ds-color.scss +37 -12
  74. package/styles/_focus.scss +16 -0
  75. package/styles/_skeleton-shimmer.scss +10 -26
  76. package/styles/_tokens-charts.scss +2 -3
  77. package/styles/_tokens.scss +158 -321
  78. package/themes/README.md +32 -1
  79. package/themes/_base-palette.scss +35 -76
  80. package/themes/_semantic.scss +16 -4
  81. package/types/ids-group-ltd-ids-design-system.d.ts +205 -230
package/themes/README.md CHANGED
@@ -69,14 +69,45 @@ On-fill text is the literal `white`, or the theme-stable `--static-ink` where th
69
69
  ### Option B — à la carte (advanced, opt-in global side-effects)
70
70
 
71
71
  ```scss
72
+ @use 'styles/breakpoints' as bp;
72
73
  @use 'themes/base-palette';
73
74
  @use 'styles/theme-activation'; // light at :root + dark at [data-theme='dark']
74
75
  @use 'styles/tokens';
76
+ @use 'styles/tokens-charts';
75
77
  @use 'styles/fonts';
76
78
  @use 'styles/reset';
77
- // …
79
+ @use 'styles/typography';
80
+ @use 'styles/link';
81
+ @use 'styles/focus';
82
+ @use 'styles/ds-color';
83
+ @use 'styles/layout-utils';
84
+ @use 'styles/page-grid';
85
+ @use 'styles/scrollbar';
86
+ @use 'styles/icon-base';
87
+ @use 'styles/dropdown-overlay';
88
+ @use 'styles/toast-overlay';
89
+ @use 'styles/surface-motion';
90
+ @use 'styles/overlay-motion';
91
+ @use 'styles/skeleton-shimmer';
92
+
93
+ @include bp.emit-vars; // REQUIRED, and not implied by the @use above
78
94
  ```
79
95
 
96
+ That is the whole list `styles/ds` forwards — it is written out rather than trailed off, because
97
+ the parts that are easy to leave out are the ones that fail silently:
98
+
99
+ - **`bp.emit-vars` is a separate call.** `@use 'styles/breakpoints'` alone emits nothing; the mixin
100
+ is what writes `--bp-*`. Without it `ds-container` reads `var(--bp-sm|md|lg)` with no fallback, so
101
+ `max-width` is invalid at computed-value time and `size="sm|md|lg"` silently goes full-bleed. The
102
+ default `size="xl"` resolves from `tokens` and looks fine, which is what makes the omission hard
103
+ to spot.
104
+ - **`ds-color`** is what defines the `[ds-color="…"]` zones. Leave it out and the accent never
105
+ recolours — no error, just the primary palette everywhere.
106
+ - **`focus`** carries the focus-ring roles; without it interactive elements lose their ring.
107
+ - **`dropdown-overlay` and `toast-overlay`** style panels that portal to `document.body`, which is
108
+ why they cannot live in a component's own stylesheet. Omitting them renders every dropdown,
109
+ picker panel and toast unstyled.
110
+
80
111
  `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.
81
112
 
82
113
  ### Option C — brand layer on top
@@ -1,22 +1,13 @@
1
- // =========================================================================
2
- // Base palette — Tier 1 theme-independent primitives.
3
- //
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.
8
- //
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.
12
- // =========================================================================
1
+ // Base palette — Tier 1 primitives that are identical in every theme, emitted at
2
+ // :root. What is NOT here, because it is per-theme, lives in each theme's
3
+ // _palette.scss mixin: the --neutral-* family slot (which gray ramp is active)
4
+ // and --shadow-tint-l. Components consume only semantic roles; they never
5
+ // reference this file directly.
13
6
 
14
7
  :root {
15
- // -----------------------------------------------------------------------
16
- // Cool gray ramp (13 stops) — hand-drawn slate-family gray. The hue drifts
17
- // 210 → 227 toward the brand hue (229) as it darkens; chroma follows a
18
- // designed U-curve (S 40% → 12% → 37%). Appearance name, Carbon-style.
19
- // -----------------------------------------------------------------------
8
+ // Hand-drawn slate gray. The hue drifts 210 → 227 toward the brand hue (229)
9
+ // as it darkens and chroma follows a U-curve (S 40% → 12% → 37%); the stops
10
+ // are hex, so a new one has to be placed on those curves by hand.
20
11
  --cool-gray-0: #FFF;
21
12
  --cool-gray-50: #F8FAFC;
22
13
  --cool-gray-100: #F1F4F9;
@@ -31,13 +22,9 @@
31
22
  --cool-gray-900: #161A28;
32
23
  --cool-gray-950: #0B0E18;
33
24
 
34
- // -----------------------------------------------------------------------
35
- // Brand gray ramp (13 stops) — derived, M3-style: the cool-gray S/L curve
36
- // and hue drift are kept, but the hue source is --neutral-h (defaults to
37
- // the brand hue). Re-skinning --primary-h re-tints these grays to match
38
- // the brand automatically. With the default blue brand this ramp matches
39
- // cool-gray to within rounding.
40
- // -----------------------------------------------------------------------
25
+ // The same S/L curve and hue drift as cool-gray, but sourced from --neutral-h,
26
+ // so re-skinning --primary-h re-tints every gray to match the brand. With the
27
+ // default blue brand the two ramps match to within rounding.
41
28
  --neutral-h: var(--primary-h, var(--blue-h));
42
29
  --brand-gray-0: #FFF;
43
30
  --brand-gray-50: hsl(calc(var(--neutral-h) - 19) 40.0% 98.0%);
@@ -53,12 +40,8 @@
53
40
  --brand-gray-900: hsl(calc(var(--neutral-h) - 2) 29.0% 12.2%);
54
41
  --brand-gray-950: hsl(calc(var(--neutral-h) - 3) 37.1% 6.9%);
55
42
 
56
- // -----------------------------------------------------------------------
57
- // Blue — defined as HSL channels so we can compose hsla() halos and tints
58
- // from the same source. #2F54FF ≈ hsl(229, 100%, 59%). This is the ramp the
59
- // default theme maps --primary onto (see themes/_semantic.scss). Naming is
60
- // concrete (the colour) — the semantic --primary mapping lives in the lib.
61
- // -----------------------------------------------------------------------
43
+ // Blue — channel-split so halos and tints compose from the same source.
44
+ // #2F54FF ≈ hsl(229, 100%, 59%). _semantic.scss maps --primary onto this ramp.
62
45
  --blue-h: 229;
63
46
  --blue-s: 100%;
64
47
  --blue-l: 59%;
@@ -74,11 +57,9 @@
74
57
  --blue-800: hsl(var(--blue-h) 79% 40%);
75
58
  --blue-900: hsl(var(--blue-h) 77% 30%);
76
59
 
77
- // -----------------------------------------------------------------------
78
- // Orange — focus / secondary signal
79
- // -----------------------------------------------------------------------
80
- // HSL channels (additive — --secondary composes its fill + tints from these).
81
- // Reproduce --orange-500 ≈ #FF7A2E; ramp stops below stay hand-picked hex.
60
+ // Orange — the secondary / accent family. The channels reproduce --orange-500
61
+ // ≈ #FF7A2E for composing fills and tints; the ramp stops stay hand-picked hex
62
+ // and are NOT derived from them.
82
63
  --orange-h: 22; --orange-s: 100%; --orange-l: 59%;
83
64
  --orange-50: #FFF7F0;
84
65
  --orange-100: #FFEEDF;
@@ -90,11 +71,8 @@
90
71
  --orange-700: #B84812;
91
72
  --orange-800: #8A340A;
92
73
 
93
- // -----------------------------------------------------------------------
94
- // Green — success
95
- // -----------------------------------------------------------------------
96
- // HSL channels (additive — for focus-ring composition + ds-color). The ramp
97
- // stops below stay hand-picked hex; these reproduce --green-500 ≈ #22A33A.
74
+ // Green — success. The channels reproduce --green-500 ≈ #22A33A for focus-ring
75
+ // composition and ds-color; the ramp stops stay hand-picked hex.
98
76
  --green-h: 132; --green-s: 66%; --green-l: 39%;
99
77
  --green-50: #ECFAEE;
100
78
  --green-100: #D6F3DB;
@@ -105,11 +83,8 @@
105
83
  --green-600: #1B8A2E;
106
84
  --green-700: #156822;
107
85
 
108
- // -----------------------------------------------------------------------
109
- // Yellow — attention / warning
110
- // -----------------------------------------------------------------------
111
- // HSL channels (additive — for focus-ring composition + ds-color). Reproduce
112
- // --yellow-400 ≈ #F4D43A; ramp stops below stay hand-picked hex.
86
+ // Yellow — warning. The channels reproduce --yellow-400 ≈ #F4D43A for
87
+ // focus-ring composition and ds-color; the ramp stops stay hand-picked hex.
113
88
  --yellow-h: 47; --yellow-s: 89%; --yellow-l: 59%;
114
89
  --yellow-50: #FFFBEA;
115
90
  --yellow-100: #FEF8DC;
@@ -120,10 +95,8 @@
120
95
  --yellow-600: #B89B00;
121
96
  --yellow-700: #8A7400;
122
97
 
123
- // -----------------------------------------------------------------------
124
- // Red — HSL-channel-split for halo derivation. #D81F1F ≈ hsl(0, 75%, 49%).
125
- // The default theme maps --error onto this ramp (see themes/_semantic.scss).
126
- // -----------------------------------------------------------------------
98
+ // Red — channel-split for halo derivation. #D81F1F ≈ hsl(0, 75%, 49%).
99
+ // _semantic.scss maps --error onto this ramp.
127
100
  --red-h: 0;
128
101
  --red-s: 75%;
129
102
  --red-l: 49%;
@@ -137,11 +110,9 @@
137
110
  --red-600: hsl(var(--red-h) 78% 41%);
138
111
  --red-700: hsl(var(--red-h) 78% 31%);
139
112
 
140
- // -----------------------------------------------------------------------
141
- // Sky — info role ramp. A brighter, cooler blue (#3B82F6) kept distinct
142
- // from the primary --blue ramp (#2F54FF) so "informational" reads apart
143
- // from "primary action".
144
- // -----------------------------------------------------------------------
113
+ // Sky — the info role. A brighter, cooler blue (#3B82F6) kept distinct from the
114
+ // primary --blue ramp (#2F54FF) so "informational" reads apart from "primary
115
+ // action".
145
116
  --sky-50: #EFF6FF;
146
117
  --sky-100: #DBEAFE;
147
118
  --sky-200: #BFDBFE;
@@ -151,35 +122,23 @@
151
122
  --sky-600: #2563EB;
152
123
  --sky-700: #1D4ED8;
153
124
 
154
- // -----------------------------------------------------------------------
155
- // Violet — tertiary brand hue. Channel-split only (--tertiary composes its
156
- // fill + tints from these); no discrete ramp stops yet — add hand-picked hex
157
- // if a component ever needs stepped violet swatches.
158
- // -----------------------------------------------------------------------
125
+ // Violet — the tertiary brand hue, channel-split only. No discrete ramp stops
126
+ // yet; add hand-picked hex if a component ever needs stepped violet swatches.
159
127
  --violet-h: 262; --violet-s: 70%; --violet-l: 56%;
160
128
 
161
- // -----------------------------------------------------------------------
162
- // Shadow tint — channel-split substrate h/s only. The lightness (-l) is
163
- // per-theme: light uses 7%, dark uses 95% (so the same alphas read as soft
164
- // glows over dark surfaces). Each theme's _palette.scss mixin sets -l.
165
- // -----------------------------------------------------------------------
129
+ // Shadow substrate, h/s only — the lightness is per-theme and each theme's
130
+ // _palette.scss mixin sets it (light 7%, dark 95%).
166
131
  --shadow-tint-h: 225;
167
132
  --shadow-tint-s: 39%;
168
133
 
169
- // -----------------------------------------------------------------------
170
- // Theme-stable ink anchor — never flips with the theme. On-DARK-fill text
171
- // (e.g. text on the yellow warning fill) points here so it stays dark in
172
- // both themes. On-LIGHT-fill text uses the literal `white` keyword directly
173
- // (a token would be pure indirection — var(--x) === white for a constant).
174
- // -----------------------------------------------------------------------
134
+ // Never flips with the theme. Text on a DARK fill (e.g. the yellow warning
135
+ // fill) points here so it stays dark in both themes. There is no counterpart
136
+ // for text on a LIGHT fill: that uses the `white` keyword directly, since a
137
+ // token for a constant would be pure indirection.
175
138
  --static-ink: #161A28;
176
139
 
177
- // -----------------------------------------------------------------------
178
- // Font families — a theme/brand choice (the size/weight/leading SCALE is
179
- // theme-independent and lives in styles/_tokens.scss). Display + heading
180
- // default to body sans; a brand can mix a serif/display family here without
181
- // touching component code.
182
- // -----------------------------------------------------------------------
140
+ // Font families are a theme/brand choice; the size/weight/leading SCALE is
141
+ // theme-independent and lives in ../styles/_tokens.scss.
183
142
  --font-sans: "Mulish", -apple-system, blinkmacsystemfont, "Segoe UI", roboto, sans-serif;
184
143
  --font-mono: "JetBrains Mono", ui-monospace, sfmono-regular, menlo, monospace;
185
144
  --font-display: var(--font-sans);
@@ -1,4 +1,3 @@
1
- // =========================================================================
2
1
  // Shared role structure — Tier 2 semantic role ASSIGNMENTS.
3
2
  //
4
3
  // Exposes @mixin roles: the role map whose structure is identical across
@@ -10,7 +9,6 @@
10
9
  // This mixin is an authoring-DRY device. At runtime, exactly one theme block
11
10
  // matches (`:not([data-theme='dark'])` vs `[data-theme='dark']`), and that
12
11
  // block declares the complete token set itself (palette + roles + overrides).
13
- // =========================================================================
14
12
 
15
13
  @mixin roles {
16
14
  /* Surfaces — six-stop scale.
@@ -185,8 +183,11 @@
185
183
  --error-border: var(--red-200);
186
184
  --error-text: var(--red-600);
187
185
 
188
- /* -pressed (success/warning) + -on aliases — added for the --accent-* pointer
189
- family so every ds-color family resolves --accent-pressed / --accent-on. */
186
+ /* -pressed (success/warning) and -on — roles the --accent-* pointer family needs from
187
+ every ds-color family and the status block above does not spell out. There is
188
+ deliberately no --<status>-strong: the readable on-tint colour of a status family is
189
+ what -text already is, and --accent-strong asks for -text by name. The brand families
190
+ are the ones that carry it as -strong, because they have no -text. */
190
191
  --success-pressed: color-mix(in srgb, var(--success) 76%, black);
191
192
  --warning-pressed: color-mix(in srgb, var(--warning) 76%, black);
192
193
  --error-on: var(--text-on-error);
@@ -216,6 +217,17 @@
216
217
  --focus-ring-outer-l: var(--primary-l);
217
218
  --focus-ring-outer-alpha: 1;
218
219
 
220
+ /* A flat focus colour, for components that draw an `outline` instead of a shadow (a row
221
+ inside a clipping list, a swatch grid). It must stay DEFINED: an `outline-color` that
222
+ falls through resolves to `currentColor`, so a row rings itself in its own text colour.
223
+
224
+ `--accent`, not the ring's own primary channels: outside a zone it IS `--primary`, and
225
+ inside `[ds-color="error"]` it becomes that family, which is the same adaptivity the
226
+ zone already gives the shadow ring through `--accent-focus-ring`. Composing it from
227
+ `--focus-ring-outer-*` would have pinned the outline to the brand hue in a zone whose
228
+ every other accent had moved. */
229
+ --focus-ring-color: var(--accent);
230
+
219
231
  --focus-ring:
220
232
  0 0 0 2px var(--focus-ring-inner),
221
233
  0 0 0 4px hsl(var(--focus-ring-outer-h) var(--focus-ring-outer-s) var(--focus-ring-outer-l) / var(--focus-ring-outer-alpha));