@ids-group-ltd/ids-design-system 0.11.0 → 0.11.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/CHANGELOG.md +1164 -1011
- package/components.md +49 -26
- package/design-system.md +18 -18
- package/fesm2022/ids-group-ltd-ids-design-system.mjs +527 -116
- package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
- package/migrations/0.10.0.json +19 -19
- package/migrations/0.10.1.json +20 -7
- package/migrations/0.10.2.json +8 -8
- package/migrations/0.10.3.json +2 -2
- package/migrations/0.11.0.json +12 -12
- package/migrations/0.11.1.json +305 -0
- package/migrations/0.2.2.json +1 -1
- package/migrations/0.3.0.json +1 -1
- package/migrations/0.5.1/badge-statuses.md +1 -3
- package/migrations/0.5.1.json +1 -1
- package/migrations/0.6.3.json +1 -1
- package/migrations/0.7.1.json +3 -3
- package/migrations/0.8.0.json +5 -5
- package/migrations/0.9.0.json +10 -9
- package/migrations/0.9.1.json +2 -2
- package/migrations/README.md +34 -52
- package/package.json +1 -1
- package/styles/_dropdown-overlay.scss +35 -13
- package/styles/_ds-color.scss +3 -3
- package/styles/_field-box.scss +2 -6
- package/styles/_field-label.scss +5 -10
- package/styles/_field-state.scss +3 -2
- package/styles/_focus.scss +0 -2
- package/styles/_layout-utils.scss +2 -2
- package/styles/_overlay-motion.scss +2 -3
- package/styles/_press.scss +3 -5
- package/styles/_reset.scss +0 -1
- package/styles/_scrollbar.scss +1 -3
- package/styles/_status.scss +1 -2
- package/styles/_surface-motion.scss +3 -4
- package/styles/_text-clip.scss +1 -1
- package/styles/_theme-activation.scss +1 -1
- package/styles/_tokens-charts.scss +1 -3
- package/styles/_tokens.scss +4 -3
- package/styles/_typography.scss +2 -2
- package/themes/README.md +3 -3
- package/themes/_base-palette.scss +2 -2
- package/themes/_semantic.scss +2 -2
- package/themes/dark/_palette.scss +1 -2
- package/themes/light/_palette.scss +1 -1
- package/themes/light/_theme.scss +1 -1
- package/types/ids-group-ltd-ids-design-system.d.ts +274 -49
package/components.md
CHANGED
|
@@ -6,12 +6,13 @@
|
|
|
6
6
|
> which type role where, how a page is composed) see `design-system.md`, which carries
|
|
7
7
|
> the rules this catalogue deliberately does not.
|
|
8
8
|
>
|
|
9
|
-
> **Where it overlaps with generated output:**
|
|
9
|
+
> **Where it overlaps with generated output:** the documentation site
|
|
10
|
+
> (https://ids-ds.proto.ids-group.co.uk/) carries a generated Component API table and
|
|
10
11
|
> a token reference from source on every build, and those cannot go stale. Where this file
|
|
11
|
-
> and
|
|
12
|
+
> and the generated tables disagree, the generated ones are right — prefer them for exact inputs and token names, and
|
|
12
13
|
> 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
|
>
|
|
14
|
-
> **Import path:** `import { ButtonComponent, … } from '
|
|
15
|
+
> **Import path:** `import { ButtonComponent, … } from '@ids-group-ltd/ids-design-system'`.
|
|
15
16
|
>
|
|
16
17
|
> **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
|
|
|
@@ -45,7 +46,7 @@ Loaded via `@use 'styles/tokens';` (when the consumer also `@use 'styles/ds';` t
|
|
|
45
46
|
|
|
46
47
|
**Typography:**
|
|
47
48
|
- 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 (
|
|
49
|
+
- Weights: `--font-weight-regular` 400, `--font-weight-medium` 500, `--font-weight-semibold` 600, `--font-weight-bold` 700, `--font-weight-extrabold` 800 (a brand overlay may step this down to 700)
|
|
49
50
|
- 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
51
|
- 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
52
|
- Letter spacing: `--letter-spacing-tight`, `--letter-spacing-snug`, `--letter-spacing-normal`, `--letter-spacing-wide`, `--letter-spacing-wider`
|
|
@@ -68,7 +69,7 @@ Loaded via `@use 'styles/tokens';` (when the consumer also `@use 'styles/ds';` t
|
|
|
68
69
|
|
|
69
70
|
### Grid
|
|
70
71
|
|
|
71
|
-
Responsive 4-tier page grid loaded via `@use 'styles/ds'` (or directly via `@use '
|
|
72
|
+
Responsive 4-tier page grid loaded via `@use 'styles/ds'` (or directly via `@use '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
|
|
|
73
74
|
| Tier | Range | Cols | Gutter | Margin | Container cap |
|
|
74
75
|
| ------------ | ------------- | ---- | ------------- | -------------- | ------------------------ |
|
|
@@ -88,7 +89,7 @@ Responsive 4-tier page grid loaded via `@use 'styles/ds'` (or directly via `@use
|
|
|
88
89
|
- Snap to columns, not pixels. Canonical two-column splits: 8+4, 6+6, 9+3. Never 7+5.
|
|
89
90
|
- 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
91
|
- 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
|
|
92
|
+
- 8+4 is canonical for record-detail pages (main + meta sidebar); 9+3 is reserved for a narrow picker or filter rail.
|
|
92
93
|
|
|
93
94
|
**Markup example:**
|
|
94
95
|
|
|
@@ -121,11 +122,11 @@ The DS aggregate (`@use 'styles/ds'`) forwards the full stack: theme primitives
|
|
|
121
122
|
|
|
122
123
|
## Components
|
|
123
124
|
|
|
124
|
-
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
|
|
125
|
+
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, it does not avoid it.
|
|
125
126
|
|
|
126
127
|
**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.
|
|
127
128
|
|
|
128
|
-
> **Token and API lists below are hand-maintained, so treat this file as prose about intent.** The authoritative surfaces are the **Component API tables** and the **token reference**
|
|
129
|
+
> **Token and API lists below are hand-maintained, so treat this file as prose about intent.** The authoritative surfaces are the **Component API tables** and the **token reference** on the documentation site, both generated from the source of each release, so they cannot go stale — trust those first, and read this file for the reasoning a generated table cannot carry. Where the two disagree, the generated one is right.
|
|
129
130
|
|
|
130
131
|
### Form & input
|
|
131
132
|
|
|
@@ -147,12 +148,12 @@ is not a validated field; where a search needs a label or an error line, use `ds
|
|
|
147
148
|
|
|
148
149
|
#### `<ds-button>` — `ButtonComponent`
|
|
149
150
|
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`. Plus the refusal pair below: `disabledReason`, and the field message inputs `hint` / `warning` / `error` / `messageIcon` / `reserveMessage` / `ariaDescribedBy`.
|
|
150
|
-
Axis meaning: **variant is loudness** (solid > tonal > outline/ghost/text), **color is hue** — every pair renders, and the UX-discouraged ones dev-warn
|
|
151
|
+
Axis meaning: **variant is loudness** (solid > tonal > outline/ghost/text), **color is hue** — every pair renders, and the UX-discouraged ones dev-warn with the reason. Only solid and tonal paint a fill: outline, ghost and text are TRANSPARENT, so they adopt the surface they sit on. Disabled splits by whether the fill can carry the state: `solid` and `tonal` keep `oklch(from accent 70% 0.035 h)`, while `outline`, `ghost` and `text` — the three with no fill of their own — mix the label toward the surface, `color-mix(in srgb, <label> 40%, var(--surface-default))`, because a fixed lightness cannot serve both themes. (History: the single `variant` axis was split into color × variant in 2026-06; `danger`→`error`, `link`→`text`, the old `ghost`→`outline`.)
|
|
151
152
|
Output: `(pressed): MouseEvent` — only fires when not disabled and not loading
|
|
152
153
|
Content slots: default (label / leading or trailing icon), plus `[dsButtonSubtext]` for a projected second line. For icon-only actions use `<ds-icon-button>`.
|
|
153
154
|
**Saying WHY a button is refused, and the two kinds of refusal.** A greyed control that does not say why is a dead end, and until 0.10.4 the only way to explain one was a tooltip — mouse-only. Which input to reach for is decided by whether the user can lift the refusal on this screen:
|
|
154
155
|
- **Standing** (no permission, no integration — nothing here will change it): `disabledReason` beside `disabled`. The reason renders as a second line INSIDE the button, and setting it flips how the button is disabled — `aria-disabled="true"` instead of the native attribute, because a natively disabled button never takes focus and its description would never be announced (measured; Chrome's a11y tree reports name `"Approve invoice"`, description `"Needs the Finance role"`, state disabled). The click is swallowed in the handler instead, so `(pressed)` still never fires. Leave `disabledReason` unset and NOTHING changes: the native attribute stays, and so does every existing layout. Length is deliberately uncapped — the text wraps and the button grows.
|
|
155
|
-
- **Temporary** (the form is not filled in yet): do NOT disable the button at all. Leave it live, judge validity in the submit handler
|
|
156
|
+
- **Temporary** (the form is not filled in yet): do NOT disable the button at all. Leave it live, judge validity in the submit handler, and carry the text UNDER the button with `hint` / `warning` / `error` — the same three inputs the fields take, resolved and rendered by the same `ds-field-message` row the fields use, with the same `messageIcon` and `reserveMessage` knobs and the same `DS_CONFIG.field.*` fallbacks. Those inputs live on an internal shared base class that `ButtonComponent` and every field extend, so the behaviour cannot drift apart. What it does NOT take is `errors` / `invalid` / `touched`: a button has no validation state of its own.
|
|
156
157
|
Layout: a message-bearing button becomes a column (host class `with-message`), and because the host shrinks to fit, a message longer than the label widens the pair — button included, exactly as a field's control spans its own message. Without a message the host keeps the `inline-flex` box every existing layout was built against.
|
|
157
158
|
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`, `--ds-button-shadow`, `--ds-button-shadow-hover`. The last two are the REST and hover shadow, both `none` by default — before them the only way to give a button a resting shadow was a deep selector into its inner `<button>`. `-shadow-hover` falls back to `-shadow`, so setting the resting one alone keeps the button steady under the pointer; focus and pressed keep their own hooks and still win while those states are on. 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.
|
|
158
159
|
|
|
@@ -202,21 +203,43 @@ Inputs: `checked: model<boolean>`, `disabled: boolean = false`, `name: string =
|
|
|
202
203
|
#### `<ds-switch>` — `SwitchComponent`
|
|
203
204
|
Inputs: `checked: model<boolean>`, `disabled: boolean = false`, `name: string | null = null`, `variant: 'default' | 'success' | 'error' = 'default'`, `inputId: string | null = null`
|
|
204
205
|
|
|
206
|
+
#### The picker family — `<ds-select>`, `<ds-multi-select>`, `<ds-autocomplete>`
|
|
207
|
+
Five rules hold across all three: one meaning per member name, difference only where a reason is stated, one panel implementation (`.dropdown-panel` / `.dropdown-list`), no library-invented string without a slot to replace it, and one way to clip a line.
|
|
208
|
+
|
|
209
|
+
Shared inputs: `options` (flat items, groups, or a mix), `value: model`, `placeholder`, `size: DsSize | null = null`, `width: DsControlWidth = 'fill'` (`'fill' | 'content'`), `label`, `disabled`, `required`, `optional`, `success`, `ariaLabel`.
|
|
210
|
+
|
|
211
|
+
Shared option shape: `DsOption<T> = { label, value, disabled? }` and `DsOptionGroup<T> = { label, options, disabled? }`, with `DsOptionItem<T>` the union. Each picker re-exports it under its own name (`SelectItem`, `MultiSelectItem`, `AutocompleteItem<T>`), so one array literal fits all three.
|
|
212
|
+
|
|
213
|
+
Shared slots — content-projected directives, each a `<ng-template>`:
|
|
214
|
+
- `[dsOptionTemplate]` — the option row, on all three
|
|
215
|
+
- `[dsChipTemplate]` — a selected chip, on multi-select and autocomplete
|
|
216
|
+
- `[dsPickerTrigger]` — replaces the trigger, on all three
|
|
217
|
+
- `[dsEmptyTemplate]` — the "no matches" state, on all three
|
|
218
|
+
- `[dsCreateTemplate]` — the "create «…»" row, on autocomplete
|
|
219
|
+
|
|
220
|
+
Shared panel tokens — the three pickers portal their panel out of the component, so these are declared on the host and forwarded onto the pane; a per-instance `ds-select { --ds-dropdown-panel-radius: 8px }` reaches it. `--ds-dropdown-panel-bg-color`, `-radius`, `-maxh`, `-minw`, `-maxw` (the last two bound the panel in `width="content"`). Each picker's own `--ds-<name>-panel-bg-color` / `-radius` / `-maxh` is an ALIAS of the shared one and still works.
|
|
221
|
+
|
|
222
|
+
Shared option tokens, painting the row inside any of the three panels: `--ds-option-selected-bg-color`, `-hover`, `--ds-option-selected-label-color`, `--ds-option-check-color`. `ds-select` and `ds-autocomplete` mark the selection with the check glyph these paint; `ds-multi-select` uses a checkbox and answers to `--ds-multi-select-check-bg-color` instead.
|
|
223
|
+
|
|
205
224
|
#### `<ds-select>` — `SelectComponent`
|
|
206
|
-
Inputs: `value: model<string>`, `options: SelectItem[]
|
|
207
|
-
|
|
225
|
+
Inputs: `value: model<string>`, `options: SelectItem[]`, `placeholder: string = ''`, `size`, `width`, `label`, `disabled`, `readOnly`, `readonly` (an alias of `readOnly`, because signal forms binds by name), `success`, `required`, `optional`, `clearable`, `name: string | null = null`, `ariaLabel`
|
|
226
|
+
Trigger plus a CDK overlay panel. Keyboard: ArrowUp/Down, Enter/Space, Home/End, Escape, skipping group headers. `isSelectOptionGroup(item)` is re-exported as a type guard.
|
|
227
|
+
|
|
228
|
+
#### `<ds-multi-select>` — `MultiSelectComponent`
|
|
229
|
+
Inputs: `value: model<string[]>`, `options: readonly MultiSelectItem[]`, `placeholder: string = 'Select…'`, `searchPlaceholder: string = 'Filter…'`, `searchable: boolean | number | null = null` (`true` always shows the filter row, `false` never, a NUMBER shows it once the option count reaches it), `selectAll: boolean | 'group' | 'both' = false` (`'group'` puts a row per group, `'both'` adds a global row beside them), `triggerDisplay: DsTriggerDisplay = 'full'` (`'full' | 'count' | 'labels'`), `maxVisibleChips: number | 'fit' | 'all' | null = null` (a NUMBER is a ceiling, not an exact count — fewer fit when the trigger is narrow), `width`, `size`, `label`, `disabled`, `success`, `required`, `optional`, `ariaLabel`
|
|
208
230
|
|
|
209
|
-
#### `<ds-
|
|
210
|
-
|
|
211
|
-
Inputs: `options: readonly
|
|
212
|
-
|
|
231
|
+
#### `<ds-autocomplete>` — `AutocompleteComponent<T>`
|
|
232
|
+
Type-ahead picker, generic on the option value.
|
|
233
|
+
Inputs: `options: readonly AutocompleteItem<T>[]`, `value: model<T | readonly T[] | null>`, `multiple: boolean = false`, `placeholder: string = 'Select…'`, `showChevron: boolean = true`, `valueOverflow: AutocompleteValueOverflow = 'ellipsis'` (`'ellipsis' | 'wrap'` — a settled single value clips rather than growing the trigger), `maxVisibleChips`, `allowCreate: boolean = false`, `width`, `size`, `label`, `disabled`, `success`, `required`, `optional`, `ariaLabel`
|
|
234
|
+
Output: `(create): string` — the typed text, when `allowCreate` is on and nothing matched.
|
|
235
|
+
In multiple mode the selection renders as chips above the trigger.
|
|
213
236
|
|
|
214
237
|
#### `<ds-search>` — `SearchComponent`
|
|
215
238
|
Pre-styled search input with built-in icon. A form control, but not a field: no label, no message row.
|
|
216
239
|
Inputs: `value: model<string>`, `placeholder: string = 'Search'`, `shortcut: string = ''` (rendered as a hint pill, e.g. `⌘K`), `showIcon: boolean = true`, `clearable: boolean = false`, `ariaLabel: string = ''`, `disabled: boolean = false`, `hidden: boolean = false`, `size: DsSize | null = null`, `debounce: number = 0` (ms held before `value` updates; clearing, Enter and `clear()` all skip the timer)
|
|
217
240
|
Output: `(submitted): string` — emits the current value on Enter / form submit
|
|
218
241
|
Methods: `clear()` — empties the field, drops an armed keystroke and publishes `''` at once, which writing `''` into `value` does not; `focus()`.
|
|
219
|
-
Binds through `NG_VALUE_ACCESSOR`, taking the
|
|
242
|
+
Binds through `NG_VALUE_ACCESSOR`, taking the value plumbing without the field-message layer — so `hint` / `error` / `warning` / `errors` / `invalid` / `touched` / `reserveMessage` / `messageIcon` are NOT inputs here.
|
|
220
243
|
|
|
221
244
|
#### `<ds-date-picker>` — `DatePickerComponent`
|
|
222
245
|
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`
|
|
@@ -299,13 +322,13 @@ When `expandable=true` renders header button with toggle + caret; collapses body
|
|
|
299
322
|
#### `<ds-sidenav-item>` — `SidenavItemComponent`
|
|
300
323
|
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`, `rail: boolean | null = null` (draws the active item's edge marker; unset follows the parent `ds-sidenav`)
|
|
301
324
|
Content slots: `[icon]` (custom icon when not using a DS IconName), `[trailing]` (right-aligned chrome — badges, indicators, kbd shortcuts)
|
|
302
|
-
**Three elements, decided by destination.** `routerLink` → an `<a [routerLink]>` with `routerLinkActive`; `href` → a plain `<a href>`; **neither → a `<button type="button">`**. Until 0.11.0 the last case fell back to `href="#"`, which navigates: it rewrites the URL and discards the scroll position on every click
|
|
325
|
+
**Three elements, decided by destination.** `routerLink` → an `<a [routerLink]>` with `routerLinkActive`; `href` → a plain `<a href>`; **neither → a `<button type="button">`**. Until 0.11.0 the last case fell back to `href="#"`, which navigates: it rewrites the URL and discards the scroll position on every click. An item that only emits `activate` is a button. Styling is identical across all three — the rules are class-based (`.item`) and the button's UA chrome is reset — so target the class, never the tag.
|
|
303
326
|
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: `--accent-subtitle` — a wash, not a solid pill), `--ds-sidenav-item-label-color-active` (default: `--accent-strong`), `--ds-sidenav-item-bg-color-active-hover` (default: `--accent-muted`, deepening toward the accent), `--ds-sidenav-item-rail` (left rail, default: `--accent-strong`), `--ds-sidenav-item-radius`, `--ds-sidenav-alert-color`
|
|
304
327
|
|
|
305
328
|
#### `<ds-topbar>` — `TopBarComponent`
|
|
306
329
|
No inputs.
|
|
307
330
|
Content slots: `[title]`, `[breadcrumbs]`, `[search]`, `[actions]`. Sits at `--topbar-h` height.
|
|
308
|
-
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.
|
|
331
|
+
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.
|
|
309
332
|
|
|
310
333
|
#### `<ds-app-layout>` — `AppLayoutComponent`
|
|
311
334
|
Inputs: `topbarSpan: 'content' | 'full' = 'content'`, `railOpen: model<boolean> = false` (the overlay rail below `--bp-lg`), `railLabel: string = 'Navigation'`, `restoreScroll: boolean = false`, `restoreScrollTimeout: number = 2000` (ms), `scrollReset: 'path' | 'always' | 'never' = 'path'`
|
|
@@ -359,7 +382,7 @@ Inputs: `elevation: 'flat' | 'raised' | 'hover' | 'interactive' = 'flat'`, `padd
|
|
|
359
382
|
Output: `(pressed): MouseEvent` — fires only when `elevation="interactive"`
|
|
360
383
|
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`, `--ds-card-overflow`
|
|
361
384
|
Full-bleed child: a child whose background reaches the card edge paints square corners over the radius, and the host cannot fix it — the rounded box is the card's inner element. Set `--ds-card-overflow: clip` (`clip`, not `hidden`, so the card stays out of the scroll-container business). It is opt-in because a clipped card also cuts the focus ring off a child at its edge; where the clipped card holds focusable content, pair it with `data-focus="inset"`.
|
|
362
|
-
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;
|
|
385
|
+
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; a brand can step it down to `var(--font-size-h5)`). 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`.
|
|
363
386
|
|
|
364
387
|
#### `<ds-accordion>` + `<ds-accordion-item>` — `AccordionComponent`, `AccordionItemComponent`
|
|
365
388
|
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).
|
|
@@ -437,14 +460,14 @@ All built-in icons (kebab-case where indicated, camelCase otherwise — DS uses
|
|
|
437
460
|
|
|
438
461
|
`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`
|
|
439
462
|
|
|
440
|
-
|
|
463
|
+
Icons render inside `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor">`. For consumer-side icons without forking DS, use `provideDsIcons(…)` below.
|
|
441
464
|
|
|
442
465
|
#### `DS_ICON_REGISTRY` / `provideDsIcons(icons)`
|
|
443
466
|
|
|
444
467
|
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).
|
|
445
468
|
|
|
446
469
|
```ts
|
|
447
|
-
import { provideDsIcons } from '
|
|
470
|
+
import { provideDsIcons } from '@ids-group-ltd/ids-design-system';
|
|
448
471
|
|
|
449
472
|
bootstrapApplication(AppComponent, {
|
|
450
473
|
providers: [
|
|
@@ -467,7 +490,7 @@ Lookup order: built-in `ICONS` first, then the consumer registry. Names that col
|
|
|
467
490
|
Inject `DS_CONFIG` token (default factory returns `{}`) to set library-wide defaults that consumer-level component inputs can still override.
|
|
468
491
|
|
|
469
492
|
```ts
|
|
470
|
-
import { provideDsConfig } from '
|
|
493
|
+
import { provideDsConfig } from '@ids-group-ltd/ids-design-system';
|
|
471
494
|
|
|
472
495
|
bootstrapApplication(AppComponent, {
|
|
473
496
|
providers: [
|
|
@@ -478,9 +501,9 @@ bootstrapApplication(AppComponent, {
|
|
|
478
501
|
});
|
|
479
502
|
```
|
|
480
503
|
|
|
481
|
-
`DsConfig` shape (
|
|
504
|
+
`DsConfig` shape (the exported `DsConfig` type is the full contract):
|
|
482
505
|
|
|
483
|
-
Twelve sections. `
|
|
506
|
+
Twelve sections. The exported `DsConfig` type is the source of truth — each key carries its own
|
|
484
507
|
doc comment there, including why it is an app-level decision at all.
|
|
485
508
|
|
|
486
509
|
```ts
|
|
@@ -542,7 +565,7 @@ this.crumbs.clear();
|
|
|
542
565
|
|
|
543
566
|
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).
|
|
544
567
|
|
|
545
|
-
2. **Route-driven** — annotate routes with `data.breadcrumb` and run a Router→Service bridge once at app bootstrap.
|
|
568
|
+
2. **Route-driven** — annotate routes with `data.breadcrumb` and run a Router→Service bridge once at app bootstrap. `breadcrumb` accepts:
|
|
546
569
|
- `string` → `{ label: string, href: <built-from-url> }`
|
|
547
570
|
- `BreadcrumbItem`
|
|
548
571
|
- `BreadcrumbItem[]`
|
package/design-system.md
CHANGED
|
@@ -3,7 +3,8 @@
|
|
|
3
3
|
> **This file is the HOW.** Which spacing goes between what, which type role a piece of
|
|
4
4
|
> text takes, where a value belongs and where a literal is a bug. For the WHAT — the
|
|
5
5
|
> inventory of components, their inputs and their tokens — see `components.md`, and
|
|
6
|
-
> prefer the
|
|
6
|
+
> prefer the Component API and token reference on the documentation site
|
|
7
|
+
> (https://ids-ds.proto.ids-group.co.uk/), which are generated from source
|
|
7
8
|
> on every build and cannot go stale.
|
|
8
9
|
>
|
|
9
10
|
> **Audience: whoever composes a screen, human or agent.** Knowing the 639 tokens is not
|
|
@@ -139,10 +140,9 @@ the next reader of your CSS.
|
|
|
139
140
|
Measured by which property each one actually lands on, across every component that uses one:
|
|
140
141
|
|
|
141
142
|
- **`--<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
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
glyph-on-tint pair is the pattern to copy**, and the reason not to put prose in this member:
|
|
143
|
+
`color` of a MARKER — a required asterisk, an icon badge's glyph. Every `color: var(--error)`
|
|
144
|
+
declaration in this library lands on a marker of that kind: an asterisk, or a glyph sitting on an
|
|
145
|
+
`--error-subtitle` tint. **That glyph-on-tint pair is the pattern to copy**, and the reason not to put prose in this member:
|
|
146
146
|
it is contrast-checked as a large glyph, not as text.
|
|
147
147
|
- **`--<status>-text`** — `color`, on a light surface. This is the contrast-safe member, and the
|
|
148
148
|
one you want for a message.
|
|
@@ -193,7 +193,7 @@ and `--ds-motion-exit-*`, which is deliberately FASTER than its entrance.
|
|
|
193
193
|
|
|
194
194
|
### Transition properties, not `all`
|
|
195
195
|
|
|
196
|
-
|
|
196
|
+
In this library: `background-color` (20), `transform` (12), `color` (10), `border-color` (5),
|
|
197
197
|
`opacity` (2). Nothing in the library transitions `all`, and only three places transition a
|
|
198
198
|
`width` — animating a layout property costs a reflow per frame. Prefer `transform` and
|
|
199
199
|
`opacity`; if you find yourself animating `height`, the answer is usually a `grid-template-rows`
|
|
@@ -219,11 +219,11 @@ anything with an exit.
|
|
|
219
219
|
|
|
220
220
|
### Labels are sentence case
|
|
221
221
|
|
|
222
|
-
|
|
222
|
+
Most multi-word labels in this system already are, and the
|
|
223
223
|
apparent exceptions are not exceptions — they are acronyms and notation the case rule does not
|
|
224
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. `
|
|
226
|
-
`
|
|
225
|
+
and whatever is a proper noun or an acronym, and nothing else. `Order history`, not
|
|
226
|
+
`Order History`. No trailing colon: the field's shape already says a value follows.
|
|
227
227
|
|
|
228
228
|
Mark the exception, not the rule. `required` is the default expectation in most forms, so
|
|
229
229
|
`ds-input` and its siblings carry an `optional` input that renders "(optional)" rather than
|
|
@@ -238,19 +238,19 @@ told the user nothing in four different ways. The pattern's own worked examples
|
|
|
238
238
|
|
|
239
239
|
| Variant | Title says the SITUATION | Body says the NEXT STEP or the CAUSE |
|
|
240
240
|
| --- | --- | --- |
|
|
241
|
-
| `none` | "No
|
|
242
|
-
| `error` | "Couldn't load
|
|
243
|
-
| `locked` | "You don't have access to this
|
|
241
|
+
| `none` | "No items in this order yet" | "Add a product from the catalogue to start building it." |
|
|
242
|
+
| `error` | "Couldn't load the order lines" | "Network error — the request timed out after 30 seconds." |
|
|
243
|
+
| `locked` | "You don't have access to this warehouse" | "Warehouses are restricted to the Operations and Manager roles. Ask your workspace admin." |
|
|
244
244
|
|
|
245
|
-
Three things to copy from those: the title is a **statement, not a label** — "No
|
|
246
|
-
|
|
245
|
+
Three things to copy from those: the title is a **statement, not a label** — "No items
|
|
246
|
+
in this order yet", never "Empty"; the error body names a **concrete** cause with the number in it,
|
|
247
247
|
not "Something went wrong"; and the locked body names **who can unblock them**, because a
|
|
248
248
|
permission wall with no next step is a dead end.
|
|
249
249
|
|
|
250
250
|
### A message says what happened, what follows, and what to do
|
|
251
251
|
|
|
252
|
-
The library holds itself to this.
|
|
253
|
-
printed
|
|
252
|
+
The library holds itself to this. Every message it prints is tagged with the component that
|
|
253
|
+
printed it (`[ds-table] …`), states the consequence, and where there is one names the
|
|
254
254
|
fix outright:
|
|
255
255
|
|
|
256
256
|
> `[ds-table] lazy needs virtualScroll: without a window there is no range to fetch, so every
|
|
@@ -309,8 +309,8 @@ internals.
|
|
|
309
309
|
## 8. Where the rest lives
|
|
310
310
|
|
|
311
311
|
The decisions this file does NOT make are the ones about which COMPONENT to reach for, and they
|
|
312
|
-
have their own home:
|
|
312
|
+
have their own home: the documentation site's `Practice → Do / Don't` (modal vs drawer, button hierarchy, table
|
|
313
313
|
density, badge proliferation, status without colour, tooltips vs banners) and
|
|
314
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
|
|
315
|
+
inventory is `components.md`; the generated Component API and token reference on the documentation site are
|
|
316
316
|
extracted from source on every build and are the only surfaces that cannot go stale.
|