@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/CHANGELOG.md CHANGED
@@ -8,6 +8,315 @@ While the package is on `0.x`, minor releases may contain breaking changes.
8
8
 
9
9
  ## Unreleased
10
10
 
11
+ ## 0.11.4 — 2026-09-03
12
+
13
+ ### Breaking
14
+
15
+ - **`ds-banner` and `ds-alert` no longer announce themselves unless asked.** Both applied `role` and
16
+ `aria-live` unconditionally, and an `alert` region fires on INSERTION — so a static "maintenance on
17
+ Sunday" strip interrupted a screen reader on every client-side route into the page. MDN says it
18
+ outright: do not use `alert` on content the user has not interacted with. Measured on this site's own
19
+ pages: 12 assertive regions before, 0 now. Pass `[announce]="true"` for a banner the app raises in
20
+ response to an event; for anything transient use `ToastService`, which owns a region built for it.
21
+
22
+ - **`<ds-toast>`'s `message` input is now `body`**, matching `ToastOptions.body` and `ToastEntry.body`.
23
+ One concept had three spellings across the family; `body` wins because it is the one every consumer
24
+ already passes to the service.
25
+
26
+ - **Five toast border tokens gain the `-color` the rest of the library uses**:
27
+ `--ds-toast-border` → `--ds-toast-border-color`, and the four variant suffixes with it. They are
28
+ colours, and they were the last holdouts of the old naming.
29
+
30
+ - **`maxVisible` defaults to 5 instead of unlimited.** An uncapped stack was more permissive than any
31
+ system this component is measured against — Material shows one snackbar and dismisses the previous,
32
+ Carbon and Halstack stack but expect a ceiling. `provideDsConfig({ toast: { maxVisible: n } })` still sets it, and `0` still means
33
+ no cap; a configured `0` is now forwarded rather than skipped, since it is the only way left to ask
34
+ for one.
35
+
36
+ - **A screen reader was told nothing about a toast, for three of the five variants.** `aria-live` sat
37
+ on each toast, and a live region has to exist in the DOM *before* its text arrives — a node created
38
+ with its message already inside it is the one case NVDA and JAWS reliably do not announce. The
39
+ region host was `role="region"`, a landmark, not a live region. Announcements now go through the CDK
40
+ `LiveAnnouncer`, whose region is built once at service construction and only has its text replaced.
41
+ `error` and `warning` announce assertively, the rest politely. WCAG 2.2 SC 4.1.3.
42
+
43
+ A burst is coalesced into one announcement rather than queued, and that is forced rather than
44
+ chosen: `announce()` clears its region synchronously and writes on a 120ms timeout, resolving its
45
+ promise inside that callback — so even a strictly serialised chain loses all but the last message.
46
+ Measured: five announcements each landed and were cleared again in the same millisecond.
47
+
48
+ A `<ds-toast>` you place yourself is now silent to a reader. It is a specimen, not an event; use
49
+ `ToastService` for anything that should be announced.
50
+
51
+ - **Toast defaults move into `provideDsConfig`, and the two toast tokens are gone.**
52
+ `DS_TOAST_CONFIG` and `DS_TOAST_POSITION` were the only configuration in the library that did not
53
+ go through `DsConfig` — thirteen other areas already did — so an app set everything in one call and
54
+ then remembered two bare `InjectionToken` providers for toasts. They are now
55
+ `provideDsConfig({ toast: { maxVisible, position } })`, and the `DsToastConfig` interface is
56
+ removed with its token.
57
+ `position` is PARTIAL and merged field by field over `right` / `top` / `var(--space-6)`: the old
58
+ token's type required all three fields, so moving the stack to the bottom meant restating the other
59
+ two. `DS_TOAST_POSITION_DEFAULT` is unchanged and still exported. One caveat, and it is not new:
60
+ `ToastService` is `providedIn: 'root'`, so the `toast` section resolves only at the root injector —
61
+ a route-level `provideDsConfig` cannot narrow it, unlike every other section.
62
+
63
+ ### Changed
64
+
65
+ - **Toast and table class internals moved again — only matters if you SUBCLASS one of them.**
66
+ Every name here is a `private` or `protected` internal, not public API and not a signal, but
67
+ `private` collides with TS2415 exactly as a public name does, so a member of yours sharing one
68
+ still stops the build. `ToastComponent` **lost `role`** — the component no longer sets one, so
69
+ an `override role` overrides nothing. `ToastRegionComponent` gained `leaveTimers`,
70
+ `slideNeighbours`, `toastNodes`, `measureTops` and `leaveDuration`, and **renamed
71
+ `promoteFromQueue` to `drainQueue`**; an override of the old name now runs never, so move it.
72
+ `ToastService` gained `announcer`, `pendingAnnouncements`, `pendingAssertive`, `announceTimer`,
73
+ `scrimWatcher`, `announce` and `keepAboveScrims`, and **lost `position`** with the token it
74
+ read. `TableComponent` gained `eventsAtExport`,
75
+ `eventMessages`, `tableHead`, `hostElement` and `announceExport`; its inputs, outputs, models
76
+ and exported types are unchanged. `BannerComponent` and `AlertComponent` each gained
77
+ `announce`, and their `ariaRole` and `ariaLive` now return `null` as well — a subclass that
78
+ narrowed either type back, or code that assumed the getter is never null, stops compiling.
79
+ The compiler enumerates every collision, so building after the upgrade is the whole check.
80
+
81
+ - **The stack no longer jumps when a toast is added.** Its neighbours are put back where they were
82
+ with a `transform` and released, so the re-stack runs on the compositor instead of the browser
83
+ moving them all in one frame. Two new tokens tune it: `--ds-toast-shift-duration` (default
84
+ `--duration-fast`) and `--ds-toast-shift-easing`. A dismissal keeps its own, longer timing — a
85
+ re-stack and a leave are different motions.
86
+
87
+ ### Fixed
88
+
89
+ - **A click between a boolean control and its label hit nothing.** `ds-radio`, `ds-checkbox` and
90
+ `ds-switch` set the space between control and label with a flex `gap`, which belongs to neither
91
+ box — so the 8px strip between them swallowed the click instead of toggling. That space is now
92
+ padding on the label, which extends its clickable box across the strip: the target grows from
93
+ 18px to 26px tall while the text's start position and the row height stay put. No API or token
94
+ change.
95
+
96
+ - **`ds-table`'s bulk-actions bar rendered its buttons invisible.** The bar is an inverted
97
+ surface, and its buttons were coloured through a bare `.button` rule that stopped applying once
98
+ the button became `ds-button` — which takes its label from `--ds-button-label-color` and ignores
99
+ inherited `color`, so the label sat on the bar's own colour and disappeared. The bar now sets
100
+ ds-button's public tokens for an inverted surface: label to `--text-inverted`, background to
101
+ `transparent`, and hover and active backgrounds to `--surface-inverted-hover`. No new token —
102
+ these are ds-button's existing hooks.
103
+
104
+ - **The skeleton shimmer stepped instead of sweeping, on any page but a light one.** The travel was
105
+ `--skeleton-shimmer-x`, one animated, registered, INHERITED custom property on `:root` that
106
+ every skeleton read through `mask-position`. A registered custom property is a computed value, so changing it invalidated
107
+ style for the ENTIRE document on every frame and then repainted — fine on the docs site, visibly
108
+ jerky inside a heavy host application. The animation moved onto each skeleton's own band,
109
+ animating `mask-position` per element; `--skeleton-shimmer-x` and the `:root` animation that drove
110
+ it are gone, so anything that referenced it now resolves to nothing. The trade is that a skeleton mounted mid-cycle starts its own pass instead
111
+ of joining the one in flight; the old lock-step was never viewport-anchored anyway, because
112
+ `mask-position` is measured from the host's own box.
113
+ - **A focused row drew TWO rings, and neither was the focus colour.** `ds-list-item`, `ds-tree`,
114
+ `ds-tag`, `ds-description-list` and `ds-color-picker` each drew their own `outline` on
115
+ `:focus-visible` while the blanket `:where(:focus-visible)` shadow kept painting under it — an
116
+ accent halo outside, their own outline inside. Worse, that outline asked for
117
+ `--focus-ring-color`, which **nothing defined**, so all seven call sites fell through to
118
+ `currentColor` and ringed themselves in their own text colour: near-black on a list row, grey on
119
+ a tree node. The token is defined now, from the same hue channels as the ring's outer halo, and
120
+ the seven sites share a `focus.outline-indicator` mixin that silences the shadow. The colour is
121
+ `--accent`, so it is the brand hue by default and the family's hue inside a `ds-color` zone —
122
+ measured: `hsl(229 100% 59%)` outside, `hsl(0 75% 49%)` under `[ds-color="error"]`. Override it
123
+ per brand with `--focus-ring-color`.
124
+ - **A selected `ds-list-item` or `ds-tree` node retinted its label and left its icon behind.**
125
+ On the list the icon stayed on its resting colour beside an accent label; on the tree the row
126
+ set `color` correctly but `.node-icon` declared its own and won. Both follow the label now,
127
+ through new
128
+ `--ds-list-item-selected-icon-color` / `--ds-tree-row-selected-icon-color` hooks that default to
129
+ the selected label colour.
130
+ - **`ds-avatar-group` and `ds-button-group` styled their children by tag name, so a host that
131
+ renames the tag got neither.** Both pierced encapsulation with `::ng-deep ds-avatar` /
132
+ `::ng-deep ds-button`. Measured through the custom-element build, where a tag nested inside
133
+ another component's template has to be renamed (angular/angular#24536), all three
134
+ avatars came back `margin-left: 0` with no ring, and the joined buttons lost their overlap
135
+ margin and every flattened radius. They match the direct child now, so the grouping holds whatever the child is rendered
136
+ as. Computed output in an ordinary Angular app is unchanged — verified identical before and
137
+ after.
138
+
139
+ - **Six connected-panel tokens did nothing when scoped to one picker.** `--ds-option-padding`,
140
+ `-gap`, `-radius`, `-row-gap`, `--ds-option-bg-color-active` and `--ds-dropdown-panel-maxh` are read
141
+ on the panel, which the CDK portals outside the component, so they only ever resolved from a global
142
+ declaration: `ds-select { --ds-option-padding: … }` was silently ignored while
143
+ `ds-select { --ds-dropdown-panel-radius: … }` beside it worked, because that one was on the
144
+ forwarded list and these were not. They join the shared list every connected picker forwards, so the
145
+ family behaves one way. `--ds-dropdown-panel-maxh` was also the one token `ds-autocomplete` forwarded
146
+ and its two siblings did not. Nothing moves unless you had written one of these on an element, where
147
+ it now takes effect — if you reached for a global declaration because the scoped one did nothing, the
148
+ scoped one is the narrower fix.
149
+
150
+ - **`ds-split-button`'s hover left its label unreadable inside a status zone.** The hover background defaulted to the family's readable ON-TINT colour — the one meant for text on light surfaces — and this was the only place in the library using it as a background, so the label landed at 1.87:1 on `success` in dark and 2.46:1 on `error`. It now defaults to `--accent-hover`, the family base mixed toward black in light and white in dark, so the hover follows the rest state instead of jumping to another hue: error 5.94 light / 4.22 dark, success 4.17 / 2.85, warning 9.11 / 12.31. `--ds-split-button-bg-hover-color` still overrides it.
151
+
152
+ This does not close the whole problem. The label colour on a family's solid background already falls below 4.5:1 at REST for `success` (3.30) and `secondary` (3.31), in both themes and on every solid button — a palette question, not this component's.
153
+
154
+ - **A chip row could drop a chip, or fail to, when the field sat in a box that sizes itself to its content.** The budget for how many chips fit comes off the trigger's parent, which is only a fixed quantity while that parent takes its width from somewhere else. A parent at `fit-content`, an `inline-block` one, or a flex item that cannot grow all take their width from the chips instead, so the cut was reading back its own result. The parent is now asked whether its width depends on the trigger, and the trigger's own width is used only when it cannot answer. Affects `ds-multi-select` and `ds-autocomplete`.
155
+
156
+ - **Eight defects the two-wave review confirmed and nobody had acted on.** The toast region and its
157
+ service never tore anything down, so every pending timer fired into a destroyed component — harmless
158
+ in a long-lived app, a stream of "N timers still in the queue" in a consumer's `fakeAsync` tests. The
159
+ 180 ms leave timer was untracked and survived `dismissAll()`. `remove()` had no existence guard, so a
160
+ stale `ToastRef.dismiss()` ran the whole leave path on an id nothing held. `LEAVE_DURATION_MS` was
161
+ hardcoded against `--ds-toast-leave-duration`, a public token: the leave length is now READ off the
162
+ node, measured at 964 ms with the token set to 900, where it used to be 180 whatever the consumer
163
+ asked for. Raising `maxVisible` at runtime promoted nothing until the next dismissal; promotion is a
164
+ drain loop now. A negative `maxVisible` said the opposite of what it did and warns in dev. The
165
+ spinner inside a `loading` toast carried its own `role="status"`, which — now that announcements have
166
+ moved to the announcer — was the only live node left in there, so it is `aria-hidden`. And
167
+ `ToastPromiseMessages` is generic, so `promise<T>` stops discarding `T` and a `success` callback
168
+ receives the resolved value instead of `unknown`.
169
+
170
+
171
+ - **A modal, drawer, confirm or bottom sheet opened after a toast covered it and swallowed its action
172
+ button.** `--layer-toast: 1500` could not prevent it and never could: CDK 21 gives every overlay host
173
+ `popover="manual"` and calls `showPopover()`, so hosts live in the browser's top layer, which paints
174
+ strictly in the order things were shown and ignores z-index and stacking contexts. The toast host is
175
+ now re-shown when a scrimmed overlay appears, which is the only thing that moves it back to the
176
+ front. Measured before and after on the same probe: the scrim was the topmost element at the toast's
177
+ centre, and is not any more.
178
+
179
+ Only *scrimmed* overlays trigger it. A tooltip or dropdown neither covers the toast meaningfully nor
180
+ eats a click, and the documented scale deliberately puts `--layer-tooltip` above the toast.
181
+
182
+
183
+ - **Typing on a CLOSED `ds-select` did nothing.** Type-ahead landed with the jump wired only for
184
+ an open panel: the closed branch of the key handler returned before reaching it, so a letter
185
+ pressed on a collapsed trigger neither jumped nor committed. It now commits the first
186
+ matching option without opening the panel — `value` is a `model`, so `valueChange` fires —
187
+ the way a native `<select>` does; a key that matches nothing is ignored.
188
+ - **A `ds-table` loading scrim covered the top of the first row, or overlapped the header.**
189
+ Its top edge assumed a 40px header. The header is 42.89px at the default density and
190
+ 26.89px under `[data-density="ultra-compact"]`, so it cut 2.89px into the header normally
191
+ and started 13.11px too low under that density, where the first row showed through it. The
192
+ header is measured now, so the edge lands on it at every density and at any header font size
193
+ you set. `--ds-table-head-h` still overrides it if you set that, which you should no longer
194
+ need to.
195
+ - **One export left `ds-table`'s live region stuck for the rest of the page's life.** The export
196
+ status outranked the sort, row-range and row-expansion lines and was never cleared, so from the
197
+ first export onwards a screen reader heard "Export ready" and nothing else: every later sort,
198
+ page change and bulk expansion was swallowed. The export line now holds the region only until
199
+ one of those lines has something new to say, so "Export failed" still stands until the reader
200
+ moves on, and everything after it is announced again.
201
+
202
+ ## 0.11.3 — 2026-09-02
203
+
204
+ ### Breaking
205
+
206
+ - **`ds.color()` now refuses a family it does not know, and that stops your Sass build.**
207
+ `@include ds.color(brand)` used to compile and emit eleven `--accent-*` pointers at values that
208
+ could never resolve, so a zone painted itself with `unset` and the mistake looked like a theming
209
+ problem. It `@error`s now, naming the five families it takes: `secondary`, `tertiary`, `error`,
210
+ `success`, `warning`. Anything else fails the build at the `@include`. The `ds-color="…"`
211
+ attribute is untouched — no Sass runs for it.
212
+
213
+ ### Changed
214
+
215
+ - **The banner and toast icon now centres on the message block**, where most shapes aligned it to
216
+ the first line of text. The two rules agree on a one-line message — which is most toasts — and
217
+ diverge as the text grows: the icon sat some 12px above the block centre at two lines and 21px at
218
+ three. A `compact` banner was already centred and does not move.
219
+
220
+ It is `align-self` on the icon rather than `align-items` on the row, so the close button and the
221
+ action buttons keep the positions they had. `--banner-ic-mt` is **removed**; it existed only to
222
+ nudge the icon down by one border-width under the old rule.
223
+
224
+ `ds-alert` follows, for the same reason: it carried the same nudge inlined as
225
+ `var(--border-width-default)` rather than through the token.
226
+
227
+ **Known limit.** The icon centres on the flex LINE, which equals the message block only while the
228
+ message is the tallest thing in the row. A one-line toast with a close button is 0.53px off, and with
229
+ a projected `[actions]` button 6–14px off depending on its size. `align-items: center` would be
230
+ unconditional but moves the close button, which is the trade above.
231
+
232
+ - **`ToastRegionComponent`'s member surface moved again — only matters if you SUBCLASS it.** The
233
+ timer and pause work gained `arm`, `focusWithin`, `host`, `hovered`, `onFocusWithin`, `onHover`,
234
+ `paused`, `pauseAll`, `remaining`, `resumeAll`, `startedAt` and `syncPause`, and **lost
235
+ `startCountdown`**: a countdown is armed when a toast becomes visible and re-armed from what is
236
+ left when a pause ends, where before the region started one timer per toast. Every one is a
237
+ `private` or `protected` internal — none is public API, none is a signal, and there is no
238
+ replacement to call for `startCountdown`, so an override of it should simply go. A member of
239
+ yours sharing one of those names still stops the build, because `private` collides with TS2415
240
+ exactly as a public name does. `host` is the one most likely to clash.
241
+ Rename yours — `override` is not a way out for ten of the twelve, because a member whose base
242
+ declaration is `private` rejects it with the same TS2415 as a plain redeclaration, and that
243
+ includes `host`. Only the two `protected` ones, `onHover` and `onFocusWithin`, accept it. The
244
+ compiler enumerates every
245
+ collision, so building after the upgrade is the whole check.
246
+
247
+ Worth flagging for anyone who followed 0.11.2's note: `startCountdown` was announced there as a
248
+ member the region had just gained, so an `override startCountdown` added one release ago now
249
+ overrides nothing and silently never runs. There is no public replacement to call — the countdown
250
+ is the region's own business now. Delete the override.
251
+
252
+ - **`components.md` documented a component that does not exist and four events that never fired.**
253
+ It carried a `<ds-dropdown>` entry through nine releases; that component was absorbed into
254
+ `<ds-select>` and an import written from the document fails to compile. Four documented event
255
+ names were never identifiers here: `ds-banner` and `ds-toast` emit `(closed)`, not `(dismissed)`;
256
+ `ds-pagination` emits `(currentPageChange)`, not `(pageChange)`; `ds-table` emits `(rowClicked)`,
257
+ not `(rowClick)`. An unknown event binding registers a DOM listener and never fires, so those
258
+ four handlers were silently dead with nothing in the console. `<ds-alert>` was missing from the
259
+ document entirely and is now in it, `'neutral'` variant included.
260
+
261
+ ### Fixed
262
+
263
+ - **`ds-color="error"`, `="success"` and `="warning"` lost their accent colour.** Those zones map
264
+ `--accent-strong` onto `--<family>-strong`, and the three status families never defined it — only
265
+ the brand families did. The declaration was invalid at computed-value time, so inside a status
266
+ zone every place that reads `--accent-strong` reset to `unset`: selected list and tree rows,
267
+ the active sidenav item and its rail, the active tab pill, avatar and avatar-group initials, the
268
+ active tag, dropzone text, the date-picker range label, the toast's action label, the selected
269
+ toggle button, the split-button hover fill, the `tonal`, `ghost`, `outline` and `text` variants
270
+ of `ds-button`, and the `tonal` variant of `ds-icon-button`. Text there fell through to the
271
+ inherited body colour; the fill
272
+ and the rail, which inherit nothing, disappeared.
273
+
274
+ No new token was needed: a status family already carries its readable on-tint colour as `-text`,
275
+ so `--accent-strong` now asks for `-strong` first and `-text` second, and the brand families keep
276
+ answering it as `-strong` because they have no `-text`. Each pointer also ends in a fallback — to
277
+ the family's base for `-hover`, `-pressed` and `-strong`, to its `-muted` for the tint pointers,
278
+ and to the theme-wide role for `-on` and the two focus pointers — so a role that goes missing in
279
+ future degrades instead of disappearing.
280
+
281
+ - **`ToastService.promise()` could destroy its own result.** It ran the settled toast's
282
+ auto-dismiss on a wall-clock timer started when the promise resolved, not when the toast became
283
+ visible — the one thing the rest of the timer work had already moved into the region. With a
284
+ `maxVisible` cap set, a promise that settled while its toast was still queued had the result spliced
285
+ out of the queue before anyone saw it: the user saved, it succeeded, and no toast appeared at all.
286
+ The settled duration is now handed to the region with the content, so it starts on promotion.
287
+
288
+ - **A toast carrying an `action` no longer auto-dismisses.** The overlay is the last child of `body`,
289
+ so the region is dead last in tab order; a keyboard user cannot cross a real page in the five
290
+ seconds the button was alive. An `action` toast now waits, and is always dismissible. Note that
291
+ a `durationMs` you pass alongside an `action` is discarded — the toast waits regardless — and
292
+ `dismissible: false` is discarded on any toast that cannot expire, not only on a `loading` one.
293
+
294
+ - **Hovering or focusing the region pauses every countdown**, resuming when the pointer or focus
295
+ leaves. A toast being read is not a toast that has been read. The pause is derived from both
296
+ sources rather than latched, so tabbing out of a region the pointer is still over does not
297
+ resume, moving focus between the action and the close button is not a leave, and a toast that
298
+ becomes visible under a stationary pointer — a burst past the cap, or a promise settling — is
299
+ banked rather than counted. A toast paused with almost nothing left resumes with at least 600ms, so
300
+ one hovered with
301
+ almost nothing left does not vanish as the pointer leaves.
302
+
303
+ - **A disabled accordion item's chevron did not look disabled.** It asked for a colour token this
304
+ library does not define, so the declaration was invalid at computed-value time and the chevron
305
+ inherited whatever colour surrounded it — while the label beside it greyed correctly. It reads the
306
+ disabled text colour now, like the label.
307
+
308
+ - **The `ds-banner` close button had no accessible name.** It announced as a bare "button", where
309
+ the same control on `ds-toast` and `ds-alert` already said "Dismiss". It says it now.
310
+
311
+ - **A long unbroken word in a toast overflowed the pill.** A URL or an id with no break
312
+ opportunity ran past the rounded edge instead of wrapping inside it.
313
+
314
+ - **Nothing that cannot expire can also be unclosable.** The rule is now that any toast with no
315
+ duration is dismissible, whatever you asked for — a `loading` variant, one carrying an `action`,
316
+ or an explicit `durationMs: 0`. A `loading` toast was created with `dismissible: false` and no
317
+ duration, so a promise that never settled held its slot for the life of the page — with a cap of 3, three hung requests blocked the whole channel, including the error
318
+ toasts that would have explained the hang.
319
+
11
320
  ## 0.11.2 — 2026-09-01
