Mercurial

comparison design_system/TOKENS.md @ 258:60a876c4587a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ui] Add semantic primitive ownership Build a layered Zenbu token and sizing system, make authored controls use native-underneath primitives, migrate mrjunejune without imposing visual surfaces, and document/enforce HTML ownership in the catalog and wiki. Co-authored-by: Copilot <[email protected]>
author MrJuneJune <me@mrjunejune.com>
date Wed, 05 Aug 2026 05:25:40 -0700
parents
children
comparison
equal deleted inserted replaced
257:609d3c6aff4e 258:60a876c4587a
1 # Zenbu UI token architecture
2
3 Zenbu UI uses three CSS custom-property layers:
4
5 ```text
6 Reference values Semantic system roles Local component aliases
7 --zenbu-ref-* --zenbu-sys-* --zenbu-<component>-*
8 ```
9
10 ## Reference values
11
12 `reference.css` defines context-free values: color ramps, spacing, type sizes,
13 weights, line heights, radii, strokes, shadows, durations, easing, opacity,
14 icon sizes, control sizes, and z-index levels.
15
16 Reference values answer what exists in the system. Application and component
17 CSS must not consume reference colors directly.
18
19 ## Semantic roles
20
21 `semantic.css` maps reference values to stable intent:
22
23 ```css
24 var(--zenbu-sys-color-text-primary)
25 var(--zenbu-sys-color-surface-raised)
26 var(--zenbu-sys-color-action-primary-background)
27 var(--zenbu-sys-type-body-size)
28 var(--zenbu-sys-space-container)
29 var(--zenbu-sys-radius-control)
30 var(--zenbu-sys-motion-duration-state)
31 ```
32
33 Themes and density change semantic assignments. Component selectors continue
34 to consume the same roles.
35
36 ## Local aliases
37
38 Components use private aliases where variants remap one internal role:
39
40 ```css
41 zen-button:not([appearance="plain"]) > button {
42 --zenbu-button-background:
43 var(--zenbu-sys-color-action-primary-background);
44 background: var(--zenbu-button-background);
45 }
46 ```
47
48 Do not turn every internal declaration into public API. A local alias becomes a
49 documented host override only when multiple applications need that stable
50 customization point.
51
52 ## Themes and density
53
54 Themes use `data-zen-theme`; density uses `data-zen-density`:
55
56 ```html
57 <html data-zen-theme="paper" data-zen-density="compact">
58 ```
59
60 Available densities:
61
62 - no attribute or `comfortable`: canonical five-step control sizes;
63 - `compact`: reduced visual heights, padding, and gaps.
64
65 Explicit component `size="xs|sm|md|lg|xl"` maps through density-aware semantic
66 tokens.
67
68 ## Compatibility
69
70 Older `--zen-*` variables remain temporarily in `tokens.css` as aliases. New
71 code must use `--zenbu-ref-*`, `--zenbu-sys-*`, or a documented local
72 `--zenbu-<component>-*` alias.
73
74 ## Enforcement
75
76 `//design_system/test:design_system_policy_test` checks:
77
78 - raw colors appear only in token source files;
79 - every referenced `--zenbu-*` property is declared;
80 - component CSS does not consume reference colors directly;
81 - source and documentation use first-party naming;
82 - exported JavaScript APIs retain typed documentation;
83 - icon and dependency policies remain intact.