# 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`.