@ids-group-ltd/ids-design-system 0.11.1 → 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 (82) hide show
  1. package/CHANGELOG.md +342 -31
  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 +1530 -865
  65. package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
  66. package/migrations/0.11.0.json +0 -45
  67. package/migrations/0.11.1.json +9 -35
  68. package/migrations/0.11.2.json +158 -0
  69. package/migrations/0.11.3.json +152 -0
  70. package/migrations/0.2.0.json +17 -5
  71. package/migrations/0.4.0.json +1 -1
  72. package/migrations/0.7.1.json +3 -3
  73. package/migrations/0.9.0.json +2 -2
  74. package/package.json +1 -1
  75. package/styles/_dropdown-overlay.scss +50 -38
  76. package/styles/_ds-color.scss +31 -12
  77. package/styles/_tokens-charts.scss +2 -3
  78. package/styles/_tokens.scss +159 -322
  79. package/themes/README.md +35 -4
  80. package/themes/_base-palette.scss +35 -76
  81. package/themes/_semantic.scss +5 -2
  82. package/types/ids-group-ltd-ids-design-system.d.ts +424 -188
package/CHANGELOG.md CHANGED
@@ -8,6 +8,340 @@ While the package is on `0.x`, minor releases may contain breaking changes.
8
8
 
9
9
  ## Unreleased
10
10
 
