@dcs-tech/tokens 0.0.0-stage → 0.15.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 +32 -0
- package/README.md +73 -2
- package/dist/tokens.d.ts +841 -0
- package/dist/tokens.js +900 -0
- package/package.json +46 -4
- package/src/tokens.css +921 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# @dcs-tech/tokens
|
|
2
|
+
|
|
3
|
+
## 0.15.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- c9eb745: Icon sizes follow MUI's model, sized to the reference app: **an icon's size comes from the slot it sits in, never from the text around it.** A visual change in every app.
|
|
8
|
+
|
|
9
|
+
- **One slot table**: `ICON_SLOT_SIZES` / type `IconSlot` in core and `--icon-slot-*` tokens (× `--ui-scale`): `button` 16 (icon buttons, the icon beside a small / medium Button's label), `prominent` 18 (app bar icon buttons, large / xl Buttons), `nav` 16 (Sidebar incl. rail, NavList, menu and option rows), `inline` 14 (chevrons, breadcrumb separators, sort arrows, header ⋮), `field` 16 (adornments, prefix / suffix, field icons), `dense` 13 (chips, xs / xxs Buttons, the table footer's pagination), `default` 16 (an icon in no slot). Every library component now sets one of these; the per-component numbers are gone.
|
|
10
|
+
- **Button**: `BUTTON_ICON_SLOTS` — xxs / xs → 13, small / medium → 16, large / xl → 18, with or without a label (medium icon-only was 20, large 24, xl 28; a label icon was 1em of the label).
|
|
11
|
+
- **Sidebar** top-level rows are 40px tall (the 16px nav icon and 12px above and below), the rail too; their icons are 16 (were 12). Child rows are a step smaller, as the reference app's: 30px tall, 13px icons, regular weight; a child row's trailing action fits the row. The collapse bar's chevron is 18 (was 14), the reference app's.
|
|
12
|
+
- **App bar** icon buttons carry 18px icons: an open line drawing reads larger than a filled glyph of the same extent, so 18 matches the reference app's 20px filled icons by eye.
|
|
13
|
+
- **Drawing margin**: the library's line icons (`IconDefinition.inset`, new) get Material's live area — the viewBox is inset by `ICON_INSET` (1.5 grid units; `iconInset`, `iconViewBox`) and the stroke thickened by `ICON_INSET_STROKE` (1.125), so an icon's ink fills about 76–83% of its box like Material's (was 84–92%) at the same line weight. Brand icons, artwork, wide icons and your own drawings are unchanged.
|
|
14
|
+
- **Icon-only Buttons without a `color` now use the text colour (`neutral`), like MUI's IconButton** (`resolveButtonColor`); a Button with a label stays `primary`, and a ButtonGroup's colour still wins.
|
|
15
|
+
- React Native: the same slot tokens through `useTokens()`, the same Button sizes, the same drawing margin and the same default colour.
|
|
16
|
+
|
|
17
|
+
Upgrading:
|
|
18
|
+
|
|
19
|
+
- An icon with no `size` outside a library component is now **16px** (it was 1em of the text around it). For an icon inside running text, pass **`size="inherit"`** (new, like MUI `fontSize="inherit"`).
|
|
20
|
+
- An explicit `size` (a name or pixels) still wins everywhere. The `--icon-size-*` tokens and the `action` / `marker` / `chip` / `status` names still work.
|
|
21
|
+
- Icon-only Buttons that should stay blue need `color="primary"`.
|
|
22
|
+
- Your own `IconDefinition`s are drawn edge to edge as before; add `inset: true` to give one the library's margin.
|
|
23
|
+
- A container of your own can size the icons in it with `--dcs-icon-size: var(--icon-slot-…)`.
|
|
24
|
+
|
|
25
|
+
- c9eb745: Script tokens: a font stack and line heights for Tamil and Devanagari, which apply by themselves
|
|
26
|
+
under `:lang(ta)` / `:lang(hi)`. An app only sets `<html lang="ta">` (or `lang` on a section),
|
|
27
|
+
and loads 'Noto Sans Tamil' / 'Noto Sans Devanagari' if it wants them; the library does not load
|
|
28
|
+
them, and without them the system's font is used. New tokens: `--font-sans-tamil`,
|
|
29
|
+
`--font-sans-devanagari`, and `--line-height-{tight,snug,normal}-{tamil,devanagari}`. They are also
|
|
30
|
+
in `tokens.ts` / `tokens.dart` (`fontSansTamil`, `lineHeightSnugDevanagari`, …), so a native app
|
|
31
|
+
can pick them by its locale. Latin text keeps `--font-sans` and the line heights it had.
|
|
32
|
+
- 3357a5b: New package `@dcs-tech/tokens`: the design tokens from one hand-edited source, for every platform. `tokens.css` (the same file `@dcs-tech/ui` always shipped, as `@dcs-tech/tokens/tokens.css`) for the web; generated from it, `tokens.ts` for React Native and any TypeScript (`light`, `dark`, `reducedMotion`, `uiScaled`: every token as plain data, keys in camel case) and `tokens.dart` for Flutter. `@dcs-tech/ui` takes its tokens from it; `style.css` and everything else it ships are byte-for-byte unchanged, so nothing changes for a web app. The two packages now always share a version.
|
package/README.md
CHANGED
|
@@ -1,3 +1,74 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @dcs-tech/tokens
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The design tokens of the DCS Tech UI library: colours, sizes, spacing, radii, shadows, motion
|
|
4
|
+
and layers, from one hand-edited source, for every platform.
|
|
5
|
+
|
|
6
|
+
| File | For | What it is |
|
|
7
|
+
|---|---|---|
|
|
8
|
+
| `src/tokens.css` | web | **The source.** CSS custom properties; edited by hand |
|
|
9
|
+
| `src/tokens.ts` → `dist/` | React Native, any TypeScript | generated: every token as plain data |
|
|
10
|
+
| `dart/lib/tokens.dart` | Flutter | generated: the same tokens as Dart constants |
|
|
11
|
+
|
|
12
|
+
`@dcs-tech/ui` already includes `tokens.css` in its `style.css`; a web app needs nothing more.
|
|
13
|
+
|
|
14
|
+
## Web
|
|
15
|
+
|
|
16
|
+
```css
|
|
17
|
+
@import '@dcs-tech/tokens/tokens.css';
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
`[data-theme="dark"]` on `<html>` switches to the dark theme; `--ui-scale` scales the UI.
|
|
21
|
+
|
|
22
|
+
## TypeScript / React Native
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
import { light, dark, reducedMotion, uiScaled, type Tokens } from '@dcs-tech/tokens';
|
|
26
|
+
|
|
27
|
+
const t: Tokens = scheme === 'dark' ? dark : light;
|
|
28
|
+
<View style={{ padding: t.spacingMd, backgroundColor: t.bgSecondary }} />
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
- Keys are the CSS names in camel case: `--spacing-2xl` → `spacing2xl`. Each field's doc comment
|
|
32
|
+
names its CSS variable and unit.
|
|
33
|
+
- `light` and `dark` hold the same keys, at UI scale 1.
|
|
34
|
+
- `uiScaled` lists the sizes that follow the UI scale: multiply them by it. Radii, borders and
|
|
35
|
+
breakpoints do not scale, as on the web.
|
|
36
|
+
- `reducedMotion` is what changes under the OS reduce-motion setting: spread it over the theme.
|
|
37
|
+
|
|
38
|
+
| Kind | Value |
|
|
39
|
+
|---|---|
|
|
40
|
+
| colour | `'#rrggbb'`, or `'rgba(r, g, b, a)'` when translucent |
|
|
41
|
+
| length | px (dp), a number |
|
|
42
|
+
| duration | ms, a number |
|
|
43
|
+
| percentage | a fraction 0–1 |
|
|
44
|
+
| easing | `{ type: 'cubicBezier', x1, y1, x2, y2 }` or `{ type: 'linear', stops: [{ value, at }] }` |
|
|
45
|
+
| shadow | `[{ offsetX, offsetY, blur, spread, color, inset }]`, in CSS terms (`[]` is none) |
|
|
46
|
+
| font family | the list, first choice first |
|
|
47
|
+
| fluid size | `{ min, max, fromWidth, toWidth }`: `min` up to `fromWidth`, `max` from `toWidth`, a straight line between (the headings; CSS `clamp()` with `vw`) |
|
|
48
|
+
|
|
49
|
+
## Flutter
|
|
50
|
+
|
|
51
|
+
`dart/` is a Dart package (`dcs_tech_tokens`, not published on its own; the Flutter library
|
|
52
|
+
uses it). `DcsTokens.light` / `DcsTokens.dark`, then `.withUiScale(scale)` and
|
|
53
|
+
`.withReducedMotion()`. Colours are `Color`, durations `Duration`, easings `Curve`, sizes `double`.
|
|
54
|
+
Shadows are `DcsShadow` with CSS numbers: CSS blur is not `BoxShadow.blurRadius`, so widgets
|
|
55
|
+
convert.
|
|
56
|
+
|
|
57
|
+
## Web only
|
|
58
|
+
|
|
59
|
+
A few tokens are CSS constructs with no plain value — a gradient, a transform, a transition
|
|
60
|
+
list, `currentColor`, a size relative to `1em`. They are listed, each with its reason, at the
|
|
61
|
+
top of both generated files and in `scripts/config.ts`.
|
|
62
|
+
|
|
63
|
+
## Changing a token
|
|
64
|
+
|
|
65
|
+
1. Edit `src/tokens.css` (rules: DESIGN_TOKENS.md in the repository).
|
|
66
|
+
2. `npm run generate --workspace=@dcs-tech/tokens` — loads the file in Chromium and writes both
|
|
67
|
+
generated files. Needs Chromium once: `npx playwright install chromium`.
|
|
68
|
+
3. With the Flutter SDK: `cd dart && flutter pub get && dart analyze && flutter test`.
|
|
69
|
+
`npm test` checks `tokens.dart` only as text.
|
|
70
|
+
4. Commit all three.
|
|
71
|
+
|
|
72
|
+
The generator fails, naming the token, on anything it cannot turn into a plain value; it never
|
|
73
|
+
skips a token or guesses. `npm run build` fails if the generated files are older than
|
|
74
|
+
`tokens.css` or were edited by hand.
|