Mercurial

comparison .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
comparison
equal deleted inserted replaced
257:609d3c6aff4e 258:60a876c4587a
6 # Zenbu UI design system 6 # Zenbu UI design system
7 7
8 ## Structure 8 ## Structure
9 9
10 - `design_system/src/components/`: dependency-free ES module Web Components. 10 - `design_system/src/components/`: dependency-free ES module Web Components.
11 - `design_system/src/styles/tokens.css`: shared `--zen-*` design tokens. 11 - `design_system/src/styles/reference.css`: context-free `--zenbu-ref-*` scales.
12 - `design_system/src/styles/components.css`: component presentation. 12 - `design_system/src/styles/semantic.css`: theme-aware `--zenbu-sys-*` roles.
13 - `design_system/src/styles/density.css`: comfortable/compact role mappings.
14 - `design_system/src/styles/components.css` and `elements.css`: presentation.
15 - `design_system/src/styles/tokens.css`: compatibility aliases only.
13 - `design_system/src/index.html`: declarative component stories. 16 - `design_system/src/index.html`: declarative component stories.
14 - `design_system/src/storybook.js` and `storybook.css`: catalog shell. 17 - `design_system/src/catalog.js`, `component_catalog.js`, and `catalog.css`:
18 catalog shell and story inventory.
15 - `design_system/main.c`: Seobeo catalog server. 19 - `design_system/main.c`: Seobeo catalog server.
16 20
17 ## Component conventions 21 ## Component conventions
18 22
19 - Stay close to native HTML and use light DOM. 23 - Stay close to native HTML and use light DOM.
20 - Wrap native interactive elements instead of recreating form/link semantics. 24 - Wrap native interactive elements instead of recreating form/link semantics.
25 - Keep behavior reusable without forcing presentation. Support
26 `appearance="plain"` for button/card/field integrations, and require visual
27 surfaces, borders, shadows, and backgrounds to be deliberate opt-ins at the
28 application boundary.
29 - Do not wrap existing content in a visual component merely to demonstrate
30 design-system adoption; use components only where they add behavior,
31 semantics, or an explicitly requested visual recipe.
21 - Do not add framework or runtime dependencies. 32 - Do not add framework or runtime dependencies.
22 - Keep application state outside components. 33 - Keep application state outside components.
23 - Keep notification action tokens opaque and out of DOM attributes; use scoped, 34 - Keep notification action tokens opaque and out of DOM attributes; use scoped,
24 non-composed `zen-notify` events and bounded queues. 35 non-composed `zen-notify` events and bounded queues.
25 - Keep `zen-notifications` behavior aligned with 36 - Keep `zen-notifications` behavior aligned with
26 `design_system/NOTIFICATIONS.md`. 37 `design_system/NOTIFICATIONS.md`.
27 - Notification presentation uses a measured collapsed depth stack that expands 38 - Notification presentation uses a measured collapsed depth stack that expands
28 on hover/focus; do not import Sonner or Radix. 39 on hover/focus and remains entirely first-party.
29 - Preserve keyboard, form, validity, label, and ARIA behavior. 40 - Preserve keyboard, form, validity, label, and ARIA behavior.
30 - Prefix custom elements and tokens with `zen-` / `--zen-`. 41 - Prefix custom elements and canonical tokens with `zen-` / `--zenbu-`.
31 - Keep selectors low-specificity so applications can override tokens. 42 - Keep selectors low-specificity so applications can override tokens.
43 - Use the canonical `xs` / `sm` / `md` / `lg` / `xl` scale for typography,
44 control heights, block/inline padding, gaps, icons, and containers. Do not
45 introduce one-off component dimensions when a scale token fits.
46 - Plain controls inherit `--zenbu-control-*` variables from their size attribute
47 without receiving visual CSS; consuming applications should build their own
48 appearance from those variables.
49 - Keep the token graph layered: `--zenbu-ref-*` defines context-free values,
50 `--zenbu-sys-*` defines theme/density-aware intent, and private
51 `--zenbu-<component>-*` aliases simplify variants. New component and
52 application CSS must consume semantic roles rather than reference colors or
53 deprecated `--zen-*` aliases.
32 - Support light, dark, reduced-motion, desktop, and mobile behavior. 54 - Support light, dark, reduced-motion, desktop, and mobile behavior.
33 - Disclosure, overlay, and collapsing surfaces require smooth tokenized motion 55 - Disclosure, overlay, and collapsing surfaces require smooth tokenized motion
34 plus a reduced-motion fallback. Native disclosure markers must be replaced by 56 plus a reduced-motion fallback. Native disclosure markers must be replaced by
35 first-party `zen-icon` geometry. 57 first-party `zen-icon` geometry.
36 - Reset browser chrome for design-system form controls and restyle every state 58 - Reset browser chrome for design-system form controls and restyle every state
41 - Preserve the warm, restrained MUJI-like visual character: paper neutrals, 63 - Preserve the warm, restrained MUJI-like visual character: paper neutrals,
42 natural material colors, strong typography, and deliberate color accents. 64 natural material colors, strong typography, and deliberate color accents.
43 - Treat themes as semantic-token compositions. Preserve the built-in Paper, 65 - Treat themes as semantic-token compositions. Preserve the built-in Paper,
44 Ink, and Playful themes plus automatic system light/dark behavior; components 66 Ink, and Playful themes plus automatic system light/dark behavior; components
45 must not branch on theme names. 67 must not branch on theme names.
46 - Use semantic `--zen-color-*` aliases in component CSS. Use primitive ramps 68 - Use semantic `--zenbu-sys-*` aliases in component CSS. Add a semantic role
47 or the ten data tokens only when a semantic role does not fit; never encode 69 instead of consuming reference colors directly; never encode meaning through
48 meaning through color alone. 70 color alone.
49 - Raw color literals are forbidden outside `src/styles/tokens.css`. Run 71 - Raw color literals are forbidden outside `src/styles/reference.css` and the
72 compatibility-only `src/styles/tokens.css`. Run
50 `//design_system/test:design_system_policy_test` whenever styles, components, 73 `//design_system/test:design_system_policy_test` whenever styles, components,
51 stories, or catalog markup changes. 74 stories, or catalog markup changes.
52 - Render every interface icon with the first-party `zen-icon` component. Emoji, 75 - Render every interface icon with the first-party `zen-icon` component. Emoji,
53 text-glyph icons, ad hoc SVG, icon fonts, and external icon packages are 76 text-glyph icons, ad hoc SVG, icon fonts, and external icon packages are
54 forbidden. 77 forbidden.
58 81
59 ## Bazel targets 82 ## Bazel targets
60 83
61 ```bash 84 ```bash
62 bazel run //design_system:dev 85 bazel run //design_system:dev
63 bazel test //design_system/test:storybook_test 86 bazel test //design_system/test:catalog_test
64 bazel test //design_system/test:design_system_policy_test 87 bazel test //design_system/test:design_system_policy_test
65 bazel build //design_system:design_system_server_bundle 88 bazel build //design_system:design_system_server_bundle
66 ``` 89 ```
67 90
68 Reusable targets: 91 Reusable targets:
74 ## Story convention 97 ## Story convention
75 98
76 Write stories declaratively with `zen-story` and a direct `template`. Every 99 Write stories declaratively with `zen-story` and a direct `template`. Every
77 component state should have a rendered example and visible source. Browser tests 100 component state should have a rendered example and visible source. Browser tests
78 must cover native semantics and interactions rather than only element presence. 101 must cover native semantics and interactions rather than only element presence.
102
103 ## Wiki requirement
104
105 Read `design_system/wiki/README.md` before authoring application HTML. Follow
106 its one-owner native-underneath rules and update the wiki whenever a public
107 primitive or authoring contract changes.