Page templates

Every page in this site follows one of three templates depending on what it documents. Templates are not arbitrary — they exist so agents and humans can find what they need at the same place on every page, and so cross-page navigation feels coherent.

This page is the page-shape and building-block reference. The writing rules — frontmatter fields, heading depth, code blocks, callouts, links, and MDX authoring gotchas — live in the Fumadocs content standard at .claude/standards/fumadocs-content.md, retrieved by agents via brik-rag query "fumadocs writing standard". This page does not restate them; it covers the structure a page takes and the components it can use.

Templates

Component page

For pages under /docs/components/. The shape:

1. One-line summary (no heading — opens the page)
2. <ComparisonGrid> — only if there are sibling components to disambiguate (e.g. Button vs LinkButton vs IconButton)
3. ## Use it for          — concrete situations, bullet list
4. ## Import              — copy-paste import line
5. ## Anatomy             — <ComponentAnatomy> with numbered parts
6. ## Variants            — <EmphasisLadder> for ordered ladders, <ComponentPreview> for state/style families
7. ## Sizes               — <ComponentPreview> grid of every size
8. ## Other variant axes   — Icons, Loading, Full width, etc. — one ## per axis
9. ## Sub-components       — LinkButton, IconButton, etc. each get their own ##
10. ## When *not* to use   — bulleted "Don't" rules
11. ## Accessibility       — keyboard, focus, aria, screen-reader behavior
12. ## API                 — props tables (one ### per component); Storybook deep-link for full ArgTypes
13. ## CSS Override API    — only if the component exposes scoped vars
14. ## Related             — cross-links to playground, patterns, sibling components

Button is the reference implementation. New component pages should match its structure section-by-section.

Primitive page

For pages under /docs/primitives/. The shape:

1. One-line summary (no heading — opens the page)
2. <Callout> — the most-broken rule for this primitive (e.g. "never use --text-* on a background")
3. ## {Group}             — viz block per token group; e.g. Page and surface, Background, Text, Border
4. ## Status / States     — interaction or status-state tokens if applicable
5. ## Primitives          — <PaletteGrid>, <SpacingScale>, <BorderRadiusPreview>, etc. — raw scale below the semantic groups
6. ## Modes               — only if the primitive has Figma "modes" (e.g. spacing has Base/Spacious)
7. ## Related             — sibling primitive pages

Color and Spacing are reference implementations.

Content-system page

For pages under /docs/content-system/industries/, /voices/, /atmospheres/. The shape:

1. <MetadataStrip> — Version · Last reviewed · Cadence (required for industry packs and voice patterns)
2. One-line summary
3. ## 1. Overview
4. ## 2. Default affinities (industries) or Tone profile (voices)
5. ## 3. Pain points or Use cases
6. ## 4. Seasonality (industries only)
7. ## 5. Competitive landscape (industries only)
8. ## 6. Listings requirements (industries only)
9. ## 7. Regulatory summary (industries only)
10. ## 8. Vocabulary — Avoid (HTML <table> — needs JSX .map() over pack data)
11. ## 9. Navigation IA (industries only)
12. ## 10. Brik Strategic POV (industries only)
13. ## 11. Site Audit Extractors (industries only — only if the pack defines siteAudit)
14. ## Related

Industries → Dental is the reference. Numbering the sections is intentional — it lets section-2 tables of contents read as a checklist.

Building blocks

Components registered in lib/mdx-components.tsx are available in any .mdx without an explicit import.

Universal blocks

• <ComponentPreview code={...}> — live render + Code tab + copy. Pass JSX as children, the source string as code.
• <EmphasisLadder caption rungs={[...]}> — ordered variant ladder, top = strongest. Each rung is { label, example, use }.
• <ComparisonGrid items={[...]}> — three-column "X vs Y vs Z" decision grid. Each item is { title, preview, whenToUse, whenNotToUse?, code? }.
• <ComponentAnatomy parts={[...]}> — preview left, numbered parts right. Each part is { number, name, description, required? }. Children render as the live preview.
• <MetadataStrip items={[...]}> — page-header label/value strip. Each item is { label, value }.

Foundation viz blocks

Used on primitive pages.

• <ColorGrid colors={[...]} columns={N}> — live click-to-copy swatches.
• <PaletteGrid title palette prefix columns> — static hex swatches for primitive scales.
• <SpacingScale title scale prefix> / <SemanticSpacing title tokens varPrefix>
• <TypographyScale title scale prefix> / <FontFamilyShowcase families={[...]}> / <SemanticTypographyTable title tokens={[...]}> / <FontWeightShowcase weights={...}>
• <BorderRadiusPreview title scale prefix> / <BorderWidthPreview title scale prefix> / <ShadowScale title scale prefix label>

Live BDS components

Imported globally as a namespace.

<ComponentPreview code={`<BDS.Button variant="primary">Save</BDS.Button>`}>
  <BDS.Button variant="primary">Save</BDS.Button>
</ComponentPreview>

Always namespaced as BDS.* to avoid collisions with HTML primitives like <Card>, <Tabs>, <Switch>.

Fumadocs primitives

Imported per page as needed.

import { Callout } from 'fumadocs-ui/components/callout';
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
import { Cards, Card } from 'fumadocs-ui/components/card';

How this site relates to Storybook

If a page would be 80% prop tables with one prose paragraph at the top, it belongs in Storybook only — link out, don't migrate. If a page would be 80% prose with one code snippet, it belongs here.

Adding a new page

1. Pick the template (component, primitive, content-system).
2. Drop a new .mdx file in the right folder under content/docs/.
3. Add the slug to the parent folder's meta.json pages array.
4. Run npm run build from docs-site/ to verify it compiles.
5. Reload the dev server (Turbopack picks up new files automatically).

The page renders at /docs/{folder}/{slug} once the meta.json knows about it.