# Zenbu UI design system

Zenbu UI is a dependency-free set of light-DOM Web Components and CSS tokens.
It stays close to ordinary HTML: components wrap native controls and sectioning
elements instead of replacing their semantics.

## Catalog

Run the Seobeo-backed component catalog:

```bash
bazel run //design_system:dev
```

Open `http://127.0.0.1:6980`. Override the port with
`DESIGN_SYSTEM_PORT`.

The catalog is intentionally Storybook-like without depending on Storybook. Its
stories are declared as HTML templates:

```html
<zen-story name="Primary button">
  <template>
    <zen-button>
      <button type="button">Save</button>
    </zen-button>
  </template>
</zen-story>
```

The story component renders the example and its source side by side.

## Reuse

Reusable assets are public Bazel targets:

```text
//design_system:components
//design_system:styles
//design_system:web_assets
```

Applications should copy the assets while preserving `components/` and
`styles/`, then load:

```html
<link rel="stylesheet" href="/design-system/styles/tokens.css">
<link rel="stylesheet" href="/design-system/styles/components.css">
<script type="module" src="/design-system/components/index.js"></script>
```

Every visual token is a `--zen-*` custom property and can be overridden by the
application.

## Native HTML contract

| Component | Native content | Attributes | Events |
| --- | --- | --- | --- |
| `zen-button` | direct `button` or `a` | `variant`, `loading`, `disabled` | native click/form events |
| `zen-card` | direct `article` or `section` | `interactive` | native descendant events |
| `zen-alert` | message HTML | `tone`, `dismissible` | `zen-dismiss` |
| `zen-field` | direct `label`, form control, help text | native control attributes | native input/change/invalid |
| `zen-stack` | any HTML | `direction`, `gap` | native descendant events |

Do not put business state into the design-system components. They provide
presentation, small accessibility wiring, and interaction affordances while
applications retain data and workflow ownership.

## Tests

```bash
bazel test //design_system/test:storybook_test
bazel build //design_system:design_system_server_bundle
```