Mercurial
comparison design_system/wiki/HTML_AUTHORING.md @ 258:60a876c4587a
[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 | |
| children |
comparison
equal
deleted
inserted
replaced
| 257:609d3c6aff4e | 258:60a876c4587a |
|---|---|
| 1 # HTML authoring | |
| 2 | |
| 3 ## Native underneath | |
| 4 | |
| 5 Seeing a native `button`, `input`, `textarea`, `select`, or `a` inside a Zenbu | |
| 6 element is intentional: | |
| 7 | |
| 8 ```html | |
| 9 <zen-button size="md"> | |
| 10 <button type="submit">Save</button> | |
| 11 </zen-button> | |
| 12 ``` | |
| 13 | |
| 14 The native element retains form submission, keyboard activation, focus, | |
| 15 validation, autofill, link navigation, and browser APIs. The Zenbu host owns | |
| 16 shared behavior, sizing, tokens, and optional presentation. | |
| 17 | |
| 18 Do not replace the inner button with text-only custom-element content. | |
| 19 | |
| 20 ## One owner per control | |
| 21 | |
| 22 An authored control must have one nearest owner: | |
| 23 | |
| 24 ```html | |
| 25 <zen-field appearance="plain" size="lg"> | |
| 26 <label for="token">Access token</label> | |
| 27 <input id="token" required> | |
| 28 </zen-field> | |
| 29 ``` | |
| 30 | |
| 31 Do not nest a control inside unrelated visual primitives merely to increase | |
| 32 component usage. A toggle button is already owned by `zen-toggle`. Overlay and | |
| 33 layout components only coordinate behavior, so their authored actions still | |
| 34 use the control primitive: | |
| 35 | |
| 36 ```html | |
| 37 <zen-drawer> | |
| 38 <zen-button size="md"> | |
| 39 <button type="button" data-zen-trigger>Open drawer</button> | |
| 40 </zen-button> | |
| 41 <dialog> | |
| 42 <zen-button size="md"> | |
| 43 <button type="button" data-zen-close>Close</button> | |
| 44 </zen-button> | |
| 45 </dialog> | |
| 46 </zen-drawer> | |
| 47 ``` | |
| 48 | |
| 49 ## Plain integration | |
| 50 | |
| 51 Use plain appearance to preserve an application's visual language: | |
| 52 | |
| 53 ```html | |
| 54 <zen-button appearance="plain" size="sm"> | |
| 55 <button class="existing-toolbar-button">Close</button> | |
| 56 </zen-button> | |
| 57 ``` | |
| 58 | |
| 59 Plain mode: | |
| 60 | |
| 61 - retains component behavior and ARIA wiring; | |
| 62 - exposes inherited `--zenbu-control-*` aliases; | |
| 63 - does not add borders, shadows, colors, padding, or hover effects; | |
| 64 - leaves application selectors on the native element effective. | |
| 65 | |
| 66 ## Structural HTML | |
| 67 | |
| 68 Keep semantic structure native unless a primitive adds a concrete contract: | |
| 69 | |
| 70 ```html | |
| 71 <main> | |
| 72 <section aria-labelledby="activity-heading"> | |
| 73 <zen-heading size="xl"> | |
| 74 <h2 id="activity-heading">Activity</h2> | |
| 75 </zen-heading> | |
| 76 <zen-text size="md"><p>Latest repository events.</p></zen-text> | |
| 77 </section> | |
| 78 </main> | |
| 79 ``` | |
| 80 | |
| 81 `main`, `section`, `nav`, lists, tables, paragraphs, and heading levels still | |
| 82 carry document meaning. Zenbu must not obscure that meaning. | |
| 83 | |
| 84 ## Links | |
| 85 | |
| 86 Use `zen-link` when a reusable effect is requested: | |
| 87 | |
| 88 ```html | |
| 89 <zen-link effect="paw"> | |
| 90 <a href="/blog">Blog</a> | |
| 91 </zen-link> | |
| 92 ``` | |
| 93 | |
| 94 Use a native link without a Zenbu wrapper when no link behavior or effect is | |
| 95 being added. Button-like links belong in `zen-button`. |