12
321
 
13
322
  ### Added
@@ -168,14 +477,13 @@ While the package is on `0.x`, minor releases may contain breaking changes.
168
477
 
169
478
  ### Fixed
170
479
  - **Dev-mode warnings no longer ship to production bundles.** They were guarded by
171
- `isDevMode()`, which is a function CALL — a bundler cannot prove the branch dead, so all fourteen
480
+ `isDevMode()`, which is a function CALL — a bundler cannot prove the branch dead, so all thirteen
172
481
  warning sites and their message closures reached production builds. Each site is now guarded inline
173
482
  with `typeof ngDevMode === 'undefined' || ngDevMode`, which `@angular/build` folds away whenever
174
483
  script optimization is on, closures included. **Measured: 1 590 B gzip off an app using most of the
175
484
  library, 827 B of it off a single `<ds-button>`.** Nothing changes for you — no API, no behaviour,
176
485
  and the warnings still fire in development builds exactly as before.
177
486
 
178
-
179
487
  - **A loading scrim stopped the pointer and let the keyboard walk straight under it.**
180
488
  `ds-loading-overlay` paints an absolutely positioned scrim over its content, which intercepts
181
489
  every pointer event — so a control behind it could not be clicked, and looked unavailable. Nothing
@@ -2738,6 +3046,15 @@ genuine gap worth reporting.
2738
3046
  - **Fields no longer expose a `protected messageState`;** the resolved `message` (text + state) and
