--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/design_system/COMPONENTS.md	Tue Aug 04 15:12:09 2026 -0700
@@ -0,0 +1,125 @@
+# Zenbu UI component contracts
+
+Zenbu UI covers the 65 concepts in the shadcn/ui component catalog without
+copying its React, Radix, or third-party runtime. Every Zenbu component uses
+light DOM and keeps the corresponding native HTML control visible.
+
+## Inventory
+
+| shadcn/ui concept | Zenbu UI element |
+| --- | --- |
+| Accordion | `zen-accordion` |
+| Alert | `zen-alert` |
+| Alert Dialog | `zen-alert-dialog` |
+| Aspect Ratio | `zen-aspect-ratio` |
+| Attachment | `zen-attachment` |
+| Avatar | `zen-avatar` |
+| Badge | `zen-badge` |
+| Breadcrumb | `zen-breadcrumb` |
+| Bubble | `zen-bubble` |
+| Button | `zen-button` |
+| Button Group | `zen-button-group` |
+| Calendar | `zen-calendar` |
+| Card | `zen-card` |
+| Carousel | `zen-carousel` |
+| Chart | `zen-chart` |
+| Checkbox | `zen-checkbox` |
+| Collapsible | `zen-collapsible` |
+| Combobox | `zen-combobox` |
+| Command | `zen-command` |
+| Context Menu | `zen-context-menu` |
+| Data Table | `zen-data-table` |
+| Date Picker | `zen-date-picker` |
+| Dialog | `zen-dialog` |
+| Direction | `zen-direction` |
+| Drawer | `zen-drawer` |
+| Dropdown Menu | `zen-dropdown-menu` |
+| Empty | `zen-empty` |
+| Field | `zen-field` |
+| Form | `zen-form` |
+| Hover Card | `zen-hover-card` |
+| Input | `zen-input` |
+| Input Group | `zen-input-group` |
+| Input OTP | `zen-input-otp` |
+| Item | `zen-item` |
+| Kbd | `zen-kbd` |
+| Label | `zen-label` |
+| Marker | `zen-marker` |
+| Menubar | `zen-menubar` |
+| Message | `zen-message` |
+| Message Scroller | `zen-message-scroller` |
+| Native Select | `zen-native-select` |
+| Navigation Menu | `zen-navigation-menu` |
+| Pagination | `zen-pagination` |
+| Popover | `zen-popover` |
+| Progress | `zen-progress` |
+| Radio Group | `zen-radio-group` |
+| Resizable | `zen-resizable` |
+| Scroll Area | `zen-scroll-area` |
+| Select | `zen-select` |
+| Separator | `zen-separator` |
+| Sheet | `zen-sheet` |
+| Sidebar | `zen-sidebar` |
+| Skeleton | `zen-skeleton` |
+| Slider | `zen-slider` |
+| Sonner | `zen-notifications` |
+| Spinner | `zen-spinner` |
+| Switch | `zen-switch` |
+| Table | `zen-table` |
+| Tabs | `zen-tabs` |
+| Textarea | `zen-textarea` |
+| Toast (deprecated) | `zen-notifications` |
+| Toggle | `zen-toggle` |
+| Toggle Group | `zen-toggle-group` |
+| Tooltip | `zen-tooltip` |
+| Typography | `zen-typography` |
+
+`zen-stack` remains a Zenbu-specific layout primitive in addition to this
+catalog.
+
+## Native HTML rules
+
+- Dialog, alert dialog, sheet, and drawer contain a real `dialog`.
+- Accordion and collapsible contain `details` and `summary`.
+- Input, textarea, select, checkbox, radio, switch, and slider contain their
+  corresponding native form controls.
+- Calendar and date picker keep a native date value for form submission while
+  rendering the first-party keyboard month grid. The browser date-picker chrome
+  is not exposed.
+- Table and data table contain a real `table`; pagination and breadcrumbs use
+  native links in a `nav`.
+- Button-like components contain native `button` or `a` elements.
+- Components do not own application data, network requests, routing, or
+  persistence.
+
+## Interactive hooks
+
+| Elements | Required light-DOM hooks | Emitted event |
+| --- | --- | --- |
+| `zen-dialog`, `zen-alert-dialog`, `zen-sheet`, `zen-drawer` | `[data-zen-trigger]`, `dialog`, optional `[data-zen-close]` | native `close` |
+| `zen-popover`, `zen-hover-card`, `zen-tooltip` | `[data-zen-trigger]`, `[data-zen-content]` | native toggle/focus events |
+| Menu elements | `[data-zen-trigger]`, `[role="menu"]`, `[role="menuitem"]` | native click |
+| `zen-tabs` | `[role="tablist"]`, `[role="tab"]`, `[role="tabpanel"]` | `zen-change` with `{ value }` |
+| `zen-toggle` | direct `button` | `zen-change` with `{ pressed }` |
+| `zen-toggle-group` | direct buttons with `value` | `zen-change` with `{ values }` |
+| `zen-sidebar` | `[data-zen-sidebar-trigger]`, `[data-zen-sidebar-panel]` | `zen-change` with `{ open }` |
+| `zen-combobox` | `input`, `[role="listbox"]`, `[role="option"]` | native `input`/`change` and `zen-change` |
+| `zen-command` | `input`, `[role="menu"]`, `[role="menuitem"]` | `zen-command` with `{ value }` |
+| `zen-input-otp` | one native input, optional `[data-zen-otp-slots]` | `zen-complete` with `{ value }` |
+| `zen-calendar`, `zen-date-picker` | native date input plus generated month grid | native `input`/`change` and `zen-change` |
+| `zen-carousel` | `[data-zen-viewport]`, `[data-zen-prev]`, `[data-zen-next]` | `zen-change` with `{ index }` |
+| `zen-resizable` | two `[data-zen-panel]` elements and `[data-zen-handle]` | `zen-resize` with `{ percent }` |
+| `zen-data-table` | `button[data-zen-sort]` and matching cell `data-key` values | `zen-sort` |
+
+All custom events bubble but remain inside their current DOM tree unless a
+component-specific document says otherwise. Application code should listen at
+the nearest owning feature boundary.
+
+## Catalog
+
+Every inventory row has a route at `/components/<name>`, a rendered example,
+and copyable HTML source in the Seobeo-backed catalog:
+
+```bash
+bazel run //design_system:dev
+```