--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/design_system/README.md	Tue Aug 04 09:14:57 2026 -0700
@@ -0,0 +1,74 @@
+# 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
+```