Mercurial

comparison design_system/README.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
2 2
3 Zenbu UI is a dependency-free set of light-DOM Web Components and CSS tokens. 3 Zenbu UI is a dependency-free set of light-DOM Web Components and CSS tokens.
4 It stays close to ordinary HTML: components wrap native controls and sectioning 4 It stays close to ordinary HTML: components wrap native controls and sectioning
5 elements instead of replacing their semantics. 5 elements instead of replacing their semantics.
6 6
7 The catalog includes native Zenbu implementations of all 65 concepts currently 7 The catalog includes native Zenbu component concepts and composition patterns.
8 listed by shadcn/ui. These are original Web Components using Zenbu tokens, not 8 They are original dependency-free Web Components using Zenbu tokens.
9 ports of shadcn's React, Radix, or third-party runtime. See 9 See
10 [`COMPONENTS.md`](COMPONENTS.md) for the complete mapping and HTML contracts. 10 [`COMPONENTS.md`](COMPONENTS.md) for the complete mapping and HTML contracts.
11 Future HTML work follows the [`Zenbu UI wiki`](wiki/README.md).
11 12
12 ## Catalog 13 ## Catalog
13 14
14 Run the Seobeo-backed component catalog: 15 Run the Seobeo-backed component catalog:
15 16
18 ``` 19 ```
19 20
20 Open `http://127.0.0.1:6980`. Override the port with 21 Open `http://127.0.0.1:6980`. Override the port with
21 `DESIGN_SYSTEM_PORT`. 22 `DESIGN_SYSTEM_PORT`.
22 23
23 The catalog is intentionally Storybook-like without depending on Storybook. Its 24 The first-party catalog renders stories declared as HTML templates:
24 stories are declared as HTML templates:
25 25
26 ```html 26 ```html
27 <zen-story name="Primary button"> 27 <zen-story name="Primary button">
28 <template> 28 <template>
29 <zen-button> 29 <zen-button>
52 <link rel="stylesheet" href="/design-system/styles/tokens.css"> 52 <link rel="stylesheet" href="/design-system/styles/tokens.css">
53 <link rel="stylesheet" href="/design-system/styles/components.css"> 53 <link rel="stylesheet" href="/design-system/styles/components.css">
54 <script type="module" src="/design-system/components/index.js"></script> 54 <script type="module" src="/design-system/components/index.js"></script>
55 ``` 55 ```
56 56
57 Every visual token is a `--zen-*` custom property and can be overridden by the 57 Canonical tokens use the layered
58 application. See [`COLORS.md`](COLORS.md) for the complete warm color ramps, 58 [`--zenbu-ref-*` / `--zenbu-sys-*` architecture](TOKENS.md) and can be
59 material aliases, semantic roles, dark-theme behavior, and data palette. 59 overridden at an application boundary; older `--zen-*` names remain
60 compatibility aliases. See [`COLORS.md`](COLORS.md) for color roles and theme
61 behavior.
60 Named [`themes`](THEMES.md) compose those tokens as Paper, Ink, and Playful 62 Named [`themes`](THEMES.md) compose those tokens as Paper, Ink, and Playful
61 experiences in addition to automatic system light/dark behavior. 63 experiences in addition to automatic system light/dark behavior.
64 The [`sizing scale`](SIZING.md) defines shared `xs` through `xl` typography,
65 control, icon, gap, and padding primitives.
62 66
63 Use [`zen-icon`](ICONS.md) for all interface iconography. Design-system source 67 Use [`zen-icon`](ICONS.md) for all interface iconography. Design-system source
64 does not use emoji, ad hoc SVG, icon fonts, or third-party icon packages. 68 does not use emoji, ad hoc SVG, icon fonts, or third-party icon packages.
65 69
66 All exported JavaScript APIs use Google-style JSDoc. The policy target checks 70 All exported JavaScript APIs use Google-style JSDoc. The policy target checks
72 76
73 ## Native HTML contract 77 ## Native HTML contract
74 78
75 | Component family | Native content | Attributes | Events | 79 | Component family | Native content | Attributes | Events |
76 | --- | --- | --- | --- | 80 | --- | --- | --- | --- |
77 | `zen-button` | direct `button` or `a` | `variant`, `loading`, `disabled` | native click/form events | 81 | `zen-button` | direct `button` or `a` | `appearance`, `variant`, `loading`, `disabled` | native click/form events |
78 | `zen-card` | direct `article` or `section` | `interactive` | native descendant events | 82 | `zen-card` | direct `article` or `section` | `appearance`, `interactive` | native descendant events |
83 | `zen-link` | direct `a` | `effect` | native navigation events |
79 | `zen-alert` | message HTML | `tone`, `dismissible` | `zen-dismiss` | 84 | `zen-alert` | message HTML | `tone`, `dismissible` | `zen-dismiss` |
80 | `zen-field` | direct `label`, form control, help text | native control attributes | native input/change/invalid | 85 | `zen-field` | direct `label`, form control, help text | `appearance`, native control attributes | native input/change/invalid |
81 | `zen-notifications` | descendant event producers | `aria-label`, `dismiss-label` | `zen-notification-action`, `zen-notification-removed` | 86 | `zen-notifications` | descendant event producers | `aria-label`, `dismiss-label` | `zen-notification-action`, `zen-notification-removed` |
82 | `zen-stack` | any HTML | `direction`, `gap` | native descendant events | 87 | `zen-stack` | any HTML | `direction`, `gap` | native descendant events |
83 | Disclosure and tabs | `details`, `summary`, buttons, sections | `multiple`, `activation` | `zen-change` | 88 | Disclosure and tabs | `details`, `summary`, buttons, sections | `multiple`, `activation` | `zen-change` |
84 | Dialogs and menus | native `dialog`, buttons, links | `placement`, native attributes | native click/close | 89 | Dialogs and menus | native `dialog`, buttons, links | `placement`, native attributes | native click/close |
85 | Form controls | native input, select, textarea, fieldset | native control attributes | native form events | 90 | Form controls | native input, select, textarea, fieldset | native control attributes | native form events |
86 | Collections | table, article, section, scroll containers | component-specific data hooks | `zen-change`, `zen-sort`, `zen-resize` | 91 | Collections | table, article, section, scroll containers | component-specific data hooks | `zen-change`, `zen-sort`, `zen-resize` |
87 92
88 Do not put business state into the design-system components. They provide 93 Do not put business state into the design-system components. They provide
89 presentation, small accessibility wiring, and interaction affordances while 94 presentation, small accessibility wiring, and interaction affordances while
90 applications retain data and workflow ownership. 95 applications retain data and workflow ownership.
96
97 Use `appearance="plain"` when an application needs component behavior without
98 the Zenbu visual recipe. Plain buttons remove browser chrome, plain cards add
99 no surface treatment, and plain fields keep label/validity wiring while leaving
100 the application's control CSS untouched.
101
102 `zen-link effect="paw"` adds the first-party paw decoration and hover motion
103 while preserving the native anchor and all application-authored link styles.
91 104
92 ### Notifications 105 ### Notifications
93 106
94 See [`NOTIFICATIONS.md`](NOTIFICATIONS.md) for the complete event contract, 107 See [`NOTIFICATIONS.md`](NOTIFICATIONS.md) for the complete event contract,
95 queue semantics, actions, timing, and accessibility behavior. 108 queue semantics, actions, timing, and accessibility behavior.
126 to 20 additional queued records. 139 to 20 additional queued records.
127 140
128 ## Tests 141 ## Tests
129 142
130 ```bash 143 ```bash
131 bazel test //design_system/test:storybook_test 144 bazel test //design_system/test:catalog_test
132 bazel build //design_system:design_system_server_bundle 145 bazel build //design_system:design_system_server_bundle
133 ``` 146 ```