Design System Component Spec Writer for Figma Handoff

Produces a developer-ready component specification covering anatomy, variants, states, tokens, accessibility, and open questions from a short component brief.

You get: Summary and readiness verdict, anatomy list and variants and sizes table

More like this

The prompt

design-system-component-spec-writer-for-figma-handoff.md
Role: You are a design systems designer writing specs that engineers and other designers can implement without a meeting.Context: Job to be done: document the {component_name} component for the {design_system} system so it can be built and reused consistently. Decision to support: whether the spec is ready for engineering handoff or needs more design decisions first.
Task: Write the component specification from the inputs and flag every gap.Constraints: Do not invent token names or values that I did not provide; propose them clearly marked as Proposed. Do not assume a framework. Follow WCAG 2.2 AA for contrast, focus, target size, and keyboard behavior. Keep facts and assumptions in separate sections.

Inputs
- Component purpose and where it is used: {purpose_and_usage}
- Platforms and frameworks: {platforms}
- Existing tokens (color, spacing, type, radius): {existing_tokens}
- Known variants, sizes, and states: {known_variants}
- Content rules (label length, truncation, localization): {content_rules}
- Similar components already in the system: {related_components}
If purpose or platforms are missing, ask up to 4 questions first.

Workflow
1. Restate the job and decision; list Assumptions separately from provided facts.
2. Define anatomy: named parts and which are optional.
3. Define variants and sizes, then a state matrix (default, hover, focus, pressed, disabled, loading, error where relevant).
4. Map each part and state to tokens; mark each as Provided or Proposed.
5. Specify behavior: keyboard interaction, focus order, ARIA role and attributes, screen reader label, and motion or reduced-motion handling.
6. Add usage guidance: do and do not, and when to use a related component instead.
7. Identify gaps and run a readiness check.

Output format
1. Summary and readiness verdict (Ready / Ready with conditions / Not ready)
2. Assumptions
3. Anatomy list
4. Variants and sizes table: Variant | Size | Use when | Notes
5. State matrix table: State | Visual change | Token | Source (Provided/Proposed)
6. Accessibility and keyboard behavior checklist
7. Content and localization rules
8. Do and do not guidance
9. Risks, missing information, and open questions
10. Next actions (owner role, order of work)

Acceptance criteria
- An engineer could build the component from the spec without guessing a state or token.
- Every Proposed token is labeled and justified.
- Accessibility requirements are testable statements, not general advice.
- The readiness verdict is supported by the listed gaps.

Quality checks
- No state appears in the matrix without a defined visual change.
- Keyboard behavior covers Tab, Enter, Space, and Escape where applicable.
- Contrast requirements cite the threshold (for example 4.5:1 for normal text) but do not claim measured values.
- Terminology matches {related_components}.

Tool notes: Output tables so they can be pasted into Figma documentation, Notion, or a Markdown file. In Claude or ChatGPT, paste token lists as plain text. Ask for a JSON token appendix as a follow-up if engineering needs one.

Example output

AI-written example

Toggle Switch: Meridian Design System Spec

1. Summary and readiness verdict

Immediate on/off setting control, used in Settings and Notifications. Platforms: Web (React) and iOS (SwiftUI).
Verdict: Ready with conditions. Loading behavior and the iOS haptic decision are unresolved (see section 9).

2. Assumptions

  • Changes apply immediately, with no Save button.
  • The label always sits to the right of the track in LTR and mirrors in RTL.
  • The same visual spec applies on web and iOS. Native iOS behavior is not overridden.

3. Anatomy

  1. Track (required)
  2. Thumb (required)
  3. Label (required)
  4. Helper text (optional)
  5. Loading spinner (optional, replaces thumb icon)

4. Variants and sizes

VariantSizeUse whenNotes
DefaultMedium (40×24)Standard settings lists44px min hit area via padding
DefaultSmall (32×20)Dense tablesHit area still 24×24 minimum
With helper textMediumSetting needs explanationHelper max 2 lines

5. State matrix

StateVisual changeTokenSource
Off, defaultNeutral track, thumb leftcolor.bg.neutral-strongProvided
On, defaultBrand track, thumb rightcolor.bg.brandProvided
HoverTrack darkens one stepcolor.bg.brand-hoverProposed: no hover token exists
Focus2px ring, 2px offsetcolor.border.focusProvided
PressedThumb widens 4pxspace.100Proposed: matches existing spacing scale
Disabled40% opacity, no pointer eventsopacity.disabledProposed
LoadingSpinner in thumb, input lockedmotion.duration.spinProposed
ErrorDanger border plus message belowcolor.border.dangerProposed

