Mercurial

comparison design_system/README.md @ 254:2b6e732087ff

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ui] Add complete native component catalog Co-authored-by: Copilot <[email protected]>
author MrJuneJune <me@mrjunejune.com>
date Tue, 04 Aug 2026 15:12:09 -0700
parents 7a7581f040e8
children 30c2196d03d4
comparison
equal deleted inserted replaced
253:fdf3816959cb 254:2b6e732087ff
1 # Zenbu UI design system 1 # Zenbu UI design system
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
7 The catalog includes native Zenbu implementations of all 65 concepts currently
8 listed by shadcn/ui. These are original Web Components using Zenbu tokens, not
9 ports of shadcn's React, Radix, or third-party runtime. See
10 [`COMPONENTS.md`](COMPONENTS.md) for the complete mapping and HTML contracts.
6 11
7 ## Catalog 12 ## Catalog
8 13
9 Run the Seobeo-backed component catalog: 14 Run the Seobeo-backed component catalog:
10 15
48 <link rel="stylesheet" href="/design-system/styles/components.css"> 53 <link rel="stylesheet" href="/design-system/styles/components.css">
49 <script type="module" src="/design-system/components/index.js"></script> 54 <script type="module" src="/design-system/components/index.js"></script>
50 ``` 55 ```
51 56
52 Every visual token is a `--zen-*` custom property and can be overridden by the 57 Every visual token is a `--zen-*` custom property and can be overridden by the
53 application. 58 application. See [`COLORS.md`](COLORS.md) for the complete warm color ramps,
59 material aliases, semantic roles, dark-theme behavior, and data palette.
60
61 Use [`zen-icon`](ICONS.md) for all interface iconography. Design-system source
62 does not use emoji, ad hoc SVG, icon fonts, or third-party icon packages.
63
64 All exported JavaScript APIs use Google-style JSDoc. The policy target checks
65 the documentation contract along with token-only colors and first-party icons.
66
67 The catalog navigation is searchable with `/`, and every route is exercised at
68 desktop and mobile widths. Form controls reset browser chrome; date selection
69 uses Zenbu's first-party keyboard calendar.
54 70
55 ## Native HTML contract 71 ## Native HTML contract
56 72
57 | Component | Native content | Attributes | Events | 73 | Component family | Native content | Attributes | Events |
58 | --- | --- | --- | --- | 74 | --- | --- | --- | --- |
59 | `zen-button` | direct `button` or `a` | `variant`, `loading`, `disabled` | native click/form events | 75 | `zen-button` | direct `button` or `a` | `variant`, `loading`, `disabled` | native click/form events |
60 | `zen-card` | direct `article` or `section` | `interactive` | native descendant events | 76 | `zen-card` | direct `article` or `section` | `interactive` | native descendant events |
61 | `zen-alert` | message HTML | `tone`, `dismissible` | `zen-dismiss` | 77 | `zen-alert` | message HTML | `tone`, `dismissible` | `zen-dismiss` |
62 | `zen-field` | direct `label`, form control, help text | native control attributes | native input/change/invalid | 78 | `zen-field` | direct `label`, form control, help text | native control attributes | native input/change/invalid |
63 | `zen-notifications` | descendant event producers | `aria-label`, `dismiss-label` | `zen-notification-action`, `zen-notification-removed` | 79 | `zen-notifications` | descendant event producers | `aria-label`, `dismiss-label` | `zen-notification-action`, `zen-notification-removed` |
64 | `zen-stack` | any HTML | `direction`, `gap` | native descendant events | 80 | `zen-stack` | any HTML | `direction`, `gap` | native descendant events |
81 | Disclosure and tabs | `details`, `summary`, buttons, sections | `multiple`, `activation` | `zen-change` |
82 | Dialogs and menus | native `dialog`, buttons, links | `placement`, native attributes | native click/close |
83 | Form controls | native input, select, textarea, fieldset | native control attributes | native form events |
84 | Collections | table, article, section, scroll containers | component-specific data hooks | `zen-change`, `zen-sort`, `zen-resize` |
65 85
66 Do not put business state into the design-system components. They provide 86 Do not put business state into the design-system components. They provide
67 presentation, small accessibility wiring, and interaction affordances while 87 presentation, small accessibility wiring, and interaction affordances while
68 applications retain data and workflow ownership. 88 applications retain data and workflow ownership.
69 89