docs: rewrite the documentation site for v1 (168 pages)

.docwright/tamagui-reference.md

@@ -0,0 +1,205 @@
+# Tamagui docs — structural reference (motif mirror)
+
+**Crawled:** 2026-05-15
+**Source:** `tamagui.dev/docs`, `tamagui.dev/ui/*`, `tamagui.dev/llms.txt`
+**Why this exists:** Phase 1 captures Tamagui's IA and per-component page template as the structural reference for motif's per-component pages. Motif borrows the shape, not the prose. Voice stays in `voice-card.md`.
+
+## Tamagui top-level IA
+
+Sidebar structure observed:
+
+```
+Core
+  Introduction
+  Installation
+  CLI
+  Releases
+  Configuration
+  Config v5                  (versioned config alternative)
+  Tokens
+  Themes
+  Styling
+  Components                 (overview, then UI section per-component)
+  Hooks
+  Animations
+  Compiler
+  Bundlers
+  Guides
+
+UI                           (component pages)
+  Intro
+  Stacks
+  Headings
+  Text
+  Native
+  Z-Index
+  Forms                      (group; multiple components inside)
+  Menus
+  Panels
+  Content
+  Functional
+  Visual
+  Dialog                     (one of ~20 component pages)
+  Button
+  …
+```
+
+Tamagui mixes flat Core docs with a separate UI namespace for per-component pages. The split is deliberate: Core covers "how to build with the styling system", UI covers "the components you can import".
+
+## Per-component page template (Tamagui)
+
+Observed across `Button`, `Dialog`, and other component pages:
+
+| #   | Section                                                            | Notes                                                                                                                                                                                                                             |
+| --- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **Title**                                                          | Component name, e.g. "Button".                                                                                                                                                                                                    |
+| 2   | **One-line subtitle**                                              | "Show a modal with configurable layout and accessible actions." Below the H1, not in frontmatter.                                                                                                                                 |
+| 3   | **Hero demo**                                                      | Interactive, often with multiple example tabs (Plain / Outlined / Active variants). "Show code" button reveals source.                                                                                                            |
+| 4   | **Features**                                                       | Bulleted list. "Size prop that works on all styles." "Comes with styling, yet completely customizable and themeable."                                                                                                             |
+| 5   | **Component reference links**                                      | Cross-links to related components / sub-component pages.                                                                                                                                                                          |
+| 6   | **Installation**                                                   | "Button is already installed in `tamagui`, or you can install it independently." NPM snippet for the dedicated package.                                                                                                           |
+| 7   | **Usage** (simple components) or **Anatomy** (compound components) | Button uses "Usage": `export default () => <Button>Lorem ipsum</Button>`. Dialog uses "Anatomy" with the full compound API laid out as nested JSX.                                                                                |
+| 8   | **Behavior-specific sections**                                     | Highly component-dependent. Dialog has "Scoping", "Dismissal Behavior", "Modal vs Non-Modal", "Preventing Outside Dismissal". Button has "Sizing", "Variants", "Icon Theming", "Group Theming", "Web Form Props", "Text Styling". |
+| 9   | **Creating your own**                                              | Recipe for replacing the built-in with a custom equivalent. Optional.                                                                                                                                                             |
+| 10  | **API Reference**                                                  | Prop tables. For compound components, **one table per sub-component** (Dialog.Root, Dialog.Trigger, Dialog.Content, Dialog.Title, Dialog.Description, Dialog.Close…).                                                             |
+| 11  | **Accessibility**                                                  | Sometimes folded into Features (Button); sometimes implicit in the API reference (Dialog). **Not always a standalone section.**                                                                                                   |
+
+## Motif-shaped per-component template
+
+Synthesised from Tamagui's template + the motif voice card + the existing `<ApiSignature>` and `<ComponentDemoStrip>` components.
+
+````mdx
+---
+title: <Component>
+description: <One sentence describing what it is and when to reach for it.>
+diataxis: reference
+covers: [<Component>, <subcomponents>]
+last_verified: <YYYY-MM-DD>
+---
+
+import {
+  ApiSignature,
+  ArticleMeta,
+  Callout,
+  CodeBlock,
+  ComponentDemoStrip,
+  Eyebrow,
+  Lede,
+} from '../../../components/index.js';
+
+<Eyebrow><Family></Eyebrow>
+
+# <Component>
+
+<Lede>
+  <One to three sentences. What it is, what it carries (its contract), and where to use it.
+   Aphoristic, declarative — see voice card.>
+</Lede>
+
+<ComponentDemoStrip demo="<component-key>" />
+
+<ArticleMeta />
+
+## What it is
+
+One short paragraph. Aphoristic opening sentence ("Box is the styling primitive."). Then 1-2
+sentences extending. No headings inside.
+
+## Install
+
+For components reachable from the meta `usemotif` package:
+
+> `<Component>` is exported from `usemotif`. No separate install.
+
+For components only in a sub-package:
+
+> ```bash
+> yarn add @usemotif/<package>
+> ```
+>
+> Then: `import { <Component> } from '@usemotif/<package>'`.
+
+## Anatomy
+
+For compound components only (Dialog, Menu, Combobox, etc.). Shows the full nested JSX.
+
+```tsx
+<Component.Root>
+  <Component.Trigger />
+  <Component.Content>
+    <Component.Title />
+    <Component.Description />
+  </Component.Content>
+</Component.Root>
+```
+````
+
+(For simple components — Box, Stack, Text — skip Anatomy and go straight to API.)
+
+## API
+
+For each (sub-)component, an `<ApiSignature>` followed by a props table.
+
+<ApiSignature
+name="<Component>"
+status="stable"
+signature={`function <Component>(props: <Component>Props): JSX.Element`}
+params={[…]}
+/>
+
+Then a `### Props` heading with a description table.
+
+## Variants
+
+When the component is `styled()`-built and exposes a `variants` axis. Skip when not relevant.
+
+## Cross-platform notes
+
+For components with a `.native.tsx` divergence (Dialog, Drawer, Menu, ScrollView, VirtualList,
+SafeArea…). Use the "On web …; on native …" pattern from the voice card.
+
+## Accessibility
+
+For headless components and any styled component that asserts an accessibility contract
+(Pressable, Button, Link). Lists the keyboard-interactions, aria-attributes the component
+manages, and the responsibility the consumer keeps (e.g. supplying an aria-label for icon-only
+buttons).
+
+For purely visual primitives (Box, Stack, Spacer), skip.
+
+## Examples
+
+Three to six short snippets demonstrating common shapes. Each example is a self-contained
+<CodeBlock>. Order by complexity, simplest first.
+
+<Callout variant="info" title="Related">
+  <links to 1-2 closely related component pages>
+</Callout>
+```
+
+## Sections by component class
+
+| Class                                                           | Sections present                                                                                                                                 |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Visual primitive** (Box, Stack, Text)                         | Title • Lede • Demo • What it is • Install • API • Variants† • Cross-platform† • Examples • Related                                              |
+| **Interactive primitive** (Pressable, Button, IconButton, Link) | Title • Lede • Demo • What it is • Install • API • Variants† • Cross-platform† • A11y • Examples • Related                                       |
+| **Headless behavior** (Dialog, Menu, Combobox)                  | Title • Lede • Demo • What it is • Install • Anatomy • Behavior sections • API (per sub-component) • Cross-platform† • A11y • Examples • Related |
+| **Hook** (useTheme, useThemeSetting)                            | Title • Lede • ApiSignature • What it does • Returns • Examples • Related                                                                        |
+
+† Only when the component has variants / native divergence.
+
+## What motif borrows from Tamagui
+
+- **Hero demo at the top of every per-component page.** Owns the page's first impression.
+- **API reference per sub-component for compound components.** A single sprawling table is harder to scan.
+- **"Installed in the meta package, or available standalone"** install messaging.
+- **Features-as-bullets is replaced by the motif Lede.** Motif's Lede is a thesis sentence(s) — denser than a bullet list, more memorable, and matches the existing voice.
+- **Sibling component navigation at the bottom** (motif uses the existing `<Callout variant="info" title="Related">` pattern instead of Tamagui's "Component Reference Links" header).
+
+## What motif rejects from Tamagui
+
+- **Versioned per-component pages** (Tamagui has `/ui/dialog/1.0.0`, `/ui/dialog/2.0.0`). Motif is always-latest; version-to-version stories live in `/migrating/*`.
+- **Title-case headings** (Tamagui uses Title Case throughout). Motif keeps sentence case per voice card.
+- **Configuration alternatives split across pages** (Tamagui has `Configuration` and `Config v5`). Motif keeps one config page per surface.
+- **Feature-bullet-list opener.** Replaced by the motif Lede.
+- **"Comes with styling, yet completely customizable and themeable"** style marketing prose. Forbidden per voice card.

.docwright/voice-card.md

@@ -0,0 +1,172 @@
+---
+voice_profile: motif-essayistic
+sampled_pages:
+  - apps/docs/content/getting-started/introduction.mdx # tutorial
+  - apps/docs/content/getting-started/installation.mdx # howto
+  - apps/docs/content/concepts/tokens.mdx # explanation
+  - apps/docs/content/concepts/theming.mdx # explanation
+  - apps/docs/content/concepts/responsive.mdx # explanation
+  - apps/docs/content/recipes/buttons.mdx # howto
+  - apps/docs/content/reference/styled.mdx # reference
+  - apps/docs/content/guides/performance.mdx # howto
+generated: 2026-05-15
+generator: docwright-voice-mirror
+---
+
+# motif voice card
+
+## Hard rules
+
+```yaml
+person: 2nd-sparing-mixed # "you" used when instructional ("Drop a <Box>"). Otherwise impersonal ("Motif resolves...", "A theme is...").
+tense: present # imperative for step instructions only ("Install", "Mount", "Open the page")
+formality: neutral-precise # educated, not stuffy; never casual; never academic
+sentence_length:
+  median_words: 15
+  range: [3, 30]
+  cadence: aphoristic-then-explanatory # short declarative sentences open paragraphs, longer ones extend
+code_prose_ratio:
+  tutorial: 0.45
+  howto: 0.6
+  reference: 0.7
+  explanation: 0.3 # essayistic; concepts pages are prose-heavy
+hedge_words: avoided # no "probably / maybe / might / should / we recommend / it's worth"
+marketing_adjectives: avoided # never "simple / easy / powerful / blazing / seamlessly / leverage / robust / delightful / elegant / intuitive / modern"
+contractions: used-moderately # "doesn't / isn't / you're / it's / that's" — present, not casual
+oxford_comma: yes # consistent
+em_dashes: liberal # mid-sentence pivots, asides, summary clauses — em dashes are a hallmark
+british_spellings: yes # "colour / colours / behaviour / organise / authorise" — distinctive choice
+numbers_as_text_in_prose: small # "three responsive syntaxes", "two renderers"; numerals for measurements
+heading_style: sentence # never title case. Often aphoristic ("Tokens are values", "Switches are attribute swaps")
+list_style: bullets-with-bold-leadins # `- **Atomic deduplication.** Every unique style bag…`
+```
+
+## Signature phrasings (prefer when natural)
+
+These are the rhetorical fingerprints. Reach for them when they fit; don't force.
+
+- "**X is Y**" as a paragraph or section opener ("A token is a named value", "Tokens are values", "Themes share the same primitive layer", "Switches are attribute swaps").
+- "**X is how Y**" mechanical/factual formulation ("That path is how the rest of the library refers to the value", "The cascade is how a theme switch happens").
+- "**The X is the Y one**" parallelism for trade-offs ("The web path is the cheap one", "The runtime is the slow path").
+- "**Same X, two Y**" / "**One tree, two renderers**" — paired-thing pattern for cross-platform / dual-renderer / dual-mode framings.
+- "**That is the only Y**" — declarative narrowing of scope ("That is the only mounting step", "The collector is the only SSR-specific surface").
+- "**Three steps: X, Y, Z.**" — colon-and-list Lede pattern.
+- "**You'll reach for X when**" / "**Reach for X when**" — placement-in-the-ecosystem phrasing.
+- "**The interesting part is what's underneath**" — closing pivot toward concepts.
+- "**The pattern that costs you on motif is the pattern that costs you elsewhere**" — orientational claim before practical advice.
+- Parallel conditionals: "**If X, ... . If A, ...**" — for branching guidance.
+- "**X carries Y**" — for contracts/responsibilities ("Pressable carries the interactive contract", "Box carries the style-prop pipeline").
+
+## Forbidden words
+
+Never emit. The existing docs visibly avoid all of these.
+
+```
+simple, simply, easy, easily, easier (when describing the library/its use)
+powerful, robust, production-grade
+blazing, lightning-fast, blazing-fast
+seamlessly, magically, automagically, just-works
+leverage (use "use")
+delightful, elegant, intuitive
+modern, next-generation, cutting-edge
+out of the box, out-of-the-box
+boilerplate (only when literally meant)
+just (as condescending "just do X")
+obviously, clearly, of course
+basically, essentially (filler)
+best practices (use "the standard pattern" or "the pattern")
+kind of, sort of, somewhat
+quite, very, really (intensifier filler)
+```
+
+## Page opening sequence
+
+Every prose page starts with this scaffold. Order is fixed.
+
+```mdx
+---
+title: <Title>
+description: <One-sentence; appears in social cards + meta tags>
+diataxis: <tutorial | howto | reference | explanation | migration | adr | changelog | readme>
+covers: [<symbols this page is the canonical home for>]
+last_verified: <YYYY-MM-DD>
+---
+
+import { ArticleMeta, Callout, CodeBlock, Eyebrow, Lede } from '../../components/index.js';
+
+<Eyebrow><Section></Eyebrow>
+
+# <Title>
+
+<Lede>
+  <One to three sentences. Aphoristic. The Lede is the page's thesis, not a teaser.>
+</Lede>
+
+<ArticleMeta />
+
+## <First H2 — the most fundamental concept or step>
+```
+
+For reference pages: replace the post-`<Lede>` block with `<ApiSignature>` containing `name`, `status`, `signature`, `params`. Put `<ArticleMeta />` _after_ the signature block.
+
+## Page closing sequence
+
+Almost every page closes with a single `<Callout>` linking 1–2 related pages.
+
+```mdx
+<Callout variant="info" title="Where to next">
+  [<Page A>](/path/a) covers <one-line description>.
+  [<Page B>](/path/b) covers <one-line description>.
+</Callout>
+```
+
+Variants: `info` for orientation, `tip` for a callout-in-passing, `warning` for caveats. Never decorative.
+
+## Code blocks
+
+Always via the `<CodeBlock>` MDX component — never raw fenced code in source.
+
+```mdx
+<CodeBlock lang="tsx" code={`...`} />
+<CodeBlock filename="App.tsx" lang="tsx" code={`...`} />
+<CodeBlock
+  tabs={[
+    { label: 'npm', code: 'npm install usemotif', filename: 'terminal' },
+    { label: 'pnpm', code: 'pnpm add usemotif', filename: 'terminal' },
+    { label: 'yarn', code: 'yarn add usemotif', filename: 'terminal' },
+    { label: 'bun', code: 'bun add usemotif', filename: 'terminal' },
+  ]}
+/>
+```
+
+`lang` is always `tsx`, `ts`, `bash`, or `css`. Multi-line code uses backticked template literals. Always include `filename=` when the snippet represents a real project file.
+
+## Per-quadrant register
+
+The voice card constants stay constant across quadrants. The _register_ (depth, code:prose ratio, length) shifts by Diataxis quadrant.
+
+| Quadrant        | Register                                      | Reach-for moves                                                                 |
+| --------------- | --------------------------------------------- | ------------------------------------------------------------------------------- |
+| **Tutorial**    | warm, second-person sparingly, end-to-end     | "Three steps:", "Open the page", "You should see…"                              |
+| **How-to**      | terse, recipe-shaped, instruction-first       | "Wrap X with Y", "Add Z when…", "Strip the bg once intents own them"            |
+| **Reference**   | dense, neutral, complete                      | `<ApiSignature>`, prop tables, "Returns…", "Throws…"                            |
+| **Explanation** | essayistic, low code:prose ratio, comparative | "A token is a named value", "Two layers, one tree", "Same model, two renderers" |
+
+## Cross-platform calls
+
+For motif specifically, every component-page section that describes per-platform divergence uses the **"X is Y on web; X is Z on native"** pattern. Examples from existing prose:
+
+- "On web, motif emits each leaf as a CSS custom property. On native, the same tree lives in memory."
+- "Set `data-theme='dark'` on the wrapper. … Update the `active` prop. The provider re-reads from the in-memory token tree."
+
+Never "on the web side" or "the web version" — it's always "on web" / "on native".
+
+## What this voice card overrides
+
+When a docwright doc-type skill's house style conflicts with this card:
+
+- `forbidden_words` always win.
+- The opening-sequence scaffold (Eyebrow / Lede / ArticleMeta) is mandatory.
+- Heading style is sentence case — overrides any title-case defaults.
+- British spellings — overrides US English defaults.
+- Em dashes are encouraged — overrides any "minimize em dash" defaults.

.gitignore

@@ -45,8 +45,18 @@ yarn-error.log*
 # Claude Code per-session runtime state
 .claude/
 
-# docwright agent state (local-only; do not ship)
-.docwright/
+# docwright agent state (local-only; do not ship).
+# Exceptions at the repo root: durable contracts the docs system relies
+# on across sessions. Voice card + final IA + Tamagui reference are
+# project artefacts, not runtime scratch — they get committed so a
+# fresh clone can rebuild the docs without re-running discovery.
+/.docwright/*
+!/.docwright/voice-card.md
+!/.docwright/final-ia.md
+!/.docwright/tamagui-reference.md
+# Anywhere deeper in the tree, .docwright/ is purely agent scratch.
+apps/**/.docwright/
+packages/**/.docwright/
 
 # Env
 .env