actual-css 0.2.0 → 0.3.1

package/docs/pages/enhancements/flyout.md

@@ -0,0 +1,391 @@
+# Flyout
+
+> Positioned surface attached to a trigger, commonly used for action lists and small panels.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.flyout-trigger` | Composition | Positioning wrapper for a trigger and its panel; gives the flyout a local absolute-position fallback before JavaScript positions it. |
+| `.stretch` | Modifier | Stretches a `.flyout-trigger` to span its container, e.g. the last row of a full-width sidebar nav list. |
+| `.flyout` | Component | Floating action or nav surface, positioned by JavaScript. |
+| `.menu` | Component | Action-list primitive with strict `.menu > li > .menu-item` anatomy. |
+| `.menu-item` | Component | One action row; participates in roving focus. |
+| `.menu-item-icon` | Slot | Fixed leading column for a decorative icon. |
+| `.menu-item-text` | Slot | Flexible label column; truncates when the row is constrained. |
+| `.menu-item-end` | Slot | Trailing metadata such as a shortcut, badge, or status. |
+| `.menu-label` | Variant | Muted section heading inside a menu; not interactive. |
+| `.menu-separator` | Variant | Divider between menu groups (`<hr role="separator">`). |
+| `.sm` / `.lg` | Variant | Compact or large density. |
+
+## Usage
+
+Flyout and context menu share one action-surface runtime:
+
+- Flyout = a visible trigger opens a surface.
+- Context menu = right click or a keyboard context action opens that same surface.
+- Sheet = mobile presentation mode of that same surface.
+
+### Trigger wiring
+
+The runtime resolves the panel from the trigger, so the wiring is part of the
+contract:
+
+- Put `data-enhance="flyout"` on the **trigger** (the button, link, or other
+  clickable element), never on a wrapper around it.
+- The trigger references its panel with `aria-controls="…"` and the panel owns
+  the matching `id`. The runtime reads `aria-controls` to find the panel — a
+  trigger without the pairing never opens anything.
+- Wrap the trigger and panel in `.flyout-trigger`. It is the positioning
+  context for the no-JS fallback: without it the panel lays out against the
+  nearest positioned ancestor (or the page edge) instead of under the trigger.
+- Start the panel with `hidden` so it does not flash open before the runtime
+  hides and positions it.
+
+```html
+<div class="flyout-trigger">
+  <button data-enhance="flyout"
+          aria-expanded="false"
+          aria-controls="my-panel">
+    Menu
+  </button>
+  <div class="flyout" id="my-panel" hidden>…</div>
+</div>
+```
+
+Use `data-flyout-mobile` on the flyout to control mobile behavior:
+
+- `auto` is the default. It keeps the surface anchored on desktop and switches to a bottom sheet on coarse pointers below the breakpoint.
+- `sheet` always uses the sheet presentation.
+- `anchored` always uses floating positioning.
+- `none` disables the mobile transformation.
+
+`data-flyout-breakpoint` only matters for `auto`. Prefer the built-in tokens
+(`sm`, `md`, `lg`) and use raw pixel values only as an escape hatch, for example
+`data-flyout-breakpoint="640"`.
+
+Use `data-flyout-placement` for the preferred anchored placement. It accepts the
+placement strings supported by the floating runtime, such as `bottom-start`,
+`bottom-end`, `top-start`, `right`, or `left`.
+
+Use `data-flyout-distance` for the trigger gap in pixels. The default is `4`.
+
+Use `data-flyout-auto-close` when the default click dismissal behavior is not
+right. Escape still follows the shared surface lifecycle.
+
+- `true` is the default. Clicks inside or outside close the flyout.
+- `inside` closes on inside clicks only.
+- `outside` closes on outside click only.
+- `false` disables automatic click closing.
+
+These values follow Bootstrap's auto-close vocabulary. They apply to action
+menus and rich panels alike. Add `data-flyout-close` to a control inside the
+flyout when that specific control must close it regardless of the automatic
+policy. This is useful for an Apply or Done action in an `outside` or `false`
+panel. The trigger and Escape continue to close the flyout in every mode.
+
+```html
+<div class="flyout"
+     id="filters"
+     data-flyout-auto-close="outside"
+     hidden>
+  <label><input type="checkbox"> Available only</label>
+  <button type="button" data-flyout-close>Done</button>
+</div>
+```
+
+Flyout covers two distinct patterns, detected by the `<menu>` element or
+`.menu` class on the panel:
+
+## Action list
+
+A list of *actions* the user can take: sign out, copy, delete.
+
+- Flyout triggers are opt-in: add `data-enhance="flyout"` to the trigger.
+- Wrap the trigger and flyout in `.flyout-trigger` when the flyout should have a local absolute-position fallback before JavaScript positions it. Add `.stretch` when the trigger must span its container, such as the last row of a full-width sidebar nav list.
+- Use `<menu class="flyout menu">` with strict anatomy: `.menu > li > .menu-item`. Items must carry the `.menu-item` class to participate in directional keyboard navigation. ArrowUp/Down and Home/End move focus without rewriting their normal tab stops.
+- Use `.menu-label` on a `li` for a muted section heading inside a menu (e.g. a group title before its items). It is non-interactive and does not participate in roving focus. Use `.menu-separator` (`<hr role="separator">`) between groups.
+- Items are regular `<button>` or `<a>` elements.
+- Use `.sm` or `.lg` for density changes.
+- Add `role="menu"` / `role="menuitem"` only when you intentionally need the ARIA menu pattern described below.
+
+```html demo
+<div class="flyout-trigger">
+  <button class="btn outline"
+          type="button"
+          data-enhance="flyout"
+          aria-expanded="false"
+          aria-controls="account-actions"
+          id="account-flyout-trigger">
+    Account
+    <i class="ti ti-chevron-down" aria-hidden="true"></i>
+  </button>
+
+  <menu class="flyout sm menu"
+        id="account-actions"
+        aria-labelledby="account-flyout-trigger"
+        hidden>
+    <li><button class="menu-item" type="button">Profile</button></li>
+    <li><button class="menu-item" type="button">Settings</button></li>
+    <hr class="menu-separator" role="separator">
+    <li><button class="menu-item danger" type="button">Sign out</button></li>
+  </menu>
+</div>
+```
+
+### ARIA menu pattern
+
+Adding `role="menu"` opts the action list into a composite with one roving tab
+stop. Its usable `.menu-item` children with `role="menuitem"`,
+`role="menuitemcheckbox"`, or `role="menuitemradio"` participate in vertical,
+wrapping Arrow/Home/End navigation. Items without one of those roles are not
+part of the focus group. Plain `.menu` action lists keep every item's normal
+tab stop instead.
+
+The runtime owns only focus movement and `tabindex`. The application still owns
+command state and updates attributes such as `aria-checked`.
+
+### Rich items and selection state
+
+Wrap rich item content in the three optional slots when a menu needs aligned
+icons or trailing metadata. Keep decorative icons hidden from assistive
+technology. Plain text directly inside `.menu-item` remains valid for simple
+actions.
+
+```html
+<li>
+  <button class="menu-item" type="button" role="menuitem">
+    <span class="menu-item-icon" aria-hidden="true">…</span>
+    <span class="menu-item-text">Duplicate</span>
+    <span class="menu-item-end"><kbd>⌘D</kbd></span>
+  </button>
+</li>
+```
+
+Use `role="menuitemcheckbox"` for independent options and
+`role="menuitemradio"` for an exclusive choice. Put `aria-checked` on the menu
+item itself; do not nest a checkbox, radio, or switch inside it. The runtime
+recognizes all three menu-item roles for keyboard activation and the CSS draws
+their state indicator. The application remains responsible for updating
+`aria-checked`, just as it owns the state behind the command.
+
+```html
+<li>
+  <button class="menu-item"
+          type="button"
+          role="menuitemcheckbox"
+          aria-checked="true">
+    <span class="menu-item-text">Show weekends</span>
+  </button>
+</li>
+```
+
+Badges and shortcuts are passive trailing metadata. If a trailing pin, switch,
+or button is independently interactive, use a rich flyout panel with normal
+Tab navigation instead of `role="menu"`: a menu item must remain one command.
+
+## Nav panel
+
+A panel of *links* to other pages: product categories, docs sections. Nav panels
+can be multi-column with `<section>` / `<ul>` groups.
+
+- Items are regular `<a href>` links, not `role="menuitem"`.
+- No roving focus — ArrowDown/Enter open the panel and focus the first focusable descendant. Tab from an open trigger also enters the panel. There is no arrow-key navigation between items inside.
+- Just a toggle with outside-click and Escape dismissal.
+- Use grid utilities, such as `.grid-3`, for wider multi-column flyouts.
+
+```html demo
+<nav aria-label="Main navigation">
+  <ul class="list-reset cluster">
+    <li class="flyout-trigger">
+      <button class="btn ghost"
+              type="button"
+              data-enhance="flyout"
+              aria-expanded="false"
+              aria-controls="products-panel">
+        Products
+        <i class="ti ti-chevron-down" aria-hidden="true"></i>
+      </button>
+
+      <div class="flyout"
+           id="products-panel"
+           aria-label="Products"
+           data-flyout-mobile="auto"
+           hidden>
+        <section aria-labelledby="products-design">
+          <h3 id="products-design">Design</h3>
+          <ul>
+            <li><a href="/figma">Figma integration</a></li>
+            <li><a href="/tokens">Design tokens</a></li>
+          </ul>
+        </section>
+
+        <section aria-labelledby="products-dev">
+          <h3 id="products-dev">Development</h3>
+          <ul>
+            <li><a href="/components">Components</a></li>
+            <li><a href="/api">API</a></li>
+          </ul>
+        </section>
+
+        <footer>
+          <a href="/pricing" class="btn primary">See pricing</a>
+        </footer>
+      </div>
+    </li>
+
+    <li><a href="/about" class="btn ghost">About</a></li>
+    <li><a href="/contact" class="btn ghost">Contact</a></li>
+  </ul>
+</nav>
+```
+
+## Mega menu
+
+Use `class="flyout grid-3"` when a nav panel needs multiple link groups. Keep
+links regular anchors and let the panel collapse to a one-column sheet on mobile
+with `data-flyout-mobile="auto"`.
+
+```html demo
+<nav aria-label="Product navigation">
+  <ul class="list-reset cluster">
+    <li class="flyout-trigger">
+      <button class="btn ghost"
+              type="button"
+              data-enhance="flyout"
+              aria-expanded="false"
+              aria-controls="product-mega-menu">
+        Platform
+        <i class="ti ti-chevron-down" aria-hidden="true"></i>
+      </button>
+
+      <div class="flyout grid-3"
+           id="product-mega-menu"
+           aria-label="Platform"
+           data-flyout-mobile="auto"
+           style="--flyout-inline-size: 42rem; --flyout-max-inline-size: 42rem"
+           hidden>
+        <section aria-labelledby="mega-design">
+          <h3 id="mega-design">Design</h3>
+          <ul>
+            <li><a href="/figma">Figma integration</a></li>
+            <li><a href="/tokens">Design tokens</a></li>
+            <li><a href="/handoff">Developer handoff</a></li>
+          </ul>
+        </section>
+
+        <section aria-labelledby="mega-develop">
+          <h3 id="mega-develop">Development</h3>
+          <ul>
+            <li><a href="/components">Components</a></li>
+            <li><a href="/api">API</a></li>
+            <li><a href="/changelog">Changelog</a></li>
+          </ul>
+        </section>
+
+        <section aria-labelledby="mega-operate">
+          <h3 id="mega-operate">Operate</h3>
+          <ul>
+            <li><a href="/analytics">Analytics</a></li>
+            <li><a href="/security">Security</a></li>
+            <li><a href="/support">Support</a></li>
+          </ul>
+        </section>
+
+        <footer class="cluster"
+                style="grid-column: 1 / -1; --cluster-justify: flex-end; border-block-start: var(--border-width) solid var(--border)">
+          <a href="/pricing" class="btn primary">See pricing</a>
+        </footer>
+      </div>
+    </li>
+  </ul>
+</nav>
+```
+
+## Context menu
+
+Context menus use the same `.menu > li > .menu-item` presentation primitive as
+action-list flyouts.
+
+Put `data-context-menu` on the smallest unit the actions operate on: a file row,
+card, or canvas item. Several units may reference the same
+`<menu class="flyout">`. An explicit trigger button inside the unit, marked with
+`data-context-menu-trigger` and `aria-controls`, opens the menu through the same
+context-aware path — its `aria-controls` must match the `data-context-menu` id
+of the host.
+
+Before opening, the context element dispatches the cancelable
+`actual:context-menu` event. Its `detail` contains the shared `menu`, the owning
+`context`, the exact `origin`, and the opening `trigger` (`pointer`, `touch`,
+`keyboard`, or `button`). Use it to tailor the static menu to the selected item,
+or cancel the event to keep it closed. `contextFor(menu)` from
+`actual-css/js/context-menu` returns that detail while handling a menu action.
+Context menus dismiss when a new user interaction scrolls their surrounding
+content. Scroll caused by opening focus, and scrolling inside the menu itself,
+do not dismiss it.
+
+Add `data-context-menu-scope` only when the flyout should stay inside a specific
+region. Empty or `self` constrains to the target itself, `parent` constrains to
+the parent, and a selector constrains to the closest matching ancestor or first
+matching element. The scope also constrains the available height, so omit it
+when the menu is allowed to escape the card or list item.
+
+Long press is opt-in with `data-context-menu-long-press`. Empty uses the default
+delay; a number sets the delay in milliseconds.
+
+```html demo
+<div class="card stack"
+     id="file-card"
+     data-context-menu="file-actions"
+     data-context-menu-long-press
+     tabindex="0"
+     style="min-block-size: 12rem;">
+  <div class="cluster justify-content-space-between items-center">
+    <strong>File.pdf</strong>
+    <button class="btn ghost"
+            type="button"
+            data-context-menu-trigger
+            aria-controls="file-actions"
+            id="file-actions-trigger">
+      More
+    </button>
+  </div>
+  <p class="text-sm text-muted">Right click a detail below, press the context-menu key, or use More.</p>
+  <div class="cluster">
+    <span class="badge" data-context-item="File name">File.pdf</span>
+    <span class="badge" data-context-item="Owner">Design team</span>
+  </div>
+  <output id="context-result" class="text-sm text-muted" aria-live="polite">No context selected.</output>
+
+  <menu class="flyout menu"
+        id="file-actions"
+        aria-labelledby="file-actions-trigger"
+        hidden>
+    <li><button class="menu-item" type="button">Open</button></li>
+    <li><button class="menu-item" type="button">Rename</button></li>
+    <hr class="menu-separator" role="separator">
+    <li><button class="menu-item danger" type="button">Delete</button></li>
+  </menu>
+</div>
+
+<script>
+  const card = document.getElementById("file-card");
+  const result = document.getElementById("context-result");
+
+  card.addEventListener("actual:context-menu", (event) => {
+    const item = event.detail.origin.closest?.("[data-context-item]");
+    const label = item?.dataset.contextItem ?? "the card";
+    result.textContent = `Menu opened for ${label} (${event.detail.trigger}).`;
+  });
+</script>
+```
+
+## CSS hooks
+
+- `--flyout-inline-size` — panel width.
+- `--flyout-max-inline-size` — panel width cap.
+- `--menu-item-size` — minimum row height of `.menu-item`.
+- `--menu-item-icon-size` — shared leading-column width for icons and checked-state indicators.
+
+`--available-height` and `--surface-anchor-width` are written by the positioner
+at runtime, not set by the author. See the JavaScript runtime documentation.

package/docs/pages/enhancements/overview.md

@@ -0,0 +1,36 @@
+# Progressive Enhancements
+
+> The optional JavaScript runtime that completes Actual's interactive components — dialog, drawer, flyout, tooltip, tabs, scrollspy, and status bar — through progressive enhancement.
+
+UI components need JavaScript or modern platform behavior to be complete. They
+follow the same principles as every component: semantic markup first, small
+class API, shared tokens, and progressive enhancement.
+
+- CSS owns layout, surfaces, state styling, and transitions.
+- JavaScript owns open/closed state, ARIA synchronization, focus management, keyboard behavior, and dismissal.
+- Prefer native platform features when they fit, with small helpers where browser support or ergonomics need it.
+- Keep behavior optional when possible. Markup should remain understandable without JavaScript.
+- Use shared button classes and variants for triggers.
+- Do not add toasts. Use alerts, status regions, dialogs, or inline validation instead.
+
+## Modules
+
+The full runtime is `actual-css/js`. Each enhancer is also importable on its own
+for projects that use custom components or want a smaller behavior surface:
+
+```js
+import "actual-css/js/dialog";
+import "actual-css/js/flyout";
+import "actual-css/js/tooltip";
+```
+
+Enhancer modules self-register when imported. They do not require init calls and
+are safe to import during server-side rendering: outside a browser, registration
+is a no-op until the module is loaded again with a DOM.
+
+## Component pages
+
+Each interactive component has its own page documenting the exact markup its
+enhancement expects: Dialog, Drawer, Flyout, Tooltip, Tabs, Scrollspy, and
+Status Bar. The default runtime is loaded on the docs pages, so the examples
+work with the documented markup alone.

package/docs/pages/enhancements/scrollspy.md

@@ -0,0 +1,71 @@
+# Scrollspy
+
+> Behavior hook for navigation that marks the active section while the page scrolls.
+
+Scrollspy is a behavior hook, not a visual component. It marks a navigation
+region for the JavaScript enhancement. Pair it with `.nav-list` and `.nav-link`,
+or style `[aria-current]` yourself.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.scrollspy` | Component | Marks the nav region for the enhancer; adds no visual styles. |
+| `.nav-list` | Composition | Vertical list of navigation links. |
+| `.nav-link` | Component | Navigation link whose active state comes from `[aria-current]`. |
+
+## Usage
+
+- `.scrollspy` marks the region for JS detection. It does not add visual styles.
+- `.nav-list` and `.nav-link` provide the visible list and active link styling.
+- The JS enhancer toggles `aria-current="location"` on the active link. Without JavaScript, the links remain regular anchor links.
+- Detection is geometric and deterministic: on each scroll, the active section is the last one whose top has crossed an activation line. Reaching the end of the scroll always activates the last section, and sitting above the first activates none.
+- `data-scrollspy-root="#container"` measures a scroll container instead of the viewport.
+- `data-scrollspy-offset` moves the activation line: a bare number or `px` value is pixels, a `%` value is a share of the root's visible height. Invalid values fall back to `20%`, and negatives clamp to `0`.
+- The same markup also works with the CSS-native scroll markers path (see below).
+
+```html demo
+<nav class="scrollspy" data-enhance="scrollspy" aria-label="Page sections">
+  <ol class="nav-list stack">
+    <li><a class="nav-link" href="#overview" aria-current="location">Overview</a></li>
+    <li><a class="nav-link" href="#tokens">Tokens</a></li>
+    <li><a class="nav-link" href="#components">Components</a></li>
+  </ol>
+</nav>
+
+<main>
+  <section id="overview" tabindex="-1">
+    <h2>Overview</h2>
+  </section>
+
+  <section id="tokens" tabindex="-1">
+    <h2>Tokens</h2>
+  </section>
+
+  <section id="components" tabindex="-1">
+    <h2>Components</h2>
+  </section>
+</main>
+```
+
+## Native scroll markers
+
+Modern browsers are starting to support CSS-native scroll markers with
+`scroll-target-group` and `:target-current`. This can style the active link
+without JavaScript.
+
+```css
+@supports selector(:target-current) {
+  .scrollspy {
+    scroll-target-group: auto;
+  }
+
+  .scrollspy a:target-current {
+    color: var(--primary);
+    font-weight: var(--font-weight-medium);
+  }
+}
+```
+
+Keep this as progressive enhancement. The JavaScript enhancement remains the
+portable fallback — the same markup serves both paths.