11
+ ## 0.11.3 — 2026-09-02
12
+
13
+ ### Breaking
14
+
15
+ - **`ds.color()` now refuses a family it does not know, and that stops your Sass build.**
16
+ `@include ds.color(brand)` used to compile and emit eleven `--accent-*` pointers at values that
17
+ could never resolve, so a zone painted itself with `unset` and the mistake looked like a theming
18
+ problem. It `@error`s now, naming the five families it takes: `secondary`, `tertiary`, `error`,
19
+ `success`, `warning`. Anything else fails the build at the `@include`. The `ds-color="…"`
20
+ attribute is untouched — no Sass runs for it.
21
+
22
+ ### Changed
23
+
24
+ - **The banner and toast icon now centres on the message block**, where most shapes aligned it to
25
+ the first line of text. The two rules agree on a one-line message — which is most toasts — and
26
+ diverge as the text grows: the icon sat some 12px above the block centre at two lines and 21px at
27
+ three. A `compact` banner was already centred and does not move.
28
+
29
+ It is `align-self` on the icon rather than `align-items` on the row, so the close button and the
30
+ action buttons keep the positions they had. `--banner-ic-mt` is **removed**; it existed only to
31
+ nudge the icon down by one border-width under the old rule.
32
+
33
+ `ds-alert` follows, for the same reason: it carried the same nudge inlined as
34
+ `var(--border-width-default)` rather than through the token.
35
+
36
+ **Known limit.** The icon centres on the flex LINE, which equals the message block only while the
37
+ message is the tallest thing in the row. A one-line toast with a close button is 0.53px off, and with
38
+ a projected `[actions]` button 6–14px off depending on its size. `align-items: center` would be
39
+ unconditional but moves the close button, which is the trade above.
40
+
41
+ - **`ToastRegionComponent`'s member surface moved again — only matters if you SUBCLASS it.** The
42
+ timer and pause work gained `arm`, `focusWithin`, `host`, `hovered`, `onFocusWithin`, `onHover`,
43
+ `paused`, `pauseAll`, `remaining`, `resumeAll`, `startedAt` and `syncPause`, and **lost
44
+ `startCountdown`**: a countdown is armed when a toast becomes visible and re-armed from what is
45
+ left when a pause ends, where before the region started one timer per toast. Every one is a
46
+ `private` or `protected` internal — none is public API, none is a signal, and there is no
47
+ replacement to call for `startCountdown`, so an override of it should simply go. A member of
48
+ yours sharing one of those names still stops the build, because `private` collides with TS2415
49
+ exactly as a public name does. `host` is the one most likely to clash.
50
+ Rename yours — `override` is not a way out for ten of the twelve, because a member whose base
51
+ declaration is `private` rejects it with the same TS2415 as a plain redeclaration, and that
52
+ includes `host`. Only the two `protected` ones, `onHover` and `onFocusWithin`, accept it. The
53
+ compiler enumerates every
54
+ collision, so building after the upgrade is the whole check.
55
+
56
+ Worth flagging for anyone who followed 0.11.2's note: `startCountdown` was announced there as a
57
+ member the region had just gained, so an `override startCountdown` added one release ago now
58
+ overrides nothing and silently never runs. There is no public replacement to call — the countdown
59
+ is the region's own business now. Delete the override.
60
+
61
+ - **`components.md` documented a component that does not exist and four events that never fired.**
62
+ It carried a `<ds-dropdown>` entry through nine releases; that component was absorbed into
63
+ `<ds-select>` and an import written from the document fails to compile. Four documented event
64
+ names were never identifiers here: `ds-banner` and `ds-toast` emit `(closed)`, not `(dismissed)`;
65
+ `ds-pagination` emits `(currentPageChange)`, not `(pageChange)`; `ds-table` emits `(rowClicked)`,
66
+ not `(rowClick)`. An unknown event binding registers a DOM listener and never fires, so those
67
+ four handlers were silently dead with nothing in the console. `<ds-alert>` was missing from the
68
+ document entirely and is now in it, `'neutral'` variant included.
69
+
70
+ ### Fixed
71
+
72
+ - **`ds-color="error"`, `="success"` and `="warning"` lost their accent colour.** Those zones map
73
+ `--accent-strong` onto `--<family>-strong`, and the three status families never defined it — only
74
+ the brand families did. The declaration was invalid at computed-value time, so inside a status
75
+ zone every place that reads `--accent-strong` reset to `unset`: selected list and tree rows,
76
+ the active sidenav item and its rail, the active tab pill, avatar and avatar-group initials, the
77
+ active tag, dropzone text, the date-picker range label, the toast's action label, the selected
78
+ toggle button, the split-button hover fill, the `tonal`, `ghost`, `outline` and `text` variants
79
+ of `ds-button`, and the `tonal` variant of `ds-icon-button`. Text there fell through to the
80
+ inherited body colour; the fill
81
+ and the rail, which inherit nothing, disappeared.
82
+
83
+ No new token was needed: a status family already carries its readable on-tint colour as `-text`,
84
+ so `--accent-strong` now asks for `-strong` first and `-text` second, and the brand families keep
85
+ answering it as `-strong` because they have no `-text`. Each pointer also ends in a fallback — to
86
+ the family's base for `-hover`, `-pressed` and `-strong`, to its `-muted` for the tint pointers,
87
+ and to the theme-wide role for `-on` and the two focus pointers — so a role that goes missing in
88
+ future degrades instead of disappearing.
89
+
90
+ - **`ToastService.promise()` could destroy its own result.** It ran the settled toast's
91
+ auto-dismiss on a wall-clock timer started when the promise resolved, not when the toast became
92
+ visible — the one thing the rest of the timer work had already moved into the region. With a
93
+ `maxVisible` cap set, a promise that settled while its toast was still queued had the result spliced
94
+ out of the queue before anyone saw it: the user saved, it succeeded, and no toast appeared at all.
95
+ The settled duration is now handed to the region with the content, so it starts on promotion.
96
+
97
+ - **A toast carrying an `action` no longer auto-dismisses.** The overlay is the last child of `body`,
98
+ so the region is dead last in tab order; a keyboard user cannot cross a real page in the five
99
+ seconds the button was alive. An `action` toast now waits, and is always dismissible. Note that
100
+ a `durationMs` you pass alongside an `action` is discarded — the toast waits regardless — and
101
+ `dismissible: false` is discarded on any toast that cannot expire, not only on a `loading` one.
102
+
103
+ - **Hovering or focusing the region pauses every countdown**, resuming when the pointer or focus
104
+ leaves. A toast being read is not a toast that has been read. The pause is derived from both
105
+ sources rather than latched, so tabbing out of a region the pointer is still over does not
106
+ resume, moving focus between the action and the close button is not a leave, and a toast that
107
+ becomes visible under a stationary pointer — a burst past the cap, or a promise settling — is
108
+ banked rather than counted. A toast paused with almost nothing left resumes with at least 600ms, so
109
+ one hovered with
110
+ almost nothing left does not vanish as the pointer leaves.
111
+
112
+ - **A disabled accordion item's chevron did not look disabled.** It asked for a colour token this
113
+ library does not define, so the declaration was invalid at computed-value time and the chevron
114
+ inherited whatever colour surrounded it — while the label beside it greyed correctly. It reads the
115
+ disabled text colour now, like the label.
116
+
117
+ - **The `ds-banner` close button had no accessible name.** It announced as a bare "button", where
118
+ the same control on `ds-toast` and `ds-alert` already said "Dismiss". It says it now.
119
+
120
+ - **A long unbroken word in a toast overflowed the pill.** A URL or an id with no break
121
+ opportunity ran past the rounded edge instead of wrapping inside it.
122
+
123
+ - **Nothing that cannot expire can also be unclosable.** The rule is now that any toast with no
124
+ duration is dismissible, whatever you asked for — a `loading` variant, one carrying an `action`,
125
+ or an explicit `durationMs: 0`. A `loading` toast was created with `dismissible: false` and no
126
+ 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
127
+ toasts that would have explained the hang.
128
+
129
+ ## 0.11.2 — 2026-09-01
130
+
131
+ ### Added
132
+
133
+ - **`PageUp` and `PageDown`.** Ten rows a press, which is the native `<select>` step and the APG
134
+ listbox example’s — a fixed number rather than a measured screenful, so the jump is the same
135
+ wherever the panel happens to be clipped. No picker had these.
136
+
137
+ - **`clear()` on `ds-select` and `ds-multi-select`.** `ds-autocomplete` has had it; the other two
138
+ offered only the in-trigger button, so an app with its own “reset filters” had to write the empty
139
+ value by hand and guess what empty means for that control. It does NOT move focus, deliberately:
140
+ the caller may be navigating away.
141
+
142
+
143
+ - **Panel header and footer slots.** The panel was a closed box between the filter row and the
144
+ options: "3 of 40 selected", a "clear all" button, a hint or a link under the list had nowhere to
145
+ go. `dsPanelHeaderTemplate` and `dsPanelFooterTemplate` fill a strip above and below, with
146
+ `count`, `total` and `query` in context. Both sit OUTSIDE the `listbox`, so nothing you put there
147
+ is counted as an option or breaks a reader's "N of M" position, and neither scrolls with the list —
148
+ the panel clips and the list is the scroller.
149
+
150
+ - **`dsGroupLabelTemplate`.** A group heading rendered its text and nothing else, so a count, a team
151
+ glyph or a second line was impossible. The heading ELEMENT stays the library's — it keeps the id the
152
+ group's `aria-labelledby` points at — and only its contents are yours.
153
+
154
+ - **The option row's geometry is tokens.** `--ds-option-gap`, `--ds-option-padding`,
155
+ `--ds-option-radius` and `--ds-option-row-gap`, plus `--ds-option-bg-color-active` for the
156
+ hover/keyboard fill. A denser panel meant re-declaring the row before, which is exactly how a second
157
+ copy of the panel ended up inside a component.
158
+
159
+ - **`searchPlaceholder` on `ds-autocomplete`.** Its `placeholder` was doing two jobs — the
160
+ empty-field caption and the hint for typing over a settled value. `ds-multi-select` already
161
+ separated them; now the name means one thing on both. Empty by default, so nothing moves.
162
+
163
+ - **The result count is announced.** A reader typed into the filter and heard nothing: no live region
164
+ existed in any picker. One is created per picker now, outside the listbox and empty at first — a
165
+ region created together with its text is the case screen readers reliably do not announce.
166
+
167
+ - **Type-ahead on `ds-select` and `ds-multi-select`.** Typing "ba" jumps to the first option starting
168
+ with "ba", the way a native `<select>` does, and repeating one letter cycles through the options
169
+ beginning with it. On a closed `ds-select` the jump commits, matching the native control.
170
+ `ds-autocomplete` is deliberately excluded: its trigger IS a text field, so typing there is the
171
+ filter and a jump would fight it.
172
+
173
+ - **`disabledReason` on an option, rendered by `ds-select`.** A disabled row said it could not be
174
+ picked and never why. On `ds-select` the reason reaches the row through `aria-describedby` and is
175
+ visually hidden — the row already looks disabled; the text is for whoever cannot see that. The
176
+ field is on the shared `DsOption`, so `SelectOption`, `MultiSelectOption` and `AutocompleteOption`
177
+ all accept it and it type-checks on all three pickers; `ds-multi-select` and `ds-autocomplete` do
178
+ not yet render it, so a reason set there is carried and not shown.
179
+
180
+
181
+ - **The keyboard cursor keeps its row in view.** On a list longer than the panel the arrows walked the
182
+ cursor out of sight — the reader pressed down and could not see where they were. All three pickers
183
+ scroll the active row into view now, on by default; `scrollActiveIntoView="false"` gives the scroll
184
+ position back to you. It uses `block: 'nearest'`, so a row that is already visible does not move and
185
+ the mouse is never fought.
186
+
187
+ - **`Home` and `End` on every picker.** They existed on `ds-select` alone, while ten other components
188
+ in the library already had them. The index arithmetic all three had written out separately — next,
189
+ previous, first, last, skipping disabled and wrapping — is one shared helper now, so the three
190
+ behave identically. It is internal: nothing new is exported.
191
+
192
+ - **`compareWith` on `ds-autocomplete`.** The component is generic over its value type but compared
193
+ with `===`, which is reference identity: a re-fetch that returned equal data as new objects silently
194
+ dropped the selection. Pass a comparator keyed on what identifies the value —
195
+ `[compareWith]="(a, b) => a?.id === b?.id"`. The default is unchanged, so string and number values
196
+ behave exactly as before. `ds-select` and `ds-multi-select` key on `string` and do not need it.
197
+
198
+ - **`loading`.** While options were being fetched the panel said "No matches", which is a lie the
199
+ consumer had no way to correct. It shows a spinner instead now, and the listbox reports
200
+ `aria-busy`. Spelled `booleanAttribute` to match `ds-button`, `ds-input` and `ds-loading-overlay`.
201
+
202
+ - **`opened` and `closed`.** There was no way to know a panel had opened, so a picker whose options
203
+ are fetched on demand had nowhere to start the request. `closed` is the name eight other components
204
+ already use; `opened` is its missing pair. They fire on the transition, not on every write, so
205
+ closing by Escape emits once rather than twice.
206
+
207
+ - **`filterWith` and `filterChange` — one input for both server-side search and a custom match.**
208
+ The query matcher was hardcoded to a case-insensitive substring of `label`: matching a second field,
209
+ ignoring diacritics or scoring fuzzily was impossible, and so was letting a server do the filtering.
210
+ `filterWith` takes a predicate for the first and the literal `'none'` for the second, where every
211
+ option handed in is rendered and `filterChange` reports what was typed. One input rather than two,
212
+ because they are one decision: who decides what the query matches.
213
+
214
+ - **`name`, `readOnly` and `clearable` on `ds-multi-select` and `ds-autocomplete`.** The last three
215
+ form-contract members that were `ds-select`'s alone. `name` reaches seven other controls in the
216
+ library, so the two pickers were the outliers; `readOnly` takes focus without opening, and carries
217
+ the same `readonly` binding alias `ds-select` has for signal forms; `clearable` uses the same button
218
+ and the same accessible name as `ds-select`'s.
219
+
220
+
221
+ - **`ds-table` row expansion: one-at-a-time, expand-all, and events.** The base feature shipped
222
+ already; these are the three edges it was missing. `expandMode="single"` collapses the open row
223
+ when another expander is clicked, so a detail panel cannot stack up down the page — enforced when
224
+ the user clicks, not on the binding, because `expandedIds` is the host's model to write and
225
+ rewriting it underneath would be the table arguing with its own consumer. `expandAllToggle` puts
226
+ a chevron in the expander column header, page-scoped when paginating exactly as select-all is.
227
+ `(rowExpanded)` and `(rowCollapsed)` name the row as it opens and closes, expand-all included,
228
+ which is where panel content gets lazy-loaded; a collapse the host writes into `expandedIds`
229
+ itself stays silent, and so does an id whose row is no longer in `data()` — an event carries a
230
+ row, and there is none to carry. Opening two rows or more now also reaches the table's live
231
+ region, which a full page of panels appearing from one keypress previously did not.
232
+
233
+
234
+ - **Column resizing works on a touch device, where the drag handle never could.** The handle
235
+ paints its line on `:hover` and `:focus-visible`; a coarse pointer produces neither, so it was
236
+ invisible — while `touch-action: none` still took the horizontal swipe that scrolls the table,
237
+ leaving a dead 8px strip at the right edge of every header. Under
238
+ `(hover: none) and (pointer: coarse)` the handle now stands down and width moves into the column
239
+ panel: each row carries −, + and Fit next to its visibility and order controls, and the panel
240
+ opens as a `ds-bottom-sheet` rather than a popover. The buttons render on desktop as well, where
241
+ the handle remains the primary route. All three routes share one step, so drag, arrow keys and
242
+ buttons move a column by the same amount, and all three clamp at the scroll viewport.
243
+
244
+
245
+ ### Changed
246
+
247
+ - **Exported class member surface grew — only matters if you SUBCLASS a DS component.**
248
+ `SelectComponent`, `MultiSelectComponent`, `AutocompleteComponent`, `TableComponent`,
249
+ `LoadingOverlayComponent` and `ToastRegionComponent` all gained members for the inputs and outputs
250
+ above, and `DsPanelHeaderTemplateDirective`,
251
+ `DsPanelFooterTemplateDirective` and `DsGroupLabelTemplateDirective` are new classes.
252
+ Subclassing a DS component is unsupported but consumers do it, and a
253
+ member of yours that shares a name with one of ours stops the build. Rename yours, or add `override`
254
+ if you meant to replace ours — the compiler enumerates every collision, so building after the
255
+ upgrade is the whole check.
256
+
257
+ - **BREAKING for code that CONSTRUCTS a `ToastEntry`: `durationMs` is now a required
258
+ `readonly number`.** The field did not exist on the type before, so it arrives required rather
259
+ than widened: an object literal typed as `ToastEntry` — a test double, a hand-rolled region, a
260
+ store that holds toasts — stops compiling until it carries one. The entry has to know its own
261
+ duration now that the countdown belongs to the region rather than the service.
262
+ `ToastOptions.durationMs` is untouched — still optional, still `5000` by default, still `0` for a
263
+ loading toast — so a caller of `ToastService` writes nothing new.
264
+
265
+ - **BREAKING visually where a stack of toasts is part of the page: the newest toast enters at the
266
+ top of a top-anchored region.** Every toast was appended, so in a region resolving to a top
267
+ position — the default — the newest one landed at the BOTTOM of the stack, furthest from the
268
+ corner the stack grows out of, and the thing that had just happened was the last one you read. A
269
+ top position prepends now; a bottom position still appends. Either way the newest toast is the one
270
+ nearest the screen edge the region is anchored to.
271
+
272
+ - **`ds-select`'s option list caps 40px shorter.** The list's `max-height` was declared in
273
+ `ds-multi-select`'s own stylesheet; it sits in the shared panel partial now, so it reaches
274
+ `ds-select` and `ds-autocomplete` too. `ds-select`'s list was previously bounded only by the panel
275
+ cap `--ds-dropdown-panel-maxh` (320px) and now stops at `--picker-maxh` (280px) — roughly one
276
+ option row — which is the height the other two panels already used. `ds-autocomplete` had pinned
277
+ its panel to that value itself and does not move. Set `--picker-maxh` to take the height back, on
278
+ the panel where only that select should change or globally where all three should follow; the
279
+ panel cap is unchanged and is simply no longer what decides where a `ds-select` list stops.
280
+
281
+ - **`skeleton-mode` is gone from the inner `<table>` element of `ds-table` — only matters if you
282
+ reach in with `::ng-deep`.** The class was bound on that element, not the host, and nothing in the
283
+ library ever painted it, so a rule keyed on it was the only thing giving it meaning. If you have
284
+ one, key it off a class of your own on the host instead; if you do not, nothing about the rendered
285
+ table changes.
286
+
287
+ ### Fixed
288
+ - **Dev-mode warnings no longer ship to production bundles.** They were guarded by
289
+ `isDevMode()`, which is a function CALL — a bundler cannot prove the branch dead, so all thirteen
290
+ warning sites and their message closures reached production builds. Each site is now guarded inline
291
+ with `typeof ngDevMode === 'undefined' || ngDevMode`, which `@angular/build` folds away whenever
292
+ script optimization is on, closures included. **Measured: 1 590 B gzip off an app using most of the
293
+ library, 827 B of it off a single `<ds-button>`.** Nothing changes for you — no API, no behaviour,
294
+ and the warnings still fire in development builds exactly as before.
295
+
296
+ - **A loading scrim stopped the pointer and let the keyboard walk straight under it.**
297
+ `ds-loading-overlay` paints an absolutely positioned scrim over its content, which intercepts
298
+ every pointer event — so a control behind it could not be clicked, and looked unavailable. Nothing
299
+ stopped focus: Tab reached the same control, Enter activated it, and `ds-table` with
300
+ `rowInteractive` would emit `(rowClicked)` for a row whose data the host was in the middle of
301
+ replacing. Neither `onRowClick` nor `onRowKey` consulted the loading state, and a row's
302
+ `tabindex` never did either. The overlay now marks the content it covers `inert` while loading,
303
+ which is the one mechanism that stops pointer and keyboard together and takes the covered controls
304
+ out of the accessibility tree; `aria-busy` stays on the host, so a reader is still told why.
305
+ `inertContent="false"` turns it off for a scrim that covers only PART of its content, and the
306
+ consumer then marks the covered subtree itself — `ds-table` does this, because its scrim starts
307
+ below the header and re-sorting during a refresh is exactly what puts the scrim up.
308
+
309
+ - **A toast queued behind `maxVisible` expired while it was still waiting.** The auto-dismiss
310
+ countdown started when `ToastService` was called, not when the toast reached the screen, so a
311
+ burst past the cap retired toasts that had never been visible — the more you fired at once, the
312
+ fewer were read, and the ones lost were the ones at the back. The countdown starts when the region
313
+ shows the toast now, promotion out of the queue included, so a queued toast gets its full duration
314
+ on screen. One gap remains: `ToastService.promise()` runs its own timers, so a promise toast held
315
+ behind the cap can still be removed before it is shown.
316
+
317
+ - **Dismissing a toast that was still queued promoted a different one instead of removing it.** The
318
+ id belonged to an entry that had not become visible yet, so the entry stayed in the queue and
319
+ another toast was pulled forward: the one you dismissed still appeared later, and one you had not
320
+ touched was hurried on screen ahead of its turn. A queued id is spliced out of the queue now and
321
+ nothing is promoted in its place.
322
+
323
+ - **A column resize handle announced no position and no limits.** The handle is a `role="separator"`,
324
+ which a screen reader presents as a slider, but an auto-sized column carried no `aria-valuenow` at
325
+ all — the user was handed a control with no current value and no way to hear how far it could go in
326
+ either direction. While the handle holds focus it now carries a measured `aria-valuenow` in px,
327
+ `aria-valuemin` of `48` and an `aria-valuemax` of the scroll viewport's width, which is the same
328
+ ceiling the drag, the arrow keys and the column-panel buttons clamp at. All three are present only
329
+ while the handle is focused.
330
+
331
+ - **A table's loading scrim slid off the table as it scrolled sideways.** `ds-loading-overlay` sat
332
+ inside the scroll container, and the scrim is `position: absolute; inset: 0` — so it was sized to a
333
+ single viewport of the table and then travelled with the content: at 400px of horizontal scroll it
334
+ sat 400px to the left of where it was needed, and every column the scroll had revealed was left
335
+ uncovered. The overlay wraps the scroll container now, so the scrim covers what is on screen at any
336
+ scroll offset.
337
+
338
+ - **A compact trigger showed one chip where several fitted.** `triggerDisplay="count"` and
339
+ `"labels"` make the trigger hug its content, so the width the chip fit measured was decided by the
340
+ chips it was about to cut — each pass shrank its own input and the split settled on one. The fit
341
+ reads the space AVAILABLE now, the trigger's parent, which no cut can move. `ds-autocomplete` gets
342
+ the same correction since both pickers measure through one helper, and a `width="fill"` trigger is
343
+ unaffected because there the two numbers are identical.
344
+
11
345
  ## 0.11.1 — 2026-08-31
