Design system docs

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:

1. Summary — one sentence + hero image.
2. Anatomy — labeled diagram.
3. Variants — complete matrix, rendered.
4. Usage — when to use / when not to.
5. Accessibility — contract and testable claims.
6. API — per-platform reference (autogenerated).
7. Tokens — which tokens it consumes.
8. 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.

/**
 * Primary app button.
 *
 * @param label Visible text.
 * @param intent Visual intent; see [ButtonIntent].
 * @param size Touch-target size; see [ButtonSize].
 * @sample com.ds.samples.ButtonSamples.primaryMedium
 */
@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

• One canonical docs site shows tokens and per-platform API.
• Component docs are stored next to component source as MD/MDX, with a fixed page template.
• Live, interactive examples exist for at least one platform; static screenshots are CI-generated.
• API reference is autogenerated from source comments (DokkaHtml / DocC / dartdoc / TypeDoc).
• Token tables read from generated JSON and render all shipped themes.
• Docs are versioned alongside the package and a "What's new" aggregates per-component changelogs.