@livx.cc/bare-v3 0.1.0-alpha.10

package/dist/references/cross-screen.md

@@ -0,0 +1,34 @@
+# One app, phone and desktop
+
+Default to a useful layout on both screens. Phone-first or desktop-first is a deliberate brief choice; neither means ignoring the other screen. Establish the information hierarchy once and preserve meaningful DOM order.
+
+Choose a semantic composition:
+
+- Peers such as cards, metrics or routine groups: `b3-grid` fits as many readable columns as the container allows. Set `--b3-grid-min` to a useful minimum (8rem for concise metrics; the default is 17rem).
+- Actions or filters: `b3-cluster` wraps independent peers. `b3-inline` keeps an icon and label together while the label text wraps.
+- Title and actions: `b3-split` separates groups and wraps when necessary.
+- A bounded page: `b3-shell`; set `--b3-content` to the desired content measure.
+- Reading: `b3-prose` bounds paragraphs. A short form should not expand merely because the screen is wide.
+- A bounded app with persistent navigation: `b3-mobile-app b3-app-frame`, with direct `header`, `main`, and `nav` children. Read `app-frame.md`. The main scrolls; grid reserves the real bar height. Do not add fixed-bar padding.
+- An app with legacy fixed bottom navigation: read `mobile.md`. The shell supports wide content; platform styling is independent of viewport width.
+
+```html
+<main class="b3-shell b3-stack">
+  <header class="b3-split">
+    <div><h1 class="b3-title">Your next plans</h1><p class="b3-muted">Make room for something good.</p></div>
+    <button class="b3-button" type="button">New plan</button>
+  </header>
+  <div class="b3-grid" aria-label="Plans">
+    <article class="b3-surface b3-stack"><h2 class="b3-heading">Morning walk</h2><p>One readable card.</p></article>
+    <article class="b3-surface b3-stack"><h2 class="b3-heading">Studio time</h2><p>A peer with the same hierarchy.</p></article>
+  </div>
+</main>
+```
+
+Use named CSS for app-specific composition, not a second utility vocabulary. Start with intrinsic wrapping and content bounds. Add a breakpoint only when the interaction or information hierarchy needs a real mode change. Do not shrink text, remove labels, duplicate a whole screen or create a phone frame to make a desktop layout fit.
+
+Task-first density matters as much as fitting the width. A dashboard should reveal useful data early; a marketing hero should not be reused as its header. When a sidebar becomes mobile navigation, remove duplicated context and relocate secondary links. Preserve primary destinations, readable text and touch targets. Verify the first meaningful content is actually visible at the target phone height, not just free of horizontal overflow.
+
+Read `dialog.md` before adding overlays. Backdrop dismissal suits details, navigation and reversible review. Entry forms need a deliberate draft/unsaved-work policy. Explicit close, Escape and backdrop should agree about whether work is retained; outside dismissal never confirms an action.
+
+Check the changed layout at one phone and one desktop width, plus a narrower boundary when content suggests risk. Inspect text wrapping, visual hierarchy, obscured actions and scroll behavior. Derive rem-based size expectations from the measured root font size. Reuse unchanged behavior evidence; do not retest persistence merely because a grid changed. A clean screenshot is not proof of native-device behavior.

package/dist/references/data-display.md

@@ -0,0 +1,9 @@
+# Tables, definitions and metrics
+
+Table-wrap provides intentional horizontal scroll. Use native table/caption/th scopes; data-b3-density=compact changes spacing. aria-selected is visual only: app owns selection and sorting. Definition uses dl/dt/dd. Stat groups label, value and explanation; format numbers in the app.
+
+Classes: b3-table-wrap, b3-table, b3-definition, b3-stat, b3-stat-value
+
+```html
+<div class="b3-table-wrap"><table class="b3-table"><caption>Invoices</caption><thead><tr><th scope="col">Client</th><th scope="col">Amount</th></tr></thead><tbody><tr><td>Studio North</td><td>$4800</td></tr></tbody></table></div><dl class="b3-definition"><dt>Status</dt><dd>Active</dd></dl>
+```

package/dist/references/dialog.md

