# 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-notifications` | descendant event producers | `aria-label`, `dismiss-label` | `zen-notification-action`, `zen-notification-removed` |
| `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.

### Notifications

See [`NOTIFICATIONS.md`](NOTIFICATIONS.md) for the complete event contract,
queue semantics, actions, timing, and accessibility behavior.

Place one scope around the part of the application that owns notifications:

```html
<zen-notifications aria-label="Notifications">
  <main id="application"></main>
</zen-notifications>
```

Any descendant can dispatch a non-composed bubbling event:

```js
source.dispatchEvent(new CustomEvent("zen-notify", {
  bubbles: true,
  composed: false,
  detail: {
    version: 1,
    id: "deployment-complete",
    tone: "success",
    message: "Deployment complete",
    announcement: "polite",
    durationMs: 5000,
  },
}));
```

Use `zen-dismiss-notification` with `{ version: 1, id }` to dismiss by ID.
Actions contain only an opaque token and label; clicking dispatches
`zen-notification-action`. Tokens are held in private component state and never
written to DOM attributes. The component renders three records and retains up
to 20 additional queued records.

## Tests

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