/usage-guidelines

name: usage-guidelines
description: "Write usage guidelines for a specific, named component — covering when to use it, when not to, edge cases, and anti-patterns for that one component. This documents HOW to use a component you have already chosen, NOT how to choose between components. Trigger when someone says: write usage guidelines for [component], do's and don'ts for [component], how should [component] be used, usage rules, write the guidelines for [component], or anything about creating prescriptive guidance for a single named component. Do NOT trigger for choosing between components — use component-decision-tree for that. Do NOT trigger for documenting multi-component patterns — use pattern-documentation for that."
references:
  - ../../knowledge-notes/ai-readiness.md
  - ../../knowledge-notes/component-bestiary-reference.md

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.

Cover the primary use case first, then secondary use cases. Three to five conditions is usually the right scope — more than that and the guidelines are covering for an unclear component contract.

Format: "Use [component name] when [specific condition]."

Examples (Button):

• Use a primary button for the single most important action in a context. There should be at most one primary button in any given view.
• Use a secondary button for an action that is available but not the expected next step. Secondary buttons often appear alongside primary buttons to give users an alternative.
• Use a ghost button when the action is available but should not visually compete with other actions or content on the page.

---

When not to use

As important as the above, and often more valuable. Each entry should name a specific misuse and point to an alternative.

Format: "Do not use [component name] for [misuse condition]. Use [alternative] instead."

Examples (Button):

• Do not use a button for navigation to another page. Use a link. Buttons trigger actions; links navigate. Using a button for navigation misrepresents the interaction to screen readers and keyboard users.
• Do not use more than one primary button in the same context. If two actions feel equally important, reconsider the information hierarchy.
• Do not use a button when no action occurs. If the element is decorative or informational, it is not a button.

---

Variants and configurations

For each variant or major configuration option: one sentence on what it is for and one sentence on when to use it. Do not repeat information already in the component API — this section should add intent context, not restate prop values.

Only document variants that require usage judgment. If a variant is self-explanatory ("size" on a component that comes in sm, md, and lg) skip it or document it briefly. Spend the space on variants where misuse is plausible.

---

Edge cases

Edge cases are the situations the happy path documentation does not cover. They are the most important section for preventing real-world mistakes and the most commonly omitted.

Document:

• What happens when the label text is very long?
• What happens in a right-to-left layout?
• What happens when the component is used on a non-white or non-standard background?
• What happens when multiple instances appear in close proximity?
• What happens when the action is destructive and irreversible?

Not every component has every type of edge case. Only document the edge cases that are real for this component — do not produce a generic list.

---

Accessibility

Do not relegate accessibility to a separate section or an afterthought. For each point in the usage guidelines where an accessibility concern is relevant, integrate it in context.

Additionally, provide a consolidated accessibility reference covering:

• Keyboard interaction: which keys, in which order, with which outcomes
• Focus behaviour: where focus sits in default state, how it changes on interaction
• Screen reader: what gets announced, when, and how that announcement is produced
• Minimum touch target: if relevan