@@ -0,0 +1,9 @@
+# Dialog and drawer
+
+Use native dialog with aria-labelledby and explicit close button. mount() wires data-b3-open=dialog-id and data-b3-close. showModal() owns focus containment, Escape dismissal and return focus. data-b3-placement=end presents a drawer with the same native modal behavior. App owns submission and unsaved-change decisions. Set data-b3-backdrop=dismiss on read-only details, navigation drawers and reversible pickers. Forms default to no backdrop dismissal; preserve drafts or guard the cancel event when work could be lost. Backdrop dismissal requires a pointer press and release outside the panel, so dragging from inside does not close it. Backdrop and data-b3-close dispatch cancel before closing; preventDefault keeps the dialog open, matching native Escape. Never use outside dismissal as confirmation of a destructive action.
+
+Classes: b3-dialog
+
+```html
+<button class="b3-button" data-b3-open="confirm">Open dialog</button><dialog class="b3-dialog" id="confirm" aria-labelledby="confirm-title"><h2 id="confirm-title">Confirm changes</h2><p>Review before continuing.</p><button class="b3-button" data-b3-close>Close</button></dialog>
+```

package/dist/references/disclosure.md

@@ -0,0 +1,9 @@
+# Accordion, dropdown and hierarchy
+
+Accordion and dropdown use native details/summary. Dropdown is a disclosure containing ordinary links/buttons, not an ARIA menu. mount() adds outside-click and Escape dismissal. Tree is a nested list/details presentation, not a role=tree widget. Browser disclosure behavior supplies keyboard activation.
+
+Classes: b3-accordion, b3-dropdown, b3-dropdown-panel, b3-tree
+
+```html
+<details class="b3-accordion"><summary>More information</summary><p>Useful details.</p></details><details class="b3-dropdown"><summary class="b3-button">Actions</summary><div class="b3-dropdown-panel"><a class="b3-nav-link" href="#details">View details</a></div></details>
+```

package/dist/references/feedback.md

@@ -0,0 +1,9 @@
+# Alerts, toast and loading
+
+Alert data-b3-tone supports info, success, warning, danger. Include explanatory text; icons/color alone are insufficient. Add role=alert only for urgent dynamic messages. Toast region uses aria-live=polite and toast dismissal data-b3-dismiss with mount(). No automatic timers are imposed. Spinner/skeleton need a separate accessible loading description; decorative shapes use aria-hidden. Reduced motion uses root defaults.
+
+Classes: b3-alert, b3-toast-region, b3-toast, b3-spinner, b3-skeleton
+
+```html
+<div class="b3-alert" data-b3-tone="warning"><div><strong>Check your input</strong><p>Enter a valid email address.</p></div></div><div class="b3-toast-region" aria-live="polite"><div class="b3-toast"><p>Changes saved.</p><button class="b3-button" data-b3-dismiss>Dismiss</button></div></div>
+```

package/dist/references/field.md

@@ -0,0 +1,9 @@
+# Input and error
+
+Associate label for/id. Use aria-invalid and aria-describedby for errors; explain a fix. Never depend on color alone. App owns validation. Native input/select/textarea behavior is retained. Single selects reserve an inline-end indicator lane that mirrors in RTL; multiple/listbox selects keep native presentation. Forced-colors mode restores the native indicator.
+
+Classes: b3-field, b3-input, b3-error
+
+```html
+<div class="b3-field"><label for="name">Name</label><input id="name" class="b3-input" aria-invalid="true" aria-describedby="error"><p id="error" class="b3-error">Enter a name.</p></div>
+```

package/dist/references/form-composition.md

@@ -0,0 +1,9 @@
+# Native form composition and input variants
+
+Group related controls with fieldset/legend; use b3-form-grid for responsive rows. Choice cards are labels containing a single native radio or checkbox and descriptive text; checked, focus-visible and disabled appearance follow the input. Use b3-help with aria-describedby; success/warning tones require meaningful text and never imply remote validation. Inputs support data-b3-size=small/large, data-b3-emphasis=subtle/outline and data-b3-tone=success/warning. aria-invalid=true always has error-border priority. b3-range styles the native range control; app owns its output. Native file, date, time, color and multi-select preserve browser behavior. File selection does not upload anything. Keep all controls labelled. For validation, link a focused error summary to each invalid field, preserve help references and user input, and clear errors when corrected. App owns validation/persistence; no hidden form submission handler.
+
+Classes: b3-form-grid, b3-fieldset, b3-help, b3-range, b3-choice-card
+
+```html
+<fieldset class="b3-fieldset"><legend>Workspace type</legend><div class="b3-form-grid"><label class="b3-choice-card"><input type="radio" name="kind" value="studio"><span>Studio</span></label><label class="b3-choice-card"><input type="radio" name="kind" value="team"><span>Team</span></label></div></fieldset><div class="b3-field"><label for="seats">Seats</label><input class="b3-range" id="seats" type="range" min="2" max="20" value="5" aria-describedby="seats-help"><p class="b3-help" id="seats-help">Include the owner.</p></div>
+```

