--- a/.claude/skills/zenbu-design-system/SKILL.md	Tue Aug 04 16:49:11 2026 -0700
+++ b/.claude/skills/zenbu-design-system/SKILL.md	Wed Aug 05 05:25:40 2026 -0700
@@ -8,16 +8,27 @@
 ## Structure
 
 - `design_system/src/components/`: dependency-free ES module Web Components.
-- `design_system/src/styles/tokens.css`: shared `--zen-*` design tokens.
-- `design_system/src/styles/components.css`: component presentation.
+- `design_system/src/styles/reference.css`: context-free `--zenbu-ref-*` scales.
+- `design_system/src/styles/semantic.css`: theme-aware `--zenbu-sys-*` roles.
+- `design_system/src/styles/density.css`: comfortable/compact role mappings.
+- `design_system/src/styles/components.css` and `elements.css`: presentation.
+- `design_system/src/styles/tokens.css`: compatibility aliases only.
 - `design_system/src/index.html`: declarative component stories.
-- `design_system/src/storybook.js` and `storybook.css`: catalog shell.
+- `design_system/src/catalog.js`, `component_catalog.js`, and `catalog.css`:
+  catalog shell and story inventory.
 - `design_system/main.c`: Seobeo catalog server.
 
 ## Component conventions
 
 - Stay close to native HTML and use light DOM.
 - Wrap native interactive elements instead of recreating form/link semantics.
+- Keep behavior reusable without forcing presentation. Support
+  `appearance="plain"` for button/card/field integrations, and require visual
+  surfaces, borders, shadows, and backgrounds to be deliberate opt-ins at the
+  application boundary.
+- Do not wrap existing content in a visual component merely to demonstrate
+  design-system adoption; use components only where they add behavior,
+  semantics, or an explicitly requested visual recipe.
 - Do not add framework or runtime dependencies.
 - Keep application state outside components.
 - Keep notification action tokens opaque and out of DOM attributes; use scoped,
@@ -25,10 +36,21 @@
 - Keep `zen-notifications` behavior aligned with
   `design_system/NOTIFICATIONS.md`.
 - Notification presentation uses a measured collapsed depth stack that expands
-  on hover/focus; do not import Sonner or Radix.
+  on hover/focus and remains entirely first-party.
 - Preserve keyboard, form, validity, label, and ARIA behavior.
-- Prefix custom elements and tokens with `zen-` / `--zen-`.
+- Prefix custom elements and canonical tokens with `zen-` / `--zenbu-`.
 - Keep selectors low-specificity so applications can override tokens.
+- Use the canonical `xs` / `sm` / `md` / `lg` / `xl` scale for typography,
+  control heights, block/inline padding, gaps, icons, and containers. Do not
+  introduce one-off component dimensions when a scale token fits.
+- Plain controls inherit `--zenbu-control-*` variables from their size attribute
+  without receiving visual CSS; consuming applications should build their own
+  appearance from those variables.
+- Keep the token graph layered: `--zenbu-ref-*` defines context-free values,
+  `--zenbu-sys-*` defines theme/density-aware intent, and private
+  `--zenbu-<component>-*` aliases simplify variants. New component and
+  application CSS must consume semantic roles rather than reference colors or
+  deprecated `--zen-*` aliases.
 - Support light, dark, reduced-motion, desktop, and mobile behavior.
 - Disclosure, overlay, and collapsing surfaces require smooth tokenized motion
   plus a reduced-motion fallback. Native disclosure markers must be replaced by
@@ -43,10 +65,11 @@
 - Treat themes as semantic-token compositions. Preserve the built-in Paper,
   Ink, and Playful themes plus automatic system light/dark behavior; components
   must not branch on theme names.
-- Use semantic `--zen-color-*` aliases in component CSS. Use primitive ramps
-  or the ten data tokens only when a semantic role does not fit; never encode
-  meaning through color alone.
-- Raw color literals are forbidden outside `src/styles/tokens.css`. Run
+- Use semantic `--zenbu-sys-*` aliases in component CSS. Add a semantic role
+  instead of consuming reference colors directly; never encode meaning through
+  color alone.
+- Raw color literals are forbidden outside `src/styles/reference.css` and the
+  compatibility-only `src/styles/tokens.css`. Run
   `//design_system/test:design_system_policy_test` whenever styles, components,
   stories, or catalog markup changes.
 - Render every interface icon with the first-party `zen-icon` component. Emoji,
@@ -60,7 +83,7 @@
 
 ```bash
 bazel run //design_system:dev
-bazel test //design_system/test:storybook_test
+bazel test //design_system/test:catalog_test
 bazel test //design_system/test:design_system_policy_test
 bazel build //design_system:design_system_server_bundle
 ```
@@ -76,3 +99,9 @@
 Write stories declaratively with `zen-story` and a direct `template`. Every
 component state should have a rendered example and visible source. Browser tests
 must cover native semantics and interactions rather than only element presence.
+
+## Wiki requirement
+
+Read `design_system/wiki/README.md` before authoring application HTML. Follow
+its one-owner native-underneath rules and update the wiki whenever a public
+primitive or authoring contract changes.