Mercurial

view design_system/TOKENS.md @ 279:b3b547563ec7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add Google connector service and agent wiki Implement the C/Seobeo Google Drive and Gmail connector with encrypted OAuth storage, Zenbu authentication, browser testing, AI tool discovery, chunked HTTP decoding, and Bazel coverage. Consolidate repository guidance into progressive wiki documentation and enforce arena-first allocation for new first-party C code. Co-authored-by: Copilot <[email protected]> Copilot-Session: 84c338fd-0939-4bb3-b7f3-1062eb213e5d
author MrJuneJune <me@mrjunejune.com>
date Mon, 17 Aug 2026 22:22:36 -0700
parents 60a876c4587a
children
line wrap: on
line source

# 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.