--- a/design_system/README.md	Tue Aug 04 12:21:19 2026 -0700
+++ b/design_system/README.md	Tue Aug 04 15:12:09 2026 -0700
@@ -4,6 +4,11 @@
 It stays close to ordinary HTML: components wrap native controls and sectioning
 elements instead of replacing their semantics.
 
+The catalog includes native Zenbu implementations of all 65 concepts currently
+listed by shadcn/ui. These are original Web Components using Zenbu tokens, not
+ports of shadcn's React, Radix, or third-party runtime. See
+[`COMPONENTS.md`](COMPONENTS.md) for the complete mapping and HTML contracts.
+
 ## Catalog
 
 Run the Seobeo-backed component catalog:
@@ -50,11 +55,22 @@
 ```
 
 Every visual token is a `--zen-*` custom property and can be overridden by the
-application.
+application. See [`COLORS.md`](COLORS.md) for the complete warm color ramps,
+material aliases, semantic roles, dark-theme behavior, and data palette.
+
+Use [`zen-icon`](ICONS.md) for all interface iconography. Design-system source
+does not use emoji, ad hoc SVG, icon fonts, or third-party icon packages.
+
+All exported JavaScript APIs use Google-style JSDoc. The policy target checks
+the documentation contract along with token-only colors and first-party icons.
+
+The catalog navigation is searchable with `/`, and every route is exercised at
+desktop and mobile widths. Form controls reset browser chrome; date selection
+uses Zenbu's first-party keyboard calendar.
 
 ## Native HTML contract
 
-| Component | Native content | Attributes | Events |
+| Component family | 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 |
@@ -62,6 +78,10 @@
 | `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 |
+| Disclosure and tabs | `details`, `summary`, buttons, sections | `multiple`, `activation` | `zen-change` |
+| Dialogs and menus | native `dialog`, buttons, links | `placement`, native attributes | native click/close |
+| Form controls | native input, select, textarea, fieldset | native control attributes | native form events |
+| Collections | table, article, section, scroll containers | component-specific data hooks | `zen-change`, `zen-sort`, `zen-resize` |
 
 Do not put business state into the design-system components. They provide
 presentation, small accessibility wiring, and interaction affordances while