Authoring documentation

app/design/
├── nav.ts                 # rail, page metadata, breadcrumb and pager order
├── design-shell.tsx       # persistent responsive shell and route transition
├── docs-components.tsx    # previews, callouts, tokens and page chrome
├── components/page.tsx    # live interactive catalog
├── effects/page.tsx       # deterministic procedural-effect specimens
├── foundations/page.mdx   # prose documentation
└── quality/page.mdx       # release contract

Next’s MDX plugin compiles page.mdx files. The workspace-level mdx-components.tsx supplies the prose primitives, while each article imports only the richer documentation components it uses.

1. Add one typed item to the appropriate section in nav.ts.
2. Create the matching page.mdx or page.tsx route.
3. Begin with DocHeader; divide the article into linked DocSection regions.
4. End with DocPager using the page’s canonical pathname.
5. Add real component previews when guidance describes a public export.
6. Verify desktop and compact widths in Light, Dark, and System.

import { DocHeader, DocPager, DocSection } from "../docs-components"

<DocHeader eyebrow="Build" title="Example" description="What this page teaches." />

<DocSection id="contract" title="The contract">
  Guidance lives here.
</DocSection>

<DocPager pathname="/design/example" />

Every public component entry should cover:

• when to use it and when a simpler semantic element is better;
• its accessible name, keyboard model, focus behavior, and touch target;
• default, hover, focus, disabled, pending, empty, error, and overflow states that apply;
• compact and wide layout behavior;
• Light, Dark, forced-colors, and reduced-motion behavior;
• the smallest production-shaped example and the import path.

Lead with the contract. Prefer a small counterexample or boundary rule to a long tour of props. Name tradeoffs and recovery behavior directly. Keep headings useful when copied into search results, issue links, and review comments.