@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.
@@ -0,0 +1,316 @@
1
+ # Design System — rules and approaches
2
+
3
+ > **This file is the HOW.** Which spacing goes between what, which type role a piece of
4
+ > text takes, where a value belongs and where a literal is a bug. For the WHAT — the
5
+ > inventory of components, their inputs and their tokens — see `components.md`, and
6
+ > prefer the ds-docs Component API and token reference, which are extracted from source
7
+ > on every build and cannot go stale.
8
+ >
9
+ > **Audience: whoever composes a screen, human or agent.** Knowing the 639 tokens is not
10
+ > enough to build a page with them: the tokens are a vocabulary, and these are the rules
11
+ > that decide which word.
12
+ >
13
+ > **Every rule below was measured against this library, not imported from general UI
14
+ > advice.** Where a generic rule and this file disagree, this file wins — it describes
15
+ > the system you are actually building on. The scale rule below is a live example.
16
+
17
+ ---
18
+
19
+ ## 1. Spacing
20
+
21
+ ### The scale is 4px-based WITH half-steps — not a 4/8 scale
22
+
23
+ ```
24
+ 0 · 2 · 4 · 6 · 8 · 10 · 12 · 16 · 20 · 24 · 32 · 40 · 48 · 56 · 64 · 80
25
+ ```
26
+
27
+ `--space-0-5` (2px), `--space-1-5` (6px) and `--space-2-5` (10px) are real, deliberate
28
+ steps used for the inside of small controls. A reviewer applying a strict "everything on
29
+ 4 or 8" rule will flag correct DS values as violations — that rule belongs to other
30
+ systems, not this one.
31
+
32
+ ### Which step, by distance
33
+
34
+ Measured across the library's own components (occurrence counts in parentheses), the
35
+ scale is used in four bands. Match the band to the relationship, not to a pixel target:
36
+
37
+ | Between | Token | Why |
38
+ | --- | --- | --- |
39
+ | Parts of one control — icon and its label, a chip and its × | `--space-1` (74) or `--space-2` (130) | They read as one object; more than 8px starts to separate them |
40
+ | Sibling controls in a row — a field and its button, two chips | `--space-2` (130) or `--space-3` (82) | Related, but individually clickable |
41
+ | Blocks inside a section — a heading and its table, stacked fields | `--space-4` (55) | The default "these belong together" gap |
42
+ | Sections of a page | `--space-6` (21) and up | A visible break in the reading order |
43
+
44
+ `--space-2` being the most-used value in the library is not an accident to copy blindly:
45
+ it is the dominant *intra-component* gap. Reaching for it between page sections is the
46
+ most common way a screen ends up feeling cramped.
47
+
48
+ ### Page gutters are already decided — do not re-pick them
49
+
50
+ The grid sets the horizontal rhythm per breakpoint tier, and a page should inherit it
51
+ rather than declare padding:
52
+
53
+ | Tier | Gutter | Margin |
54
+ | --- | --- | --- |
55
+ | ≤ 640px (4 col) | `--page-gutter-mobile` (12px) | `--page-margin-mobile` (16px) |
56
+ | 641–1024px (8 col) | `--page-gutter-tablet` (16px) | `--page-margin-tablet` (24px) |
57
+ | 1025–1440px (12 col) | `--page-gutter-desktop` (20px) | — |
58
+ | ≥ 1441px (12 col) | `--page-gutter-wide` (24px) | — |
59
+
60
+ ### Who owns the gap
61
+
62
+ A stack sets `gap`, and every child is expected to carry its own trailing space. That is
63
+ why `gap="none"` works on a column of fields: each field already reserves its message
64
+ row. The failure mode is reaching for `gap="md"` to rescue one child that does not — it
65
+ re-adds the doubled rhythm to every other child in the column. Fix the child, not the
66
+ container.
67
+
68
+ ---
69
+
70
+ ## 2. Type
71
+
72
+ ### Choose a ROLE, never a raw size
73
+
74
+ The library ships named roles. Use the class; the size, weight, line-height and tracking
75
+ come with it, and every one is retunable through `--ds-t-<role>-*` without touching the
76
+ call site.
77
+
78
+ | Role | Use for |
79
+ | --- | --- |
80
+ | `.t-display` | One number or word that IS the screen — a hero metric |
81
+ | `.t-h1` … `.t-h5` | Document hierarchy. A page title is `.t-h2` here more often than `.t-h1` |
82
+ | `.t-card-title` | The title inside a card or tile, which is not part of the page's heading outline |
83
+ | `.t-l` / `.t-m` / `.t-s` / `.t-xs` | Body copy, descending. `.t-s` is the workhorse for dense admin UI |
84
+ | `.t-overline` | The small uppercase eyebrow above a title |
85
+ | `.t-caption` | Supporting text under a control or figure |
86
+ | `.t-mono-inline` / `.t-mono-block` | Code, tokens, IDs — anything where character alignment carries meaning |
87
+ | `*-bold` variants | The same role, emphasised. Do not reach for a larger role to get weight |
88
+
89
+ Writing `font-size: var(--font-size-s)` by hand reproduces one of four properties the
90
+ role would have set, and silently opts out of every future retune.
91
+
92
+ ---
93
+
94
+ ## 3. Size and density
95
+
96
+ ### A control in a field row takes the field-height contract
97
+
98
+ `--ds-field-height` overrides the family; `--field-h-sm` / `-md` / `-lg` are the scale.
99
+ Every field-shaped control resolves it — inputs, selects, pickers, search, buttons, the
100
+ field group, the number stepper. A literal `height` on a control is a bug: it will not
101
+ line up with its neighbours and will not follow a density change.
102
+
103
+ ### Never express a rule in pixels
104
+
105
+ `[data-density]` retunes the private spacing and height tokens underneath everything
106
+ above. A value written as `12px` survives that; a value written as `var(--space-3)`
107
+ follows it. This is why every rule on this page names a token.
108
+
109
+ ---
110
+
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
282
+
283
+ Set the component's own `--ds-*` token **on the host element**, scoped as narrowly as the
284
+ change deserves:
285
+
286
+ ```scss
287
+ ds-select { --ds-field-height: 44px; } /* every select */
288
+ .toolbar ds-select { --ds-field-height: 32px; } /* only in the toolbar */
289
+ ```
290
+
291
+ Defaults are declared on `:host` (or the component's root class) with a read-with-fallback
292
+ chain, so a consumer declaration cascades in without `!important` and without knowing the
293
+ internals.
294
+
295
+ **Two things that break this, both by design:**
296
+
297
+ - **Reaching for an internal class** — `ds-button .button.v-tonal { … }` — works until the
298
+ internals move. Components reflect what you need on the host instead: `ds-button` carries
299
+ `[data-variant]` and `[data-color]`, so `ds-button[data-variant="outline"]` is the
300
+ supported form.
301
+ - **Portaled panels.** A dropdown, a date picker's calendar and a modal render under
302
+ `<body>`, outside the host's subtree, so a host-scoped declaration cannot reach them.
303
+ Those components forward their own panel tokens onto the pane on open, and the theme's
304
+ radius and elevation ROLES travel with them when the host overrides one. A token that is
305
+ neither is best set at `:root`.
306
+
307
+ ---
308
+
309
+ ## 8. Where the rest lives
310
+
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.