--- a/design_system/README.md	Tue Aug 04 16:49:11 2026 -0700
+++ b/design_system/README.md	Wed Aug 05 05:25:40 2026 -0700
@@ -4,10 +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
+The catalog includes native Zenbu component concepts and composition patterns.
+They are original dependency-free Web Components using Zenbu tokens.
+See
 [`COMPONENTS.md`](COMPONENTS.md) for the complete mapping and HTML contracts.
+Future HTML work follows the [`Zenbu UI wiki`](wiki/README.md).
 
 ## Catalog
 
@@ -20,8 +21,7 @@
 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:
+The first-party catalog renders stories declared as HTML templates:
 
 ```html
 <zen-story name="Primary button">
@@ -54,11 +54,15 @@
 <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. See [`COLORS.md`](COLORS.md) for the complete warm color ramps,
-material aliases, semantic roles, dark-theme behavior, and data palette.
+Canonical tokens use the layered
+[`--zenbu-ref-*` / `--zenbu-sys-*` architecture](TOKENS.md) and can be
+overridden at an application boundary; older `--zen-*` names remain
+compatibility aliases. See [`COLORS.md`](COLORS.md) for color roles and theme
+behavior.
 Named [`themes`](THEMES.md) compose those tokens as Paper, Ink, and Playful
 experiences in addition to automatic system light/dark behavior.
+The [`sizing scale`](SIZING.md) defines shared `xs` through `xl` typography,
+control, icon, gap, and padding primitives.
 
 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.
@@ -74,10 +78,11 @@
 
 | 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 |
+| `zen-button` | direct `button` or `a` | `appearance`, `variant`, `loading`, `disabled` | native click/form events |
+| `zen-card` | direct `article` or `section` | `appearance`, `interactive` | native descendant events |
+| `zen-link` | direct `a` | `effect` | native navigation 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-field` | direct `label`, form control, help text | `appearance`, 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` |
@@ -89,6 +94,14 @@
 presentation, small accessibility wiring, and interaction affordances while
 applications retain data and workflow ownership.
 
+Use `appearance="plain"` when an application needs component behavior without
+the Zenbu visual recipe. Plain buttons remove browser chrome, plain cards add
+no surface treatment, and plain fields keep label/validity wiring while leaving
+the application's control CSS untouched.
+
+`zen-link effect="paw"` adds the first-party paw decoration and hover motion
+while preserving the native anchor and all application-authored link styles.
+
 ### Notifications
 
 See [`NOTIFICATIONS.md`](NOTIFICATIONS.md) for the complete event contract,
@@ -128,6 +141,6 @@
 ## Tests
 
 ```bash
-bazel test //design_system/test:storybook_test
+bazel test //design_system/test:catalog_test
 bazel build //design_system:design_system_server_bundle
 ```