6. Accessibility and keyboard checklist

  • [ ] Role is switch with aria-checked true/false (web).
  • [ ] Tab moves focus to the switch. Space toggles it. Enter toggles it.
  • [ ] Escape has no effect, because there is no overlay.
  • [ ] Focus ring has at least 3:1 contrast against adjacent colors.
  • [ ] Label text meets 4.5:1. Track and thumb meet 3:1 against the background in both states.
  • [ ] Target size is at least 24×24 CSS px (WCAG 2.5.8).
  • [ ] State is never conveyed by color alone: the thumb position changes and an optional On/Off text is available.
  • [ ] Loading sets aria-busy="true". Result changes are announced via a polite live region.
  • [ ] Under prefers-reduced-motion, the thumb moves with no transition.

7. Content and localization

  • Labels are 40 characters or fewer, written as a noun phrase ("Email notifications").
  • Labels wrap and are never truncated.
  • Allow 30% text expansion. Mirror the layout in RTL.

8. Do and do not

  • Do use it for settings that take effect immediately.
  • Do not use it in forms that need a Submit action. Use Checkbox instead.
  • Do not use it to choose between two named options. Use Segmented Control.

9. Risks and open questions

  1. Should failed saves revert the switch automatically? (Blocks Error state.)
  2. Is a haptic required on iOS?
  3. Are the 5 proposed tokens approved by the token owner
Generated from this prompt by AI. Your results will vary.

Tips and common edits

Paste real tokens when you have them to reduce Proposed values. Run once per component. Use the readiness verdict in design review to decide whether to hand off or resolve open questions first.

Questions about this prompt

More in Design

UX Flow Audit from Screenshots with Prioritized Fix Plan

Audits a user flow from screenshots or descriptions and returns an evidence-labeled issue table plus a fix-now, next, defer plan for a sprint decision.

30-Minute Moderated Usability Test Script with Tasks and Notes Template

Produces a timed 30-minute moderated usability script with task scenarios, neutral follow-up questions and a ready-to-use notes template.

Competitor UX Pattern Research Plan with Evidence Table and Design Recommendation

Builds a source discovery plan, evidence log, citation table, and synthesis for comparing UX patterns across competitors, without claiming live browsing.

Design Brief from Client Notes with Assumptions and Next Actions

Turns a client's rough notes into a structured design brief with goals, audience, deliverables, constraints, references to gather and measurable success criteria.

UX Copy Audit: Flag Unclear Labels, Jargon and Weak CTAs with Rewrites

Audits pasted screen copy for unclear labels, jargon and weak calls to action, then returns a table with a rewrite and a one-line reason for each issue.

Architecture Decision Record for a Technology Choice

Compares realistic options against your constraints and produces a decision record. The record has a weighted comparison, risks, a reversal plan, and a recommendation the team can approve or challenge.

Conventional Commit and PR Description from a Diff and Ticket

Produces a Conventional Commits message and a reviewer-ready PR description covering what changed, why, how to test it, and the risks, based on your diff and ticket.

Trending

Developmental Edit Memo for an Essay Draft With Revise-or-Cut Decisions

Gives a draft essay a structured developmental edit: thesis check, paragraph-by-paragraph audit, and a prioritized revision plan so you can decide what to keep, rewrite, or cut before line editing.

4-Week Small Business Launch Plan: $0 and Small-Budget Versions

Builds a 4-week launch plan for a product or service in a specific market, with channels and weekly tasks in a $0 version and a small-budget version.

60-Minute Lesson Plan with Checks for Understanding and Differentiation

Builds a timed, objective-aligned lesson plan with formative checks, differentiation, and a teach-or-revise readiness verdict. It asks for missing inputs first and keeps assumptions separate.

90-Day Lifecycle Marketing Diagnostic and Experiment Roadmap for Onboarding and Retention

Diagnoses drop-off across the customer lifecycle from your funnel data and produces a prioritized 90-day plan of messages, triggers, and experiments with metrics so teams can decide where to invest first.

Above-the-Fold Landing Page Critique with 3 Headline, Subhead, and CTA Variants

Critiques landing page copy for clarity and conversion, then rewrites the headline, subhead, and CTA in three distinct variants.