/usage-guidelines

name: usage-guidelines
description: "Write usage guidelines for one named component: when to use, when not to, edge cases, anti-patterns, a11y, quick-reference card. Triggers: usage guidelines for X, do's and don'ts for X. Choosing between components: component-decision-tree. Multi-component patterns: pattern-documentation."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(find:*), Bash(head:*), Bash(ls:*)
references:
  - ../../knowledge-notes/ai-readiness.md
  - ../../knowledge-notes/component-bestiary-reference.md
  - ../../knowledge-notes/output-discipline.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.

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

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 0: Read the component

Before asking the user anything, read what's available:

• `.ai/metadata/<Component>.metadata.json`, if `metadata-schema-generator` has run: props, states and the accessibility contract, each with a provenance marker. Take them from there and don't re-derive them; carry the markers through
• the component's source (variants, rendered element, ARIA attributes, key handlers, focus calls), its stories, existing docs, and the Figma component when a Figma MCP is connected
• the system's voice and tone guide: `system.content_guidelines_path` in config, or `CONTENT.md`, `VOICE.md`, `writing-guidelines.md` or similar, so the content guidelines section uses the team's rules from the start rather than generic UX writing advice

Much of Step 1 is answered there. If the component can't be found in source, stories, docs, metadata or Figma, stop and ask where it lives; guidelines for a component you haven't seen are generic by construction.

**Provenance rule.** Every behaviour the guidelines state as fact (variants, keyboard interaction, focus, announcements, contrast) traces to source, stories, docs, Figma or the user. Anything you can't confirm is marked "unverified"; misuse you haven't seen evidence of is marked "anticipated". See "Every figure and fact needs a source" in the output-discipline knowledge note.

Step 1: Gather component information

Confirm from Step 0, and ask the user for the rest:

• 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: ask; don't infer] **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 (illustrative 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 (illustrative 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 infor