Generate Design-System Docs per Component

Workflow area: Design Systems · Tier: Core · Hands-on time: ~35 minutes

Undocumented components get misused, and misuse becomes de facto convention faster than any steward can object. But documentation loses the prioritization fight every sprint because writing it is slow, and it is slow because each page is being composed from scratch. The insight this playbook runs on: most of each component's documentation already exists — in its property structure, its variant names, its usage across product files, and the critique decisions that shaped it. AI is the assembler that turns those raw materials into a draft page in minutes. What it cannot know is your system's opinions — when to reach for this component over its neighbor, which configurations are traps — and opinions are exactly what makes documentation worth reading. Draft from anatomy; edit in judgment.

When to use — and when not to

• Use it to pay down a documentation backlogtwenty undocumented components at manual pace is a quarter of nobody's time; at draft-and-edit pace it is a sprint.
• Use it at component birtha new component with docs from day one never accumulates folk-usage; make drafting part of the definition of done.
• Use it when docs and components have driftedregenerate from current anatomy and diff against the published page; the diff is your staleness report.
• Skip it for components in churndocumenting a component mid-redesign produces confident docs for an API that will not exist next month; stabilize first.
• Skip the generation for the system's foundational essaysprinciples, token philosophy and voice pages are opinion all the way down; AI can copy-edit them, not draft them.

The recipe

1. 1.

   Assemble the component's evidence pack. For each component: a screenshot of every variant and state, the property/variant structure from the Figma panel (names, options, defaults), two or three screenshots of real in-product usage, and any critique notes or decision records touching it. Thin input produces generic docs — the pack is what makes the page yours.

2. 2.

   Generate the draft against your documentation template. In Claude, with the pack attached:

   Copy

   Draft design-system documentation for this component.
   Component: Button. Evidence attached: variant screenshots,
   property structure, real usage examples, decision notes.
   
   Follow this structure exactly:
   1. PURPOSE — one sentence: the job this component does.
   2. WHEN TO USE / WHEN NOT — bullets; for "not," name the
      component to use instead (our system has: Link, IconButton,
      Menu, SegmentedControl).
   3. ANATOMY — parts, from the screenshots.
   4. VARIANTS & PROPS — each property, its options, when each
      applies. Use ONLY the property names in the attached structure.
   5. CONTENT — label writing rules: verb-first, max length,
      sentence case.
   6. ACCESSIBILITY — contrast expectations per variant, target
      size, focus behavior, keyboard interaction, screen-reader
      label guidance.
   7. DO / DON'T — 4 pairs, each one sentence + the reason, drawn
      from the real usage examples where possible.
   
   Rules: do not invent props, variants, or behaviors not in the
   evidence. Where the evidence doesn't answer (e.g. focus
   behavior), write "[VERIFY: ...]" instead of guessing.
   Tone: direct, second person, no marketing language.
   

3. 3.

   Resolve every [VERIFY] marker against the real component. This is the verification pass: check focus behavior in the coded component, confirm contrast in the token values, test the keyboard interaction. Each marker either becomes a verified statement or a ticket for the component's owner. A published guess about accessibility behavior is worse than silence — consumers will build to it.

4. 4.

   Edit in the opinions — the 20% that is the point. The draft knows what the component is; you know what it is for. Add the judgment layer: the decision boundary against neighboring components ("three or more actions of equal weight: use Menu, not a Button row"), known misuse patterns from your files as concrete don'ts, and your system's voice. Cut every sentence that could appear in any company's docs — what remains is documentation only your system could have written.

5. 5.

   Publish and wire the maintenance loop. Move the page to zeroheight, Supernova, or your docs surface, linked from the Figma component description so it is one click from the point of use. Then set the trigger: any component change that touches properties or behavior regenerates the draft and diffs against the published page. Documentation that has no update trigger is documentation with an expiry date nobody wrote down.

Make it yours

• Batch mode for the backlog: run all components of one family (form controls, then navigation, then feedback) in a single session per family — the drafts come out consistent with each other, which is half of what makes a docs site feel authoritative.
• Supernova or zeroheight with code hooked in: where docs sit next to synced tokens and code snippets, have the draft reference token names and include the coded component's props alongside design props — one page serving both audiences.
• Do/don't pairs from your drift audit: feed pb-25's off-system findings in as raw material — real misuses from your own product make more convincing don'ts than any invented example.

Quality check

• Every documented prop existsnames in the docs match the component panel exactly; a documented prop that isn't there erodes trust in the entire site.
• All [VERIFY] markers are resolvednone shipped; each became a checked fact or a filed ticket.
• Do/don't pairs carry reasonsa don't without a why teaches compliance, not judgment, and gets ignored the first time it is inconvenient.
• The when-not-to-use section names alternativesredirection is the difference between documentation and scolding.
• A reader can tell this is your systemif the page would be true of any Button anywhere, the opinion edit did not happen.