@ids-group-ltd/ids-design-system 0.9.0 → 0.10.0

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 CHANGED
@@ -120,23 +120,23 @@ Every entry below names its exported class (`ButtonComponent`, `TableComponent<T
120
120
 
121
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
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`.
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-color`, `-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
124
 
125
125
  ### Form & input
126
126
 
127
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.)
128
+ Inputs: **two orthogonal axes** — `color: ButtonColor = 'primary'` (`'primary' | 'secondary' | 'tertiary' | 'neutral' | 'error' | 'success' | 'warning'`) and `variant: ButtonVariant = 'solid'` (`'solid' | 'tonal' | 'outline' | 'ghost' | 'text'`). Plus `size: DsSize | null = null` (unset resolves `DS_CONFIG.control.size`, then `md`), `type: 'button' | 'submit' | 'reset' = 'button'`, `disabled`, `loading`, `fullWidth`, `icon: IconName | null`.
129
+ Axis meaning: **variant is loudness** (solid > tonal > outline/ghost/text), **color is hue** — every pair renders, and the UX-discouraged ones dev-warn (see `DISCOURAGED_COMBOS`). Only solid and tonal paint a fill: outline, ghost and text are TRANSPARENT, so they adopt the surface they sit on. Disabled uses one label recipe for every variant, `oklch(from accent 70% 0.035 h)`. (History: the single `variant` axis was split into color × variant in 2026-06; `danger`→`error`, `link`→`text`, the old `ghost`→`outline`.)
130
130
  Output: `(pressed): MouseEvent` — only fires when not disabled and not loading
