@ids-group-ltd/ids-design-system 0.8.0 → 0.9.1

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.
package/components.md ADDED
@@ -0,0 +1,500 @@
1
+ # DS Component Catalogue
2
+
3
+ > Index of the design system components, global helpers, tokens and icons. Use it as a single reference when migrating UI to DS.
4
+ >
5
+ > **This file is the WHAT — the inventory.** For the HOW (which spacing between what,
6
+ > which type role where, how a page is composed) see `design-system.md`, which carries
7
+ > the rules this catalogue deliberately does not.
8
+ >
9
+ > **Where it overlaps with generated output:** ds-docs extracts a Component API table and
10
+ > a token reference from source on every build, and those cannot go stale. Where this file
11
+ > and ds-docs disagree, ds-docs is right — prefer it for exact inputs and token names, and
12
+ > use this catalogue for orientation. Each entry shows the selector, the key inputs/outputs/slots, and the public CSS custom properties that consumers can override.
13
+ >
14
+ > **Import path:** `import { ButtonComponent, … } from 'ds'` (the library publishes as `ds`; consumer apps add a `paths` mapping in their `tsconfig.json` or install the built `dist/ds` package).
15
+ >
16
+ > **Templating note:** every component is standalone with `ViewEncapsulation.Emulated`. Pass classes on the host element to scope local tweaks; override DS tokens at the host level (`ds-xxx { --ds-xxx-…: … }`) — defaults are declared on `:host` (or the root class) so consumer overrides cascade in.
17
+
18
+ ---
19
+
20
+ ## Foundations
21
+
22
+ ### Tokens (Tier 2 — semantic roles)
23
+
24
+ Loaded via `@use 'styles/tokens';` (when the consumer also `@use 'styles/ds';` the full aggregate is pulled in). Brand themes override Tier 1 palette + a few Tier 2 roles in their own `_brand-*.scss`.
25
+
26
+ **Colour roles:**
27
+ - Surfaces: `--surface-canvas`, `--surface-default`, `--surface-secondary`, `--surface-overlay`, `--surface-tint`, `--surface-disabled`, `--surface-muted`, `--surface-inverted`, `--surface-inverted-hover`, `--surface-scrim`
28
+ - Borders: `--border-default`, `--border-strong`, `--border-subtle`, `--border-divider`, `--border-disabled`, `--border-inverted`
29
+ - Text: `--text-primary`, `--text-secondary`, `--text-tertiary`, `--text-muted`, `--text-disabled`, `--text-inverted`, `--text-link`, `--text-on-primary`, `--text-on-success`, `--text-on-error`
30
+ - Icons: `--icon-default`, `--icon-strong`, `--icon-muted`, `--icon-on-primary`
31
+ - Primary (main brand fill): `--primary`, `--primary-hover`, `--primary-pressed`, `--primary-selected-hover`, `--primary-strong`, `--primary-subtle`, `--primary-muted`, `--primary-muted-strong`, `--primary-on` + HSL channels `--primary-h/s/l`
32
+ - Secondary (paired CTAs, accent rails, opt-in variants): `--secondary`, `--secondary-hover`, `--secondary-pressed`, `--secondary-strong`, `--secondary-subtle`, `--secondary-muted`, `--secondary-on` + HSL channels `--secondary-h/s/l`
33
+ - Tertiary (third brand hue — tertiary button, tonal chips, indicators): `--tertiary`, `--tertiary-hover`, `--tertiary-pressed`, `--tertiary-strong`, `--tertiary-subtle`, `--tertiary-muted`, `--tertiary-on` + HSL channels `--tertiary-h/s/l`
34
+ - Error (destructive, was --danger): `--error`, `--error-hover`, `--error-pressed`, `--error-subtle`, `--error-muted`, `--error-border`, `--error-text` + HSL channels `--error-h/s/l`
35
+ - Status: `--success`, `--success-hover`, `--success-subtle`, `--success-muted`, `--success-border`, `--success-text`
36
+ - Status (warning/info): same shape with prefix swapped
37
+ - Status pills: the DS ships no predefined status keys — consumers register their own vocabulary (e.g. `planning`, `confirmed`) and wire colours per key via `@use 'styles/status'` (`status.define(...)` / `status.semantic-preset`), which sets `--ds-badge-bg-color` / `--ds-badge-label-color` / `--ds-status-dot-color` per `[data-status]`. Full guide (model, worked example, migration from factory statuses): [`migrations/0.5.1/badge-statuses.md`](migrations/0.5.1/badge-statuses.md)
38
+
39
+ **Geometry:**
40
+ - Spacing: `--space-0`, `--space-px`, `--space-0-5` (2px), `--space-1` (4px), `--space-1-5` (6px), `--space-2` (8px), `--space-2-5` (10px), `--space-3` (12px), `--space-4` (16px), `--space-5` (20px), `--space-6` (24px), `--space-8` (32px), `--space-10` (40px), `--space-12` (48px), `--space-14` (56px), `--space-16` (64px), `--space-20` (80px), `--space-24` (96px), `--space-32` (128px)
41
+ - Radius: `--radius-0`, `--radius-sm` (4px), `--radius-md` (8px), `--radius-lg` (12px), `--radius-2xl` (24px), `--radius-pill` (999px), `--radius-pill-value`, `--radius-flat`
42
+ - Border widths: `--border-width-default` (1px), `--border-width-strong` (2px)
43
+ - Hit targets: `--hit-xs` (24), `--hit-sm` (28), `--hit-md` (36), `--hit-min` (32), `--hit-cozy` (40), `--hit-comfy` (44), `--hit-touch` (48)
44
+ - Icon sizes: `--icon-2xs` (10), `--icon-xs` (12), `--icon-sm` (14), `--icon-md` (16), `--icon-lg` (20)
45
+
46
+ **Typography:**
47
+ - Families: `--font-sans`, `--font-mono`, `--font-display`, `--font-heading`
48
+ - Weights: `--font-weight-regular` 400, `--font-weight-medium` 500, `--font-weight-semibold` 600, `--font-weight-bold` 700, `--font-weight-extrabold` 800 (overridden to 700 in brand-mm)
49
+ - Sizes: `--font-size-display` 64, `--font-size-h1` 48, `--font-size-h2` 36, `--font-size-h3` 28, `--font-size-h4` 22, `--font-size-h5` 18, `--font-size-h5-strong` 20, `--font-size-l` 18, `--font-size-m` 16, `--font-size-s` 14, `--font-size-xs` 12, `--font-size-2xs` 11, `--font-size-3xs` 10, `--font-size-4xs` 9, `--font-size-mono` 13
50
+ - Line heights: `--line-height-tight` 1.1, `--line-height-snug` 1.25, `--line-height-base` 1.4, `--line-height-loose` 1.6, `--line-height-flat` 1
51
+ - Letter spacing: `--letter-spacing-tight`, `--letter-spacing-snug`, `--letter-spacing-normal`, `--letter-spacing-wide`, `--letter-spacing-wider`
52
+
53
+ **Motion:**
54
+ - Durations: `--duration-instant` 80ms, `--duration-fast` 120ms, `--duration-base` 180ms, `--duration-slow` 260ms, `--duration-slower` 400ms
55
+ - Loop: `--duration-loop-fast` 700ms, `--duration-loop-slow` 1400ms
56
+ - Easing: `--ease-standard`, `--ease-emphasized`, `--ease-decelerate`, `--ease-accelerate`, `--ease-spring`
57
+
58
+ **Elevation:**
59
+ - `--z100/200/300/400` (raw), `--shadow-popover`, `--shadow-modal`, `--shadow-toast`, `--shadow-card`
60
+ - `--blur-sm`, `--blur-md`
61
+
62
+ **Z-index:**
63
+ - `--layer-base`, `--layer-raised`, `--layer-sticky`, `--layer-dropdown`, `--layer-overlay`, `--layer-drawer`, `--layer-modal`, `--layer-popover`, `--layer-toast`, `--layer-tooltip`
64
+
65
+ **Focus rings:** `--focus-ring`, `--focus-ring-inverted`, `--focus-ring-error`, `--focus-field`, `--focus-field-error`
66
+
67
+ ---
68
+
69
+ ### Grid
70
+
71
+ Responsive 4-tier page grid loaded via `@use 'styles/ds'` (or directly via `@use '../../ds/src/lib/styles/page-grid';`). One column-count per breakpoint, gutters and margins scale with the viewport, container caps on the widest tier and stays fluid below.
72
+
73
+ | Tier | Range | Cols | Gutter | Margin | Container cap |
74
+ | ------------ | ------------- | ---- | ------------- | -------------- | ------------------------ |
75
+ | Mobile | ≤ 640px | 4 | `--space-3` (12) | `--space-4` (16) | fluid |
76
+ | Tablet | 641 – 1024px | 8 | `--space-4` (16) | `--space-6` (24) | fluid |
77
+ | Desktop | 1025 – 1440px | 12 | `--space-5` (20) | `--space-8` (32) | fluid |
78
+ | Desktop wide | ≥ 1441px | 12 | `--space-6` (24) | `--space-10` (40) | `--col-cap-content` 1280 |
79
+
80
+ **Tokens:** `--bp-xs` 480, `--bp-sm` 640, `--bp-md` 768, `--bp-lg` 1024, `--bp-xl` 1441, `--bp-2xl` 1536. Per-tier gutters/margins live as `--page-gutter-{mobile|tablet|desktop|wide}` and `--page-margin-{mobile|tablet|desktop|wide}`; the active values resolve through `--page-gutter` / `--page-margin` on `.page-grid`. Content caps: `--col-cap-text` 720, `--col-cap-content` 1280.
81
+
82
+ **Class API:**
83
+ - `.page-grid` — root grid container. Sets `display: grid`, tier-appropriate `grid-template-columns`, `gap`, horizontal `padding`, and `max-width: var(--col-cap-content)` with `margin: 0 auto` for centring at the widest tier.
84
+ - `.col-span-1` … `.col-span-12` — span helpers. At narrower tiers (8 / 4 cols), a span wider than the active column-count wraps to its own row.
85
+
86
+ **Composition rules:**
87
+ - One grid per page. Sub-regions align to the same column tracks — never invent a local grid.
88
+ - Snap to columns, not pixels. Canonical two-column splits: 8+4, 6+6, 9+3. Never 7+5.
89
+ - Sidenav lives OUTSIDE the grid. Reserve its rail (collapsed 64px / open 240px via `--sidenav-w` / `--sidenav-w-collapsed`), then start `.page-grid` in the remaining width.
90
+ - Prose caps at 720px via `--col-cap-text` regardless of grid width.
91
+ - 8+4 is canonical for record-detail pages (main + meta sidebar); 9+3 is reserved for kit / track-plan picker rails.
92
+
93
+ **Markup example:**
94
+
95
+ ```html
96
+ <main class="page-grid">
97
+ <section class="col-span-8">Main content</section>
98
+ <aside class="col-span-4">Meta sidebar</aside>
99
+ </main>
100
+ ```
101
+
102
+ ---
103
+
104
+ ### Global helper classes
105
+
106
+ The DS aggregate (`@use 'styles/ds'`) forwards the full stack: theme primitives + tokens + tokens-charts + fonts + reset + typography + link + layout-utils + page-grid + scrollbar + icon-base + dropdown-overlay + skeleton-shimmer. Consumers that only `@use 'styles/tokens'` get pure tokens — **no** font faces, `.link`, typography utilities, `.grid-*`, `.page-grid` / `.col-span-*`, or the dropdown/skeleton overlay rules — load each partial explicitly (`@use 'styles/fonts'; @use 'styles/link';` …) or switch to the aggregate.
107
+
108
+ - `.link` — anchor styling, declared in `_link.scss`. Modifiers: `.quiet` `.inline` `.standalone` `.xs` `.sm` `.lg`. Hover→`color-mix(text-link, black 20%)`, active→`color-mix(text-link, black 35%)`, disabled via `[aria-disabled="true"]`. Loaded via `@use 'styles/link'` (included in the `@use 'styles/ds'` aggregate).
109
+ - Typography utilities (`_typography.scss`): `.t-display`, `.t-h1`, `.t-h2`, `.t-h3`, `.t-h4`, `.t-h5`, `.t-l`, `.t-l-bold`, `.t-m`, `.t-m-bold`, `.t-s`, `.t-s-bold`, `.t-xs`, `.t-xs-bold`, `.t-overline`, `.t-caption`, `.t-mono`, `.t-mono-block`, `.sr-only`
110
+ - Layout (`_layout-utils.scss`): `.grid-2`, `.grid-3`, `.grid-4`. Breakpoints: at ≤1100px `.grid-4` drops to 3 columns; at ≤820px both `.grid-3` and `.grid-4` drop to 2 columns. Gap is `--space-4`.
111
+ - Page grid (`_page-grid.scss`): `.page-grid` + `.col-span-1` … `.col-span-12`. 4-tier responsive grid (4 / 8 / 12 / 12 columns); see Foundations → Grid above for the full spec.
112
+ - Skeleton shimmer (`_skeleton-shimmer.scss`): drives the global `--skeleton-shimmer-x` keyframe used by `<ds-skeleton>` and table skeleton rows.
113
+ - Dropdown overlay (`_dropdown-overlay.scss`): styles the `.ds-dropdown-panel` class used by select/dropdown/combobox/date-picker CDK portals — these panels live outside the host's encapsulated tree, so the styles must be global.
114
+
115
+ ---
116
+
117
+ ## Components
118
+
119
+ Every entry below names its exported class (`ButtonComponent`, `TableComponent<T>`, …). Those names are exported for typing, DI, `viewChild` and template refs — **not as an extension point: subclassing a DS component is unsupported.** Any minor release may add members to a class, and a subclass that happens to have used one of those names breaks on it (TS4114 "must have an 'override' modifier", or TS2416 when the signature differs) — DS 0.6.3 added ~76 members to `TableComponent` alone. Compose instead: wrap the component, project into its slots, retune it through its `--ds-*` tokens. If you subclass anyway, treat every upgrade as potentially build-breaking — the changelog flags the risk (see `migrations/AUTHORING.md`), it does not avoid it.
120
+
121
+ **The `--ds-*` token contract, once for every component below.** Every public `--ds-<component>-*` token is READ WITH A FALLBACK and never declared by the component, so a consumer's value always wins and always inherits: set it on the host (`ds-button { --ds-button-bg-color: teal }`), on any ancestor, at `:root`, or inline. Unset tokens fall through to the component's own default, so there is nothing to opt into and nothing to reset. Two consequences worth stating: a token set at `:root` reaches EVERY instance — scope per instance or per section and keep theme-wide re-skins at role level (`--primary`, `--ds-radius-control`) — and where a component derives one value from another (a hover fill mixed from the resolved background), overriding the source retunes the derived states with it. Individual entries below therefore note only what DEVIATES from this: a derived state, a variant-specific default, a token that beats a size class.
122
+
123
+ > **Token and API lists below are hand-maintained and have drifted.** `ds-button` in particular is documented here with its pre-`color`×`variant` API and the pre-rename token names (`--ds-button-bg`, `-fg`), neither of which is current. The authoritative, auto-generated surfaces are the **Component API tables** and the **token reference** in `ds-docs` (extracted from source on every build, so they cannot go stale) — trust those first, and treat this file as prose about intent. Re-verified 2026-08-05; the sweep to reconcile it is tracked in `docs/todo.md`.
124
+
125
+ ### Form & input
126
+
127
+ #### `<ds-button>` — `ButtonComponent`
128
+ Inputs: `variant: ButtonVariant = 'primary'` (`'primary' | 'secondary' | 'tertiary' | 'outline' | 'error' | 'success' | 'warning' | 'text'`), `size: ButtonSize = 'l'` (`'s' | 'm' | 'l' | 'sm' | 'md' | 'lg'` — legacy s/m/l = 24/32/40, canonical sm/md/lg = 32/40/48), `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled: boolean = false`, `loading: boolean = false`, `fullWidth: boolean = false` (stretches the host to `display: block; width: 100%` — for mobile primary CTAs and full-bleed submits)
129
+ Variant → role mapping: `primary` → `--primary` fill · `secondary` → `--primary-muted` tonal fill · `tertiary` → transparent with `--primary-strong` text · `outline` → bordered neutral surface · `error/success/warning` → status fills · `text` → no-chrome text button. (Renamed 2026-06 from danger→error, link→text, ghost→outline.)
130
+ Output: `(pressed): MouseEvent` — only fires when not disabled and not loading
131
+ Content slots: default (label / leading or trailing icon). For icon-only actions use `<ds-icon-button>`.
132
+ Tokens: `--ds-button-bg`, `--ds-button-bg-hover`, `--ds-button-bg-active`, `--ds-button-bg-disabled`, `--ds-button-fg`, `--ds-button-fg-disabled`, `--ds-button-border`, `--ds-button-radius`, `--ds-button-focus-shadow`, `--ds-button-pressed-shadow`. For solid variants (primary/error/success/warning), `-bg-hover` / `-bg-active` / `-pressed-shadow` default to a `color-mix()` derivation from the resolved `-bg` (88 % / 76 % + black — the theme's hover/pressed recipe), so overriding the bg alone retints the full state set; tonal variants (secondary/tertiary/outline/text) keep explicit ramp defaults, so a full retint there means also setting the state tokens.
133
+
134
+ #### `<ds-icon-button>` — `IconButtonComponent`
135
+ Icon-only action with its own taxonomy, distinct from `ds-button`. `ariaLabel` is required (icon-only must be labelled for a11y).
136
+ Inputs: `icon: required IconName`, `ariaLabel: required string`, `variant: IconButtonVariant = 'standard'` (`'standard' | 'filled' | 'tonal' | 'outlined'`), `size: IconButtonSize = 'md'` (`'sm' | 'md' | 'lg'` = 32/40/48), `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled: boolean = false`, `selected: boolean = false` (toggle — sets `aria-pressed`)
137
+ Output: `(pressed): MouseEvent` — fires when not disabled
138
+ Variant emphasis: `standard` chromeless (hover-reveal) · `filled` `--primary` · `tonal` `--primary-muted` · `outlined` bordered. `selected` renders the pressed/active fill.
139
+ Tokens: `--ds-icon-button-bg`, `--ds-icon-button-fg`, `--ds-icon-button-border`, `--ds-icon-button-bg-hover`, `--ds-icon-button-bg-active`, `--ds-icon-button-fg-hover`, `--ds-icon-button-radius`, `--ds-icon-button-focus-shadow`. `filled`/`selected` derive hover/active from the resolved bg, `standard`/`tonal`/`outlined` keep explicit ramp defaults.
140
+
141
+ #### `<ds-input>` — `InputComponent`
142
+ Inputs: `value: model<string>`, `type: InputType = 'text'` (`'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search'`), `size: 'sm' | 'md' | 'lg' = 'md'`, `label: string = ''`, `hint: string = ''`, `placeholder: string = ''`, `disabled: boolean = false`, `invalid: boolean = false`, `required: boolean = false`, `optional: boolean = false`, `name: string | null = null`, `clearable: boolean | null = null` (inline clear (×) button; `null` resolves to `true` for `type="search"` and `false` otherwise)
143
+ Content slots — addon attributes apply to any child element:
144
+ - `[dsInputPrefix]` — leading content (icon, label, etc.)
145
+ - `[dsInputSuffix]` — trailing content (icon button, label, etc.)
146
+ - `class="addon"` — heavyweight slot pill with its own background + divider (use for textual `https://` style prefixes; for icons, prefer plain `dsInputPrefix`)
147
+
148
+ Example:
149
+ ```html
150
+ <ds-input label="Email" type="email" [(value)]="email">
151
+ <ds-icon dsInputPrefix name="mail" [size]="16"/>
152
+ <button dsInputSuffix type="button" (click)="reveal()">
153
+ <ds-icon name="eye-off" [size]="16"/>
154
+ </button>
155
+ </ds-input>
156
+ ```
157
+
158
+ Tokens: `--ds-input-bg`, `--ds-input-border`, `--ds-input-border-hover`, `--ds-input-border-focus`, `--ds-input-fg`, `--ds-input-placeholder`, `--ds-input-radius`, `--ds-input-pad-x`, `--ds-input-pad-y`, `--ds-input-focus-shadow`, `--ds-input-border-error`, `--ds-input-bg-error`, `--ds-input-border-success`, `--ds-input-bg-disabled`
159
+
160
+ #### `<ds-textarea>` — `TextareaComponent`
161
+ Multi-line counterpart to `<ds-input>` — same wrapper/states, reuses the `--ds-input-*` token family. No prefix/suffix slots.
162
+ Inputs: `value: model<string>`, `size: 'sm' | 'md' | 'lg' = 'md'`, `label`, `hint`, `placeholder`, `disabled`, `invalid`, `required`, `optional: boolean = false`, `name`, `rows: number = 3`
163
+ Tokens: same `--ds-input-*` family as `<ds-input>` (textarea overrides `--ds-input-pad-y` to `--space-3` for vertical breathing room).
164
+ New: `autosize: boolean = false` (grows with content; forces `resize='none'`), `minRows`/`maxRows: number | null = null`, `resize: 'none' | 'vertical' | 'horizontal' | 'both' = 'vertical'`.
165
+
166
+ #### `<ds-number-stepper>` — `NumberStepperComponent`
167
+ Spinbox for bounded quantities — −/+ buttons around a numeric value.
168
+ Inputs: `value: model<number> = 0`, `min: number = 0`, `max: number | null = null`, `step: number = 1`, `size: 'sm' | 'md' | 'lg' = 'md'`, `disabled: boolean = false`
169
+ Methods: `inc()`, `dec()` (clamp to min/max). Buttons disable at the bounds.
170
+
171
+ #### `<ds-checkbox>` — `CheckboxComponent`
172
+ Inputs: `checked: model<boolean>`, `indeterminate: boolean = false`, `disabled: boolean = false`, `name: string | null = null`, `inputId: string | null = null`
173
+
174
+ #### `<ds-radio>` — `RadioComponent`
175
+ Inputs: `checked: model<boolean>`, `disabled: boolean = false`, `name: string = ''`, `value: string = ''`, `inputId: string | null = null`. Use in groups via shared `name`.
176
+
177
+ #### `<ds-switch>` — `SwitchComponent`
178
+ Inputs: `checked: model<boolean>`, `disabled: boolean = false`, `name: string | null = null`, `variant: 'default' | 'success' | 'error' = 'default'`, `inputId: string | null = null`
179
+
180
+ #### `<ds-select>` — `SelectComponent`
181
+ Inputs: `value: model<string>`, `options: SelectItem[]` (`SelectOption | SelectOptionGroup`, where `SelectOption = { label, value, disabled? }` and `SelectOptionGroup = { label, options: SelectOption[], disabled? }`), `placeholder: string = ''`, `size: 'sm' | 'md' | 'lg' = 'md'`, `label: string = ''`, `disabled: boolean = false`, `invalid: boolean = false`, `required: boolean = false`, `optional: boolean = false`, `name: string | null = null`
182
+ Renders trigger + CDK overlay panel; keyboard support: ArrowUp/Down, Enter/Space, Home/End, Escape — skipping group-header labels. Pass a mix of flat `SelectOption`s and `SelectOptionGroup`s to render `<optgroup>`-style sections; existing flat-list consumers keep working unchanged. Type guard `isSelectOptionGroup(item)` is re-exported.
183
+
184
+ #### `<ds-combobox>` — `ComboboxComponent<T>`
185
+ Searchable select with typeahead. Generic on the option value type `T`.
186
+ Inputs: `options: readonly ComboboxOption<T>[]` (`{ value: T, label: string }`), `value: model<T | readonly T[] | null>`, `multiple: boolean = false`, `placeholder: string = 'Select…'`
187
+ In multi mode, selected values render as `<ds-tag closable>` chips above the trigger.
188
+
189
+ #### `<ds-search>` — `SearchComponent`
190
+ Pre-styled search input with built-in icon.
191
+ Inputs: `value: model<string>`, `placeholder: string = 'Search'`, `shortcut: string = ''` (rendered as a hint pill, e.g. `⌘K`), `showIcon: boolean = true`
192
+ Output: `(submitted): string` — emits the current value on Enter / form submit
193
+
194
+ #### `<ds-date-picker>` — `DatePickerComponent`
195
+ Inputs: `mode: 'single' | 'range' = 'single'`, `size: 'sm' | 'md' | 'lg' = 'md'`, `value: model<Date | RangeValue | null>` (`RangeValue = [Date | null, Date | null]`), `placeholder: string = 'Select date'`, `label: string = ''`, `hint: string = ''`, `required: boolean = false`, `optional: boolean = false`
196
+ Trigger button opens a CDK overlay calendar; selecting a day in `'single'` closes the panel, in `'range'` it closes after the second pick.
197
+
198
+ #### `<ds-dropzone>` — `DropzoneComponent`
199
+ File upload area.
200
+ Inputs: `accept: string = ''`, `multiple: boolean = false`, `files: model<DropzoneFile[]>` (`{ id, name, size, state: 'uploading' | 'success' | 'error', progress }`)
201
+ Outputs: `(filesAdded): File[]` (raw browser File list from drop or picker), `(fileRemoved): DropzoneFile` (a chip's remove button)
202
+
203
+ ---
204
+
205
+ ### Display & feedback
206
+
207
+ #### `<ds-badge>` — `BadgeComponent`
208
+ 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`
209
+ Content: label text. Use for status pills, counts, lifecycle markers.
210
+
211
+ #### `<ds-status-dot>` — `StatusDotComponent`
212
+ Input: `status: DsStatusKey` (same consumer-registered vocabulary as `ds-badge`; colours wired via `styles/status`, unset → neutral). Tiny coloured dot.
213
+
214
+ #### `<ds-tag>` — `TagComponent`
215
+ Inputs: `variant: 'solid' | 'neutral' = 'solid'`, `closable: boolean = false`
216
+ Output: `(closed): void` — emits when the close button is pressed
217
+ Content: label.
218
+
219
+ #### `<ds-avatar>` — `AvatarComponent`
220
+ 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)
221
+
222
+ #### `<ds-avatar-group>` — `AvatarGroupComponent`
223
+ 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).
224
+ Content: project `<ds-avatar>` children.
225
+
226
+ #### `<ds-progress>` — `ProgressComponent`
227
+ Linear progress bar (no circular variant).
228
+ Inputs: `value: number = 0` (0–100, clamped), `variant: 'default' | 'success' | 'warn' | 'error' | 'indeterminate' = 'default'`
229
+
230
+ #### `<ds-spinner>` — `SpinnerComponent`
231
+ Input: `size: 'sm' | 'md' | 'lg' = 'md'`. Pure-CSS spinner, `role="status"` with built-in `aria-label`.
232
+
233
+ #### `<ds-skeleton>` — `SkeletonComponent`
234
+ 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`).
235
+
236
+ #### `<ds-stat>` — `StatComponent`
237
+ Inputs: `label: required string`, `value: required string | number`, `delta: number | null = null`, `deltaLabel: string = ''`, `caption: string = ''`, `unit: string = ''`, `variant: 'default' | 'danger' = 'default'`
238
+ Delta direction is derived from the sign of `delta`: positive → up (arrow + green), negative → down (arrow + red), zero/null → neutral.
239
+
240
+ #### `<ds-empty-state>` — `EmptyStateComponent`
241
+ 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 = ''`
242
+ Content slot: `[actions]` — CTA buttons / links.
243
+
244
+ #### `<ds-banner>` — `BannerComponent`
245
+ 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`
246
+ Output: `(dismissed): void`
247
+ Content slots: default (body text), `[actions]` (trailing CTAs)
248
+ - `layout="stacked"` (default): actions wrap onto a new line, indented under the body. Use for multi-line messages or multiple CTAs.
249
+ - `layout="row"`: actions sit at the right edge, vertically centred with the body. Use for one-line messages with a single trailing CTA.
250
+
251
+ #### `<ds-toast>` — `ToastComponent`
252
+ Inputs: `variant: 'info' | 'success' | 'warning' | 'error' = 'info'`, `title: string = ''`, `message: string = ''`, `dismissible: boolean = false`, `icon: IconName | null = null` (variant-derived default)
253
+ Output: `(dismissed): void`
254
+
255
+ 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.
256
+
257
+ ---
258
+
259
+ ### Layout & navigation
260
+
261
+ #### `<ds-sidenav>` — `SidenavComponent`
262
+ Inputs: `collapsed: boolean = false`, `brand: string = ''` (renders a letter mark + name; omit to project custom content)
263
+ Content: default slot for groups/items + custom brand/footer rows
264
+ Tokens: `--ds-sidenav-bg`, `--ds-sidenav-border`, `--ds-sidenav-width`, `--ds-sidenav-width-collapsed`, `--ds-sidenav-mark-bg`, `--ds-sidenav-mark-fg`
265
+
266
+ #### `<ds-sidenav-group>` — `SidenavGroupComponent`
267
+ Inputs: `label: string = ''`, `icon: IconName | null = null`, `expandable: boolean = false`, `expanded: model<boolean> = true`
268
+ Content slots: default (items); `[ds-group-icon]` (custom group icon when not using a DS IconName)
269
+ When `expandable=true` renders header button with toggle + caret; collapses body when not expanded.
270
+
271
+ #### `<ds-sidenav-item>` — `SidenavItemComponent`
272
+ Inputs: `icon: IconName | null = null` (optional — falls back to `[icon]` slot), `label: required string`, `href: string = ''`, `routerLink: string | readonly unknown[] | null = null`, `active: boolean = false`, `badge: number | null = null`, `hasAlert: boolean = false`
273
+ Content slots: `[icon]` (custom icon when not using a DS IconName), `[trailing]` (right-aligned chrome — badges, indicators, kbd shortcuts)
274
+ Tokens (on `:host`): `--ds-sidenav-item-fg`, `--ds-sidenav-item-fg-hover`, `--ds-sidenav-item-bg-hover`, `--ds-sidenav-item-bg-active` (default: `--primary`), `--ds-sidenav-item-fg-active` (default: `--text-on-primary`), `--ds-sidenav-item-rail` (left rail, default: `--secondary`), `--ds-sidenav-item-radius`, `--ds-sidenav-alert-color`
275
+
276
+ #### `<ds-topbar>` — `TopBarComponent`
277
+ No inputs.
278
+ Content slots: `[title]`, `[breadcrumbs]`, `[search]`, `[actions]`. Sits at `--topbar-h` height.
279
+ Tokens (on `:host`): `--ds-topbar-margin-b` (default `--space-4` = 16px) — bottom gap to the next content block. The topbar owns this gap globally; pages MUST NOT add their own `padding-top` to compensate.
280
+
281
+ #### `<ds-page-header>` — `PageHeaderComponent`
282
+ Inputs: `eyebrow: string = ''`, `title: required string`, `subtitle: string = ''`, `compact: boolean = false`, `divider: boolean = false`, `metaDivider: boolean = false`
283
+ Content slots: `[breadcrumbs]`, `[title-badge]` (sits next to the title text), `[actions]` (right edge of title row), `[meta]` (under the title row), `[tabs]` (under the meta row)
284
+ Tokens: `--ds-pagehdr-eyebrow-fg`, `--ds-pagehdr-title-fg`, `--ds-pagehdr-subtitle-fg`, `--ds-pagehdr-meta-fg`, `--ds-pagehdr-meta-icon-fg`, `--ds-pagehdr-divider`, `--ds-pagehdr-title-fs` (default `--font-size-h3`; `compact` flips to `--font-size-h4`). The page-header does NOT own its bottom gap — the parent page `:host` owns spacing via `display: flex; flex-direction: column; gap: var(--space-4)`.
285
+
286
+ #### `<ds-page-footer>` — `PageFooterComponent`
287
+ Input: `variant: 'default' | 'compact' | 'save' = 'default'`
288
+ Content: default `<ng-content>`. Sticky footer bar pattern.
289
+
290
+ #### `<ds-breadcrumbs>` — `BreadcrumbsComponent`
291
+ Inputs: `items: BreadcrumbItem[] | null = null` (`{ label?, href?, icon? }` — when `null`/omitted, the component reads from `BreadcrumbsService.items` so route-driven flows work without a per-page `[items]` binding), `separator: IconName | null = null` (overrides `DsConfig.breadcrumbs.separator`, falls back to `'chevronRight'`), `clickable: boolean | null = null` (overrides `DsConfig.breadcrumbs.clickable`, falls back to `true`)
292
+ Output: `(navigate): BreadcrumbItem` — emits when an item with `href` is clicked and `clickable` resolves to `true` (event is `preventDefault`-ed so the consumer can decide what to do)
293
+
294
+ #### `<ds-tabs>` + `<ds-tab>` — `TabsComponent`, `TabComponent`
295
+ Container holds `<ds-tab label="…">` children.
296
+ Tabs inputs: `selectedIndex: model<number> = 0`, `variant: 'line' | 'pills' = 'line'`
297
+ Tab inputs: `label: required string`, `icon: IconName | null = null`, `count: number | null = null`, `disabled: boolean = false`. The tab's projected content renders in the active panel.
298
+ Tokens: `--ds-tab-fg`, `--ds-tab-fg-hover`, `--ds-tab-fg-active`, `--ds-tab-indicator-color`, `--ds-tab-indicator-width`, `--ds-tab-pad-x`, `--ds-tab-pad-y`, `--ds-tabs-divider`, `--ds-tabs-pills-bg`, `--ds-tab-pill-bg-hover` (inactive hover, defaults to `var(--primary-subtle)`), `--ds-tab-pill-bg-active` (defaults to `var(--surface-default)` — elevated card), `--ds-tab-pill-bg-active-hover` (defaults to `var(--primary-subtle)`), `--ds-tab-pill-fg-active` (defaults to `var(--primary-strong)`), `--ds-tab-pill-radius` (defaults to `var(--radius-md)` — same as buttons/inputs; override per-instance to `var(--radius-pill)` for fully round pills).
299
+
300
+ #### `<ds-stepper>` — `StepperComponent`
301
+ Inputs: `steps: readonly string[] = []`, `current: number = 0`. Horizontal step indicator with done/active/upcoming nodes.
302
+
303
+ #### `<ds-pagination>` — `PaginationComponent`
304
+ Inputs: `total: required number`, `pageSize: model<number> = 10`, `currentPage: model<number> = 1`, `pageSizeOptions: number[] = [10, 25, 50, 100]`, `showLabel: boolean = true`
305
+ Outputs: `(pageChange): number`, `(pageSizeChange): number`
306
+
307
+ #### `<ds-divider>` — `DividerComponent`
308
+ Inputs: `variant: 'default' | 'strong' | 'vertical' | 'label' = 'default'`, `spacing: 'none' | 'sm' | 'md' | 'lg' = 'md'`
309
+ Content: label text (when `variant="label"`).
310
+
311
+ ---
312
+
313
+ ### Surfaces
314
+
315
+ #### `<ds-card>` — `CardComponent`
316
+ Inputs: `elevation: 'flat' | 'raised' | 'hover' | 'interactive' = 'flat'`, `padding: 'none' | 'sm' | 'md' | 'lg' | null = null` (when `null`, no `padding-*` class is applied and the consumer controls padding via own CSS or `--ds-card-pad`)
317
+ Output: `(pressed): MouseEvent` — fires only when `elevation="interactive"`
318
+ Tokens: `--ds-card-bg`, `--ds-card-border`, `--ds-card-radius`, `--ds-card-pad`, `--ds-card-shadow`, `--ds-card-shadow-hover`, `--ds-card-focus-shadow`, `--ds-card-hover-lift`
319
+ Convention tokens (consumer-side `.title` projected into the card slot — declared at `:root`, not on the host): `--card-title-fs` (default `var(--font-size-h4)` = 22px; MM brand steps down to `var(--font-size-h5)` = 18px). Consumer markup: `<h3 class="title">…</h3>`; local `.title` class reads the token via `font:` shorthand together with `--font-weight-bold` / `--line-height-snug` / `--font-heading`.
320
+
321
+ #### `<ds-accordion>` + `<ds-accordion-item>` — `AccordionComponent`, `AccordionItemComponent`
322
+ Accordion is a thin wrapper that rounds + borders its children. Item inputs: `title: string = ''`, `expanded: model<boolean> = false`. Content slots on item: default (body), `[badge]` (rendered next to the title in the header).
323
+
324
+ ---
325
+
326
+ ### Overlay
327
+
328
+ #### `<ds-modal>` — `ModalComponent`
329
+ Inputs: `open: model<boolean> = false`, `size: 'sm' | 'md' | 'lg' = 'md'`, `danger: boolean = false`, `title: required string`
330
+ Output: `(closed): void` — fires on backdrop click, close button, or `open` being set to false. `(confirmed)` is declared on the component but no internal handler emits it; treat it as not implemented and emit confirmation from the consumer-side action button instead.
331
+ Content slots: `[body]`, `[impact]` (highlighted strip under the body for destructive consequences), `[actions]` (footer button row). Backdrop click + close button close the dialog.
332
+
333
+ #### `<ds-modal-card>` — `ModalCardComponent`
334
+ The visual card the `<ds-modal>` host renders inside its backdrop. Exposed as a separate selector for cases where you need custom positioning (e.g. inside a drawer) without re-implementing the dialog chrome. Inputs: `size`, `danger`, `title: required`, `showClose: boolean = true`. Output: `(closed)`. Slots: `[body]`, `[impact]`, `[actions]`.
335
+
336
+ #### `<ds-drawer>` — `DrawerComponent`
337
+ Side panel (no `side` input — always anchored right).
338
+ Inputs: `open: model<boolean> = false`, `size: 'md' | 'lg' = 'md'`, `title: string = ''`
339
+ Output: `(closed): void`
340
+ Content slots: `[drawer-body]`, `[drawer-footer]`.
341
+
342
+ #### `<ds-bottom-sheet>` — `BottomSheetComponent`
343
+ Mobile-first panel anchored to the bottom edge (touch equivalent of drawer/modal). Drag-down on the grab strip, scrim tap, or Esc dismisses; body scroll locks while open; caps width + centres on wide viewports.
344
+ Inputs: `open: model<boolean> = false`, `title: string = ''`
345
+ Output: `(closed): void`
346
+ Content slots: default (body), `[actions]` (footer).
347
+
348
+ #### `<ds-popover>` — `PopoverComponent`
349
+ Floating panel anchored to a trigger via CDK overlay. Input: `align: 'start' | 'end' = 'start'` — controls overlay alignment relative to the trigger (`start` = left-edge anchored, `end` = right-edge anchored). Open via the component method `toggle(triggerElement)` (or `close()`), and project the panel body inside a `<ng-template #panel>` (read internally via `viewChild`).
350
+
351
+ #### `[dsTooltip]` — `TooltipDirective`
352
+ Attribute directive. Apply to any focusable element.
353
+ Inputs: `dsTooltip: string = ''` (the text; empty disables), `dsTooltipPlacement: 'top' | 'bottom' | 'left' | 'right' = 'top'`, `dsTooltipDelay: number = 120` (ms)
354
+ Renders `<ds-tooltip-panel>` via CDK overlay on hover / focus; hides on leave / blur.
355
+
356
+ #### `<ds-menu>` + `<ds-menu-item>` — `MenuComponent`, `MenuItemComponent`
357
+ 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.
358
+
359
+ #### `<ds-dropdown>` — `DropdownComponent`
360
+ Trigger button + CDK overlay panel combo.
361
+ 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`
362
+ Selection is communicated via the `value` model. Keyboard: ArrowUp/Down, Enter/Space, Home/End, Escape.
363
+
364
+ ---
365
+
366
+ ### Tables
367
+
368
+ #### `<ds-table>` — `TableComponent<T extends { id: string }>`
369
+ 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`
370
+ Outputs: `(rowClick): T`, `(sortChange): SortChangeEvent` (`{ key, dir }`)
371
+ Column shape: `{ key: string, label: string, sortable?: boolean, align?: 'left' | 'right' | 'center', cell?: (row: T) => string }`
372
+ Cell templates: `<ng-template dsCellTemplate="<colKey>" let-row>…</ng-template>` — `row` is typed `unknown`, narrow via a helper method on the host.
373
+ Content slots: `[empty]` (rendered when `data.length === 0`), `[bulk-actions]` (rendered in the bulk action bar when `selectable && some selected`)
374
+ Loading modes: `'skeleton'` replaces rows with shimmer placeholders driven by the global `--skeleton-shimmer-x` keyframe; `'overlay'` keeps existing rows visible behind a translucent layer with a centred spinner.
375
+ Tokens: `--ds-table-border: var(--border-default)`, `--ds-table-radius: var(--radius-md)`, `--ds-table-bg`, `--ds-table-head-fg: var(--text-secondary)`, `--ds-table-head-bg: var(--surface-secondary)`, `--ds-table-head-fs: var(--font-size-xs)`, `--ds-table-row-hover-bg`, `--ds-table-row-selected-bg`, `--ds-table-divider`, `--ds-table-sort-active-fg`, `--ds-table-cell-pad-x/y`. (Renamed 2026-06: `--ds-table-header-*` → `--ds-table-head-*`, matching the tokens reference.)
376
+
377
+ ---
378
+
379
+ ### Domain
380
+
381
+ #### `<ds-w3w>` — `W3wComponent`
382
+ What3Words address chip — branded display for `///word.word.word` addresses; click-to-copy.
383
+ Inputs: `address: required string`, `prefix: string = '///'`, `copyable: boolean = true`
384
+ Output: `(copied): string` — emits the raw `address` value after a copy attempt
385
+
386
+ ---
387
+
388
+ ## Icons
389
+
390
+ Icon component: `<ds-icon [name]="iconName" [size]="16" [stroke]="1.75">`. `IconName` is `keyof typeof ICONS | string` — built-in DS names autocomplete; consumer-registered names (see `provideDsIcons` below) accept any string at the cost of autocomplete.
391
+
392
+ All built-in icons (kebab-case where indicated, camelCase otherwise — DS uses both):
393
+
394
+ `search` `plus` `minus` `check` `x` `chevronDown` `chevronRight` `chevronLeft` `chevronUp` `arrowRight` `arrowUp` `arrowDown` `info` `warn` `error` `success` `bell` `settings` `user` `users` `home` `calendar` `truck` `box` `map` `activity` `folder` `edit` `external` `trash` `copy` `download` `upload` `eye` `filter` `sort` `sortAsc` `sortDesc` `grid` `list` `moreH` `moreV` `link` `flag` `star` `inbox` `archive` `clock` `refresh` `play` `pause` `cmd` `paperclip` `file` `image` `lock` `logout` `help` `pin` `bookmark` `sparkle` `layers` `chart` `gauge` `package` `git` `sun` `moon` `save` `rotate` `qr` `globe` `phone` `bin` `pen` `smile` `frown` `mail` `eye-off` `check-circle` `drag`
395
+
396
+ Adding icons to DS: edit `src/lib/icons/icons.data.ts`; SVG paths render inside `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor">`. For consumer-side icons without forking DS, use `provideDsIcons(…)` below.
397
+
398
+ #### `DS_ICON_REGISTRY` / `provideDsIcons(icons)`
399
+
400
+ Consumer apps can register additional icons without forking DS. Each entry maps a name to the raw SVG body — everything that goes *inside* `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">`. Typically one or more `<path>` / `<circle>` / `<rect>` elements with no `stroke`/`fill` of their own (the host SVG paints them).
401
+
402
+ ```ts
403
+ import { provideDsIcons } from 'ds';
404
+
405
+ bootstrapApplication(AppComponent, {
406
+ providers: [
407
+ provideDsIcons({
408
+ 'cloud-upload': '<path d="M7 18a5 5 0 1 1 .9-9.9 …"/><path d="M12 21V11"/>',
409
+ shield: '<path d="M12 3 4 6v6c0 5 …"/>',
410
+ }),
411
+ ],
412
+ });
413
+ ```
414
+
415
+ Lookup order: built-in `ICONS` first, then the consumer registry. Names that collide with built-ins are ignored — fork the DS source if you need to override a built-in.
416
+
417
+ ---
418
+
419
+ ## App config
420
+
421
+ #### `DS_CONFIG` / `provideDsConfig(config)`
422
+
423
+ Inject `DS_CONFIG` token (default factory returns `{}`) to set library-wide defaults that consumer-level component inputs can still override.
424
+
425
+ ```ts
426
+ import { provideDsConfig } from 'ds';
427
+
428
+ bootstrapApplication(AppComponent, {
429
+ providers: [
430
+ provideDsConfig({
431
+ breadcrumbs: { separator: 'chevronRight', clickable: true },
432
+ }),
433
+ ],
434
+ });
435
+ ```
436
+
437
+ `DsConfig` shape (see `src/lib/config/ds-config.ts`):
438
+
439
+ ```ts
440
+ interface DsConfig {
441
+ breadcrumbs?: {
442
+ separator?: IconName;
443
+ clickable?: boolean;
444
+ };
445
+ }
446
+ ```
447
+
448
+ Currently consumed by:
449
+ - `<ds-breadcrumbs>` — `[separator]` / `[clickable]` inputs fall back to `breadcrumbs.separator` / `breadcrumbs.clickable` from config, then to `'chevronRight'` / `true`.
450
+
451
+ Add more sections to `DsConfig` as we extract reusable defaults; the precedence chain is always: explicit input → config → component default.
452
+
453
+ ---
454
+
455
+ ## Services
456
+
457
+ #### `BreadcrumbsService`
458
+
459
+ `@Injectable({ providedIn: 'root' })`. Signal-based state primitive — apps push crumbs, `<ds-breadcrumbs>` reads from here when its `[items]` input is omitted.
460
+
461
+ ```ts
462
+ private readonly crumbs = inject(BreadcrumbsService);
463
+ // signal-readable items
464
+ this.crumbs.items() // -> BreadcrumbItem[]
465
+ // mutators
466
+ this.crumbs.set([{ label: 'Overview', href: '/workspaces' }, { label: 'Detail' }]);
467
+ this.crumbs.push({ label: 'Extra' });
468
+ this.crumbs.replaceLast({ label: 'Renamed' });
469
+ this.crumbs.pop();
470
+ this.crumbs.clear();
471
+ ```
472
+
473
+ **Two ways to feed it:**
474
+
475
+ 1. **Programmatic** — each page calls `this.crumbs.set(...)` (e.g. inside `effect(() => …)` when the page model resolves). Use when crumb labels depend on data the page already has loaded (a program name, a campaign title).
476
+
477
+ 2. **Route-driven** — annotate routes with `data.breadcrumb` and run a Router→Service bridge once at app bootstrap. Example bridge lives at `app/core/breadcrumbs/breadcrumbs-route.bootstrap.ts` in this repo. `breadcrumb` accepts:
478
+ - `string` → `{ label: string, href: <built-from-url> }`
479
+ - `BreadcrumbItem`
480
+ - `BreadcrumbItem[]`
481
+ - `(snap: ActivatedRouteSnapshot) => string | BreadcrumbItem | BreadcrumbItem[]`
482
+
483
+ Mix-and-match: route bridge sets a base trail, page effect overrides with a richer version when its data is ready.
484
+
485
+ #### `ToastService`
486
+ `@Injectable({ providedIn: 'root' })`. Inject and call:
487
+ - `show(opts: ToastOptions): ToastRef` — `{ title?, body, variant?: 'info' | 'success' | 'warning' | 'error', dismissible?, durationMs? = 5000 }`. Returns `{ id, dismiss() }`.
488
+ - `dismissAll(): void`
489
+
490
+ 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.
491
+
492
+ ---
493
+
494
+ ## Migration tips
495
+
496
+ - **Don't add `class="card"` on `<ds-card>`.** Some consumer apps carry a legacy global `.card` rule that adds a second border on top of the component's own — use `ds-card` as-is, override tokens via `ds-card { --ds-card-...: ... }`, or pass a domain class like `class="kpi"`.
497
+ - **`@use 'tokens'` alone won't give you `.link` / `.t-*` / `.grid-*`.** Pull those partials explicitly or `@use 'styles/ds'` for the full aggregate. See Foundations → Global helper classes.
498
+ - **`<ng-content>` default slot is allowed once per template.** If you duplicate it across `@if/@else` branches Angular silently drops projected children. Hoist a single default slot and toggle visibility via a class.
499
+ - **Tokens on `:host`, not on the inner root class.** Defaults declared inside `.card { --ds-card-...: … }` block external overrides because the inner specificity wins. Move them to `:host` so consumer `ds-card { --ds-card-...: ... }` cascades through.
500
+ - **Brand overrides Tier 1 palette + a few Tier 2 roles.** Don't add brand-specific values inside individual components; put them in a consumer-side `_brand-*.scss` scoped to `[data-brand="…"]` — the DS itself stays brand-agnostic.