component-spec-writer
Skill1 starsChanged 5 days agoMITView on GitHub
Turn a component screenshot or written description into a developer handoff spec covering anatomy, variants, states, a props table with types and defaults, behavior, responsive rules, edge cases, accessibility notes for an auditor to verify, and open questions, keeping what the artifact shows separate from what was inferred and turning every gap into a question instead of a plausible default. Use when a component is going to engineering and the design file is the only documentation that exists.
In this repository163 other files it gives its agents.
- agents.mdAGENTS.md
- 3d-asset-handoff-sheetSkill
- accessibility-regression-auditorSkill
- adr-writerSkill
- agent-memory-designerSkill
- agent-trajectory-evaluatorSkill
- alerting-rules-tunerSkill
- analysis-memo-writerSkill
- annotation-disagreement-ledgerSkill
- annotation-task-spec-builderSkill
- api-deprecation-plannerSkill
- api-error-contract-designerSkill
- architecture-diagram-generatorSkill
- asset-metadata-review-ledgerSkill
- auth-flow-reviewerSkill
- background-job-reliability-auditorSkill
- branch-rebaserSkill
- brand-voice-profilerSkill
- bundle-analyzerSkill
- cache-policy-designerSkill
- canary-release-plannerSkill
- caption-correction-ledgerSkill
- changelog-from-prsSkill
- chart-chooserSkill
- chunking-strategy-optimizerSkill
- circular-dependency-breakerSkill
- claude-settings-auditorSkill
- code-example-verifierSkill
- cold-email-deliverability-auditorSkill
- cold-start-optimizerSkill
- commit-splitterSkill
- competitor-teardownSkill
- connection-pool-tunerSkill
- content-repurposerSkill
- contract-obligation-registerSkill
- contract-test-designerSkill
- conventional-commitsSkill
- cors-configuratorSkill
- coverage-gap-finderSkill
- crm-export-auditorSkill
- dashboard-designerSkill
- data-retention-auditorSkill
- dataset-first-lookSkill
- dead-code-finderSkill
- deadlock-diagnoserSkill
- decision-log-reconcilerSkill
- dependency-auditSkill
- dependency-upgrade-plannerSkill
- design-brief-writerSkill
- design-critique-checklistSkill
- design-token-extractorSkill
- devcontainer-designerSkill
- distributed-tracing-instrumenterSkill
- dockerfile-optimizerSkill
- email-sequence-drafterSkill
- embedding-index-tunerSkill
- embedding-set-inspectorSkill
- entity-match-candidate-ledgerSkill
- exit-ticket-builderSkill
- extract-moduleSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
List the variants: Only variants the artifact shows or the description names, each with what changes (fill, border, color role, size) and …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Most handoff arguments are about the thing the design did not show: what the button does while the request is in flight, what happens when the label is 60 characters, whether size is a prop or three separate components. This skill writes the spec that answers those in advance, from a screenshot you attach or a description you paste. It marks every line SHOWN (visible in the artifact), INFERRED (a reasonable reading, with the reason), or OPEN (nobody has decided). It needs only what you give it, so it runs the same on claude.ai, in Claude Code, and in Claude Cowork. Anthropic's design plugin ships a design-handoff skill that produces a broad spec and can pull measurements from Figma; this one is narrower on purpose, built around a props table and an explicit open-questions list rather than a filled-in document.
When to use this skill
- You are adding a component to a shared library and need variants and states written down first.
- A brief from the design-brief-writer skill named components that now need specifying.
- An engineer is about to run /new-component and needs the props settled.
[!NOTE] The spec never invents a default. If the artifact shows one size, the spec says one size and asks whether more are needed; it does not produce
sm | md | lgbecause most systems have them. Accessibility notes here are a to-verify list (what needs a label, focus handling, an announced state), not a compliance claim. Measurement against WCAG belongs to the accessibility-auditor agent once code exists.
Instructions
- Name and classify the component. Its name, what it is (control, container, feedback, navigation), and whether it is a new primitive, a variant of something the library has, or a one-off composition. If it looks like an existing component with different styling, say so first; that is the cheapest finding in the spec.
- Describe the anatomy. A numbered list of parts in visual order, each required or optional: container, icon (optional, leading), label (required), counter (optional, trailing). Anything that might be slot-based rather than a prop is called out here.
- List the variants. Only variants the artifact shows or the description names, each with what changes (fill, border, color role, size) and when to use it. Variants you suspect are missing go to open questions, not the table.
- List the states. Walk this fixed set every time: default, hover, active, focus, disabled, loading, error, selected, read-only, empty. For each: shown in the artifact, specified here as INFERRED, or OPEN. A component with no specified focus state is always an open question.
- Write the props table. Columns: Prop, Type, Default, Required, Description. Types are concrete (
"primary" | "secondary",boolean,ReactNode,(e) => void). A default is filled only when the artifact establishes one; otherwise the cell isOPEN. Include the event handlers the component needs and anyaria-*pass-through. - Specify behavior. What happens on click, on submit, on error, on repeat clicks while loading; whether the component owns its state or is controlled; what it does when an async action fails. Name tokens where a value matters, using the set from the design-token-extractor skill rather than pasting hex codes.
- Write the responsive rules. How the component behaves as its container narrows: wrap, truncate, stack, go full width, hide a part? Name the breakpoint if the source gives one; otherwise describe the behavior and leave the number OPEN.
- List the edge cases. Longest and shortest content, a translated label roughly 30 percent longer, missing optional parts, a very long single word, zero and very large numbers, an icon with no label, slow networks, repeated rapid interaction.
- Write the accessibility notes to verify. What the component must expose (role, accessible name, state) and what needs testing, phrased as checks for the accessibility-auditor agent, which does the audit itself.
- Write the open questions, each addressed to design or engineering and marked BLOCKING or NON-BLOCKING, then assemble the spec in order.
Output
A Markdown spec with these sections: Component, Anatomy, Variants, States, Props, Behavior, Responsive, Edge cases, Accessibility to verify, Open questions. Save it as design/specs/<component>.md. The design-systems-librarian agent reads specs like this to find components whose documentation has fallen behind them.
Example
Excerpt from a spec written from one screenshot of a filled button:
## States
| State | Source | Spec |
| --- | --- | --- |
| Default | SHOWN | Filled `{color.action.primary}`, radius `{radius.md}` |
| Focus | OPEN | Not shown. Needs a visible indicator distinct from hover. |
| Loading | INFERRED | Submits a form, so it needs one: spinner replaces the label, width held |
## Props
| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `variant` | `"primary" \| "secondary"` | `"primary"` | no | Only two are shown in the artifact |
| `size` | OPEN | OPEN | — | One size shown. Are more needed? |
## Open questions
1. BLOCKING (design): focus state treatment.
2. NON-BLOCKING (engineering): is `size` a prop or does the container set it?Claude skills for designers covers the rest of the set; Figma to code with Claude covers what changes when a Figma connection supplies exact measurements.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

