Mercurial

# 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.
author	MrJuneJune <me@mrjunejune.com>
date	Fri, 07 Aug 2026 07:34:12 -0700
parents	60a876c4587a
children