package/dist/references/foundation.md

@@ -0,0 +1,9 @@
+# Root and theme
+
+Place b3-root on html to synchronize the document canvas and native controls. Set data-b3-theme="dark" explicitly for dark mode. Nested roots reset tokens; set their theme explicitly. Override complete CSS values in --b3-* properties. Consumer CSS is unlayered and wins over library defaults. Scope custom palette overrides to each theme: unlayered :root token overrides beat layered library dark defaults. Use .b3-root:not([data-b3-theme="dark"]) for light-only colors and .b3-root[data-b3-theme="dark"] for dark overrides. Set foreground/background pairs together.
+
+Classes: b3-root
+
+```html
+<html class="b3-root" data-b3-theme="dark">
+```

package/dist/references/icons.md

@@ -0,0 +1,14 @@
+# Icons
+
+Use `b3-icon` on an inline SVG with a viewBox. It supplies a 1.25em square that does not shrink in a flex row. Use `b3-inline` to align an icon with its label. Decorative SVGs need `aria-hidden="true"` and `focusable="false"`; the surrounding button supplies the accessible name. Icon-only buttons need an accessible name, a visible focus indicator and a minimum 44px hit target. Do not use a tooltip as the only label.
+
+```html
+<button class="b3-button b3-inline">
+  <svg class="b3-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true" focusable="false"><path d="M5 12h14m-6-6 6 6-6 6"/></svg>
+  Continue
+</button>
+```
+
+Choose one coherent icon family for each app. Keep stroke, optical size and filled/outline state consistent. `currentColor` follows the control's foreground/background pair in either theme. Directional arrows may need mirroring in RTL; symbols such as a clock or check should not be mirrored automatically.
+
+Bare-v3 supplies layout and styling, not an icon asset catalog or icon font. The playground provides the full pinned Lucide catalog with name/tag search, selection and copyable SVG. Its lazy catalog is workbench-only and never enters the runtime package. In Blank use the host's `blank.assets.icon('name')` provider with supported literal names; map variable states to literal calls, because Blank validates those calls. Asset availability is a host capability, not a bare-v3 promise. Platform-native icon fidelity remains unqualified.

package/dist/references/identity.md

@@ -0,0 +1,9 @@
+# Avatars and icons
+
+Icon styles an inline SVG. Label icon-only actions; decorative icons use aria-hidden. Avatar renders initials or an image with meaningful alt text, not both spoken twice. Avatar-stack overlaps peers. kbd represents a real keyboard shortcut, not a working binding.
+
+Classes: b3-icon, b3-avatar, b3-avatar-stack, b3-kbd
+
+```html
+<span class="b3-avatar" aria-label="Alex Lee">AL</span><kbd class="b3-kbd">Enter</kbd><svg class="b3-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M5 12h14M12 5v14"/></svg>
+```

package/dist/references/layout.md

@@ -0,0 +1,9 @@
+# Composition
+
+Shell bounds the page. Stack is vertical, cluster wraps horizontal peers, grid fits columns, split separates two groups. Override --b3-space locally. Preserve meaningful DOM order. Default to phone and desktop support. Use intrinsic peer columns and wrapping before media queries; bound reading/forms separately from the page. Set --b3-content for shell width. Read cross-screen.md for composition choices and targeted verification. In a bounded b3-stack, b3-scroll makes one body independently scrollable while sibling heading/actions stay in flow. Supply a meaningful height or max-height; scrolling cannot occur without a bound. Name a keyboard-focusable scroll region with tabindex=0 and aria-labelledby. Reuse the same atom in panels, dialogs and sheets. Inline keeps a small icon/text or label/badge group together, vertically centers peers and lets the text itself wrap. Use cluster for independently wrapping peers; use inline when wrapping the icon away from its label would break the meaning. Set --b3-grid-min to the minimum useful peer width (e.g. 8rem for concise metrics); the same grid then fits columns without per-screen column counts.
+
+Classes: b3-shell, b3-stack, b3-cluster, b3-grid, b3-split, b3-scroll, b3-inline
+
+```html
+<main class="b3-shell b3-stack"><header class="b3-split">…</header></main>
+```