12
346
 
13
347
  ### Added
@@ -198,6 +532,14 @@ While the package is on `0.x`, minor releases may contain breaking changes.
198
532
 
199
533
  ### Fixed
200
534
 
535
+ - **A compact trigger showed one chip where several fitted.** `triggerDisplay="count"` and
536
+ `"labels"` make the trigger hug its content, so the width the chip fit measured was decided by the
537
+ chips it was about to cut — each pass shrank its own input and the split settled on one. The fit
538
+ reads the space AVAILABLE now (the trigger's parent), which no cut can move. `ds-autocomplete` gets
539
+ the same correction, since both pickers measure through one helper, and a `width="fill"` trigger is
540
+ unaffected because there the two numbers are identical.
541
+
542
+
201
543
  - **With the filter row hidden, there was no keyboard way to pick an option.** `Enter` and `Space`
202
544
  were consumed by the trigger before the panel's own handler saw them, so the panel toggled shut
203
545
  instead of selecting the active row: open, arrow down, Enter, nothing chosen. The trigger delegates
@@ -239,26 +581,6 @@ While the package is on `0.x`, minor releases may contain breaking changes.
239
581
  its top-level items by index rather than by label, which is not unique.
240
582
 
241
583
 
242
- - **Four published migration manifests were corrected, and a repo that upgraded before today may
243
- be holding the result.** These files are executed: your upgrade tooling read them, acted and
244
- reported done, so a defect in one is a defect in your codebase.
245
- **`0.5.1#progress-variant-remap` certified the wrong component.** Its `verify` was the text
246
- belonging to the badge item beside it, checking that chips render in their status colours — so
247
- a `ds-progress` still binding `variant="warn"` or `variant="indeterminate"`, or TypeScript
248
- still naming a removed `ProgressVariant` member, passed the check and shipped.
249
- **Two items named too few locators to be found.**
250
- `0.9.0#search-height-joins-field-scale` searched only `--ds-search-height`, so a short search
251
- row pinned through `--hit-min` instead was never flagged; `0.10.1#fields-shared-base-class-members`
252
- searched the bare base names, so a subclass written `extends` one of the internal field bases
253
- went unfound and its `success` collision surfaced only at build.
254
- **`0.10.1` also gained a delete row it never carried** — a modal body torn down on `(closed)`,
255
- or held behind the open flag, purely so a re-opened `ds-date-picker` starts clean. The picker
256
- clears itself now, and the teardown never fired reliably: re-opening inside the leave animation
257
- cancels the close, so `closed` never comes.
258
- `0.11.0#exported-class-members-grew` pointed its `detect` and `verify` at a base no consumer can
259
- extend; corrected, with no consequence for anyone.
260
- Re-run those items if your last upgrade crossed those versions.
261
-
262
584
  ### What you can now DELETE
263
585
 
264
586
  None of this is required — skipping it leaves working code that is merely redundant. Each row is a
@@ -1227,17 +1549,6 @@ None of this is required — skipping it leaves working code that is merely redu
1227
1549
  neither this token nor `--ds-radius-panel` — so only `--radius-md` itself moves it, and that moves
1228
1550
  buttons, fields and tooltips with it.
1229
1551
 
1230
- - **Two migration manifests were corrected and three more were written**, so re-read them if you
1231
- subclass a DS component or upgrade across a version you skipped. `0.9.0`'s named no member collisions
1232
- at all — the note that now fills the gap lists **fifteen** classes whose member surface had grown, plus
1233
- four newly exported symbols that can shadow a local name — and `0.8.0`'s missed the private
1234
- `saveLayout` that actually stopped a build (`restoreLayout` went in beside it). **`0.6.1`, `0.6.2` and
1235
- `0.9.1` had no manifest at all**, and now every released version carries one: the auto-update planner
1236
- prefers a manifest and otherwise re-derives the plan from changelog prose on every run, which is what
1237
- an upgrade crossing those three used to do. `0.6.2`'s holds something actionable that no
1238
- machine-readable file had ever stated — a `ds-bottom-sheet` with nothing focusable inside it stopped
1239
- closing on Escape — which is exactly the kind a "just fixes" patch is assumed not to have.
1240
-
1241
1552
  - **`ds-avatar` takes a `name`, and the rule that reads it is replaceable.** One binding now does both
1242
1553
  jobs a caller used to wire by hand: it derives the initials and seeds the tint. **The tint hashes the
1243
1554
  NAME, not the initials** — two letters collide wholesale, so Alice Brown and Adam Bell used to share a
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,17 @@ 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 are set with two injection tokens, NOT through `provideDsConfig`:
591
+ - `DS_TOAST_CONFIG` — `{ maxVisible?: number }`. Unset or `0` means unlimited; extras queue and appear as earlier ones dismiss.
592
+ - `DS_TOAST_POSITION` — `{ horizontalPosition?: 'left' | 'center' | 'right', verticalPosition?: 'top' | 'bottom', offset?: string }`. Defaults to `right` / `top` / `var(--space-6)`.
593
+
594
+ Both resolve **once, at the root injector**, when the service is first used. Providing either on a `Route` or a component has no effect, 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.
582
597
 
583
598
  ---
584
599
 
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