--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/design_system/wiki/HTML_AUTHORING.md	Wed Aug 05 05:25:40 2026 -0700
@@ -0,0 +1,95 @@
+# HTML authoring
+
+## Native underneath
+
+Seeing a native `button`, `input`, `textarea`, `select`, or `a` inside a Zenbu
+element is intentional:
+
+```html
+<zen-button size="md">
+  <button type="submit">Save</button>
+</zen-button>
+```
+
+The native element retains form submission, keyboard activation, focus,
+validation, autofill, link navigation, and browser APIs. The Zenbu host owns
+shared behavior, sizing, tokens, and optional presentation.
+
+Do not replace the inner button with text-only custom-element content.
+
+## One owner per control
+
+An authored control must have one nearest owner:
+
+```html
+<zen-field appearance="plain" size="lg">
+  <label for="token">Access token</label>
+  <input id="token" required>
+</zen-field>
+```
+
+Do not nest a control inside unrelated visual primitives merely to increase
+component usage. A toggle button is already owned by `zen-toggle`. Overlay and
+layout components only coordinate behavior, so their authored actions still
+use the control primitive:
+
+```html
+<zen-drawer>
+  <zen-button size="md">
+    <button type="button" data-zen-trigger>Open drawer</button>
+  </zen-button>
+  <dialog>
+    <zen-button size="md">
+      <button type="button" data-zen-close>Close</button>
+    </zen-button>
+  </dialog>
+</zen-drawer>
+```
+
+## Plain integration
+
+Use plain appearance to preserve an application's visual language:
+
+```html
+<zen-button appearance="plain" size="sm">
+  <button class="existing-toolbar-button">Close</button>
+</zen-button>
+```
+
+Plain mode:
+
+- retains component behavior and ARIA wiring;
+- exposes inherited `--zenbu-control-*` aliases;
+- does not add borders, shadows, colors, padding, or hover effects;
+- leaves application selectors on the native element effective.
+
+## Structural HTML
+
+Keep semantic structure native unless a primitive adds a concrete contract:
+
+```html
+<main>
+  <section aria-labelledby="activity-heading">
+    <zen-heading size="xl">
+      <h2 id="activity-heading">Activity</h2>
+    </zen-heading>
+    <zen-text size="md"><p>Latest repository events.</p></zen-text>
+  </section>
+</main>
+```
+
+`main`, `section`, `nav`, lists, tables, paragraphs, and heading levels still
+carry document meaning. Zenbu must not obscure that meaning.
+
+## Links
+
+Use `zen-link` when a reusable effect is requested:
+
+```html
+<zen-link effect="paw">
+  <a href="/blog">Blog</a>
+</zen-link>
+```
+
+Use a native link without a Zenbu wrapper when no link behavior or effect is
+being added. Button-like links belong in `zen-button`.