package/dist/references/marketing.md

@@ -0,0 +1,9 @@
+# Product-page composition
+
+Hero and feature compose copy beside a visual; both stack below 48rem. Hero data-b3-align=center is a single centered column. Feature data-b3-reverse=true reverses visual order only on wide screens; keep reading order logical. Pricing featured state uses data-b3-featured=true. Price changes, billing period and selection belong to the app. Checklist marks are decorative; write meaningful list text. Quote uses figure/blockquote/figcaption with truthful attribution. Art data-b3-art=dots/glow/wash is static decoration behind content, adapts to theme roles and must not replace readable surfaces. Do not invent testimonials, payment success or integrations.
+
+Classes: b3-hero, b3-hero-copy, b3-feature, b3-feature-icon, b3-pricing, b3-price, b3-checklist, b3-quote, b3-art
+
+```html
+<section class="b3-hero"><div class="b3-hero-copy"><h1 class="b3-title">Make room for good work.</h1><p>A clear product promise.</p><a class="b3-button" href="#pricing">Explore plans</a></div><div class="b3-art" data-b3-art="dots">Product preview</div></section>
+```

package/dist/references/mobile.md

@@ -0,0 +1,9 @@
+# Mobile app composition
+
+For new apps with persistent navigation, read app-frame.md first: grid owns the navigation height rather than a fixed-padding estimate. Use b3-mobile-app on the app container with data-b3-platform=ios or android. Native anchors carry navigation; app owns URLs/history and aria-current=page. Bottom navigation stays available across primary destinations. Use dialog.b3-sheet with showModal(), a label and explicit cancel; app owns form state and focus restoration. Layout reserves env safe-area insets and targets 44/48 CSS pixels as a starting treatment, not proof of physical platform sizing. Test software keyboard, large text, orientation, real touch and device insets. Never draw fake OS status/gesture bars inside app content. Native runtime and platform fidelity require separate qualification. Default app width supports phone and desktop up to70rem; use intrinsic wrapping grids for content. Set --b3-app-width only for an intentional narrower surface. A platform treatment does not imply a phone-only layout. For a scrollable sheet use dialog.b3-sheet.b3-stack with a direct b3-scroll body and fixed siblings. For optional handle dragging add data-b3-drag=dismiss and button.b3-sheet-handle with data-b3-close and aria-label="Close sheet". mount() handles drag-to-dismiss through the cancel event. Body gestures remain native scrolling. A handle click/keyboard activation also closes. No multiple detents or content-wide drag are implied. The mounted helper gives a labeled sheet heading initial focus unless the app declares an explicit autofocus target; handles remain keyboard reachable. The sheet owns outer padding and the bottom safe area: do not repeat these on its header/body/footer. Keep b3-scroll intrinsic sizing instead of overriding it with flex:1 or a zero flex basis. Sheets fit content up to 85dvh and a 32rem reading width by default; --b3-overlay-width is an explicit width escape hatch for denser content. Use a b3-stack footer for a full-width primary action, and group descriptive row text in a stack rather than competing columns. b3-mobile-app already reserves bottom space for its fixed navigation. Do not add a second matching bottom padding to a child panel. Use b3-app-bar or an explicit comfortable top inset; a safe-area value of zero is not ordinary content spacing.
+
+Classes: b3-mobile-app, b3-app-bar, b3-bottom-nav, b3-bottom-link, b3-mobile-list, b3-mobile-row, b3-sheet, b3-sheet-handle
+
+```html
+<div class="b3-mobile-app" data-b3-platform="ios"><header class="b3-app-bar">Today</header><main><ul class="b3-mobile-list"><li><a class="b3-mobile-row" href="#detail">Read a few pages</a></li></ul></main><nav class="b3-bottom-nav" aria-label="Main"><a class="b3-bottom-link" href="#today" aria-current="page">Today</a></nav></div>
+```

package/dist/references/motion.md

