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.