Stats
Actions
Tags
From design-system-ops
Writes usage guidelines for a specific named component covering when to use, when not to, edge cases, and anti-patterns. Useful for prescriptive guidance on single components.
How this skill is triggered — by the user, by Claude, or both
Slash command
/design-system-ops:usage-guidelinesThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
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.
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.
Ask for or confirm:
The known misuse patterns are critical. Guidelines written from abstract principle tend to address imaginary mistakes. Guidelines written from observed patterns address real ones.
Version: [design system version] Last updated: [date]
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."
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):
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):
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 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:
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.
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:
Accessibility guidance should be specific to this component. Do not reference WCAG 2.1 as guidance — say what the component does.
Name the three to five most common ways this component is misused, each as a clear statement with a reason and a correction.
Write these based on observed misuse patterns where possible. Anti-patterns derived from production experience are consistently more useful than anti-patterns derived from abstract reasoning.
Format: "Anti-pattern: [description of the misuse]. This creates [specific problem]. Instead: [correct approach]."
Anti-pattern template:
For each anti-pattern, use this consistent structure to ensure they are actionable:
**Anti-pattern: [Short name]**
What happens: [One sentence describing the misuse]
Why it's harmful: [One sentence on the specific consequence — accessibility, consistency, UX, or maintenance]
What to do instead: [One sentence with the correct approach]
How to detect: [One sentence on how to spot this in a review — what to look for in code, design, or Storybook]
Example:
**Anti-pattern: Navigation button**
What happens: A Button component is used to navigate to another page.
Why it's harmful: Screen readers announce it as a button, not a link — users expect an action, not navigation. Keyboard behaviour differs (buttons activate on Space, links do not).
What to do instead: Use a Link component styled to match the desired visual weight.
How to detect: Look for Button components with onClick handlers that call router.push(), window.location, or equivalent navigation functions.
The "how to detect" field is particularly valuable for code reviewers and linting rules — it translates the anti-pattern from a principle into a checkable condition.
If the component displays text that product teams write (button labels, error messages, empty state copy, tooltip content): include brief content guidelines covering the appropriate tone, length, and framing.
These are particularly important for:
If content guidelines are not relevant to this component, skip this section.
Cross-references to components that are commonly confused with this one, or commonly used alongside it. For each:
Review the completed guidelines and confirm that accessibility considerations appear in context throughout — not only in the dedicated accessibility section. The edge cases section should address accessibility edge cases. The anti-patterns section should include accessibility anti-patterns. The "when not to use" section should include accessible alternative recommendations.
Usage guidelines often default to designer language. Confirm the guidelines are useful for developers implementing the component too — the edge cases section and anti-patterns section are particularly important here. A developer implementing usage guidelines in code benefits from specific, conditional language rather than general principles.
Full guidelines are valuable for deep understanding. But in a code review, a design crit, or a sprint, teams need a one-page reference they can check in 30 seconds. After writing the full guidelines, generate a condensed quick-reference card.
Quick-reference card format:
## [Component name] — Quick reference
**Use when:** [3–5 bullet points, one line each, from "When to use"]
**Don't use when:** [3–5 bullet points, one line each, from "When not to use"]
**Watch for:**
- [Anti-pattern 1 — one line]
- [Anti-pattern 2 — one line]
- [Anti-pattern 3 — one line]
**Accessibility:** [keyboard pattern] | [required ARIA] | [focus behaviour — one line]
**Related:** [Component A] for [distinction] | [Component B] for [distinction]
The quick-reference card should fit in roughly 150 words. It is a lookup tool, not a learning document. Every line should be a decision aid — if it does not help someone make a choice in the moment, it does not belong on the card.
Deliver both the full guidelines and the quick-reference card as separate sections in the output. Teams can publish the quick-reference card alongside the component in their documentation site for fast access.
If the design system has documented voice and tone guidelines, content principles, or a writing style guide, the content guidelines section of the usage guidelines should reflect the system's specific standards — not generic UX writing advice.
How to adapt:
Check for voice/tone documentation. Look for files like CONTENT.md, VOICE.md, writing-guidelines.md, brand/tone.md, or equivalent in the documentation or knowledge notes. If .ds-ops-config.yml specifies system.content_guidelines_path, load that file.
If system voice/tone is available: Rewrite the content guidelines section to use the system's specific principles. For example, if the system says "Use sentence case for all UI text," include that rule directly. If the system says "Error messages should explain what went wrong and what to do next," include that pattern with a component-specific example.
If system voice/tone is NOT available: Use the generic content guidelines but add a note: "These content guidelines use general UX writing principles. For stronger consistency, document your system's voice and tone and reference it here."
Specific adaptation examples:
npx claudepluginhub murphytrueman/design-system-opsWrites documentation for design system patterns—multi-component UI recipes covering use cases, anti-patterns, composition, and related patterns. For forms, data tables, etc.
Generates detailed UI component specifications for design systems, including anatomy, variants, props, states, behavior, accessibility, and usage guidelines.
Generates component API documentation with props tables, usage examples, and guidelines. Use when documenting component libraries, creating API references, or building component documentation for designers and developers.