2739
3047
  `invalidResolved` replace it. Only reachable by subclassing a field component, which is not a
2740
3048
  supported extension point, but noted for parity with the class-member changes in 0.7.0.
3049
+ - **The `ds-time-picker` panel lost its corner radius.** It had drawn `--radius-md` (8px) while every
3050
+ other floating surface — popovers, cards, modals and `ds-date-picker`'s own calendar — resolves the panel
3051
+ role. The move onto that role reads a private `:host` token, which a CDK-portaled panel cannot see, so
3052
+ `border-radius` resolves to its initial `0` and the panel renders SQUARE. The new
3053
+ `--ds-time-picker-panel-radius` hook is inert for the same reason. Force the corner back with a global
3054
+ `.cdk-overlay-container { --_time-picker-panel-radius: var(--radius-md); }`. It declares the
3055
+ private token the panel already reads on an ancestor the panel DOES have, so it inherits down;
3056
+ fighting the component’s own rule with a selector is not needed. A rule scoped under
3057
+ `ds-time-picker` cannot reach the portaled panel at all. The trigger's radius is untouched.
2741
3058
 
2742
3059
  ### Fixed
2743
3060
 
@@ -2773,16 +3090,6 @@ genuine gap worth reporting.
2773
3090
  layout's open rail instead of beneath it. The host now sets `isolation: isolate`, giving each
