---
name: zenbu-design-system
description: Use this skill when changing Zenbu UI Web Components, design tokens, component stories, catalog routes, or cross-project design-system assets.
---

# Zenbu UI design system

## Structure

- `design_system/src/components/`: dependency-free ES module Web Components.
- `design_system/src/styles/reference.css`: context-free `--zenbu-ref-*` scales.
- `design_system/src/styles/semantic.css`: theme-aware `--zenbu-sys-*` roles.
- `design_system/src/styles/density.css`: comfortable/compact role mappings.
- `design_system/src/styles/components.css` and `elements.css`: presentation.
- `design_system/src/styles/tokens.css`: compatibility aliases only.
- `design_system/src/index.html`: declarative component stories.
- `design_system/src/catalog.js`, `component_catalog.js`, and `catalog.css`:
  catalog shell and story inventory.
- `design_system/main.c`: Seobeo catalog server.

## Component conventions

- Stay close to native HTML and use light DOM.
- Wrap native interactive elements instead of recreating form/link semantics.
- Keep behavior reusable without forcing presentation. Support
  `appearance="plain"` for button/card/field integrations, and require visual
  surfaces, borders, shadows, and backgrounds to be deliberate opt-ins at the
  application boundary.
- Do not wrap existing content in a visual component merely to demonstrate
  design-system adoption; use components only where they add behavior,
  semantics, or an explicitly requested visual recipe.
- Do not add framework or runtime dependencies.
- Keep application state outside components.
- Keep notification action tokens opaque and out of DOM attributes; use scoped,
  non-composed `zen-notify` events and bounded queues.
- Keep `zen-notifications` behavior aligned with
  `design_system/NOTIFICATIONS.md`.
- Notification presentation uses a measured collapsed depth stack that expands
  on hover/focus and remains entirely first-party.
- Preserve keyboard, form, validity, label, and ARIA behavior.
- Prefix custom elements and canonical tokens with `zen-` / `--zenbu-`.
- Keep selectors low-specificity so applications can override tokens.
- Use the canonical `xs` / `sm` / `md` / `lg` / `xl` scale for typography,
  control heights, block/inline padding, gaps, icons, and containers. Do not
  introduce one-off component dimensions when a scale token fits.
- Plain controls inherit `--zenbu-control-*` variables from their size attribute
  without receiving visual CSS; consuming applications should build their own
  appearance from those variables.
- Keep the token graph layered: `--zenbu-ref-*` defines context-free values,
  `--zenbu-sys-*` defines theme/density-aware intent, and private
  `--zenbu-<component>-*` aliases simplify variants. New component and
  application CSS must consume semantic roles rather than reference colors or
  deprecated `--zen-*` aliases.
- Support light, dark, reduced-motion, desktop, and mobile behavior.
- Disclosure, overlay, and collapsing surfaces require smooth tokenized motion
  plus a reduced-motion fallback. Native disclosure markers must be replaced by
  first-party `zen-icon` geometry.
- Reset browser chrome for design-system form controls and restyle every state
  with Zenbu tokens. Calendar and date-picker UI must use the first-party
  keyboard calendar rather than exposing the browser's default date picker.
- Browser acceptance must exercise every catalog route at desktop and mobile
  widths and reject horizontal page overflow.
- Preserve the warm, restrained MUJI-like visual character: paper neutrals,
  natural material colors, strong typography, and deliberate color accents.
- Treat themes as semantic-token compositions. Preserve the built-in Paper,
  Ink, and Playful themes plus automatic system light/dark behavior; components
  must not branch on theme names.
- Use semantic `--zenbu-sys-*` aliases in component CSS. Add a semantic role
  instead of consuming reference colors directly; never encode meaning through
  color alone.
- Raw color literals are forbidden outside `src/styles/reference.css` and the
  compatibility-only `src/styles/tokens.css`. Run
  `//design_system/test:design_system_policy_test` whenever styles, components,
  stories, or catalog markup changes.
- Render every interface icon with the first-party `zen-icon` component. Emoji,
  text-glyph icons, ad hoc SVG, icon fonts, and external icon packages are
  forbidden.
- Every exported JavaScript class, function, or constant requires Google-style
  JSDoc with its public type tags. The policy test must fail when documentation
  is missing.

## Bazel targets

```bash
bazel run //design_system:dev
bazel test //design_system/test:catalog_test
bazel test //design_system/test:design_system_policy_test
bazel build //design_system:design_system_server_bundle
```

Reusable targets:

- `//design_system:components`
- `//design_system:styles`
- `//design_system:web_assets`

## Story convention

Write stories declaratively with `zen-story` and a direct `template`. Every
component state should have a rendered example and visible source. Browser tests
must cover native semantics and interactions rather than only element presence.

## Wiki requirement

Read `design_system/wiki/README.md` before authoring application HTML. Follow
its one-owner native-underneath rules and update the wiki whenever a public
primitive or authoring contract changes.