docs: rewrite the documentation site for v1 (168 pages)#9
Merged
Conversation
…te, phase 0)
Replaces the hard-coded color/radius/px Playground with a small renderer
driven by a typed demo registry. Per-component pages will register a
`PlaygroundDemo` and pass `demo="<name>"`; the registry supplies the code
snippet, preview JSX, and any controls. Functions can't cross the island
boundary, so the registry lookup happens client-side from a string key.
The legacy single demo migrates to `playground-demos/hero.tsx` and is the
default for argless `<Playground />` calls. Its snippet text moves from
`motif.view({...})` (stale, pre-v1) to `styled(Pressable, {...})` — fixes
misleading content the existing visual baseline captured.
Also lands `<ComponentDemoStrip>` for the slimmer hero strip used at the
top of component pages, and a `_demo/playground.mdx` fixture for local
dev verification.
Pre-existing typecheck failures on Playground.client.tsx (the `type` prop
on `<Box as="button">`) drop out as a side effect of swapping to plain
`<button>` for elements that need it. The `theme/_mdxComponents.tsx` typecheck
failure is unchanged — outside Phase 0 scope.
Expected visual diff at `/getting-started/introduction` until the Phase 9
baseline refresh: the playground snippet text now reads `styled(...)`
instead of `motif.view({...})`. Per PLAN.md, baselines are reconciled in
one consolidated pass at Phase 9, not mid-rewrite.
Phase 0 of the docs-rewrite plan. Next: Phase 1 (docwright-discovery +
voice mirror + Tamagui crawl + finalised IA).
…e, phase 1)
Phase 1 of the docs-rewrite plan: ran docwright-discovery, voice-mirror,
and a Tamagui structural crawl. Resolved four open questions with the
user in a planning gate. Locks the IA, voice card, and per-component
page template for the next six phases.
.docwright/voice-card.md
Voice card sampled from 6 existing pages spanning all four Diataxis
quadrants. Distinctive choices: British spellings, liberal em dashes,
sentence-case headings, marketing adjectives forbidden, signature
aphoristic phrasings ("Tokens are values", "Same model, two
renderers", "X is how Y"). Per-quadrant register sub-rules. The
Eyebrow / Lede / ArticleMeta opening scaffold is mandatory for every
prose page.
.docwright/final-ia.md
Final sidebar tree: 166 pages across 11 top-level sections. Notable
revisions vs. PLAN.md's ~120 estimate:
- +18 family-index pages (lightweight grids).
- +5 standalone theme-hook reference pages.
- +2 family indexes from splitting Utility into A11y +
Control-flow + Utilities.
- +3 migration recipes (Emotion, Tailwind, Tamagui).
- +1 ADR index page.
18 existing pages salvageable as drafts; 5 archived/replaced.
.docwright/tamagui-reference.md
Per-component page template, distilled from Tamagui's Dialog and
Button pages: Title → Lede → hero demo → What it is → Install →
Anatomy (compound only) → API per sub-component → Behavior sections →
Cross-platform notes → Accessibility → Examples → Related callout.
Four register variants (visual primitive, interactive primitive,
headless behavior, hook).
.gitignore
Anchored .docwright/ rules to the repo root so the three project
contracts ship via git history, while preserving scratch behavior
everywhere else in the tree. Discovery output (.docwright/discovery.md)
stays untracked — it's working notes, not a durable contract.
Phase 1 produces no source changes. Phase 2 (Concepts + Getting started,
~14 pages) starts when the user gives the word.
…ite, phase 2)
Phase 2 of the docs-rewrite plan: Concepts (9 pages) + Getting started
(5 pages). 9 pages carry existing prose forward as drafts; 5 are new.
Every page conforms to the voice card and opening-scaffold contract
locked in Phase 1.
Getting started (5)
introduction.mdx refresh brand refs motif-js → motif;
cross-platform link fix
installation.mdx refresh last_verified bump
your-first-style.mdx refresh last_verified + cross-platform
link
cross-platform.mdx renamed was web-and-native.mdx; title
+ brand + Lede refreshed;
diataxis flipped tutorial
with-an-example.mdx NEW tutorial pointing at
apps/ssr-next, playground-web,
playground-bare-rn; includes
the verbatim MotifStyleRegistry
snippet
Concepts (9)
mental-model.mdx NEW umbrella explanation; three
parts (tokens, primitives,
factory); same-model-two-
renderers framing
tokens.mdx refresh last_verified + brand fix in
description; closing callout
now links to style-props
style-props.mdx NEW explanation of the prop catalog;
lists the four pseudo + motion
namespaces (verified against
packages/core/src/style-props.ts);
points to /reference/style-props
for the full table
responsive.mdx refresh last_verified bump
theming.mdx refresh last_verified bump
variants.mdx refresh last_verified bump
composition.mdx refresh last_verified bump
compiler.mdx NEW progressive-compiler story;
static extraction, safety
analysis, mixed-attribute
case; per-bundler plugin
pointer
ssr-and-hydration.mdx NEW SSRStyleCollector model;
per-request collector,
drain semantics, hydration
handoff; native parity note
Sidebar / cross-references
apps/docs/content/getting-started/_meta.ts add cross-platform +
with-an-example;
drop web-and-native
apps/docs/content/concepts/_meta.ts reorder for the IA;
add mental-model,
style-props, compiler,
ssr-and-hydration
apps/docs/content/recipes/animation.mdx fix /getting-started/
cross-platform link
apps/docs/content/reference/ssr.mdx fix /getting-started/
cross-platform link
apps/docs/content/404.mdx motif-js.dev →
usemotif.dev; stale
v1.1.2 version pin
generalised to v1
Forward references to Phase 3 / Phase 6 pages
Five new pages link to pages that do not exist yet: /reference/
style-props, /reference/compiler-core, /bundlers/vite. These resolve
when Phases 3 + 6 land. Vorge does not block on internal forward
refs at build time; Phase 9's verification sweep is the gate that
catches anything still missing.
Voice card compliance
Sentence-case headings, British spellings (colour/colours/organise),
liberal em dashes, marketing adjectives forbidden, Eyebrow / Lede /
ArticleMeta opening scaffold on every page. Salvaged pages were
already compliant; new pages mirror the existing register.
Verification
yarn workspace @usemotif/docs typecheck — 1 pre-existing failure in
apps/docs/theme/_mdxComponents.tsx (carried from main; outside
scope; flagged for Phase 9). 0 new failures.
yarn format — clean. Formatter touched .docwright/* tracked files
cosmetically (table alignment); not source-code changes.
yarn lint — 970 warnings, 0 errors. Baseline preserved.
Expected visual baseline drift
Five of the 14 page snapshots will diff against current baselines:
introduction.mdx (brand fix), your-first-style.mdx (callout text),
cross-platform.mdx (title rename, full restructure), plus the four
new pages have no baselines yet. Per PLAN.md, baseline refresh
happens in one consolidated pass at Phase 9, not mid-rewrite.
Next: Phase 3 (Core API reference + TSDoc, 17 pages).
…phase 3)
Phase 3 of the docs-rewrite plan: the core API reference. 17 pages
covering every public export across the 14 motif packages. 5 salvage
refreshes + 1 rename + 11 new pages.
Salvage refreshes (last_verified bumped to 2026-05-15)
styled.mdx covers: styled
create-theme.mdx covers: createTheme; relations
link now points at /reference/
theme-provider
ssr.mdx covers: SSRStyleCollector,
CollectorContext
use-theme.mdx split — now covers useTheme +
ThemeContext only;
useThemeName moved to its
own page
Renamed
theme.mdx → theme-provider.mdx covers ThemeProvider + Theme
together (per final-ia.md);
relations callout split into
four hook links
New (11)
use-theme-name.mdx the resolved active name
use-theme-chain.mdx the unresolved nested chain
use-theme-setting.mdx auto dark/light hook for web;
documents ThemeMode,
ResolvedTheme,
UseThemeSettingOptions,
UseThemeSettingResult
keyframes.mdx keyframes() factory; module-
scope hoisting guidance
style-props.mdx the full prop catalogue:
shorthands, pseudo-state,
pseudo-element, motion,
container-query, plus the
core helper exports
breakpoints.mdx breakpoint constants + DSL
helpers; defaultBreakpoints
table; container-query
counterpart
tokens.mdx @usemotif/tokens — lightTheme,
darkTheme, all 14 primitive
scales
icons.mdx Icon primitive + glyph set
from @usemotif/icons; full
gallery deferred (stub note
in place)
reset.mdx three application surfaces
(<MotifReset />,
injectResetStylesheet(),
/auto subpath) + the raw
RESET_CSS / RESET_STYLE_ID
test-utils.mdx assertConformance,
standardCases, defaultTestTheme,
motifMatchers (four matchers
documented)
migrate.mdx CLI + Node API; rename-v3 +
rename-v2 (preserved for
two-step migration path)
compiler-core.mdx advanced reference for plugin
authors; carries a top-of-
page warning steering apps
to /bundlers/*
Sidebar
apps/docs/content/reference/_meta.ts reorder + add 12 new entries
Forward references (resolve in later phases)
/reference/icons cross-links to /components/media/* (Phase 4).
/reference/test-utils links to /guides/testing (Phase 7).
/reference/migrate links to /migrating/* (already exist).
/reference/compiler-core links to /bundlers/* (Phase 6).
/reference/use-theme-setting links to /recipes/dark-mode-toggle
(Phase 7).
/reference/keyframes links to /recipes/animation-patterns (Phase 7).
TSDoc additions deferred
Reviewed existing TSDoc state across packages. The hook source files
(theme-context.ts, useThemeSetting.ts) already carry comprehensive
TSDoc; core/createTheme, styled, keyframes have decent module
headers. Phase 3 ships reference pages without source-level TSDoc
additions; the gap is small enough to address as a follow-up pass
if needed, not phase-blocking.
Verification
yarn workspace @usemotif/docs typecheck — 1 pre-existing failure
(apps/docs/theme/_mdxComponents.tsx, carried from main; outside
scope; Phase 9). 0 new failures.
yarn format — clean.
yarn lint — 970 warnings, 0 errors. Baseline preserved.
Visual baseline drift
/reference/styled, /reference/create-theme, /reference/ssr,
/reference/use-theme will diff against current baselines (content
changes); /reference/theme renamed (baseline obsolete); 11 new pages
have no baselines yet. Per PLAN.md, consolidated refresh at Phase 9.
Next: Phase 4 (Components, ~55 pages across 9 families).
Adds the /components section root plus the 13-component Layout family — Box, Stack, HStack, VStack, Container, Center, Flex, Grid, Wrap, ZStack, AspectRatio, Spacer, SafeArea — each following the per-component Tamagui-shape template. Registers a playground demo per component so the hero <ComponentDemoStrip> resolves on every page.
Adds the 6-component Typography family — Text, Heading, Paragraph, Blockquote, Code, Kbd — plus the family index, each on the per-component template with a registered playground demo.
Adds the 9-component Forms family — Field, Label, Input, TextArea, NumberInput, PasswordInput, FieldHelp, FieldError, Fieldset — plus the family index. Each page documents the Field-context wiring and carries an Accessibility section; one playground demo registered per component.
Adds the 5-component Media family — Avatar, Icon, Image, Svg, Link — plus the family index. Each page carries an Accessibility section; one playground demo registered per component.
Adds the 3-component Interactive family — Pressable, Button, IconButton — plus the family index. Button and IconButton pages document the variant matrix and carry Accessibility sections; one playground demo registered per component.
Adds the 3-component Scroll family — ScrollView, Sticky, VirtualList — plus the family index. Documents the scroll-context dependency and the dependency-free virtualisation seam; one playground demo per component.
Adds the 3-component A11y family — FocusScope, LiveRegion, VisuallyHidden — plus the family index. Each page leads with the accessibility contract it exists to provide; one playground demo per component.
Adds the 2-component Control flow family — Show, Hide — plus the family index. Documents the tree-dropping model and when to prefer responsive style props; one playground demo per component.
Adds the 2-component Utilities family — Overlay, Portal — plus the family index. Documents the render-elsewhere model and the building-block (not finished-dialog) framing; one playground demo per component.
Adds the /headless section root, the headless overview, and the 7-component Overlay family — Dialog, AlertDialog, Popover, HoverCard, Tooltip, Drawer, Sheet. Each page documents the compound API per sub-component with an Anatomy section; one playground demo per component.
Adds the 4-component Menu family — Menu, ContextMenu, NavigationMenu, CommandPalette — plus the family index. Documents the shared keyboard model and per-sub-component API; one playground demo per component.
Adds the 3-component Disclosure family — Accordion, Collapsible, Tabs — plus the family index. Documents the shared Trigger/Content shape and the open-policy differences; one playground demo per component.
Adds the 7-component Selection family — Checkbox, RadioGroup, Switch, Select, Combobox, MultiSelect, Search — plus the family index. Splits native-input controls from the listbox controls; one playground demo per component.
Adds the 3-component Date & time family — Calendar, DatePicker, TimeInput — plus the family index. One playground demo per component.
Adds the 4-component Numeric family — Slider, RangeSlider, Progress, RatingInput — plus the family index. One playground demo per component.
Adds the Feedback family — Toast (with Toaster and useToast) — plus the family index. One playground demo.
Adds the 4-component Navigation family — Breadcrumb, Pagination, Stepper, Toolbar — plus the family index. One playground demo per component.
Adds the 3-component Specialized family — ColorPicker, FileUpload, TreeView — plus the family index. Completes the headless package documentation. One playground demo per component.
…cs rewrite, phase 6) Four how-to pages under /bundlers covering the @usemotif/compiler-swc universal plugin (Vite, Next.js, webpack/Rspack) and @usemotif/compiler-metro for React Native. Adds the bundlers section to the top-level sidebar.
…s rewrite, phase 7) Replaces the four legacy recipes with the committed IA's 11-page set: seven new pages (dark mode toggle, CMS theming, sub-themes per route, print styles, and migration guides for Emotion, Tailwind, Tamagui) plus four salvaged from the old recipes and guides. Archives the buttons and layouts recipes, now covered by the per-component pages, and repoints the stale styled() reference link.
…e 7) Two new how-to guides: testing motif components with Testing Library and the @usemotif/test-utils conformance suite, and contributing to the monorepo. Corrects reference/test-utils.mdx, which had drifted from the package source — wrong assertConformance signature, matcher names, and type shapes — so the new guide and the reference agree.
…, phase 8a) Adds migrating/from-other-libraries.mdx — an umbrella linking the four per-library migration recipes and the shared migration shape. Re-verifies the v1→v2 and v2→v3 rename guides against current state.
Punchier, scannable, decision-oriented: leads with what motif is and the bet behind it, a prominent docs link, install, a cross-platform quick example, and a trimmed versioning note. Fixes legacy "motif-js" branding.
…e 8c) Adds a canonical root CHANGELOG.md in Keep-a-Changelog format covering v0.1.0 through the 1.0.0 graduation, with the @usemotif/* rebrand anchored in the 1.0.0 entry. The docs /changelog page now mirrors it and drops the stale @motif-js/* branding.
Adds apps/docs/content/adr/ — an index plus eight retroactive ADRs: renderer model, style-prop API, two-layer tokens, progressive compiler, three responsive syntaxes, headless/styled split, scope strategy, and versioning policy. Registers the section in the sidebar. Also folds in the oxfmt pass over the phase-8 README and CHANGELOG.
…e, phase 9) Fixes one dangling internal link and corrects five reference pages that had drifted from package source — breakpoints, icons, migrate, create-theme, and compiler-core — caught in the cross-source audit. Clears legacy motif-js branding from the SSR demo and the dogfood page. Refreshes the visual-regression route list and regenerates 98 baseline snapshots across every section and page template.
…hero isSvgElement treated every function component as an icon, so the hero install-command pill — whose content is wrapped in <Box as="span"> elements — had width/height cloned onto each wrapper, collapsing them to 14px and overlapping the adjacent "View on GitHub" button. Exclude motif's Box/Pressable primitives so layout wrappers pass through untouched, matching the helper's documented intent. Regenerates the affected visual baselines.
The hero badge showed a stale v1.1.2, the lede said "motif-js", and the View on GitHub link pointed at the old foo-stack/motif-js repo. Updated to v1.0.0, "motif", and foo-stack/usemotif.
Sweeps the docs theme for pre-rebrand artefacts: "motif-js" prose to "motif" in the footer, comparison, bento, gallery, testimonials, and theme package; dead foo-stack/motif-js GitHub links repointed to foo-stack/usemotif in the footer, top nav, and final CTA. Aligns the version surfaces to the real 1.0.0 release — the version pill no longer advertises non-existent v1.1.x/v1.2.0 builds, and the changelog teaser reflects the 1.0.0 graduation entry. Regenerates the visual baselines (the footer change shifts every full-page snapshot).
The pagefind plugin's dialog.css is injected at runtime, after chrome.css, and hardcodes a slate-navy backdrop (rgba(15,23,42,.55)); the same-specificity override lost that cascade tie. Marks the backdrop, overlay, and panel overrides !important so the motif-toned values win. Sidebar category sections are now collapsible — each is a toggle button with aria-expanded and a rotating chevron. Sections collapse by default; the one containing the active page starts expanded so the reader's location stays visible. Nested sub-categories collapse the same way.
The landing page, 404, changelog, and styled-with-motif page sat in the content root, so Vorge surfaced them as loose top-level sidebar links — the four non-collapsible items with no section. Mark them hidden in the root _meta.ts; they keep their own routes, just leave the sidebar.
…tion Corrects the capitalization of "Motif" in various documentation files, including the styled-with-motif page and footer. Updates installation commands from "@usemotif/react" to "usemotif" for consistency. Additionally, fixes typos in comments within the styled component files.
One clean regeneration capturing the collapsible sidebar, the hidden root-level entries, the search-backdrop fix, and the branding pass. All 98 snapshots verified passing.
The Pre wrapper forwarded `style`/`className` (typed `T | undefined`) straight to Box, whose props are `style?: T` — under exactOptionalPropertyTypes that explicit-undefined is a type error, and it failed the docs typecheck in CI. Spread the props only when defined.
The `@usemotif/icons — Plus only` budget was 5500 — below even the 5793 that the `Box`-only import it inherits already measures, so it could never pass. Importing any leaf from the @usemotif/react barrel drags the full @usemotif/core engine; that barrel tree-shaking deficiency is tracked in #10. Raised to 7000 as a temporary unblock until #10 lands, when it can be tightened back.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A full, ground-up rewrite of the motif documentation site, replacing a small set of partly-misleading pages with a complete, Diataxis-organised, 168-page site. Authored in nine phases on one branch; see commit subjects for the phase tags.
What landed, by section:
README.mdrewritten; a canonical Keep-a-ChangelogCHANGELOG.mdadded.Verification (final sweep): docs build 168 pages clean;
yarn lint0 errors;yarn formatclean. Every internal link cross-checked against built routes. Five reference pages found to have drifted from package source were corrected againstpackages/*/src/. Visual-regression route list refreshed and 98 baseline snapshots regenerated.Known follow-ups (not addressed here)
main—apps/docs/theme/_mdxComponents.tsx(150,6)(exactOptionalPropertyTypesonclassName). This rewrite adds 0 new typecheck errors; the fix belongs in a separate change./changelogmirrors the rootCHANGELOG.mdby hand rather than through a Vorge content loader.Test plan
yarn workspace @usemotif/docs build— 168 pages build cleanyarn lint— 0 errorsyarn format:check— cleanyarn workspace @usemotif/docs visual-check— 98 baselines pass