2774
3091
  `ds-app-layout` its own stacking context — the same fix `ds-drawer` already carries. Nothing changes
2775
3092
  for a full-viewport shell with no layout embedded inside it.
2776
- - **The `ds-time-picker` panel drew the CONTROL radius, so it did not match the date picker beside it.**
2777
- Its dropdown was the one floating panel left on `--radius-md` (8px) while every other surface — menus,
2778
- popovers, cards, modals, and `ds-date-picker`'s own calendar — resolves the panel role. Two pickers in
2779
- one form therefore rendered different corners. The panel now reads
2780
- `var(--ds-time-picker-panel-radius, var(--ds-radius-panel))`, which is 12px, and the new hook is
2781
- FORWARDED onto the portaled pane — a token declared without being forwarded is dead for per-instance
2782
- overrides, which is exactly the `--ds-overlay-enter-scale` bug fixed elsewhere in this release. It was
2783
- also the only property on that element without a hook, since fill, border and shadow all had one.
2784
- Restore the old corner with `ds-time-picker { --ds-time-picker-panel-radius: var(--radius-md); }`; the
2785
- trigger's radius is untouched.
2786
3093
  - **A path change that only mirrors the reader's position no longer resets the content scroll.** A docs shell whose scroll spy rewrites `/area/section` as the user scrolls hit a loop: the rewrite looked like a page change, the layout scrolled to top, the spy saw the first section again and rewrote the path back. Such a navigation must now carry `state: { dsSamePage: true }`, which the layout skips for both the scroll reset and the rail close. Read from `Router.lastSuccessfulNavigation()` — `getCurrentNavigation()` is already cleared when `NavigationEnd` reaches a subscriber.
