usage-guidelines

Usage guidelines

A skill for writing component usage guidelines that cover the full usage contract: when to use, when not to, edge cases, anti-patterns, and accessibility guidance integrated throughout. Output reads as guidance a designer or developer can act on immediately, not a style guide entry that restates what is already visible in the component.

Context

Most component usage guidelines have the same structural problem: they describe the component rather than guiding its use. "The button component is used to trigger actions" is a description. "Use a primary button for the single most important action in a given context — never more than one per view" is guidance. The first tells you what exists. The second tells you how to use it correctly.

The goal here is the second kind. Guidelines that are worth writing are guidelines that would prevent a real mistake someone on a consuming team could plausibly make.

---

Step 1: Gather component information

Ask for or confirm:

• Component name and the system it belongs to
• Available variants or configurations
• Any existing documentation to build on or replace
• Known misuse patterns the team has actually seen in production — these are the most valuable input
• Any accessibility requirements already established for the component

The known misuse patterns are critical. Guidelines written from abstract principle tend to address imaginary mistakes. Guidelines written from observed patterns address real ones.

Step 2: Write the usage guidelines

---

[Component name] usage guidelines

Version: [design system version] Last updated: [date]

---

Overview

One to two sentences. What does this component do and what user need does it serve? Write this as the answer to "why does this component exist" not "what does it look like."

---

When to use

Write as specific conditions, not general descriptions. Each condition should be concrete enough that a designer could read it and make a decision.