@ids-group-ltd/ids-design-system 0.8.0 → 0.9.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/CHANGELOG.md +377 -0
- package/components.md +500 -0
- package/design-system.md +145 -0
- package/fesm2022/ids-group-ltd-ids-design-system.mjs +1245 -371
- package/fesm2022/ids-group-ltd-ids-design-system.mjs.map +1 -1
- package/migrations/0.9.0.json +157 -0
- package/migrations/README.md +8 -1
- package/migrations/unreleased/README.md +134 -0
- package/package.json +1 -1
- package/styles/_dropdown-overlay.scss +34 -7
- package/styles/_field-box.scss +8 -3
- package/styles/_surface-motion.scss +48 -3
- package/styles/_tokens.scss +1 -4
- package/types/ids-group-ltd-ids-design-system.d.ts +631 -113
package/design-system.md
ADDED
|
@@ -0,0 +1,145 @@
|
|
|
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. Overriding a component
|
|
112
|
+
|
|
113
|
+
Set the component's own `--ds-*` token **on the host element**, scoped as narrowly as the
|
|
114
|
+
change deserves:
|
|
115
|
+
|
|
116
|
+
```scss
|
|
117
|
+
ds-select { --ds-field-height: 44px; } /* every select */
|
|
118
|
+
.toolbar ds-select { --ds-field-height: 32px; } /* only in the toolbar */
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Defaults are declared on `:host` (or the component's root class) with a read-with-fallback
|
|
122
|
+
chain, so a consumer declaration cascades in without `!important` and without knowing the
|
|
123
|
+
internals.
|
|
124
|
+
|
|
125
|
+
**Two things that break this, both by design:**
|
|
126
|
+
|
|
127
|
+
- **Reaching for an internal class** — `ds-button .button.v-tonal { … }` — works until the
|
|
128
|
+
internals move. Components reflect what you need on the host instead: `ds-button` carries
|
|
129
|
+
`[data-variant]` and `[data-color]`, so `ds-button[data-variant="outline"]` is the
|
|
130
|
+
supported form.
|
|
131
|
+
- **Portaled panels.** A dropdown, a date picker's calendar and a modal render under
|
|
132
|
+
`<body>`, outside the host's subtree, so a host-scoped declaration cannot reach them.
|
|
133
|
+
Those components forward their own panel tokens onto the pane on open, and the theme's
|
|
134
|
+
radius and elevation ROLES travel with them when the host overrides one. A token that is
|
|
135
|
+
neither is best set at `:root`.
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## 5. What this file does not cover yet
|
|
140
|
+
|
|
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.
|