2787
3094
  - **Closing the rail by NAVIGATING no longer pulls focus back to the burger.** Restoring focus to the trigger is right for a dismissal — Escape, the scrim — and wrong for a link: the reader activated it, so focus belongs wherever the router put it, and handing it back announced "Open navigation" instead of the page they asked for. Dismissal keeps the restore; the navigation and breakpoint paths now clear `railOpen` directly. The breakpoint path had also depended on `compact` being written one line earlier to avoid focusing a trigger that is hidden on desktop — that ordering trap is gone with it.
2788
3095
  - **A closed compact `ds-app-layout` rail no longer holds focus behind the screen.** Below the
package/components.md CHANGED
@@ -2,6 +2,12 @@
2
2
 
3
3
  > Index of the design system components, global helpers, tokens and icons. Use it as a single reference when migrating UI to DS.
4
4
  >
5
+ > **If you are an agent, read `docs/agent/INDEX.md` instead of this file.** The same content
6
+ > is generated there as an index plus one leaf per entry, so answering a question about one
7
+ > component costs ~1.6 KB and the index, not the 58 KB of this catalogue. This file stays the
8
+ > single place a human edits — the leaves are derived from it and a CI gate fails when they
9
+ > drift.
10
+ >
5
11
  > **This file is the WHAT — the inventory.** For the HOW (which spacing between what,
6
12
  > which type role where, how a page is composed) see `design-system.md`, which carries
7
13
  > the rules this catalogue deliberately does not.
@@ -293,14 +299,21 @@ Content slot: `[actions]` — CTA buttons / links.
293
299
 
294
300
  #### `<ds-banner>` — `BannerComponent`
295
301
  Inputs: `variant: 'info' | 'success' | 'warning' | 'severe' | 'error' | 'neutral' = 'info'`, `title: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null` (variant-derived default), `compact: boolean = false`, `layout: 'stacked' | 'row' = 'stacked'`, `accentRail: boolean = true`
