Mercurial

diff 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
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/design_system/TOKENS.md	Wed Aug 05 05:25:40 2026 -0700
@@ -0,0 +1,83 @@
+# Zenbu UI token architecture
+
+Zenbu UI uses three CSS custom-property layers:
+
+```text
+Reference values       Semantic system roles       Local component aliases
+--zenbu-ref-*          --zenbu-sys-*               --zenbu-<component>-*
+```
+
+## Reference values
+
+`reference.css` defines context-free values: color ramps, spacing, type sizes,
+weights, line heights, radii, strokes, shadows, durations, easing, opacity,
+icon sizes, control sizes, and z-index levels.
+
+Reference values answer what exists in the system. Application and component
+CSS must not consume reference colors directly.
+
+## Semantic roles
+
+`semantic.css` maps reference values to stable intent:
+
+```css
+var(--zenbu-sys-color-text-primary)
+var(--zenbu-sys-color-surface-raised)
+var(--zenbu-sys-color-action-primary-background)
+var(--zenbu-sys-type-body-size)
+var(--zenbu-sys-space-container)
+var(--zenbu-sys-radius-control)
+var(--zenbu-sys-motion-duration-state)
+```
+
+Themes and density change semantic assignments. Component selectors continue
+to consume the same roles.
+
+## Local aliases
+
+Components use private aliases where variants remap one internal role:
+
+```css
+zen-button:not([appearance="plain"]) > button {
+  --zenbu-button-background:
+    var(--zenbu-sys-color-action-primary-background);
+  background: var(--zenbu-button-background);
+}
+```
+
+Do not turn every internal declaration into public API. A local alias becomes a
+documented host override only when multiple applications need that stable
+customization point.
+
+## Themes and density
+
+Themes use `data-zen-theme`; density uses `data-zen-density`:
+
+```html
+<html data-zen-theme="paper" data-zen-density="compact">
+```
+
+Available densities:
+
+- no attribute or `comfortable`: canonical five-step control sizes;
+- `compact`: reduced visual heights, padding, and gaps.
+
+Explicit component `size="xs|sm|md|lg|xl"` maps through density-aware semantic
+tokens.
+
+## Compatibility
+
+Older `--zen-*` variables remain temporarily in `tokens.css` as aliases. New
+code must use `--zenbu-ref-*`, `--zenbu-sys-*`, or a documented local
+`--zenbu-<component>-*` alias.
+
+## Enforcement
+
+`//design_system/test:design_system_policy_test` checks:
+
+- raw colors appear only in token source files;
+- every referenced `--zenbu-*` property is declared;
+- component CSS does not consume reference colors directly;
+- source and documentation use first-party naming;
+- exported JavaScript APIs retain typed documentation;
+- icon and dependency policies remain intact.