Mercurial

annotate design_system/TOKENS.md @ 268:f7b1188d5fb1

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