@@ -0,0 +1,44 @@
+# Motion design
+
+Use motion to preserve continuity, establish hierarchy, and acknowledge meaningful actions. A scene can enter with rhythm; an object should move to its new place; a dragged surface should follow the pointer and return convincingly. Avoid applying the same flourish to every control.
+
+## Small shared API
+
+```js
+import { motion, layout, sequence, settle } from '@livx.cc/bare-v3/ui';
+// Commit the real state immediately. Motion explains it.
+status.textContent = 'Saved';
+motion(status, 'update');
+layout(list, () => list.prepend(list.lastElementChild));
+sequence(scene.querySelectorAll('[data-scene-part]'));
+settle(card, { x: 40, y: -24 });
+```
+
+In Blank these functions are already installed as `window.BareV3UI`; do not import or mount them again. Read only the references needed for the current composition.
+
+| Helper | Intent and contract |
+| --- | --- |
+| `motion(element, 'enter')` | 320ms eased entrance, 12px travel and a small scale change. Use for a newly revealed panel, not every label. |
+| `motion(element, 'exit')` | 180ms departure. Its Animation.finished may sequence visual removal, but must never delay saving business state. |
+| `motion(element, 'update')` | 180ms fade for a changed status or content. |
+| `motion(element, 'confirm')` | 380ms restrained overshoot on a small success mark. Reserve for a meaningful completion. |
+| `motion(element, 'reveal')` | 440ms clipped reveal for an authored scene. |
+| `sequence(elements, intent?)` | Stagger with 45ms increments capped at 180ms; no unbounded wait for large collections. |
+| `layout(root, synchronousUpdate)` | Measure and animate stable nodes marked with unique, non-empty `data-b3-layout="key"`. Keeps DOM identity, focus and listeners; no clones or snapshots. |
+| `settle(element, {x?, y?})` | A 460ms damped spring from a pointer displacement to untransformed resting layout. Gesture recognition and bounds remain caller-owned; sheets already provide handle dragging. |
+
+Animation helpers cancel their previous animation on the same element. Interrupted layout changes begin at the currently visible positions. Cancellation exposes the committed final state. Individual motion/settle calls return Animation or null; layout/sequence return arrays. OS reduced motion, or an ancestor `data-b3-motion="reduce"`, preserves final state while removing motion. OS changes cancel running helper animations. Use an inner wrapper if the element has a custom resting transform; these presets assume an untransformed rest state.
+
+## Overlays and gesture ownership
+
+Native `dialog` plus the mounted shared helper provides modal focus/inertness, backdrop policy, Escape, exit and focus restoration. Dialogs enter in 280ms, sheets in 320ms, shared exits take 160ms, and incomplete drags settle with the shared spring. Cancelable Escape requests route through the same guard and exit as explicit/backdrop dismissal. Browsers can force a native close after repeated Escape without intervening activation; retain drafts independently of a cancel guard. Data-entry surfaces must preserve drafts or cancel dismissal. Read dialog.md and mobile.md for header/direct scroll body/footer composition. Do not add a second animation or remount handler to an already mounted sheet.
+
+## Composition recipes
+
+The playground's motion studio shows shared geometry, real DOM reordering, direct pointer tracking and spring return, staged scene entrance, cancellable exit/entry exchange, and a collection sheet. The adjacent collapsed feedback recipes cover pending/error/retry, undo/focus recovery and loading with reserved space. Their illustrative content and simulated operations are not runtime services.
+
+For an expanding card beside text: exit the neighboring copy before moving into its space; reveal the copy only after the return layout completes. Guard each completion against newer input. FLIP preserves geometry but does not prevent sibling intersections.
+
+For view replacement: start an exit; guard its completion with a monotonically increasing request id; if it still owns the transition, update content and enter. Rapid navigation must not commit an obsolete view. Do not await a confirmation animation before enabling the next action.
+
+Delight also needs strong composition, legible rhythm, good artwork, precise touch/focus states and useful empty/error states. Never animate foreground/background theme colors through unreadable intermediate pairs; avoid transition:all, perpetual decoration or automatic sound. Host haptics, multi-detent sheets, velocity flings, content-wide sheet dragging and scroll-to-drag handoff remain separate device-qualified capabilities. This alpha does not claim complete native fidelity or universal design quality.

package/dist/references/navigation.md

