design-system-usage-guidelines
Paste into Claude Code, Claude.ai, the desktop app, or the browser extension — ⌘/Ctrl+V. ✓ Copied. Switch to Claude and paste — ⌘/Ctrl+V.
Design System Usage Guidelines
Generate structured governance documentation for a design system section or component. Produces consistent, complete documentation that bridges design and engineering, covering usage rules, contribution process, deprecation paths, and recorded design decisions.
Usage
/design-system-usage-guidelines <section-or-component> [--type guidelines|contribution|deprecation|decisions|all] [--audience designer|engineer|both] [--format starlight|supernova|zeroheight|markdown]
Examples:
/design-system-usage-guidelines Button --type guidelines --audience both— full usage guide/design-system-usage-guidelines tokens --type contribution --audience engineer— token contribution guide/design-system-usage-guidelines "Navigation" --type deprecation— migration/deprecation notice/design-system-usage-guidelines "Color system" --type decisions— design decision log/design-system-usage-guidelines "Form components" --type all— all doc types for a section
Phase 1 — Context Discovery
If existing documentation or source files are available, read them:
ls docs/components/<section>/
ls src/components/<section>/
Gather:
- Existing component names within the section (if a section is targeted).
- Any existing README, CHANGELOG, or CONTRIBUTING files.
- The design system's version scheme (semver, date-based, etc.).
If no files exist, generate guidelines based on the component/section name and RBA's standard DX project context.
Phase 2 — Usage Guidelines (if --type includes guidelines)
Generate a <section>-guidelines.md covering:
2.1 Section overview
- What this section of the design system contains
- The design principles it embodies (e.g., "Form components prioritise clarity, not decoration")
- How it relates to other sections (e.g., "Buttons are used in all interactive form, modal, and CTA contexts")
2.2 When to use this section
A clear trigger list: situations that should use these components vs. situations that should not.
2.3 Visual guidelines
- Spacing and layout: how components in this section are typically composed
- Typography: which typographic tokens apply by default
- Colour usage: which semantic colour tokens appear and what they signal
2.4 Interaction patterns
- Expected keyboard navigation model across the section
- Focus management expectations (e.g., "modal components must trap focus")
- Touch target requirements (minimum 44×44px recommended; 24×24px WCAG AA minimum)
2.5 Content guidelines
- Voice and tone for labels, error messages, placeholder text, empty states
- Character limits or length recommendations
- Internationalisation considerations (RTL support, locale-specific formatting)
2.6 Do / Don't examples
Generate at least 5 specific do/don't pairs tailored to the section. Frame each around a real mistake that teams make on DX projects (e.g., "Don't use button variants inconsistently within a single form").
2.7 Composition patterns
Show 2–3 common compositions of components from this section (e.g., a search input + button composition, a form field stack). Document which tokens govern the gap between them.
Phase 3 — Contribution Guide (if --type includes contribution)
Generate a contributing.md covering:
3.1 Who can contribute
Define the contribution model:
- Internal team — anyone on the RBA project team can open a proposal
- Client team — client design/engineering may request changes via the design system backlog
- Design system team — maintains ownership, reviews all proposals
3.2 How to propose a change
Types of changes and the process for each:
| Change type | Process | Review SLA |
|---|---|---|
| Bug fix (visual or functional) | PR to fix branch → review → merge | 2 business days |
| New token value | RFC issue → discussion → PR | 5 business days |
| New component variant | RFC issue → design mockup → token additions → PR → review | 1 sprint |
| New component | ADR → design mockup review → token architecture → PR → review | 2 sprints |
| Breaking change | RFC → migration guide → deprecation notice → major version bump | 1 sprint minimum |
3.3 PR checklist
Generate a PULL_REQUEST_TEMPLATE.md checklist:
## Design System PR Checklist
### Tokens
- [ ] New tokens follow the three-tier naming convention (primitive → semantic → component)
- [ ] Token names are kebab-case and match the design file names exactly
- [ ] All aliases are resolved (no dangling references)
- [ ] Token `$description` fields are populated
### Component
- [ ] Component doc updated (anatomy, props, states, tokens sections)
- [ ] Storybook story covers all new variants and states
- [ ] All new props have TypeScript types and JSDoc
- [ ] Component uses token layer — no hard-coded colour, spacing, or typography values
### Accessibility
- [ ] New interactive elements have keyboard interaction documented
- [ ] Focus management implemented and tested
- [ ] Screen reader test passed (NVDA or JAWS on Windows, VoiceOver on macOS/iOS)
- [ ] Colour contrast meets WCAG 2.2 AA (4.5:1 normal text, 3:1 large/UI)
### Design file
- [ ] Figma component updated to match code implementation
- [ ] Token variables linked in Figma (not detached overrides)
- [ ] Component published to the shared library
3.4 Design review process
Describe the design review gate: who reviews, what criteria, how decisions are documented.
3.5 Token naming convention guide
Concise reference for contributors on the three-tier model and naming rules.
Phase 4 — Deprecation Notice (if --type includes deprecation)
Generate a deprecation-<component-or-version>.md:
4.1 What is deprecated
- Component or token name
- Version it was deprecated in
- Date or version when it will be removed
4.2 Reason for deprecation
Be specific: "The LegacyButton component predates the token architecture and hard-codes
colour values. The new Button component provides identical functionality via the full token
layer, enabling multi-brand theming."
4.3 Migration guide
Step-by-step migration instructions with before/after code examples:
## Migrating from LegacyButton to Button
**Before:**
```tsx
<LegacyButton color="blue" size="medium">Save</LegacyButton>
After:
<Button variant="primary" size="md">Save</Button>
Prop mapping:
| LegacyButton prop | Button equivalent | Notes |
|---|---|---|
color="blue" |
variant="primary" |
Colour is now controlled by tokens |
color="red" |
variant="danger" |
|
size="medium" |
size="md" |
Renamed to align with token scale |
size="small" |
size="sm" |
|
fullWidth |
style={{ width: '100%' }} |
Removed — use layout utilities |
### 4.4 Codemod (if applicable)
If the migration is mechanical, provide a jscodeshift codemod or an ESLint auto-fix suggestion
to handle bulk migration across a large codebase.
---
## Phase 5 — Design Decisions Log (if --type includes `decisions`)
Generate one or more ADR (Architecture Decision Record) style documents for significant design
system decisions. Format adapted from Michael Nygard's ADR template:
```markdown
# [DS-ADR-NNN] <Decision title>
**Date:** <date>
**Status:** Accepted | Superseded by DS-ADR-NNN | Deprecated
**Deciders:** <names or roles>
## Context
<What situation prompted this decision. Include constraints, stakeholder requirements,
and technical context.>
## Decision
<The decision made. Use active voice: "We will...", "We chose...", "The system uses...">
## Token impact
<Which tokens were added, changed, or removed as a result of this decision.>
## Rationale
<Why this decision was made over the alternatives. Acknowledge trade-offs explicitly.>
## Alternatives considered
| Option | Pros | Cons | Rejected because |
|--------|------|------|-----------------|
## Consequences
<What becomes easier and harder as a result of this decision. Who is affected.>
## Migration path (if replacing prior decision)
<Steps for teams to align with the new decision.>
Generate one ADR per significant decision identified from the component/section context, or generate a skeleton with prompts if no decisions are yet documented.
Phase 6 — Write Output Files
Write each document type to the appropriate location:
| Doc type | Default output path |
|---|---|
| Usage guidelines | docs/guidelines/<section>.md |
| Contribution guide | docs/contributing.md (or CONTRIBUTING.md at repo root) |
| PR template | .github/PULL_REQUEST_TEMPLATE.md |
| Deprecation notice | docs/deprecations/<component>-<version>.md |
| Design decisions | docs/decisions/DS-ADR-<NNN>-<slug>.md |
If --format starlight, prepend Starlight frontmatter. If --format supernova or zeroheight,
use plain Markdown (both platforms accept it without special frontmatter).
Print a summary of all files created.
Reference files
templates.md— Full ADR template, contribution guide template, PR checklist, deprecation notice template, do/don't table format
Technical details
- Plugin
- design-system-manager
- Author
- Dakota Smith
- Skill name
design-system-usage-guidelines- Maturity
- experimental
- Security review
- No security review
- Owners
-
- design
- engineering
- Argument hint
<section-or-component> [--type guidelines|contribution|deprecation|decisions|all] [--audience designer|engineer|both] [--format starlight|supernova|zeroheight|markdown]- Allowed tools
-
ReadWriteGlobBash(ls *)
- Source
plugins/design-system-manager/skills/design-system-usage-guidelines/SKILL.md
Edit this skill on GitHub — opens GitHub's web editor. No git knowledge needed.