--- a/.claude/skills/zenbu-design-system/SKILL.md	Tue Aug 04 12:21:19 2026 -0700
+++ b/.claude/skills/zenbu-design-system/SKILL.md	Tue Aug 04 15:12:09 2026 -0700
@@ -30,12 +30,35 @@
 - Prefix custom elements and tokens with `zen-` / `--zen-`.
 - Keep selectors low-specificity so applications can override tokens.
 - 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
+  first-party `zen-icon` geometry.
+- Reset browser chrome for design-system form controls and restyle every state
+  with Zenbu tokens. Calendar and date-picker UI must use the first-party
+  keyboard calendar rather than exposing the browser's default date picker.
+- Browser acceptance must exercise every catalog route at desktop and mobile
+  widths and reject horizontal page overflow.
+- Preserve the warm, restrained MUJI-like visual character: paper neutrals,
+  natural material colors, strong typography, and deliberate color accents.
+- 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
+  `//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,
+  text-glyph icons, ad hoc SVG, icon fonts, and external icon packages are
+  forbidden.
+- Every exported JavaScript class, function, or constant requires Google-style
+  JSDoc with its public type tags. The policy test must fail when documentation
+  is missing.
 
 ## Bazel targets
 
 ```bash
 bazel run //design_system:dev
 bazel test //design_system/test:storybook_test
+bazel test //design_system/test:design_system_policy_test
 bazel build //design_system:design_system_server_bundle
 ```