Use design-system-spec

Write a design system component spec

Write a design system component spec — purpose, anatomy, variants, every state (default, hover, focus, active, disabled, error, loading), the design tokens each part uses by name, behaviour, content rules, accessibility (keyboard, focus order, ARIA role, contrast, target size) cited to WCAG 2.2 criteria, do/don't examples, and the open questions engineering must answer.

Reach for it when the user wants a component spec, design system documentation, "spec out this button / modal / text field", a component's states and tokens, or a design-to-engineering hand-off for a component.

Install it

npx skilldrop-cli install design-system-spec                 # Claude Code, your user folder
npx skilldrop-cli install design-system-spec --project       # Claude Code, this repo
npx skilldrop-cli install design-system-spec --ide cursor    # or kiro, codex, antigravity, copilot

It is part of the Experience design pack: --pack experience-design installs it with its neighbours.

Ask for it

Say it the way you would to a colleague. Requests like these route to it:

• "Write a component spec for our button: variants, states, tokens and accessibility"
• "Document the tabs component for our design system so engineering can build it"
• "Spec out a toast notification with all its states and keyboard behaviour"
• "Our date picker behaves differently in three products — write one spec they can all build to"

Requests like these belong to a different skill, so it shouldn't answer them:

• "Audit our sign-up page for WCAG 2.2 AA problems"
• "Set up our brand kit with our logo, colours and fonts"
• "Write the error messages and helper text for the checkout form"

If another skill answers instead, ask for this one by name: "use design-system-spec".

Check what you get

A good result:

• Purpose and boundary are stated, including when to use a different component.
• Anatomy parts are numbered and the numbers are reused in the state and token tables.
• Variants sit on independent axes, each with a use case. No speculative variants.
• Every applicable state is specified, including focus, disabled, error and loading. Focus differs from hover and isn't shown by colour alone.
• Tokens are named, never raw values. Proposed tokens are tagged and listed as open questions.
• Accessibility covers keyboard, focus, role and name, contrast and announcements, and every WCAG citation is one from the reference list with the right number and name.
• Open questions for engineering each name the decision they block.
• Nothing is invented. Token names, brand values and platform constraints not in the input are tagged [proposed token] or [assumption].

See a worked example

• text field spec

Use something else when

• Auditing a built page or component against WCAG — that's accessibility-audit
• Writing the product's interface strings for a flow — that's ux-writing
• Capturing brand colours, fonts and logo — that's brand-kit
• Page-level structure or navigation — that's information-architecture

Next

• SKILL.md, the instructions the agent reads
• Its page on the site
• Related: accessibility-audit, brand-kit, information-architecture, ux-writing

Edit this page on GitHub · View source