@@ -0,0 +1,9 @@
+# Navigation and breadcrumbs
+
+Use nav with accessible label; aria-current=page marks the active link. data-b3-orientation=vertical creates sidebar navigation. Breadcrumbs is an ol within labeled nav. Native links own navigation; no hidden routing system.
+
+Classes: b3-nav, b3-nav-link, b3-breadcrumbs
+
+```html
+<nav class="b3-nav" aria-label="Main"><a class="b3-nav-link" href="/" aria-current="page">Overview</a><a class="b3-nav-link" href="/projects">Projects</a></nav>
+```

package/dist/references/page-layout.md

@@ -0,0 +1,9 @@
+# Page composition
+
+Page/body form a full-height document. App-layout supplies a sidebar and content region, stacking below 48rem. Center aligns its children. Cover gives a hero room; reel provides intentional horizontal scrolling. Preserve document order and label scrollable collections.
+
+Classes: b3-page, b3-page-body, b3-app-layout, b3-sidebar, b3-center, b3-cover, b3-reel
+
+```html
+<div class="b3-app-layout"><aside class="b3-sidebar">Navigation</aside><main class="b3-page"><header>Page heading</header><div class="b3-page-body b3-shell">Content</div><footer>Footer</footer></main></div>
+```

package/dist/references/reading.md

@@ -0,0 +1,9 @@
+# Reading layout and document outline
+
+Reading contains exactly one article and one nav.b3-toc with an accessible label. Author ordinary #id links and unique heading IDs; nested ordered lists express heading levels. Set heading tabindex=-1 for native fragment focus and scroll-margin-block-start for any fixed header. Optional mount() tracks [data-b3-toc] links with aria-current=location from window scroll; it does not generate IDs, rewrite links, relocate content or manage routing. The outline is sticky beside the article above 48rem and precedes it below. --b3-outline-top controls sticky offset. This first version tracks window scrolling, not nested scroll containers. Dynamic heading/link changes require cleanup and remount.
+
+Classes: b3-reading, b3-toc, b3-toc-link
+
+```html
+<div class="b3-reading"><nav class="b3-toc" data-b3-toc aria-label="On this page"><ol><li><a class="b3-toc-link" href="#purpose">Purpose</a></li></ol></nav><article class="b3-prose"><h2 id="purpose" tabindex="-1">Purpose</h2><p>A readable guide.</p></article></div>
+```

package/dist/references/row.md

@@ -0,0 +1,9 @@
+# List row
+
+Use li inside ul or ol when listing items. The row owns only spacing and a divider; app owns completion, selection, and ordering. Long content should wrap.
+
+Classes: b3-row
+
+```html
+<ul><li class="b3-row">Read ten pages</li></ul>
+```

package/dist/references/start.md

@@ -0,0 +1,21 @@
+# Build with bare-v3
+
+Start with a complete HTML document, viewport metadata, a meaningful title, and `class="b3-root"` on html. Link the shipped CSS. Use native HTML and ordinary JavaScript; there is no framework or hidden interaction runtime.
+
+Default to a clean app that works on phone and desktop. Use intrinsic grids and wrapping before adding breakpoints; read cross-screen.md when composing the page. Read mobile.md only when platform-specific app structure is relevant.
+
+Choose a composition before choosing components. Establish the main task, the dominant visual element, and the supporting information. Use surfaces only when grouping helps. A list can be rows and dividers; a timer can be large type and empty space. Custom CSS is welcome for the app's identity.
+
+Read foundation.md for tokens and theme rules; layout.md for flexible composition; field.md for forms and errors; button.md for actions; status.md for progress. Use CSS custom properties with complete values, e.g. `--b3-color-accent: #315b43`. Scope palette overrides to light or dark explicitly; an unconditional unlayered :root color override also overrides the library dark default. Keep foreground/background pairs readable. Override typography, density, shape, and composition to create an identity, rather than recoloring a fixed template.
+
+Task behavior belongs to the app. Persist user changes, handle reload, use native controls, associate labels, and announce meaningful changes. Never claim a control works because it looks correct. No remote scripts or implicit platform API is available.
+
+Prototype guidance is experimental. Comparison evidence has not established superiority over bare-v2 or external alternatives.
+
+For optional interactions, import `{ mount }` from `@livx.cc/bare-v3/ui` and call `mount(document)` once; retain the returned cleanup function when unmounting an app. Tabs use roles and explicit linked IDs. Dialog triggers use data-b3-open and native dialog; close actions use data-b3-close. Dropdowns are native details disclosures; the helper adds Escape/outside-click dismissal and viewport adjustment. Toasts are app-created content with data-b3-dismiss actions. Read tabs.md, dialog.md, disclosure.md and feedback.md before using these contracts. Do not assume routing, persistence or data behavior comes from the UI helper.
+
+For a product page, read marketing.md for hero/feature/pricing and static art treatments. For a guide or article, read reading.md for authored outline links, responsive structure and optional scroll tracking. These are compositions, not prescribed visual identities.
+
+For a command palette, read command.md and use the optional mount() behavior. Register a b3:command listener on the dialog to perform app-owned actions. Do not render a command that implies an unavailable service works; disable it with an explanation instead.
+
+For grouped forms, read form-composition.md and steps.md. Preserve draft values and unfinished entries across the documented save/reload path. Validate before advancing, show actionable errors linked to controls, review before committing, and claim success only after the actual save. A local preview is not a real account or invitation.

