/pattern-documentation

name: pattern-documentation
description: "Document a multi-component pattern (form validation, empty states, error handling): when to use, composition, states, a11y, anti-patterns. Triggers: document this pattern, write the pattern page. One named component: use usage-guidelines. Choosing a component: component-decision-tree."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(find:*), Bash(head:*), Bash(ls:*), Bash(grep:*), Bash(rg:*)
references:
  - ../../knowledge-notes/ai-readiness.md
  - ../../knowledge-notes/component-bestiary-reference.md
  - ../../knowledge-notes/output-discipline.md

Pattern documentation

A skill for writing documentation for design system patterns. Patterns are distinct from components: a component is a discrete, reusable UI element; a pattern is a recurring solution composed from multiple components that addresses a specific user or product problem. Form validation, empty states, error handling, progressive disclosure — these are patterns.

Before you begin: verify references

Confirm that every path in this skill's frontmatter `references:` exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example `npx skills install`) dropped the repo-root `knowledge-notes/` directory. Tell the user to reinstall by a method in `1-INSTALL.md` and run `verify-install.sh` from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

Context

Pattern documentation is systematically underdone in most design systems. Teams document components in detail and leave patterns as implicit knowledge — accumulated through convention, absorbed during onboarding, and lost when people leave. The result is parallel local solutions that drift apart over time, and product teams that rebuild the same interaction in slightly different ways because no one wrote down the shared answer.

Good pattern documentation does two things. It explains the pattern clearly enough that a designer or developer encountering it for the first time can apply it correctly. And it explains the edges: when this pattern is not the right choice, what alternatives exist, and how to handle the cases that do not fit neatly.

---

Step 0: Pattern discovery guide

Before documenting a pattern, confirm it is worth documenting. Not every recurring UI solution is a pattern — some are conventions, some are coincidences, and some are too specific to generalise.

**A UI solution is a documentable pattern if:**

• [ ] It appears in three or more distinct product contexts (not just three instances in the same product), each located in code or Figma and cited by path or URL, or named by the user
• [ ] It solves a user-facing problem, not just a layout convenience
• [ ] It composes two or more design system components in a specific relationship
• [ ] Teams have independently arrived at similar solutions (convergent evolution is the strongest signal)
• [ ] Getting it wrong has real consequences (accessibility, usability, consistency)

**A UI solution is NOT a documentable pattern if:**

• It appears in only one product context (it is a local convention)
• It is a single component used in a standard way (that belongs in the component's usage guidelines)
• It varies so much between instances that no shared structure can be extracted

**If the bar isn't met**, say which criteria failed and what to write instead: a single component used in a standard way belongs in `usage-guidelines`; a one-product solution is a local convention note in that product's docs; instances too varied to share a structure need a conversation, not a page. Then stop; don't write a pattern page for something that isn't one.

**Where to find undocumented patterns:** 1. Look at drift-detection findings classified as E (system gap) — these often reveal patterns teams are building independently 2. Review support channel questions — recurring "how do I..." questions about multi-component interactions signal undocumented patterns 3. Ask product teams: "What do you build most often that is not a single component?" The answers are pattern candidates 4. Review design file reuse — Figma frames that appear across multiple files without being components are likely patterns

**Provenance rule.** Product contexts, instances, states and accessibility behaviour in the documentation come from code, Figma, the team's docs or the user, and are cited by path or URL where they come from files. If you can't locate instances, ask the user; never invent product or team names. Rules you propose rather than observe are marked "proposed". See "Every figure and fact needs a source" in the output-discipline knowledge note.

Step 1: Establish the pattern scope

Ask for or confirm:

• Pattern name (clear, descriptive, not jargon)
• The user problem or product need this pattern addresses
• Which components from the design system are involved
• Product contexts where this pattern is already in use: search the codebase and Figma for instances first, then ask the user to confirm or add to them
• Any known edge cases or exceptions the documentation should address

If the pattern does not yet have a name, propose one before writing the documentation. Pattern names should describe the interaction or function, not the visual treatment: "confirmation dialog" not "modal with two buttons."

Step 2: Write the pattern documentation

---

[Pattern name]

**Category:** [navigation / forms / feedback / layout / data display / other] **Components used:** [list the design system components this pattern draws on] **Last updated:** [date]

---

What this pattern does

One to two sentences. Describe the pattern in terms of what it accomplishes for the user, not how it looks or which components it uses.

Example (form validation): Communicates the status of user input during and after fo