Mercurial

annotate .claude/skills/zenbu-design-system/SKILL.md @ 256:30c2196d03d4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[site] Integrate Zenbu themes and components Co-authored-by: Copilot <[email protected]>
author MrJuneJune <me@mrjunejune.com>
date Tue, 04 Aug 2026 16:49:01 -0700
parents 2b6e732087ff
children 60a876c4587a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
251
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
1 ---
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
2 name: zenbu-design-system
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
3 description: Use this skill when changing Zenbu UI Web Components, design tokens, component stories, catalog routes, or cross-project design-system assets.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
4 ---
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
5
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
6 # Zenbu UI design system
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
7
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
8 ## Structure
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
9
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
10 - `design_system/src/components/`: dependency-free ES module Web Components.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
11 - `design_system/src/styles/tokens.css`: shared `--zen-*` design tokens.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
12 - `design_system/src/styles/components.css`: component presentation.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
13 - `design_system/src/index.html`: declarative component stories.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
14 - `design_system/src/storybook.js` and `storybook.css`: catalog shell.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
15 - `design_system/main.c`: Seobeo catalog server.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
16
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
17 ## Component conventions
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
18
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
19 - Stay close to native HTML and use light DOM.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
20 - Wrap native interactive elements instead of recreating form/link semantics.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
21 - Do not add framework or runtime dependencies.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
22 - Keep application state outside components.
252
7a7581f040e8 [ui] Add scoped notification component
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
23 - Keep notification action tokens opaque and out of DOM attributes; use scoped,
7a7581f040e8 [ui] Add scoped notification component
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
24 non-composed `zen-notify` events and bounded queues.
7a7581f040e8 [ui] Add scoped notification component
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
25 - Keep `zen-notifications` behavior aligned with
7a7581f040e8 [ui] Add scoped notification component
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
26 `design_system/NOTIFICATIONS.md`.
253
fdf3816959cb [ui] Add Sonner-like notification stack
MrJuneJune <me@mrjunejune.com>
parents: 252
diff changeset
27 - Notification presentation uses a measured collapsed depth stack that expands
fdf3816959cb [ui] Add Sonner-like notification stack
MrJuneJune <me@mrjunejune.com>
parents: 252
diff changeset
28 on hover/focus; do not import Sonner or Radix.
251
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
29 - Preserve keyboard, form, validity, label, and ARIA behavior.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
30 - Prefix custom elements and tokens with `zen-` / `--zen-`.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
31 - Keep selectors low-specificity so applications can override tokens.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
32 - Support light, dark, reduced-motion, desktop, and mobile behavior.
254
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
33 - Disclosure, overlay, and collapsing surfaces require smooth tokenized motion
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
34 plus a reduced-motion fallback. Native disclosure markers must be replaced by
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
35 first-party `zen-icon` geometry.
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
36 - Reset browser chrome for design-system form controls and restyle every state
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
37 with Zenbu tokens. Calendar and date-picker UI must use the first-party
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
38 keyboard calendar rather than exposing the browser's default date picker.
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
39 - Browser acceptance must exercise every catalog route at desktop and mobile
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
40 widths and reject horizontal page overflow.
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
41 - Preserve the warm, restrained MUJI-like visual character: paper neutrals,
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
42 natural material colors, strong typography, and deliberate color accents.
256
30c2196d03d4 [site] Integrate Zenbu themes and components
MrJuneJune <me@mrjunejune.com>
parents: 254
diff changeset
43 - Treat themes as semantic-token compositions. Preserve the built-in Paper,
30c2196d03d4 [site] Integrate Zenbu themes and components
MrJuneJune <me@mrjunejune.com>
parents: 254
diff changeset
44 Ink, and Playful themes plus automatic system light/dark behavior; components
30c2196d03d4 [site] Integrate Zenbu themes and components
MrJuneJune <me@mrjunejune.com>
parents: 254
diff changeset
45 must not branch on theme names.
254
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
46 - Use semantic `--zen-color-*` aliases in component CSS. Use primitive ramps
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
47 or the ten data tokens only when a semantic role does not fit; never encode
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
48 meaning through color alone.
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
49 - Raw color literals are forbidden outside `src/styles/tokens.css`. Run
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
50 `//design_system/test:design_system_policy_test` whenever styles, components,
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
51 stories, or catalog markup changes.
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
52 - Render every interface icon with the first-party `zen-icon` component. Emoji,
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
53 text-glyph icons, ad hoc SVG, icon fonts, and external icon packages are
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
54 forbidden.
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
55 - Every exported JavaScript class, function, or constant requires Google-style
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
56 JSDoc with its public type tags. The policy test must fail when documentation
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
57 is missing.
251
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
58
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
59 ## Bazel targets
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
60
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
61 ```bash
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
62 bazel run //design_system:dev
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
63 bazel test //design_system/test:storybook_test
254
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
64 bazel test //design_system/test:design_system_policy_test
251
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
65 bazel build //design_system:design_system_server_bundle
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
66 ```
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
67
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
68 Reusable targets:
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
69
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
70 - `//design_system:components`
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
71 - `//design_system:styles`
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
72 - `//design_system:web_assets`
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
73
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
74 ## Story convention
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
75
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
76 Write stories declaratively with `zen-story` and a direct `template`. Every
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
77 component state should have a rendered example and visible source. Browser tests
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
78 must cover native semantics and interactions rather than only element presence.