🏫
Obvious University
Website
  • 👋Welcome to Obvious University!
  • Strategy
    • Sprints
      • 1️⃣Map
      • 2️⃣Sketch
      • 3️⃣Decide
      • 4️⃣Prototype
      • 5️⃣Test
    • Benchmarking
    • Research
      • 1️⃣Research guide
      • 2️⃣How to recruit users
      • 3️⃣How to conduct an interview well
      • 4️⃣How to take notes
      • 5️⃣How to prep for remote research
      • 6️⃣How to throw a watch party
      • 7️⃣How to create artefacts
  • Working with Features
    • Building with AI
      • 1️⃣Understand the tech
      • 2️⃣Map your product
      • 3️⃣Build a proof of concept
      • 4️⃣LLM Inputs
      • 5️⃣LLM Responses
    • Building Help and Support
      • 1️⃣How to scope a support experience
      • 2️⃣How to design discovery for support
      • 3️⃣How to design a support centre
      • 4️⃣How to write good support articles
  • Product Design
    • Microcopy
      • 1️⃣How to write well
      • 2️⃣How to write phrases
      • 3️⃣How to write messages
      • 4️⃣How to create a voice
    • Typography
      • 1️⃣How to compose type
      • 2️⃣How to create a type scale
      • 3️⃣How to pick typefaces
      • 4️⃣How to pair typefaces
    • Design System
      • 1️⃣Introduction to design systems
      • 2️⃣How to audit a design system
      • 3️⃣How to run a design system pilot
      • 4️⃣How to set up a design foundation
      • 5️⃣How to build components
      • 6️⃣How to document a design system
      • 7️⃣How to enable adoption and govern a design system
    • Mobile Engineering
      • 1️⃣Trunk based development
      • 2️⃣Agile development terminology
      • 3️⃣Git commit messages
      • 4️⃣Code review and pull requests
      • 5️⃣Readings
  • Delivery
    • Project Management
    • Collaboration
  • Hiring and Growth
    • Growth
      • 1️⃣Design growth framework
      • 2️⃣How to give ongoing feedback
      • 3️⃣How to check-in every quarter
      • 4️⃣How to address underperformance
      • 5️⃣FAQs
    • Hiring and careers
      • 1️⃣The Hiring Process
      • 2️⃣Diverse and Inclusive Hiring
  • PEOPLE EXPERIENCE
    • Benefits and Perks
      • 1️⃣Paid time off
      • 2️⃣Insurance and healthcare
      • 3️⃣Continuing education
      • 4️⃣Speaking at conferences
    • Starting at Obvious
      • 1️⃣Introducing Obvious
      • 2️⃣Set up your workspace
      • 3️⃣Onboarding
      • 4️⃣Finances
      • 5️⃣Code of Conduct
    • Employment policies
      • 1️⃣Equal opportunity employment
      • 2️⃣At-will employment
      • 3️⃣Employee records and privacy
      • 4️⃣Prevention of sexual harassment
      • 5️⃣Drugs and alcohol
      • 6️⃣Fraternisation
      • 7️⃣Non-compete and non-solicitation
      • 8️⃣Non-disclosure
Powered by GitBook
On this page
  • 👋 Introduction
  • 1️⃣ Create a reference website
  • 2️⃣ Further reading
  1. Product Design
  2. Design System

How to document a design system

PreviousHow to build componentsNextHow to enable adoption and govern a design system

Last updated 1 year ago

👋 Introduction

One thing that differentiates a design system from just a component library is its documentation. A design remains incomplete without guidelines and a centralised place from which it can be understood and consumed.

1️⃣ Create a reference website

Product teams will only be able to use the system properly if it’s well-understood and easily accessible. This can be accomplished by creating a reference website. A reference site primarily helps:

  • Showcasing design system components and guidelines

  • Making documentation easy to access and understand

It’s important that your reference be unique to the specific needs of your organization, but here’s set of content that any design system user will probably be looking for. Use the structure below as a starting point for the sections your design system users may expect:

  • Home

  • Get started

  • Guidelines / Patterns

    • Accessibility

    • Brand

    • Color

    • Error handling

    • Icons

    • Illustrations

    • Typography

    • Voice and tone

    • Etc..

  • Components

    • Overview (containing component status page)

    • Accordion

    • Button

    • Breadcrumb

    • Card

    • Etc.

  • Case studies

  • Support

  • Blog/News

  • About

  • Changelog

  • Search

2️⃣ Further reading

Here’s an of a component page on a reference website. Resist the urge to build a custom site for v1, and instead, use a non-code tool like Zeroheight so teams can contribute without writing code.

6️⃣
example
Design System documentation best practices
"Making Design Systems Public," an article by Dan Mall
Structuring documentation in multi-brand design systems by Amy Hupe, content designer