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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/CHANGELOG.md +119 -2
  2. package/components.md +27 -12
  3. package/design-system.md +135 -1
  4. package/docs/agent/INDEX.md +98 -0
  5. package/docs/agent/domain/ds-w3w.md +10 -0
  6. package/docs/agent/feedback/ds-alert.md +9 -0
  7. package/docs/agent/feedback/ds-avatar-group.md +7 -0
  8. package/docs/agent/feedback/ds-avatar.md +6 -0
  9. package/docs/agent/feedback/ds-badge.md +7 -0
  10. package/docs/agent/feedback/ds-banner.md +10 -0
  11. package/docs/agent/feedback/ds-empty-state.md +7 -0
  12. package/docs/agent/feedback/ds-progress.md +7 -0
  13. package/docs/agent/feedback/ds-skeleton.md +6 -0
  14. package/docs/agent/feedback/ds-spinner.md +6 -0
  15. package/docs/agent/feedback/ds-stat.md +7 -0
  16. package/docs/agent/feedback/ds-status-dot.md +6 -0
  17. package/docs/agent/feedback/ds-tag.md +8 -0
  18. package/docs/agent/feedback/ds-toast.md +12 -0
  19. package/docs/agent/forms/ds-autocomplete.md +9 -0
  20. package/docs/agent/forms/ds-button.md +14 -0
  21. package/docs/agent/forms/ds-checkbox.md +6 -0
  22. package/docs/agent/forms/ds-date-picker.md +7 -0
  23. package/docs/agent/forms/ds-dropzone.md +10 -0
  24. package/docs/agent/forms/ds-icon-button.md +10 -0
  25. package/docs/agent/forms/ds-input.md +22 -0
  26. package/docs/agent/forms/ds-multi-select.md +6 -0
  27. package/docs/agent/forms/ds-number-stepper.md +8 -0
  28. package/docs/agent/forms/ds-radio.md +6 -0
  29. package/docs/agent/forms/ds-search.md +10 -0
  30. package/docs/agent/forms/ds-select.md +7 -0
  31. package/docs/agent/forms/ds-switch.md +6 -0
  32. package/docs/agent/forms/ds-textarea.md +9 -0
  33. package/docs/agent/forms/the-picker-family-ds-select-ds-multi-select-ds-autocomplete.md +21 -0
  34. package/docs/agent/foundations/global-helper-classes.md +18 -0
  35. package/docs/agent/foundations/grid.md +35 -0
  36. package/docs/agent/foundations/tokens.md +47 -0
  37. package/docs/agent/navigation/ds-app-layout.md +10 -0
  38. package/docs/agent/navigation/ds-auth-layout.md +9 -0
  39. package/docs/agent/navigation/ds-breadcrumbs.md +7 -0
  40. package/docs/agent/navigation/ds-divider.md +9 -0
  41. package/docs/agent/navigation/ds-page-footer.md +7 -0
  42. package/docs/agent/navigation/ds-page-header.md +8 -0
  43. package/docs/agent/navigation/ds-pagination.md +7 -0
  44. package/docs/agent/navigation/ds-sidenav-group.md +8 -0
  45. package/docs/agent/navigation/ds-sidenav-item.md +9 -0
  46. package/docs/agent/navigation/ds-sidenav.md +9 -0
  47. package/docs/agent/navigation/ds-stepper.md +6 -0
  48. package/docs/agent/navigation/ds-tabs.md +9 -0
  49. package/docs/agent/navigation/ds-topbar.md +8 -0
  50. package/docs/agent/overlays/ds-bottom-sheet.md +9 -0
  51. package/docs/agent/overlays/ds-drawer.md +9 -0
  52. package/docs/agent/overlays/ds-menu.md +8 -0
  53. package/docs/agent/overlays/ds-modal-card.md +6 -0
  54. package/docs/agent/overlays/ds-modal.md +8 -0
  55. package/docs/agent/overlays/ds-popover.md +6 -0
  56. package/docs/agent/overlays/ds-tooltip.md +8 -0
  57. package/docs/agent/platform/breadcrumbs-service.md +30 -0
  58. package/docs/agent/platform/ds-config.md +60 -0
  59. package/docs/agent/platform/ds-icon-registry.md +23 -0
  60. package/docs/agent/platform/toast-service.md +19 -0
  61. package/docs/agent/surfaces/ds-accordion.md +8 -0
  62. package/docs/agent/surfaces/ds-card.md +10 -0
  63. package/docs/agent/tables/ds-table.md +15 -0
  64. package/fesm2022/ids-group-ltd-ids-design-system.mjs +262 -338
  65. package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
  66. package/migrations/0.11.3.json +152 -0
  67. package/package.json +1 -1
  68. package/styles/_dropdown-overlay.scss +25 -32
  69. package/styles/_ds-color.scss +31 -12
  70. package/styles/_tokens-charts.scss +2 -3
  71. package/styles/_tokens.scss +158 -321
  72. package/themes/README.md +32 -1
  73. package/themes/_base-palette.scss +35 -76
  74. package/themes/_semantic.scss +5 -2
  75. package/types/ids-group-ltd-ids-design-system.d.ts +115 -190
