Visual design
Share

Design System Component Visual Spec Writer

Developer-friendly visual specs: anatomy, tokenized properties per variant/state, spacing, responsive behavior, and accessibility for one component cluster.

Use Case

Figma-to-code handoff, design system docs, or reducing ambiguity before engineering builds a component.

Prompt

Act as a Lead Visual Designer and design systems expert who writes precise, developer-friendly component specifications.

I need to write a complete visual specification for the following component:

Component Details:
Component Name: [e.g., Primary Button, Toast Notification, Data Table Row, Navigation Bar]
Component Category: [e.g., Action, Feedback, Navigation, Data Display, Input, Layout]
Platform: [Web / iOS / Android / Cross-platform]
Design System Context: [e.g., new design system, extending an existing system like Material or Ant Design]
Variants Needed: [list known variants - e.g., Primary, Secondary, Ghost, Destructive, Disabled]
States Needed: [e.g., Default, Hover, Focus, Active, Disabled, Loading, Error]
Figma Frame or Description: [describe the visual design or paste a description of what it looks like]

Please generate a complete component spec with the following sections:

Component Overview
- Purpose: What does this component do and when should it be used?
- Usage guidelines: When to use this component vs. alternatives
- Anti-patterns: When NOT to use this component

Anatomy
- List every element that makes up the component (e.g., container, label, icon, border, shadow)
- For each element: name it, describe its visual role, and note if it is optional or required

Visual Specifications Table
Create a table with these columns for EACH variant and state:
| Property | Value | Token Name |
Example rows:
| Background color | #1A73E8 | color.primary.600 |
| Border radius | 8px | radius.md |
| Padding (top/bottom) | 12px | spacing.3 |
| Padding (left/right) | 24px | spacing.6 |
| Typography | 16px / Medium / Inter | text.label.md |
| Border | None | - |
| Shadow | 0 2px 4px rgba(0,0,0,0.1) | shadow.sm |
| Icon size | 20px | icon.md |
| Min width | 120px | - |
| Height | 44px | - |

State Specifications
For each state (hover, focus, active, disabled, loading, error): describe EXACTLY what changes visually from the default state (color delta, opacity, transform, cursor, etc.)

Spacing & Layout Rules
- Internal padding rules
- Spacing between this component and adjacent elements
- Alignment behavior within containers

Responsive Behavior
- How does the component adapt at mobile, tablet, and desktop breakpoints?
- Does it stack, collapse, truncate, or stretch?

Accessibility Requirements
- Minimum touch target size (mobile)
- Keyboard focus style (describe the focus ring)
- ARIA role and required attributes
- Minimum color contrast ratio for all text elements

Do / Don't Visual Rules
List 3-5 specific dos and don'ts with a one-sentence rationale each

Related Components
List 2-3 components that are commonly used alongside this one

How to use

  1. 1Run one prompt per variant cluster (e.g., all Primary Button variants first, then Icon Button) for tighter output.
  2. 2Paste your real token names or taxonomy in Design System Context so the model aligns naming.
  3. 3Optional follow-up: ask to convert the visual spec table into CSS custom properties matching your token convention.

Pro Tips

  • UI Component Specification is a lighter checklist; use this prompt when you need per-state token tables and anatomy detail.
  • Verify every numeric value against Figma - the model invents plausible numbers, not measured ones.
  • Share the Do and Don't section with content and product teams early to prevent component misuse.
  • Confirm WCAG level (AA vs AAA) with your accessibility team; the model may default to generic guidance.

Tags

visual-designdesign-systemcomponentsspecificationhandofftokensaccessibility

New prompts & templates by email

Weekly copy-paste prompts, pattern notes, and AI UX resources on Substack - no spam, unsubscribe anytime.

Subscribe on Substack