Write a component spec for engineering handoff. Use when the user says "component spec", "design handoff", "spec this component", "document this component for engineering", "Figma handoff", "component documentation", "how do I hand this off", or needs to communicate a UI component design to developers - even if they don't explicitly say "component spec".
Based on "Atomic Design" by Brad Frost. Frost's atomic design methodology organizes UI into: atoms (basic elements), molecules (groups of atoms), organisms (groups of molecules), templates (page structures), and pages (specific instances). A component spec documents where a component sits in this hierarchy, what it's made of, how it behaves, and how it should be used.
The goal of a component spec is to make the engineering handoff self-contained. A developer should be able to build the component correctly without asking questions.
Workflow
Step 1: Classify the component (Atomic Design)
Level
What it is
Examples
Atom
Smallest UI unit, not decomposable
Button, input, icon, label
Molecule
2-3 atoms working together
Search field (input + button), form field (label + input + error)
Organism
Complex UI section
Navigation bar, product card, comment thread
Template
Page-level layout
Dashboard layout, article layout
Knowing the level sets expectations for complexity and reusability.
Content variants: with icon, without icon, with badge
States:
Default
Hover
Active/pressed
Focus (keyboard navigation)
Disabled
Loading
Error
Success
Provide a Figma frame for every variant x state combination.
Step 4: Document properties (props)
List every configurable property:
Prop
Type
Required
Default
Description
label
string
Yes
-
Button text
variant
enum
No
primary
Visual style
size
enum
No
medium
Size variant
disabled
boolean
No
false
Disabled state
onClick
function
Yes
-
Click handler
Step 5: Document behavior
What happens on click / tap?
Are there animations or transitions? (duration, easing)
What are the keyboard interactions? (Enter, Space, Escape, Tab)
What happens at min/max content lengths?
What happens when text is truncated?
Step 6: Document accessibility requirements
ARIA role and attributes
Keyboard navigation behavior
Screen reader announcement
Focus management
Color contrast requirements (WCAG AA minimum)
Step 7: Document usage rules
When should this component be used? When should it not be used?
Use when: [specific contexts]
Don't use when: [anti-use-cases - what to use instead]
Anti-Patterns
1. Spec without states
Bad: One static mockup handed off.
Good: Every state documented - default, hover, focus, disabled, error, loading.
2. No accessibility section
Bad: "Engineering will figure it out."
Good: ARIA role, keyboard behavior, and contrast requirements specified by design, not guessed by engineering.
3. Props undocumented
Bad: Figma file with no prop documentation.
Good: Every configurable property listed with type, required status, and description.
4. Usage rules missing
Bad: Component documented without guidance on when to use vs. not use it.
Good: Explicit usage rules prevent misuse and inconsistency across [your product].
Quality Checklist
Atomic level classified (atom/molecule/organism)
Figma link to all variants and states
All variants documented
All states documented (default, hover, focus, disabled, error, loading)
Props table complete with types, required flag, defaults
Rate any product, feature, or experience on the 11-star scale (Brian Chesky's Airbnb thought experiment). Use when user says "rate this experience", "11-star", "star rating", "experience audit", "how good is this", "experience rating", "product audit", "quality assessment", or wants to evaluate product quality and identify improvement paths. Also trigger when user wants to benchmark a feature, assess where a product stands, or map out what "great" looks like - even if they don't explicitly say "11-star".
Generate A/B copy variants grounded in Eugene Schwartz's awareness and market-sophistication stages and John Caples' tested-headline discipline. Every variant declares its angle, the awareness stage it targets, and a falsifiable hypothesis, and the skill recommends which pair to test first and what delta counts as signal. Use when the user says "A/B test this", "write variants", "give me options", "test different angles", "copy variants", "ab copy", "test this headline", "multiple versions", "which version is better", or wants to test copy before publishing. For reviewing copy that already exists, see copy-review. For sample size and stopping rules, see growth-experiment. For diagnosing a page rather than its words, see page-cro. For full paid ad sets by platform, see ad-campaign-writer.
Design statistically rigorous experiments to test data science hypotheses. Use when the user says "design an A/B test", "run an experiment", "test this hypothesis", "is this difference significant", "how many samples do I need", "randomized controlled trial", "causal inference", "uplift test", "holdout group", "significance test", "power calculation", "avoid p-hacking", or needs to determine whether an observed effect is real before making a product or model decision. For lean build-measure-learn product experiments without the statistics, use experiment-design instead.
Write measurable acceptance criteria for requirements or user stories. Use when the user says "write acceptance criteria", "definition of done", "how do we test this", "fit criteria", "given when then", "Gherkin scenarios", "what does done look like", "testable conditions", "how will we know this works" - even if they don't explicitly say "acceptance criteria".
Build a strategic account plan for winning, retaining, or expanding a named account. Use when the user says "build an account plan", "strategic account planning", "how do I grow this account", "account expansion strategy", "whitespace analysis", "QBR prep", "key account review", "map the stakeholders in this account", "land and expand plan", "how do I break into [company]", or wants a structured strategy for a specific account.
Write paid ad copy for LinkedIn, Google, Meta, and YouTube. Produces multiple variants per platform, each targeting a different Eugene Schwartz awareness level and Cialdini persuasion principle. Use when the user asks for ad copy, ad variants, "write LinkedIn ads", Google ads, Meta ads, paid social copy, ad headlines, or wants creative for a paid campaign. Reads brand voice, ICP, and positioning from knowledge/. For organic social posts, see linkedin-post or social-calendar. For the landing page the ad points at, see landing-page-writer. For testing variants, see ab-copy-writer.