pattern-documentation

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.

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)
• 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