Mercurial

annotate design_system/README.md @ 251:117c4d53c9a4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ui] Add HTML-first Web Component system Co-authored-by: Copilot <[email protected]>
author MrJuneJune <me@mrjunejune.com>
date Tue, 04 Aug 2026 09:14:57 -0700
parents
children 7a7581f040e8
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 # Zenbu UI design system
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
2
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
3 Zenbu UI is a dependency-free set of light-DOM Web Components and CSS tokens.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
4 It stays close to ordinary HTML: components wrap native controls and sectioning
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
5 elements instead of replacing their semantics.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
6
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
7 ## Catalog
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
8
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
9 Run the Seobeo-backed component catalog:
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
10
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
11 ```bash
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
12 bazel run //design_system:dev
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
13 ```
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
14
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
15 Open `http://127.0.0.1:6980`. Override the port with
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
16 `DESIGN_SYSTEM_PORT`.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
17
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
18 The catalog is intentionally Storybook-like without depending on Storybook. Its
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
19 stories are declared as HTML templates:
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 ```html
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
22 <zen-story name="Primary button">
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
23 <template>
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
24 <zen-button>
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
25 <button type="button">Save</button>
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
26 </zen-button>
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
27 </template>
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
28 </zen-story>
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
29 ```
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
30
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
31 The story component renders the example and its source side by side.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
32
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
33 ## Reuse
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
34
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
35 Reusable assets are public Bazel targets:
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
36
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
37 ```text
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
38 //design_system:components
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
39 //design_system:styles
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
40 //design_system:web_assets
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
41 ```
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
42
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
43 Applications should copy the assets while preserving `components/` and
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
44 `styles/`, then load:
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
45
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
46 ```html
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
47 <link rel="stylesheet" href="/design-system/styles/tokens.css">
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
48 <link rel="stylesheet" href="/design-system/styles/components.css">
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
49 <script type="module" src="/design-system/components/index.js"></script>
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
50 ```
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
51
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
52 Every visual token is a `--zen-*` custom property and can be overridden by the
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
53 application.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
54
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
55 ## Native HTML contract
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
56
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
57 | Component | Native content | Attributes | Events |
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 | `zen-button` | direct `button` or `a` | `variant`, `loading`, `disabled` | native click/form events |
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
60 | `zen-card` | direct `article` or `section` | `interactive` | native descendant events |
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
61 | `zen-alert` | message HTML | `tone`, `dismissible` | `zen-dismiss` |
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
62 | `zen-field` | direct `label`, form control, help text | native control attributes | native input/change/invalid |
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
63 | `zen-stack` | any HTML | `direction`, `gap` | native descendant events |
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
64
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
65 Do not put business state into the design-system components. They provide
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
66 presentation, small accessibility wiring, and interaction affordances while
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
67 applications retain data and workflow ownership.
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
68
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
69 ## Tests
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
70
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
71 ```bash
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
72 bazel test //design_system/test:storybook_test
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
73 bazel build //design_system:design_system_server_bundle
117c4d53c9a4 [ui] Add HTML-first Web Component system
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
74 ```