Skip to main content

πŸ“– Documenting a design system

Documentation requirements​

  • description: component name, description, and uses.
  • examples: component variants and states - include interactive visuals.
  • design references: visual guidelines, do's and don'ts.
  • code references: component API details.

Documentation options​

  • use Storybook: comes with a Docs addon, which auto generates component documentation from written stories.
  • use custom doc site: build tooling and render code based on use case (example Shopify's Polaris).
  • use documentation tools (e.g. Notion, Confluence): embed stories using a story URL.
  • use a design system manager: an all purpose tool like zeroheight, InVision DSM, etc.

Documentation tools​

Confluence​

  • Part of Atlassian suite of products.
  • Allows for syncing with Jira and Figma.
  • Check out their design system template.

Docusaurus​

  • A Meta open source project.
  • Built with React and powered by MDX.
  • Allows for document versioning and Algolia DocSearch.
  • Check out projects on their showcase page.

Invision​

  • A collaborative workspace that allows for the syncing of design and code.
  • Allows for integration with Sketch.
  • Free for one design system; enterprise available for a fee.
  • Checkout their video tutorials.

Notion​

  • A collaborative workspace.
  • Allows for syncing with Jira and integration with Figma.
  • Check out their design system template.

Storybook​

  • Open source tool; geared more towards front-end developers.
  • Allows for the building of UI components.
  • Check out their design system tutorial.

zeroheight​

  • Collaborative tool that allows for the syncing of design and code.
  • Free for one project with one editor. Paid plans for other use cases.
  • Check out example documentation sites on their showcase page.

Resources to check out​