package/dist/references/status.md

@@ -0,0 +1,9 @@
+# Status and progress
+
+Badges need meaningful text. Use native progress with max/value and accessible label. Announce meaningful task changes via a separate status region; do not announce every timer tick. Badge supports data-b3-tone=success/warning/danger/info. Text must convey the status independently of color.
+
+Classes: b3-badge, b3-progress
+
+```html
+<progress class="b3-progress" aria-label="Daily goal" max="8" value="3"></progress>
+```

package/dist/references/steps.md

@@ -0,0 +1,9 @@
+# Step progress
+
+Use an ordered list with a meaningful accessible label. Exactly one b3-step has aria-current=step while the flow is active. Completed steps use data-b3-complete=true and explicit completed text for assistive technology; markers may be aria-hidden if meaning is repeated in text. This is a progress display, not a tablist. App owns Back/Continue, validation, review, persistence and heading focus after transitions. Do not make future steps look clickable if they cannot be reached. Completed saved state may replace the indicator with a completion heading.
+
+Classes: b3-stepper, b3-step, b3-step-marker
+
+```html
+<ol class="b3-stepper" aria-label="Setup progress"><li class="b3-step" aria-current="step"><span class="b3-step-marker" aria-hidden="true">1</span><span>Workspace</span></li><li class="b3-step"><span class="b3-step-marker" aria-hidden="true">2</span><span>People</span></li><li class="b3-step"><span class="b3-step-marker" aria-hidden="true">3</span><span>Review</span></li></ol>
+```

package/dist/references/surface.md

@@ -0,0 +1,9 @@
+# Surface
+
+Use surfaces to group meaningful content, not around every row. Use dividers or whitespace when a panel would add noise.
+
+Classes: b3-surface
+
+```html
+<section class="b3-surface" aria-labelledby="heading"><h2 id="heading">History</h2></section>
+```

package/dist/references/tabs.md

@@ -0,0 +1,9 @@
+# Tabbed views
+
+Optional mount() wires [role=tablist][data-b3-tabs]. Use native buttons with role=tab, unique id, aria-controls, aria-selected and matching role=tabpanel with aria-labelledby. Inactive panels start hidden. Arrow keys, Home/End and RTL direction select and focus tabs; disabled tabs are skipped. Native Tab exits the tablist.
+
+Classes: b3-tablist, b3-tab, b3-tabpanel
+
+```html
+<div class="b3-tablist" role="tablist" aria-label="Project" data-b3-tabs><button class="b3-tab" id="tab-a" role="tab" aria-controls="panel-a" aria-selected="true">Summary</button><button class="b3-tab" id="tab-b" role="tab" aria-controls="panel-b" aria-selected="false" tabindex="-1">Activity</button></div><section class="b3-tabpanel" id="panel-a" role="tabpanel" aria-labelledby="tab-a">Summary content</section><section class="b3-tabpanel" id="panel-b" role="tabpanel" aria-labelledby="tab-b" hidden>Activity content</section>
+```

package/dist/references/type.md

@@ -0,0 +1,9 @@
+# Hierarchy
+
+Use a single visual title and native heading hierarchy. Muted is secondary readable text. Label styling is optional and does not create a form label. Use b3-heading for dialog and sheet headings; b3-title is page-scale and should not be nested in a narrow overlay.
+
+Classes: b3-title, b3-heading, b3-muted, b3-label
+
+```html
+<h1 class="b3-title">Today, intentionally.</h1>
+```