package/CHANGELOG.md CHANGED
@@ -8,6 +8,124 @@ 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
+
11
129
  ## 0.11.2 — 2026-09-01
12
130
 
13
131
  ### Added
@@ -168,14 +286,13 @@ While the package is on `0.x`, minor releases may contain breaking changes.
168
286
 
169
287
  ### Fixed
170
288
  - **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
289
+ `isDevMode()`, which is a function CALL — a bundler cannot prove the branch dead, so all thirteen
172
290
  warning sites and their message closures reached production builds. Each site is now guarded inline
173
291
  with `typeof ngDevMode === 'undefined' || ngDevMode`, which `@angular/build` folds away whenever
174
292
  script optimization is on, closures included. **Measured: 1 590 B gzip off an app using most of the
175
293
  library, 827 B of it off a single `<ds-button>`.** Nothing changes for you — no API, no behaviour,
176
294
  and the warnings still fire in development builds exactly as before.
177
295
 
178
-
179
296
  - **A loading scrim stopped the pointer and let the keyboard walk straight under it.**
180
297
  `ds-loading-overlay` paints an absolutely positioned scrim over its content, which intercepts
181
298
  every pointer event — so a control behind it could not be clicked, and looked unavailable. Nothing
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
@@ -0,0 +1,98 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # DS catalogue — index
3
+
4
+ One leaf per entry. Read this index, then the single leaf you need — not the whole
5
+ catalogue. Every leaf names the selector, its inputs/outputs/slots, an example and the
6
+ public CSS custom properties.
7
+
8
+ **This catalogue is the WHAT — the inventory.** The HOW lives in `design-system.md`:
9
+ spacing bands, type roles, colour, motion, content, radius roles (§8) and page
10
+ composition — which region holds what, the five page patterns, and how to check a
11
+ composition instead of eyeballing it (§9).
12
+
13
+ **The generated API table on the documentation site is authoritative for exact inputs
14
+ and token names.** These leaves are for orientation and usage.
15
+
16
+ - [Foundations — Tokens (Tier 2 — semantic roles)](foundations/tokens.md)
17
+ - [Foundations — Grid](foundations/grid.md)
18
+ - [Foundations — Global helper classes](foundations/global-helper-classes.md)
19
+
20
+ ## domain
21
+
22
+ - [<ds-w3w> — W3wComponent](domain/ds-w3w.md) — What3Words address chip — branded display for ///word.word.word addresses; click-to-copy.
23
+
24
+ ## feedback
25
+
26
+ - [<ds-badge> — BadgeComponent](feedback/ds-badge.md) — Content: label text. Use for status pills, counts, lifecycle markers.
27
+ - [<ds-status-dot> — StatusDotComponent](feedback/ds-status-dot.md) — Input: status: DsStatusKey (same consumer-registered vocabulary as ds-badge; colours wired via styles/status,
28
+ - [<ds-tag> — TagComponent](feedback/ds-tag.md) — Content: label.
29
+ - [<ds-avatar> — AvatarComponent](feedback/ds-avatar.md) — Inputs: size: 'xs' | 'sm' | 'md' | 'lg' = 'md', initials: string = '', imageUrl: string | null = null, tint: {
30
+ - [<ds-avatar-group> — AvatarGroupComponent](feedback/ds-avatar-group.md) — Content: project <ds-avatar> children.
31
+ - [<ds-progress> — ProgressComponent](feedback/ds-progress.md) — Linear progress bar (no circular variant).
32
+ - [<ds-spinner> — SpinnerComponent](feedback/ds-spinner.md) — Input: size: 'sm' | 'md' | 'lg' = 'md'. Pure-CSS spinner, role="status" with built-in aria-label.
33
+ - [<ds-skeleton> — SkeletonComponent](feedback/ds-skeleton.md) — Inputs: width?: string, height?: string, circle: boolean = false, inline: boolean = false. Shimmer animation r
34
+ - [<ds-stat> — StatComponent](feedback/ds-stat.md) — Delta direction is derived from the sign of delta: positive → up (arrow + green), negative → down (arrow + red
35
+ - [<ds-empty-state> — EmptyStateComponent](feedback/ds-empty-state.md) — Content slot: [actions] — CTA buttons / links.
36
+ - [<ds-banner> — BannerComponent](feedback/ds-banner.md) — - layout="stacked" (default): actions wrap onto a new line, indented under the body. Use for multi-line messag
37
+ - [<ds-alert> — AlertComponent](feedback/ds-alert.md) — Inline message, ds-banner's smaller twin — same anatomy, sized for placement inside a form or a card rather th
38
+ - [<ds-toast> — ToastComponent](feedback/ds-toast.md) — The companion <ds-toast-region> lives inside the ToastService (see Services) — it is auto-mounted via a CDK ov
39
+
40
+ ## forms
41
+
42
+ - [<ds-button> — ButtonComponent](forms/ds-button.md) — Axis meaning: **variant is loudness** (solid > tonal > outline/ghost/text), **color is hue** — every pair rend
43
+ - [<ds-icon-button> — IconButtonComponent](forms/ds-icon-button.md) — Icon-only action with its own taxonomy, distinct from ds-button. ariaLabel is required (icon-only must be labe
44
+ - [<ds-input> — InputComponent](forms/ds-input.md) — Content slots — addon attributes apply to any child element:
45
+ - [<ds-textarea> — TextareaComponent](forms/ds-textarea.md) — Multi-line counterpart to <ds-input> — same wrapper/states, reuses the --ds-input-* token family. No prefix/su
46
+ - [<ds-number-stepper> — NumberStepperComponent](forms/ds-number-stepper.md) — Spinbox for bounded quantities — −/+ buttons around a numeric value.
47
+ - [<ds-checkbox> — CheckboxComponent](forms/ds-checkbox.md) — Inputs: checked: model<boolean>, indeterminate: boolean = false, disabled: boolean = false, name: string | nul
48
+ - [<ds-radio> — RadioComponent](forms/ds-radio.md) — Inputs: checked: model<boolean>, disabled: boolean = false, name: string = '', value: string = '', inputId: st
49
+ - [<ds-switch> — SwitchComponent](forms/ds-switch.md) — Inputs: checked: model<boolean>, disabled: boolean = false, name: string | null = null, variant: 'default' | '
50
+ - [The picker family — <ds-select>, <ds-multi-select>, <ds-autocomplete>](forms/the-picker-family-ds-select-ds-multi-select-ds-autocomplete.md) — Five rules hold across all three: one meaning per member name, difference only where a reason is stated, one p
51
+ - [<ds-select> — SelectComponent](forms/ds-select.md) — Trigger plus a CDK overlay panel. Keyboard: ArrowUp/Down, Enter/Space, Home/End, Escape, skipping group header
52
+ - [<ds-multi-select> — MultiSelectComponent](forms/ds-multi-select.md) — Inputs: value: model<string[]>, options: readonly MultiSelectItem[], placeholder: string = 'Select…', searchPl
53
+ - [<ds-autocomplete> — AutocompleteComponent<T>](forms/ds-autocomplete.md) — Type-ahead picker, generic on the option value.
54
+ - [<ds-search> — SearchComponent](forms/ds-search.md) — Pre-styled search input with built-in icon. A form control, but not a field: no label, no message row.
55
+ - [<ds-date-picker> — DatePickerComponent](forms/ds-date-picker.md) — Trigger button opens a CDK overlay calendar; selecting a day in 'single' closes the panel, in 'range' it close
56
+ - [<ds-dropzone> — DropzoneComponent](forms/ds-dropzone.md) — File upload area.
57
+
58
+ ## navigation
59
+
60
+ - [<ds-sidenav> — SidenavComponent](navigation/ds-sidenav.md) — Content: default slot for groups/items + custom brand/footer rows
61
+ - [<ds-sidenav-group> — SidenavGroupComponent](navigation/ds-sidenav-group.md) — When expandable=true renders header button with toggle + caret; collapses body when not expanded.
62
+ - [<ds-sidenav-item> — SidenavItemComponent](navigation/ds-sidenav-item.md) — **Three elements, decided by destination.** routerLink → an <a [routerLink]> with routerLinkActive; href → a p
63
+ - [<ds-topbar> — TopBarComponent](navigation/ds-topbar.md) — No inputs.
64
+ - [<ds-app-layout> — AppLayoutComponent](navigation/ds-app-layout.md) — Reads: railId and the read-only railOverlay signal, for a consumer-built burger; dsRailTrigger wires one for y
65
+ - [<ds-auth-layout> — AuthLayoutComponent](navigation/ds-auth-layout.md) — landmark="main" only when the page has no other <main>; the sign-in card is not automatically the document's m
66
+ - [<ds-page-header> — PageHeaderComponent](navigation/ds-page-header.md) — Inputs: eyebrow: string = '', title: required string, subtitle: string = '', compact: boolean = false, divider
67
+ - [<ds-page-footer> — PageFooterComponent](navigation/ds-page-footer.md) — Content: default <ng-content>. Sticky footer bar pattern.
68
+ - [<ds-breadcrumbs> — BreadcrumbsComponent](navigation/ds-breadcrumbs.md) — Inputs: items: BreadcrumbItem[] | null = null ({ label?, href?, icon? } — when null/omitted, the component rea
69
+ - [<ds-tabs> + <ds-tab> — TabsComponent, TabComponent](navigation/ds-tabs.md) — Container holds <ds-tab label="…"> children.
70
+ - [<ds-stepper> — StepperComponent](navigation/ds-stepper.md) — Inputs: steps: readonly string[] = [], current: number = 0. Horizontal step indicator with done/active/upcomin
71
+ - [<ds-pagination> — PaginationComponent](navigation/ds-pagination.md) — Inputs: total: required number, pageSize: model<number> = 10, currentPage: model<number> = 1, pageSizeOptions:
72
+ - [<ds-divider> — DividerComponent](navigation/ds-divider.md) — Content: label text (when variant="label").
73
+
74
+ ## overlays
75
+
76
+ - [<ds-modal> — ModalComponent](overlays/ds-modal.md) — Inputs: open: model<boolean> = false, size: 'sm' | 'md' | 'lg' = 'md', danger: boolean = false, title: require
77
+ - [<ds-modal-card> — ModalCardComponent](overlays/ds-modal-card.md) — The visual card the <ds-modal> host renders inside its backdrop. Exposed as a separate selector for cases wher
78
+ - [<ds-drawer> — DrawerComponent](overlays/ds-drawer.md) — Side panel (no side input — always anchored right).
79
+ - [<ds-bottom-sheet> — BottomSheetComponent](overlays/ds-bottom-sheet.md) — Mobile-first panel anchored to the bottom edge (touch equivalent of drawer/modal). Drag-down on the grab strip
80
+ - [<ds-popover> — PopoverComponent](overlays/ds-popover.md) — Floating panel anchored to a trigger via CDK overlay. Input: align: 'start' | 'end' = 'start' — controls overl
81
+ - [[dsTooltip] — TooltipDirective](overlays/ds-tooltip.md) — Attribute directive. Apply to any focusable element.
82
+ - [<ds-menu> + <ds-menu-item> — MenuComponent, MenuItemComponent](overlays/ds-menu.md) — Menu is a container. Item inputs: icon: IconName | null = null, disabled: boolean = false, danger: boolean = f
83
+
84
+ ## platform
85
+
86
+ - [DS_ICON_REGISTRY / provideDsIcons(icons)](platform/ds-icon-registry.md) — Consumer apps can register additional icons without forking DS. Each entry maps a name to the raw SVG body — e
87
+ - [DS_CONFIG / provideDsConfig(config)](platform/ds-config.md) — Inject DS_CONFIG token (default factory returns {}) to set library-wide defaults that consumer-level component
88
+ - [BreadcrumbsService](platform/breadcrumbs-service.md) — @Injectable({ providedIn: 'root' }). Signal-based state primitive — apps push crumbs, <ds-breadcrumbs> reads f
89
+ - [ToastService](platform/toast-service.md) — @Injectable({ providedIn: 'root' }). Inject and call:
90
+
91
+ ## surfaces
92
+
93
+ - [<ds-card> — CardComponent](surfaces/ds-card.md) — Full-bleed child: a child whose background reaches the card edge paints square corners over the radius, and th
94
+ - [<ds-accordion> + <ds-accordion-item> — AccordionComponent, AccordionItemComponent](surfaces/ds-accordion.md) — Accordion is a thin wrapper that rounds + borders its children. Item inputs: title: string = '', expanded: mod
95
+
96
+ ## tables
97
+
98
+ - [<ds-table> — TableComponent<T extends { id: string }>](tables/ds-table.md) — Column shape: { key: string, label: string, sortable?: boolean, align?: 'left' | 'right' | 'center', cell?: (r
@@ -0,0 +1,10 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-w3w>` — `W3wComponent`
3
+
4
+ Group: Domain
5
+
6
+ What3Words address chip — branded display for `///word.word.word` addresses; click-to-copy.
7
+ Inputs: `address: required string`, `prefix: string = '///'`, `copyable: boolean = true`
8
+ Output: `(copied): string` — emits the raw `address` value after a copy attempt
9
+
10
+ ---
@@ -0,0 +1,9 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-alert>` — `AlertComponent`
3
+
4
+ Group: Display & feedback
5
+
6
+ Inline message, `ds-banner`'s smaller twin — same anatomy, sized for placement inside a form or a card rather than across a page.
7
+ Inputs: `variant: 'info' | 'success' | 'warning' | 'error' | 'neutral' = 'info'`, `title: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null` (variant-derived default)
8
+ Output: `(closed): void`
9
+ Content slots: default (body text), `[actions]` (trailing CTAs)
@@ -0,0 +1,7 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-avatar-group>` — `AvatarGroupComponent`
3
+
4
+ Group: Display & feedback
5
+
6
+ Inputs: `max: number = 4` (visible avatars before "+N" overflow), `total: number | null = null` (used to compute the overflow count; without `total` no overflow chip renders).
7
+ Content: project `<ds-avatar>` children.
@@ -0,0 +1,6 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-avatar>` — `AvatarComponent`
3
+
4
+ Group: Display & feedback
5
+
6
+ Inputs: `size: 'xs' | 'sm' | 'md' | 'lg' = 'md'`, `initials: string = ''`, `imageUrl: string | null = null`, `tint: { bg, fg } | 'neutral' | null = null` (off-token override; `'neutral'` swaps to the overflow-chip palette)
@@ -0,0 +1,7 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-badge>` — `BadgeComponent`
3
+
4
+ Group: Display & feedback
5
+
6
+ Inputs: `status: DsStatusKey` (consumer-registered status key; colours wired via `styles/status`, unset → neutral), `withDot: boolean = false`, `solid: boolean = false`, `count: number | null = null`, `max: number = 99`
7
+ Content: label text. Use for status pills, counts, lifecycle markers.
@@ -0,0 +1,10 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-banner>` — `BannerComponent`
3
+
4
+ Group: Display & feedback
5
+
6
+ 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`
7
+ Output: `(closed): void`
8
+ Content slots: default (body text), `[actions]` (trailing CTAs)
9
+ - `layout="stacked"` (default): actions wrap onto a new line, indented under the body. Use for multi-line messages or multiple CTAs.
10
+ - `layout="row"`: actions sit at the right edge, vertically centred with the body. Use for one-line messages with a single trailing CTA.
@@ -0,0 +1,7 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-empty-state>` — `EmptyStateComponent`
3
+
4
+ Group: Display & feedback
5
+
6
+ Inputs: `variant: 'none' | 'loading' | 'error' | 'locked' = 'none'`, `icon: IconName | null = null` (defaults derive from variant — `warn` for error, `lock` for locked, `package` otherwise), `title: string = ''`, `body: string = ''`
7
+ Content slot: `[actions]` — CTA buttons / links.
@@ -0,0 +1,7 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-progress>` — `ProgressComponent`
3
+
4
+ Group: Display & feedback
5
+
6
+ Linear progress bar (no circular variant).
7
+ Inputs: `value: number = 0` (0–100, clamped), `variant: 'default' | 'success' | 'warn' | 'error' | 'indeterminate' = 'default'`
@@ -0,0 +1,6 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-skeleton>` — `SkeletonComponent`
3
+
4
+ Group: Display & feedback
5
+
6
+ Inputs: `width?: string`, `height?: string`, `circle: boolean = false`, `inline: boolean = false`. Shimmer animation requires the global `_skeleton-shimmer.scss` (already pulled in by `ds.scss`).
@@ -0,0 +1,6 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-spinner>` — `SpinnerComponent`
3
+
4
+ Group: Display & feedback
5
+
6
+ Input: `size: 'sm' | 'md' | 'lg' = 'md'`. Pure-CSS spinner, `role="status"` with built-in `aria-label`.
@@ -0,0 +1,7 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-stat>` — `StatComponent`
3
+
4
+ Group: Display & feedback
5
+
6
+ Inputs: `label: required string`, `value: required string | number`, `delta: number | null = null`, `deltaLabel: string = ''`, `caption: string = ''`, `unit: string = ''`, `variant: 'default' | 'danger' = 'default'`
7
+ Delta direction is derived from the sign of `delta`: positive → up (arrow + green), negative → down (arrow + red), zero/null → neutral.
@@ -0,0 +1,6 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-status-dot>` — `StatusDotComponent`
3
+
4
+ Group: Display & feedback
5
+
6
+ Input: `status: DsStatusKey` (same consumer-registered vocabulary as `ds-badge`; colours wired via `styles/status`, unset → neutral). Tiny coloured dot.
@@ -0,0 +1,8 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-tag>` — `TagComponent`
3
+
4
+ Group: Display & feedback
5
+
6
+ Inputs: `variant: 'solid' | 'neutral' = 'solid'`, `closable: boolean = false`
7
+ Output: `(closed): void` — emits when the close button is pressed
8
+ Content: label.
@@ -0,0 +1,12 @@
1
+ <!-- GENERATED by tools/split-agent-catalogue.mjs from components.md. Do not edit. -->
2
+ # `<ds-toast>` — `ToastComponent`
3
+
4
+ Group: Display & feedback
5
+
6
+ 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)
7
+ Output: `(closed): void`
8
+ 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.
9
+
10
+ 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.
11
+
12
+ ---