package/docs/pages/enhancements/status-bar.md

@@ -0,0 +1,72 @@
+# Status Bar
+
+> Singleton floating area for short, non-critical, transient feedback.
+
+A status bar is a single live region, not a stacked toaster. New messages
+replace the previous one. Keep one element in the HTML, styled with
+`.status-bar` and carrying the `[data-status][role="status"]` contract that the
+runtime targets, empty by default.
+
+- JavaScript only updates its text content; it shows when non-empty and hides when empty, while staying available as a live region.
+- Use it for transient status (`Saved.`, `Reconnected.`, `Copied.`). Critical, persistent, or actionable information belongs in `.alert`, inline messages, or dialogs.
+- Intents: `danger`, `success`, `warning`, `neutral`. The default (no intent) is a neutral dark pill.
+
+The runtime auto-wires the status bar to Actual's form validation: a form that
+fails to submit shows its `data-validation-message` in the status bar with the
+`danger` intent. No target in the DOM means the call is a no-op, so the markup
+stays optional.
+
+```html demo
+<form class="needs-validation" data-enhance="validation" data-validation-message="Please check the highlighted fields.">
+  <label class="field">
+    <span class="field-label">Email</span>
+    <input class="input" type="email" name="email" required
+           aria-describedby="sb-email-error" />
+    <span class="field-error" id="sb-email-error" role="alert">Enter a valid email.</span>
+  </label>
+  <div class="form-actions">
+    <button class="btn primary" type="submit">Submit</button>
+  </div>
+</form>
+```
+
+Submitting the empty form blocks submission and shows `data-validation-message`
+in the status bar below — no JavaScript required beyond the runtime.
+
+```html demo
+<div class="cluster">
+  <button class="btn" type="button" commandfor="sb-status" command="--status"
+          aria-controls="sb-status"
+          data-status-message="Saved." data-status-intent="success">Show success</button>
+  <button class="btn" type="button" commandfor="sb-status" command="--status"
+          aria-controls="sb-status"
+          data-status-message="Could not save." data-status-intent="danger"
+          data-status-duration="6000">Show danger</button>
+  <button class="btn outline" type="button" commandfor="sb-status" command="--status-clear"
+          aria-controls="sb-status">Clear</button>
+</div>
+
+<div class="status-bar" data-status id="sb-status" role="status" aria-live="polite" aria-atomic="true"></div>
+```
+
+No script required beyond the runtime: `command="--status"` reads its message
+from `data-status-message` (plus optional `data-status-intent` /
+`data-status-duration`), `command="--status-clear"` empties the bar.
+`commandfor` must match the status bar's own `id`.
+
+For dynamic messages — a fetch response, a computed value — dispatch the same
+event the commands use under the hood:
+
+```js
+document.dispatchEvent(new CustomEvent("actual:status", {
+  bubbles: true,
+  detail: { message: "Saved.", intent: "success" },
+}));
+```
+
+## CSS hooks
+
+- `--status-bg` — bar background.
+- `--status-fg` — bar text color.
+
+Prefer an intent class over setting these directly.

