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.

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 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 the items below. Each line ends with its source in brackets: a file and line, a story id, a metadata provenance marker, a computed ratio, a Figma node, or user. Anything with no source is marked "unverified" rather than described from what components like this usually do.

• 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 relevant, state the minimum size and how the component handles it
• Colour contrast: which colour combinations have been checked, by what, and against which level. The baseline is WCAG 2.2 AA. Some legal baselines (e.g. EN 301 549) still reference WCAG 2.1 AA; use that if it's the team's obligation.

Accessibility guidance should be specific to this component. Do not cite WCAG criteria as the guidance itself — say what the component does.

---