Design system docs

Skill almasumdev/awesome-mobile-design-system-agent-skills/.github/skills/docs_and_tooling/design-system-docs

Agent skills for building and maintaining mobile design systems, tokens, and component libraries.

Install

npx -y skills add almasumdev/awesome-mobile-design-system-agent-skills --skill design-system-docs

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Docs-as-code for design systems — Zeroheight, Storybook, DocC/DokkaHtml/dartdoc, and API reference. Use this when establishing or revising the documentation site.

SKILL.md

4.9 KB, as published. Nobody here has run it

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.

/**
 * 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.