package/docs/pages/enhancements/tabs.md

@@ -0,0 +1,80 @@
+# Tabs
+
+> In-place panel switcher using real tab semantics, with roving tabindex and arrow-key navigation.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.tabs` | Component | Tab strip; pairs with `role="tablist"`. |
+| `.tab` | Component | One tab trigger; pairs with `role="tab"`. |
+| `.primary` | Intent | Tints the selected tab's indicator and text. |
+
+## Usage
+
+- Use real tab semantics when panels switch in place.
+- Use normal links and `aria-current="page"` for page navigation that only looks like tabs.
+- JavaScript owns roving `tabindex`, `aria-selected`, `hidden`, and keyboard behavior.
+- Left/Right select tabs and wrap at the ends. Home/End jump to first/last. Down moves focus into the selected panel.
+- A tab list needs both `.tabs` and `role="tablist"`; `.tab` styles each trigger.
+- A `.tab` with an icon uses `--tab-gap` (default `0.375em`) for the space between icon and label.
+
+```html demo
+<div class="tabset">
+  <div class="tabs" data-enhance="tabs" role="tablist" aria-label="Settings">
+    <button class="tab primary"
+            type="button"
+            role="tab"
+            aria-selected="true"
+            aria-controls="panel-general"
+            id="tab-general">
+      General
+    </button>
+    <button class="tab"
+            type="button"
+            role="tab"
+            aria-selected="false"
+            aria-controls="panel-security"
+            id="tab-security"
+            tabindex="-1">
+      Security
+    </button>
+    <button class="tab"
+            type="button"
+            role="tab"
+            aria-selected="false"
+            aria-controls="panel-billing"
+            id="tab-billing"
+            tabindex="-1">
+      Billing
+    </button>
+  </div>
+
+  <section role="tabpanel" id="panel-general" aria-labelledby="tab-general" tabindex="-1" class="py">
+    General content
+  </section>
+  <section role="tabpanel" id="panel-security" aria-labelledby="tab-security" tabindex="-1" hidden class="py">
+    Security content
+  </section>
+  <section role="tabpanel" id="panel-billing" aria-labelledby="tab-billing" tabindex="-1" hidden class="py">
+    Billing content
+  </section>
+</div>
+```
+
+For navigation that only looks like tabs, keep it a plain link list — no
+JavaScript involved:
+
+```html demo
+<nav aria-label="Account sections">
+  <ul class="tabs">
+    <li><a class="tab primary" href="#account" aria-current="page">Profile</a></li>
+    <li><a class="tab" href="#security">Security</a></li>
+    <li><a class="tab" href="#billing">Billing</a></li>
+  </ul>
+</nav>
+```
+
+## CSS hooks
+
+- `--tab-gap` — space between an icon and the label text (default `0.375em`).