131
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.
132
+ Tokens: `--ds-button-bg-color`, `--ds-button-bg-color-hover`, `--ds-button-bg-color-active`, `--ds-button-bg-color-disabled`, `--ds-button-label-color`, `--ds-button-label-color-disabled`, `--ds-button-border`, `--ds-button-radius`, `--ds-button-focus-shadow`, `--ds-button-pressed-shadow`. For `variant="solid"`, `-bg-color-hover` / `-bg-color-active` / `-pressed-shadow` default to a `color-mix()` derivation of the resolved fill (88 % / 76 % + black — the theme's hover/pressed recipe), so overriding the fill alone retints the whole state set; tonal, outline, ghost and text keep explicit ramp defaults, so a full retint there means setting the state tokens too.
133
133
 
134
134
  #### `<ds-icon-button>` — `IconButtonComponent`
135
135
  Icon-only action with its own taxonomy, distinct from `ds-button`. `ariaLabel` is required (icon-only must be labelled for a11y).
136
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
137
  Output: `(pressed): MouseEvent` — fires when not disabled
138
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.
139
+ Tokens: `--ds-icon-button-bg-color`, `--ds-icon-button-icon-color`, `--ds-icon-button-border`, `--ds-icon-button-bg-color-hover`, `--ds-icon-button-bg-color-active`, `--ds-icon-button-icon-color-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
140
 
141
141
  #### `<ds-input>` — `InputComponent`
142
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)
@@ -155,7 +155,7 @@ Example:
155
155
  </ds-input>
156
156
  ```
157
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`
158
+ Tokens: `--ds-input-bg-color`, `--ds-input-border`, `--ds-input-border-hover`, `--ds-input-border-focus`, `--ds-input-text-color`, `--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-color-error`, `--ds-input-border-success`, `--ds-input-bg-color-disabled`
159
159
 
160
160
  #### `<ds-textarea>` — `TextareaComponent`
161
161
  Multi-line counterpart to `<ds-input>` — same wrapper/states, reuses the `--ds-input-*` token family. No prefix/suffix slots.
@@ -261,7 +261,7 @@ The companion `<ds-toast-region>` lives inside the `ToastService` (see Services)
261
261
  #### `<ds-sidenav>` — `SidenavComponent`
262
262
  Inputs: `collapsed: boolean = false`, `brand: string = ''` (renders a letter mark + name; omit to project custom content)
263
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`
264
+ Tokens: `--ds-sidenav-bg-color`, `--ds-sidenav-border`, `--ds-sidenav-width`, `--ds-sidenav-width-collapsed`, `--ds-sidenav-mark-bg-color`, `--ds-sidenav-mark-label-color`
265
265
 
266
266
  #### `<ds-sidenav-group>` — `SidenavGroupComponent`
267
267
  Inputs: `label: string = ''`, `icon: IconName | null = null`, `expandable: boolean = false`, `expanded: model<boolean> = true`
@@ -271,17 +271,17 @@ When `expandable=true` renders header button with toggle + caret; collapses body
271
271
  #### `<ds-sidenav-item>` — `SidenavItemComponent`
272
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
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`
274
+ Tokens (on `:host`): `--ds-sidenav-item-label-color`, `--ds-sidenav-item-label-color-hover`, `--ds-sidenav-item-bg-color-hover`, `--ds-sidenav-item-bg-color-active` (default: `--primary`), `--ds-sidenav-item-label-color-active` (default: `--text-on-primary`), `--ds-sidenav-item-rail` (left rail, default: `--secondary`), `--ds-sidenav-item-radius`, `--ds-sidenav-alert-color`
275
275
 
276
276
  #### `<ds-topbar>` — `TopBarComponent`
277
277
  No inputs.
278
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.
279
+ Tokens (on `:host`): `--ds-topbar-height`, `--ds-topbar-bg-color`, `--ds-topbar-border`, `--ds-topbar-title-text-color`, plus the `--ds-topbar-crumb-*` set for the breadcrumb row. **The topbar owns no bottom gap** — it has no margin token and sets no margin; spacing to the next block belongs to the page or to `ds-app-layout`'s content padding. (This paragraph previously documented a `--ds-topbar-margin-b` that has never existed in the shipped component.)
280
280
 
281
281
  #### `<ds-page-header>` — `PageHeaderComponent`
282
282
  Inputs: `eyebrow: string = ''`, `title: required string`, `subtitle: string = ''`, `compact: boolean = false`, `divider: boolean = false`, `metaDivider: boolean = false`
283
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)`.
284
+ Tokens: `--ds-page-header-eyebrow-text-color`, `--ds-page-header-title-text-color`, `--ds-page-header-subtitle-text-color`, `--ds-page-header-meta-text-color`, `--ds-page-header-meta-icon-color`, `--ds-page-header-divider`, `--ds-page-header-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
285
 
286
286
  #### `<ds-page-footer>` — `PageFooterComponent`
287
287
  Input: `variant: 'default' | 'compact' | 'save' = 'default'`
@@ -295,7 +295,7 @@ Output: `(navigate): BreadcrumbItem` — emits when an item with `href` is click
295
295
  Container holds `<ds-tab label="…">` children.
296
296
  Tabs inputs: `selectedIndex: model<number> = 0`, `variant: 'line' | 'pills' = 'line'`
297
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).
298
+ Tokens: `--ds-tab-label-color`, `--ds-tab-label-color-hover`, `--ds-tab-label-color-active`, `--ds-tab-indicator-color`, `--ds-tab-indicator-width`, `--ds-tab-pad-x`, `--ds-tab-pad-y`, `--ds-tabs-divider`, `--ds-tabs-pills-bg-color`, `--ds-tab-pill-bg-color-hover` (inactive hover, defaults to `var(--primary-subtle)`), `--ds-tab-pill-bg-color-active` (defaults to `var(--surface-default)` — elevated card), `--ds-tab-pill-bg-color-active-hover` (defaults to `var(--primary-subtle)`), `--ds-tab-pill-label-color-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
299
 
300
300
  #### `<ds-stepper>` — `StepperComponent`
301
301
  Inputs: `steps: readonly string[] = []`, `current: number = 0`. Horizontal step indicator with done/active/upcoming nodes.
@@ -315,7 +315,7 @@ Content: label text (when `variant="label"`).
315
315
  #### `<ds-card>` — `CardComponent`
316
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
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`
318
+ Tokens: `--ds-card-bg-color`, `--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
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
320
 
321
321
  #### `<ds-accordion>` + `<ds-accordion-item>` — `AccordionComponent`, `AccordionItemComponent`
@@ -372,7 +372,7 @@ Column shape: `{ key: string, label: string, sortable?: boolean, align?: 'left'
372
372
  Cell templates: `<ng-template dsCellTemplate="<colKey>" let-row>…</ng-template>` — `row` is typed `unknown`, narrow via a helper method on the host.
373
373
  Content slots: `[empty]` (rendered when `data.length === 0`), `[bulk-actions]` (rendered in the bulk action bar when `selectable && some selected`)
374
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.)
375
+ Tokens: `--ds-table-border: var(--border-default)`, `--ds-table-radius: var(--radius-md)`, `--ds-table-bg-color`, `--ds-table-head-text-color: var(--text-secondary)`, `--ds-table-head-bg-color: var(--surface-secondary)`, `--ds-table-head-fs: var(--font-size-xs)`, `--ds-table-row-hover-bg-color`, `--ds-table-row-selected-bg-color`, `--ds-table-divider`, `--ds-table-sort-active-icon-color`, `--ds-table-cell-pad-x/y`. (Renamed 2026-06: `--ds-table-header-*` → `--ds-table-head-*`, matching the tokens reference.)
376
376
 
377
377
  ---
378
378
 
package/design-system.md CHANGED
@@ -108,7 +108,177 @@ follows it. This is why every rule on this page names a token.
108
108
 
109
109
  ---
110
110
 
111
- ## 4. Overriding a component
111
+ ## 4. Colour
112
+
113
+ ### Pick the ROLE for the job, not the colour that looks right
114
+
115
+ Components never read a palette primitive (`--blue-600`). They read a semantic role, and the
116
+ role names say what the thing IS, so the theme and any brand can move underneath. Measured
117
+ usage across the library:
118
+
119
+ | Role | Uses | What it is for |
120
+ | --- | --- | --- |
121
+ | `--text-primary` | 82 | Body copy, labels, values — the default. If you are unsure, this. |
122
+ | `--text-tertiary` | 69 | Meta that must not compete: eyebrows, placeholders, counters, timestamps. |
123
+ | `--text-secondary` | 46 | Supporting copy that still has to be read — hints, subtitles, descriptions. |
124
+ | `--text-disabled` | 33 | Only for a disabled control. Never as "quiet text". |
125
+ | `--surface-default` | 50 | The page and the inside of a control. |
126
+ | `--surface-secondary` | 52 | A tier up from the page: table heads, sandboxes, code blocks. |
127
+ | `--surface-muted` | 16 | Hover and pressed fills on a neutral row. |
128
+ | `--surface-overlay` | 15 | Anything that floats — panels, menus, dialogs. |
129
+ | `--border-default` | 44 | The edge of a control. |
130
+ | `--border-divider` | 31 | A line BETWEEN things, not around them. |
131
+
132
+ `--text-tertiary` being the second most used role is the load-bearing fact here: most of what
133
+ looks like "grey text" in this system is a deliberate tertiary, and reaching for
134
+ `--text-disabled` to get the same greyness tells a screen reader's user nothing and lies to
135
+ the next reader of your CSS.
136
+
137
+ ### A status family has four members and they are not interchangeable
138
+
139
+ Measured by which property each one actually lands on, across every component that uses one:
140
+
141
+ - **`--<status>`** — the saturated one: `border-color`, the fill of a solid button, and the
142
+ `color` of a MARKER — a required asterisk, an icon badge's glyph. Every one of the eight
143
+ `color: var(--error)` declarations in the library is a marker of that kind, six of them the
144
+ `.req` asterisk, and the other two an icon sitting on an `--error-subtitle` tint. **That
145
+ glyph-on-tint pair is the pattern to copy**, and the reason not to put prose in this member:
146
+ it is contrast-checked as a large glyph, not as text.
147
+ - **`--<status>-text`** — `color`, on a light surface. This is the contrast-safe member, and the
148
+ one you want for a message.
149
+ - **`--<status>-subtitle`** — `background`. The tint behind an alert or an icon badge.
150
+ - **`--<status>-muted` / `-hover`** — interaction states on the tinted surface.
151
+
152
+ So a status message is `--error-text` on `--error-subtitle`, never `--error` on anything with
153
+ text on it. Statuses are `info | success | warning | error` (`DsStatus`); `danger` and `warn`
154
+ are not words this library uses.
155
+
156
+ ### Text on a saturated fill uses the on-role, and it does not flip with the theme
157
+
158
+ `--text-on-primary`, `-on-error`, `-on-success`, `-on-warning`. They resolve to
159
+ `--static-white` / `--static-ink`, which are theme-INDEPENDENT on purpose: the fill under them
160
+ is the same colour in light and dark, so flipping the text with the theme would break the pair
161
+ that was contrast-checked. Never use `--text-primary` on a filled button.
162
+
163
+ ### Colour is never the only carrier
164
+
165
+ Every status in this library also has a glyph or a word. A red border alone fails the
166
+ colour-blind reader and fails a printout; `ds-alert`, `ds-badge` and the field message all
167
+ pair the colour with an icon or text, and a new status surface should too.
168
+
169
+ ---
170
+
171
+ ## 5. Motion
172
+
173
+ ### Four durations, and 109 of the 139 uses are one of them
174
+
175
+ | Token | Value | What it is for | Uses |
176
+ | --- | --- | --- | --- |
177
+ | `--duration-instant` | 80ms | A press that must feel like contact. | 2 |
178
+ | `--duration-fast` | 120ms | Every hover, colour and border change — the default. | 109 |
179
+ | `--duration-base` | 180ms | A surface arriving (dialog, drawer) or a layout settling. | 27 |
180
+ | `--duration-slow` | 260ms | Only something large crossing the screen. | 1 |
181
+
182
+ If a transition you are adding is not `--duration-fast`, be able to say why. The one
183
+ `--duration-slow` in the library is a full-height drawer; that is the bar.
184
+
185
+ ### Easing follows direction
186
+
187
+ `--ease-standard` (132 uses) for anything that changes in place — colour, border, a fill.
188
+ `--ease-decelerate` for something ARRIVING, `--ease-accelerate` for something LEAVING: an
189
+ entrance slows into its resting place, an exit gets out of the way. The role layer already
190
+ encodes this, so prefer it to picking an easing yourself: `--ds-motion-enter-panel-*` (a
191
+ dropdown), `--ds-motion-enter-surface-*` (a dialog), `--ds-motion-enter-large-*` (a drawer),
192
+ and `--ds-motion-exit-*`, which is deliberately FASTER than its entrance.
193
+
194
+ ### Transition properties, not `all`
195
+
196
+ Measured: `background-color` (20), `transform` (12), `color` (10), `border-color` (5),
197
+ `opacity` (2). Nothing in the library transitions `all`, and only three places transition a
198
+ `width` — animating a layout property costs a reflow per frame. Prefer `transform` and
199
+ `opacity`; if you find yourself animating `height`, the answer is usually a `grid-template-rows`
200
+ trick or an overlay.
201
+
202
+ ### An animation must mean something
203
+
204
+ Motion in this library either shows where a surface came from (a panel grows out of its
205
+ trigger, a drawer travels from its edge) or confirms a hit (a press). Decoration is not a
206
+ reason. The test: describe what the animation TELLS the user in one clause — if you cannot,
207
+ delete it.
208
+
209
+ ### Reduced motion zeroes the DURATION, never the animation
210
+
211
+ `prefers-reduced-motion` sets the duration to `0ms` and leaves the keyframes in place, because
212
+ the modal, drawer and bottom sheet tear themselves down on `animationend` — removing the
213
+ animation would strand them mounted and leak the body-scroll lock. Follow that pattern in
214
+ anything with an exit.
215
+
216
+ ---
217
+
218
+ ## 6. Content
219
+
220
+ ### Labels are sentence case
221
+
222
+ Measured: of 57 multi-word labels across the docs' own specimens, **45 are sentence case**. The
223
+ apparent exceptions are not exceptions — they are acronyms and notation the case rule does not
224
+ touch (`Site URL`, `Project ID`, `Date (en-US, Sunday-first)`). So: capitalise the first word
225
+ and whatever is a proper noun or an acronym, and nothing else. `Asset register`, not
226
+ `Asset Register`. No trailing colon: the field's shape already says a value follows.
227
+
228
+ Mark the exception, not the rule. `required` is the default expectation in most forms, so
229
+ `ds-input` and its siblings carry an `optional` input that renders "(optional)" rather than
230
+ making you label every other field.
231
+
232
+ ### An empty state is five different situations, and saying which is the whole job
233
+
234
+ `ds-empty-state` takes a `variant`, and the vocabulary is the rule:
235
+ `none | loading | error | locked | success`. A screen that shows the same "No data" for a
236
+ first-run list, a filter that matched nothing, a failed request and a permission denial has
237
+ told the user nothing in four different ways. The pattern's own worked examples show the shape:
238
+
239
+ | Variant | Title says the SITUATION | Body says the NEXT STEP or the CAUSE |
240
+ | --- | --- | --- |
241
+ | `none` | "No asset allocated yet" | "Pick from the asset register to start building this Sub-record." |
242
+ | `error` | "Couldn't load resource allocations" | "Network error — the request timed out after 30 seconds." |
243
+ | `locked` | "You don't have access to this Logistics plan" | "Logistics plans are restricted to Logistics and Producer roles. Ask Alex Park or your team lead." |
244
+
245
+ Three things to copy from those: the title is a **statement, not a label** — "No asset
246
+ allocated yet", never "Empty"; the error body names a **concrete** cause with the number in it,
247
+ not "Something went wrong"; and the locked body names **who can unblock them**, because a
248
+ permission wall with no next step is a dead end.
249
+
250
+ ### A message says what happened, what follows, and what to do
251
+
252
+ The library holds itself to this. All 15 messages it prints are tagged with the component that
253
+ printed them (`[ds-table] …`), 7 of 15 state the consequence with a plain "so", and 5 name the
254
+ fix outright:
255
+
256
+ > `[ds-table] lazy needs virtualScroll: without a window there is no range to fetch, so every
257
+ > gap in `data` renders a skeleton row and nothing ever asks for the rows.`
258
+
259
+ Anatomy worth keeping: **where** (the tag) → **what is wrong** → **what follows from it** →
260
+ **what to do**. The middle clause is the one people drop, and it is the one that stops the
261
+ reader guessing whether the warning matters.
262
+
263
+ ### Field errors: the validator owns the words, and it must supply them
264
+
265
+ A DS field renders the message; it never invents one. Give the validator a message
266
+ (`required(path.email, { message: 'We need an email to send the invite to' })`) or map the kind
267
+ once for the app in `provideDsConfig({ field: { errorMessages: { … } } })`. With neither, an
268
+ invalid field goes red with no words and a dev warning names the kinds it could not resolve —
269
+ deliberately, because the alternative is the library writing copy for your domain.
270
+
271
+ Say what to do, not what went wrong: "Enter a valid email address" beats "Invalid email".
272
+
273
+ **Errors appear after the user has finished with the field, not while they type**, and the
274
+ library enforces it rather than asking you to: `errors` is gated on `touched`, so a `required`
275
+ error cannot greet an untouched form and a half-typed address is not yet wrong. An explicit
276
+ `error` string is the deliberate exception — binding it says the consumer has already decided,
277
+ so it shows immediately.
278
+
279
+ ---
280
+
281
+ ## 7. Overriding a component
112
282
 
113
283
  Set the component's own `--ds-*` token **on the host element**, scoped as narrowly as the
114
284
  change deserves:
@@ -136,10 +306,11 @@ internals.
136
306
 
137
307
  ---
138
308
 
139
- ## 5. What this file does not cover yet
309
+ ## 8. Where the rest lives
140
310
 
141
- Colour pairing (which surface takes which text role), motion (when a transition earns its
142
- place) and content rules (labels, empty states, error copy) are not written down here yet.
143
- Until they are, ds-docs `Practice → Do / Don't` carries the component-choice decisions —
144
- modal vs drawer, button hierarchy, table density, status without colour — and
145
- `Practice → Token Discipline` carries the token-vs-literal rule in worked form.
311
+ The decisions this file does NOT make are the ones about which COMPONENT to reach for, and they
312
+ have their own home: ds-docs `Practice → Do / Don't` (modal vs drawer, button hierarchy, table
313
+ density, badge proliferation, status without colour, tooltips vs banners) and
314
+ `Practice → Token Discipline` (the token-vs-literal rule, in worked pairs). The component
315
+ inventory is `components.md`; the generated Component API and token reference in ds-docs are
316
+ extracted from source on every build and are the only surfaces that cannot go stale.