skill-files/figma-to-prototype.md

# Skill File: Figma-to-Prototype Scaffold
# Version: 1.2  |  Tool: Claude (claude-sonnet)
# Purpose: Generate a reviewed React prototype scaffold from a Figma
#          design description in three prompt stages.
# ─────────────────────────────────────────────────────────────────

## When to Use
- You have a Figma frame, component, or screen-flow description
- You need a coded prototype to share with engineering or research
- The prototype should reference design system tokens (not hardcoded values)
- Target stack: React + TypeScript + CSS Modules (or Styled Components)

## Prerequisites
☐ Figma frame description or exported spec (Inspect panel / Figma AI output)
☐ Design token reference (token file path or Storybook link)
☐ Known interaction requirements (states, transitions, edge cases)

## ─────────────────────────────────────────────
## STAGE 1 — Extract Design Intent
## ─────────────────────────────────────────────

PROMPT:
"""
I have a Figma design for [describe component or screen — e.g.
"a multi-step data filtering panel with 3 filter types: date range,
status chips, and a search input"].

Key design requirements:
- [List visual states: default, hover, focus, active, disabled, error]
- [List interactive behaviors: what opens, closes, validates, submits]
- [List any token references from the design file, e.g. color.brand.primary]
- Accessibility: must meet WCAG 2.1 AA

Generate:
1. A TypeScript props interface for the component
2. A component file skeleton (JSX structure, no logic yet)
3. A CSS Module file with token-mapped custom properties
4. A list of any ambiguities or missing information I should clarify
   before proceeding
"""

EXPECTED OUTPUT:
- ComponentName.tsx skeleton with typed props
- ComponentName.module.css with --token variables stubbed
- List of open questions (e.g. "what happens on empty state?")

★ HUMAN REVIEW CHECKPOINT 1:
  ☐ Props match the design intent — nothing over-engineered
  ☐ Token names match the actual design system (not invented)
  ☐ Open questions are answered before moving to Stage 2
  ☐ Scope is appropriate — not adding production features

## ─────────────────────────────────────────────
## STAGE 2 — Add Interaction Layer
## ─────────────────────────────────────────────

PROMPT:
"""
Using the component skeleton above, implement the following
interaction behaviors using React hooks only (no external
state management libraries):

- [Specific behavior 1 — e.g. "Dropdown opens on trigger click,
  closes on Escape key or click outside"]
- [Specific behavior 2 — e.g. "Date range validates that end date
  is after start date; shows inline error if not"]
- [Specific behavior 3 — e.g. "Filter count badge updates
  reactively as filters are applied/removed"]

Constraints:
- Use useRef for DOM interactions, useState for UI state
- Keep all data mocked / static (no API calls)
- Label any mocked data with a // MOCK comment
- Add a visible "PROTOTYPE" banner so reviewers know this
  is not production code
"""

EXPECTED OUTPUT:
- Complete, runnable component with interactions
- All mock data clearly labeled
- No TypeScript errors

★ HUMAN REVIEW CHECKPOINT 2:
  ☐ Component renders without console errors
  ☐ All interactive states work as designed (hover, focus, active, error)
  ☐ Keyboard navigation works: Tab, Enter, Escape, Arrow keys as applicable
  ☐ Mock data is clearly labeled and would not confuse a research participant
  ☐ "PROTOTYPE" label is visible

## ─────────────────────────────────────────────
## STAGE 3 — Scope Documentation
## ─────────────────────────────────────────────

PROMPT:
"""
Write a short README for this prototype (3-5 sentences) covering:
1. What interaction or workflow it demonstrates
2. What is real vs. simulated (what's "real," what's mocked)
3. What specific decision or research question it's designed to answer
4. Any known limitations or edge cases not handled

Then add inline comments to any section of the code where a reviewer
might misread prototype behavior as production behavior.
"""

EXPECTED OUTPUT:
- PROTOTYPE_README.md (3-5 sentences)
- Inline // PROTOTYPE NOTE: comments on ambiguous sections

★ HUMAN REVIEW CHECKPOINT 3:
  ☐ README would make sense to an engineer or researcher cold
  ☐ Prototype scope is correctly bounded — what's in and what's out
  ☐ Would a usability test participant understand what to interact with?
  ☐ Strip any sensitive data before sharing outside the team

## ─────────────────────────────────────────────
## Quality Checklist (final, before sharing)
## ─────────────────────────────────────────────

☐ Renders in-browser without errors or warnings
☐ Token references match actual design system values
☐ Keyboard navigable (Tab, Enter, Escape, Arrow keys)
☐ Basic screen reader test passed (VoiceOver / NVDA)
☐ All mock/simulated data labeled
☐ "PROTOTYPE ONLY" label visible in the UI
☐ PROTOTYPE_README.md present and accurate
☐ Shared via prototype-only channel (not the production codebase)

## ─────────────────────────────────────────────
## Notes on Responsible AI Use
## ─────────────────────────────────────────────

- Never paste proprietary data, PII, or production credentials into prompts
- Always validate token names against the actual design system — Claude
  may invent plausible-sounding but incorrect token names
- Claude output is a starting point; all code requires human review
  before being shown to stakeholders or research participants
- When in doubt, reduce prototype scope rather than papering over
  gaps with speculative AI output