| name | design-system-docs |
| description | Docs-as-code for design systems — Zeroheight, Storybook, DocC/DokkaHtml/dartdoc, and API reference. Use this when establishing or revising the documentation site. |
Design System Docs
Instructions
A design system without searchable, versioned docs is a private joke. Docs are a product — owned, reviewed, and released alongside components and tokens.
1. One Canonical Site
Pick a single destination for designers and engineers. Split the authoring, never the site.
Common stacks:
- Zeroheight / Supernova — design-first, token-aware, syncs with Figma. Engineers link out to per-platform reference.
- Storybook (web) — ideal for RN via
@storybook/react-native-web; embeds live examples and controls.
- Custom Next.js / Docusaurus / Astro — maximal flexibility; requires a team to maintain.
Rule of thumb: designers need tokens + usage in one place; engineers need per-platform API reference. The canonical site must show both.
2. Docs-as-Code
Component usage lives next to the source, in Markdown/MDX. The site builds from these files; no parallel prose in a CMS.
src/primitives/Button/
├── Button.kt
├── ButtonTokens.kt
├── Button.md # usage, dos/don'ts, examples
├── Button.stories.tsx # Storybook stories (for RN mirror)
└── Button.snapshot.kt
Every component page must have these sections:
- Summary — one sentence + hero image.
- Anatomy — labeled diagram.
- Variants — complete matrix, rendered.
- Usage — when to use / when not to.
- Accessibility — contract and testable claims.
- API — per-platform reference (autogenerated).
- Tokens — which tokens it consumes.
- Changelog — component-local release notes.
3. Live Examples
Static screenshots rot. Embed interactive examples.
- RN / web: Storybook with Controls and a11y addon.
- iOS: Xcode previews surfaced via
swift-docc-plugin and @Preview macros; link from the web docs.
- Android:
@Preview composables rendered to images in CI, surfaced in DokkaHtml.
- Flutter:
widgetbook or storybook_flutter.
4. API Reference Generation
Do not hand-write API docs; generate them.
- Compose: DokkaHtml (
org.jetbrains.dokka) with the Compose module and KDoc on every public composable.
- SwiftUI: DocC catalogs (
DesignSystem.docc/), hosted via GitHub Pages.
- Flutter: dartdoc from triple-slash comments.
- RN: TypeDoc over TSX, or Storybook autodocs from JSDoc.
@Composable
fun Button()
5. Token Reference
Surface every token group with value previews for every theme:
<TokenTable
type="color"
group="color.action.primary"
themes={['light', 'dark', 'acme-light', 'acme-dark']}
/>
The preview reads generated JSON at build time so tokens and docs never drift.
6. Change Management
- Every PR that adds/removes tokens or components must update or generate docs. CI fails if
Button.md is missing after Button.kt changes.
- Changelog entries belong on the component page itself, not buried in a monorepo
CHANGELOG.
- Per-release notes aggregate individual changelogs into a site-wide "What's new."
7. Search and Versioning
- Full-text search over tokens, components, and prose (Algolia DocSearch or site-local).
- Version the docs alongside the package:
/v1/, /v2/, with a banner on old versions linking to the current one.
- Snapshot the docs build into the release artifacts so old versions remain reachable forever.
8. Designer Handoff
Connect tokens to Figma:
- Tokens Studio for Figma or Figma Variables import the same JSON the code pipeline consumes.
- Component docs link to the Figma library frame (e.g.,
figma.com/.../Button) so design + code stay in sync.
9. Anti-Patterns
- Wiki pages curated by a single maintainer — becomes stale the day they leave.
- Docs hosted on a corporate confluence behind VPN — contributors can't read or edit.
- Screenshots pasted into docs instead of generated snapshots.
- Token values hand-typed into a table — they drift from the build.
- A single "Components" page listing everything — unsearchable at scale.
Checklist
