---
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/tokens.css`: shared `--zen-*` design tokens.
- `design_system/src/styles/components.css`: component presentation.
- `design_system/src/index.html`: declarative component stories.
- `design_system/src/storybook.js` and `storybook.css`: catalog shell.
- `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.
- 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; do not import Sonner or Radix.
- Preserve keyboard, form, validity, label, and ARIA behavior.
- Prefix custom elements and tokens with `zen-` / `--zen-`.
- Keep selectors low-specificity so applications can override tokens.
- 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.
- Use semantic `--zen-color-*` aliases in component CSS. Use primitive ramps
  or the ten data tokens only when a semantic role does not fit; never encode
  meaning through color alone.
- Raw color literals are forbidden outside `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:storybook_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.