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

## Bazel targets

```bash
bazel run //design_system:dev
bazel test //design_system/test:storybook_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.