296
- Output: `(dismissed): void`
302
+ Output: `(closed): void`
297
303
  Content slots: default (body text), `[actions]` (trailing CTAs)
298
304
  - `layout="stacked"` (default): actions wrap onto a new line, indented under the body. Use for multi-line messages or multiple CTAs.
299
305
  - `layout="row"`: actions sit at the right edge, vertically centred with the body. Use for one-line messages with a single trailing CTA.
300
306
 
307
+ #### `<ds-alert>` — `AlertComponent`
308
+ Inline message, `ds-banner`'s smaller twin — same anatomy, sized for placement inside a form or a card rather than across a page.
309
+ Inputs: `variant: 'info' | 'success' | 'warning' | 'error' | 'neutral' = 'info'`, `title: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null` (variant-derived default)
310
+ Output: `(closed): void`
311
+ Content slots: default (body text), `[actions]` (trailing CTAs)
312
+
301
313
  #### `<ds-toast>` — `ToastComponent`
302
- Inputs: `variant: 'info' | 'success' | 'warning' | 'error' = 'info'`, `title: string = ''`, `message: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null` (variant-derived default)
303
- Output: `(dismissed): void`
314
+ Inputs: `variant: 'info' | 'success' | 'warning' | 'error' | 'loading' = 'info'`, `title: string = ''`, `message: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null` (variant-derived default), `action: ToastAction | null = null` (`{ label, handler }` — renders a trailing button)
315
+ Output: `(closed): void`
316
+ Content slots: default (body text, an alternative to `message`), `[actions]` (trailing CTAs). Neither is reachable through `ToastService`, which renders from `ToastOptions` — they are for a `<ds-toast>` you place yourself.
304
317
 
305
318
  The companion `<ds-toast-region>` lives inside the `ToastService` (see Services) — it is auto-mounted via a CDK overlay on first `toast.show()`, so consumers do **not** need to place `<ds-toast-region>` anywhere in their markup. Render `<ds-toast>` directly only for static specimens.
306
319
 
@@ -367,7 +380,7 @@ Inputs: `steps: readonly string[] = []`, `current: number = 0`. Horizontal step
367
380
 
368
381
  #### `<ds-pagination>` — `PaginationComponent`
369
382
  Inputs: `total: required number`, `pageSize: model<number> = 10`, `currentPage: model<number> = 1`, `pageSizeOptions: number[] = [10, 25, 50, 100]`, `showLabel: boolean = true`
370
- Outputs: `(pageChange): number`, `(pageSizeChange): number`
383
+ Outputs: `(currentPageChange): number`, `(pageSizeChange): number`
371
384
 
372
385
  #### `<ds-divider>` — `DividerComponent`
373
386
  Inputs: `variant: 'default' | 'strong' | 'vertical' | 'label' = 'default'`, `spacing: 'none' | 'sm' | 'md' | 'lg' = 'md'`
@@ -422,18 +435,13 @@ Renders `<ds-tooltip-panel>` via CDK overlay on hover / focus; hides on leave /
422
435
  #### `<ds-menu>` + `<ds-menu-item>` — `MenuComponent`, `MenuItemComponent`
423
436
  Menu is a container. Item inputs: `icon: IconName | null = null`, `disabled: boolean = false`, `danger: boolean = false`. Output: `(pressed): MouseEvent`. Content: label text; supports `[icon]` content slot for custom icons.
424
437
 
425
- #### `<ds-dropdown>` — `DropdownComponent`
426
- Trigger button + CDK overlay panel combo.
427
- Inputs: `value: model<string> = ''`, `options: DropdownOption[]` (`{ label, value, disabled?, icon? }`), `placeholder: string = 'Select…'`, `size: 'sm' | 'md' | 'lg' = 'md'`, `label: string = ''`, `disabled: boolean = false`, `readOnly: boolean = false`, `error: boolean = false`, `name: string | null = null`
428
- Selection is communicated via the `value` model. Keyboard: ArrowUp/Down, Enter/Space, Home/End, Escape.
429
-
430
438
  ---
431
439
 
432
440
  ### Tables
433
441
 
434
442
  #### `<ds-table>` — `TableComponent<T extends { id: string }>`
