Mercurial

annotate .claude/skills/zenbu-design-system/SKILL.md @ 258:60a876c4587a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ui] Add semantic primitive ownership Build a layered Zenbu token and sizing system, make authored controls use native-underneath primitives, migrate mrjunejune without imposing visual surfaces, and document/enforce HTML ownership in the catalog and wiki. Co-authored-by: Copilot <[email protected]>
author MrJuneJune <me@mrjunejune.com>
date Wed, 05 Aug 2026 05:25:40 -0700
parents 30c2196d03d4
children
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.
258
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
11 - `design_system/src/styles/reference.css`: context-free `--zenbu-ref-*` scales.
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
12 - `design_system/src/styles/semantic.css`: theme-aware `--zenbu-sys-*` roles.
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
13 - `design_system/src/styles/density.css`: comfortable/compact role mappings.
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
14 - `design_system/src/styles/components.css` and `elements.css`: presentation.
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
15 - `design_system/src/styles/tokens.css`: compatibility aliases only.
251
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
16 - `design_system/src/index.html`: declarative component stories.
258
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
17 - `design_system/src/catalog.js`, `component_catalog.js`, and `catalog.css`:
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
18 catalog shell and story inventory.
251
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
19 - `design_system/main.c`: Seobeo catalog server.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
20
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
21 ## Component conventions
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
22
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
23 - Stay close to native HTML and use light DOM.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
24 - Wrap native interactive elements instead of recreating form/link semantics.
258
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
25 - Keep behavior reusable without forcing presentation. Support
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
26 `appearance="plain"` for button/card/field integrations, and require visual
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
27 surfaces, borders, shadows, and backgrounds to be deliberate opt-ins at the
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
28 application boundary.
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
29 - Do not wrap existing content in a visual component merely to demonstrate
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
30 design-system adoption; use components only where they add behavior,
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
31 semantics, or an explicitly requested visual recipe.
251
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
32 - Do not add framework or runtime dependencies.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
33 - Keep application state outside components.
252
7a7581f040e8 [ui] Add scoped notification component
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
34 - 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
35 non-composed `zen-notify` events and bounded queues.
7a7581f040e8 [ui] Add scoped notification component
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
36 - Keep `zen-notifications` behavior aligned with
7a7581f040e8 [ui] Add scoped notification component
MrJuneJune <me@mrjunejune.com>
parents: 251
diff changeset
37 `design_system/NOTIFICATIONS.md`.
253
fdf3816959cb [ui] Add Sonner-like notification stack
MrJuneJune <me@mrjunejune.com>
parents: 252
diff changeset
38 - Notification presentation uses a measured collapsed depth stack that expands
258
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
39 on hover/focus and remains entirely first-party.
251
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
40 - Preserve keyboard, form, validity, label, and ARIA behavior.
258
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
41 - Prefix custom elements and canonical tokens with `zen-` / `--zenbu-`.
251
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
42 - Keep selectors low-specificity so applications can override tokens.
258
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
43 - Use the canonical `xs` / `sm` / `md` / `lg` / `xl` scale for typography,
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
44 control heights, block/inline padding, gaps, icons, and containers. Do not
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
45 introduce one-off component dimensions when a scale token fits.
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
46 - Plain controls inherit `--zenbu-control-*` variables from their size attribute
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
47 without receiving visual CSS; consuming applications should build their own
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
48 appearance from those variables.
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
49 - Keep the token graph layered: `--zenbu-ref-*` defines context-free values,
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
50 `--zenbu-sys-*` defines theme/density-aware intent, and private
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
51 `--zenbu-<component>-*` aliases simplify variants. New component and
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
52 application CSS must consume semantic roles rather than reference colors or
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
53 deprecated `--zen-*` aliases.
251
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
54 - 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
55 - Disclosure, overlay, and collapsing surfaces require smooth tokenized motion
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
56 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
57 first-party `zen-icon` geometry.
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
58 - 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
59 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
60 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
61 - 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
62 widths and reject horizontal page overflow.
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
63 - 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
64 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
65 - 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
66 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
67 must not branch on theme names.
258
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
68 - Use semantic `--zenbu-sys-*` aliases in component CSS. Add a semantic role
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
69 instead of consuming reference colors directly; never encode meaning through
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
70 color alone.
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
71 - Raw color literals are forbidden outside `src/styles/reference.css` and the
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
72 compatibility-only `src/styles/tokens.css`. Run
254
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
73 `//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
74 stories, or catalog markup changes.
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
75 - 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
76 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
77 forbidden.
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
78 - 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
79 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
80 is missing.
251
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
81
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
82 ## Bazel targets
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
83
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
84 ```bash
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
85 bazel run //design_system:dev
258
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
86 bazel test //design_system/test:catalog_test
254
2b6e732087ff [ui] Add complete native component catalog
MrJuneJune <me@mrjunejune.com>
parents: 253
diff changeset
87 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
88 bazel build //design_system:design_system_server_bundle
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
89 ```
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
90
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
91 Reusable targets:
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
92
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
93 - `//design_system:components`
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
94 - `//design_system:styles`
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
95 - `//design_system:web_assets`
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
96
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
97 ## Story convention
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
98
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
99 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
100 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
101 must cover native semantics and interactions rather than only element presence.
258
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
102
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
103 ## Wiki requirement
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
104
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
105 Read `design_system/wiki/README.md` before authoring application HTML. Follow
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
106 its one-owner native-underneath rules and update the wiki whenever a public
60a876c4587a [ui] Add semantic primitive ownership
MrJuneJune <me@mrjunejune.com>
parents: 256
diff changeset
107 primitive or authoring contract changes.