435
443
  Inputs: `data: required readonly T[]`, `columns: required readonly TableColumn<T>[]`, `selectable: boolean = false`, `bordered: boolean = false` (opt-in outer border + radius; off by default so tables flush inside `<ds-card padding="none">` don't double-border), `loading: false | 'skeleton' | 'overlay' = false`, `stickyHeader: boolean = true`, `selectedIds: model<Set<string>>`, `sortKey: model<string | null>`, `sortDir: model<SortDir>` (`'asc' | 'desc' | null`), `skeletonRows: number = 5`
436
- Outputs: `(rowClick): T`, `(sortChange): SortChangeEvent` (`{ key, dir }`)
444
+ Outputs: `(rowClicked): T`, `(sortChange): SortChangeEvent` (`{ key, dir }`)
437
445
  Column shape: `{ key: string, label: string, sortable?: boolean, align?: 'left' | 'right' | 'center', cell?: (row: T) => string }`
438
446
  Opening a row: give one column `link: (row) => <route target> | null` and its value renders as a real `<a>` — visible without hovering, in the tab order as a link, and Ctrl/Cmd-clickable, none of which a clickable `<tr>` can do. `null` for a row leaves that cell as plain text, so a partly-reachable list stays one column; external URLs go through a `[dsCellTemplate]` instead, since `link` takes Angular route targets only. It composes with `rowInteractive` (the link stops its click from reaching the row), but the two together cost **two tab stops per row** — on a long list prefer the link alone. `interactive: true` only tints a cell on row hover, which a keyboard or touch user never sees; prefer `link` wherever the row actually leads somewhere.
439
447
  Cell templates: `<ng-template dsCellTemplate="<colKey>" let-row>…</ng-template>` — `row` is typed `unknown`, narrow via a helper method on the host.
@@ -575,10 +583,25 @@ this.crumbs.clear();
575
583
 
576
584
  #### `ToastService`
577
585
  `@Injectable({ providedIn: 'root' })`. Inject and call:
578
- - `show(opts: ToastOptions): ToastRef` — `{ title?, body, variant?: 'info' | 'success' | 'warning' | 'error', dismissible?, durationMs? = 5000 }`. Returns `{ id, dismiss() }`.
586
+ - `show(opts: ToastOptions): ToastRef` — `{ title?, body, variant?: 'info' | 'success' | 'warning' | 'error' | 'loading', dismissible?, icon?, action?: ToastAction, durationMs? = 5000 }`. Returns `{ id, dismiss() }`. `durationMs: 0` (and any negative) means it never auto-dismisses, and it is counted from the moment the toast becomes VISIBLE, not from the call — a toast queued behind `maxVisible` keeps its full time on screen. A `loading` toast is forced to 0 and discards a supplied `durationMs`.
587
+ - `promise<T>(source: Promise<T>, messages: ToastPromiseMessages): Promise<T>` — shows a `loading` toast, then patches it in place to `success` or `error` when `source` settles. Returns `source` itself, so an un-`catch`ed call still produces an unhandled rejection. The settled toast dismisses after a hard-coded 4s (success) or 6s (error), counted from the moment it becomes visible and not overridable; `dismissAll()` cancels it like any other.
579
588
  - `dismissAll(): void`
580
589
 
581
- On first `show()` the service lazily creates a CDK overlay and mounts a `<ds-toast-region>` into it. **Consumers do not need to add a region element to their template** — the service handles mounting itself.
590
+ Defaults come from `provideDsConfig({ toast: … })`:
591
+ - `maxVisible?: number` — cap on concurrently visible toasts. Default `5`; `0` means unlimited. Extras queue and appear as earlier ones dismiss.
592
+ - `position?: { horizontalPosition?: 'left' | 'center' | 'right', verticalPosition?: 'top' | 'bottom', offset?: string }` — merged field by field over `right` / `top` / `var(--space-6)`, so naming one key keeps the other two.
593
+
594
+ The `toast` section resolves **once, at the root injector**, when the service is first used — unlike every other section, which a `Route` or a component can narrow. `ToastService` is `providedIn: 'root'`, so a route-level `provideDsConfig` never reaches it, and the position cannot change after the first `show()`.
595
+
596
+ On first `show()` the service lazily creates a CDK overlay and mounts a `<ds-toast-region>` into it. **Do not place `<ds-toast-region>` yourself** — the service only ever talks to the instance it created, so a hand-placed one is an invisible empty box that never receives a toast, with no warning. It appears in the generated API table only because the extractor lists every exported component.
597
+
598
+ #### `BodyScrollLockService`
599
+
600
+ `@Injectable({ providedIn: 'root' })`. Ref-counted lock on `document.body` scroll, shared by every overlay that covers the viewport — `ds-modal`, `ds-drawer`, `ds-bottom-sheet` all take one. Exported since 0.7.0 so a consumer's own full-screen overlay can participate in the same lock instead of fighting it.
601
+ - `lock(): void` — the FIRST call saves the current `body` overflow and hides it.
602
+ - `unlock(): void` — only the LAST one restores it, so closing one overlay cannot re-enable page scroll under another still open above it.
603
+
604
+ Calls must be paired: one `unlock()` per `lock()`. An unmatched `unlock()` is a no-op rather than an error, so a leaked `lock()` leaves the page unscrollable with nothing to show why.
582
605
 
583
606
  ---
584
607
 
package/design-system.md CHANGED
@@ -101,6 +101,10 @@ Every field-shaped control resolves it — inputs, selects, pickers, search, but
101
101
  field group, the number stepper. A literal `height` on a control is a bug: it will not
102
102
  line up with its neighbours and will not follow a density change.
103
103
 
104
+ ### Corner radius has its own section
105
+
106
+ Radius is a role, not a step, and nested radii must decrease — see §8.
107
+
104
108
  ### Never express a rule in pixels
105
109
 
106
110
  `[data-density]` retunes the private spacing and height tokens underneath everything
@@ -306,7 +310,137 @@ internals.
306
310
 
307
311
  ---
308
312
 
309
- ## 8. Where the rest lives
313
+ ## 8. Radius
314
+
315
+ ### Reach for a ROLE, never a step
316
+
317
+ Four role tokens carry every corner in the library. Occurrence counts across the library's own
318
+ components (measured 2026-09-01) show which one a given surface actually takes:
319
+
320
+ | Role | Resolves to | Uses | What it is for |
321
+ | --- | --- | --- | --- |
322
+ | `--ds-radius-inner` | `--radius-sm` (4px) | 37 | Something nested INSIDE a control — a tick, a kbd cap, a focus halo, a segment |
323
+ | `--ds-radius-control` | `--radius-md` (8px) | 26 | The control itself — button, field, tag, tooltip, segmented, search |
324
+ | `--ds-radius-panel` | `--radius-lg` (12px) | 13 | A surface that CONTAINS controls — card, modal, bottom sheet, popover, the picker panels, page footer |
325
+ | `--ds-radius-pill` | `--radius-pill` (999px) | 4 | Fully round by meaning, not by size — avatar, badge, radio, progress track |
326
+
327
+ The raw steps (`--radius-sm` … `--radius-2xl`) are the scale the roles map onto. Using one
328
+ directly says "this corner belongs to no role", which is almost never true. `--radius-xl` (16px)
329
+ and `--radius-2xl` (24px) have no consumer in the library at all — their comments in
330
+ the token file describe an intent, not a usage.
331
+
332
+ ### Nesting: inner < control < panel, and never equal
333
+
334
+ A rounded thing inside a rounded thing needs a SMALLER radius, or the inner corner appears
335
+ to bulge out of the outer one. The three roles are ordered for exactly this: a field
336
+ (`control`, 8px) inside a card (`panel`, 12px); a tick (`inner`, 4px) inside a checkbox
337
+ (`control`). If two nested surfaces share a radius, one of them is wrong.
338
+
339
+ The optical rule when you need a value the roles do not cover: inner radius = outer radius
340
+ minus the padding between them. A 12px panel with 8px of padding wants an 8px child, not 12px.
341
+
342
+ ### `--radius-flat` is a statement, not a zero
343
+
344
+ `--radius-flat` resolves to `--radius-0`, and it exists so that "this corner is deliberately
345
+ square" reads differently from "nobody set a radius". It is what the middle of a button
346
+ group and an in-range calendar day use. Writing `border-radius: 0` there loses the intent
347
+ the next reader needs.
348
+
349
+ ### Overriding
350
+
351
+ Most components with a corner expose `--ds-<component>-radius` on `:host`, resolving through
352
+ the role — but not all of them, and `ds-toast` is the one to know about: it reads `--radius-lg`
353
+ directly, so only the raw step moves it. Retheming corners means moving the four roles rather
354
+ than editing components: set `--ds-radius-control` once and every control that resolves it
355
+ follows.
356
+
357
+ ---
358
+
359
+ ## 9. Page composition — where things go
360
+
361
+ The grid itself (tiers, spans, the canonical 8+4 / 6+6 / 9+3 splits, the forbidden 7+5, the
362
+ 720px prose cap) is specified in `docs/agent/foundations/grid.md`. This section is the layer
363
+ above it: which region holds what, and in which order.
364
+
365
+ ### The page is four regions, and three of them are components
366
+
367
+ ```
368
+ ds-app-layout
369
+ ├── [sidenav] ds-sidenav — reserve the rail, OUTSIDE the page grid
370
+ ├── [topbar] ds-topbar — global, not per-page
371
+ └── (default) the page itself
372
+ ├── ds-page-header — breadcrumbs · title · meta · actions · tabs
373
+ ├── ds-filter-bar — only if the page has data to filter
374
+ ├── the content, on .page-grid
375
+ └── ds-page-footer — optional, page-level actions or legal
376
+ ```
377
+
378
+ The `ds-page-header` slots are the order the eye reads, and they are not interchangeable:
379
+ `[breadcrumbs]` above the title, `[title-badge]` beside it, `[meta]` under it, `[actions]`
380
+ right-aligned on the title line, `[tabs]` last so the tab row sits on the header's bottom
381
+ edge. Putting page actions anywhere else — a floating button, a row above the header —
382
+ breaks the one place a user has learned to look.
383
+
384
+ ### Filters sit directly above the data they filter
385
+
386
+ `ds-filter-bar` goes between the header and the content, full width, with no wrapper that
387
+ could clip its overflow popover. Not in a sidebar, not inside the table's own card, not
388
+ above the page header. A filter placed away from its data stops reading as a control over
389
+ that data, and the 9+3 split is what a genuine filter RAIL is for — reserved, not the
390
+ default.
391
+
392
+ ### Primary action per region, once
393
+
394
+ One primary (default `variant`) per region: one in the page header, one per card, one in a
395
+ modal's `[actions]`. A second primary in the same region makes neither primary. Secondary
396
+ work takes `outline`, dismissive work takes `ghost`. A modal's actions read
397
+ destructive-last: cancel then confirm, never the reverse.
398
+
399
+ ### When content belongs in a card, and when it does not
400
+
401
+ A `ds-card` earns its border when the content inside it is a UNIT that could be moved,
402
+ collapsed or repeated — a record summary, a KPI tile, one form section. It does not earn one
403
+ for "this page has content": a full-width table already has its own frame (`ds-table`
404
+ resolves `--ds-radius-control`), and a card around it double-borders. The DS default is no card;
405
+ reach for one when the boundary means something.
406
+
407
+ ### Supporting information goes under, never beside
408
+
409
+ Hints, counts, timestamps and helper text sit UNDER the thing they describe, at
410
+ `--space-1`. Beside is reserved for actions. `ds-field-message` is the mechanism for a
411
+ field; for anything else it is a `.t-s` line at `--text-secondary`. Never a tooltip: a
412
+ tooltip is hover-only, so it cannot carry information the user needs in order to act.
413
+
414
+ ### The pattern catalogue
415
+
416
+ Five page shapes cover what the DS is built for. Naming which one you are building settles
417
+ most placement questions before they come up:
418
+
419
+ | Pattern | Made of | The rule that is easy to miss |
420
+ | --- | --- | --- |
421
+ | **List + filters** | header · filter-bar · `ds-table` (or a card list) · `ds-pagination` | Filters above the data, pagination below it, both full width |
422
+ | **Record detail** | header with `[meta]` · 8+4 grid — main left, meta sidebar right | The sidebar is metadata, never navigation |
423
+ | **Form** | header · one `ds-card` per section · actions in the last card | One primary; submit gates on presence, never on validity |
424
+ | **Dashboard** | header · a row of `ds-stat` tiles · charts or tables below | Tiles are one row that wraps, not a grid you hand-place |
425
+ | **Empty / error** | `ds-empty-state` centred in the region that would have held the data | It replaces the region, not the page — header and filters stay |
426
+
427
+ ### Checking a composition, instead of eyeballing it
428
+
429
+ Five checks, in the order that catches the most:
430
+
431
+ 1. **Every gap is a token.** A literal `px` between two elements will not follow
432
+ `[data-density]` — see §3. Grep the diff for `px` outside a token declaration.
433
+ 2. **Every span is a column.** `col-span-*` on `.page-grid`, and the split is 8+4, 6+6 or
434
+ 9+3. If a region needs 7+5, the content is wrong, not the grid.
435
+ 3. **One grid per page.** A sub-region aligns to the page tracks; a local `display: grid`
436
+ with its own columns is how alignment drifts one screen at a time.
437
+ 4. **Nested radii decrease.** See §8. Two nested surfaces with the same radius is a defect
438
+ you can see once you look for it.
439
+ 5. **One primary per region**, and prose capped at `--col-cap-text`.
440
+
441
+ ---
442
+
443
+ ## 10. Where the rest lives
310
444
 
311
445
  The decisions this file does NOT make are the ones about which COMPONENT to reach for, and they
312
446
  have their own home: the documentation site's `Practice → Do / Don't` (modal vs drawer, button hierarchy, table