Generates a design handoff document that serves as direct implementation instructions for AI coding agents. Unlike traditional handoff notes that describe how a design "should feel," this document provides machine-parseable specifications with zero ambiguity. Every value is explicit, every state is defined, every edge case has a rule.
1# Design Handoff Notes — AI-First, Human-Readable23### A structured handoff document optimized for AI implementation agents (Claude Code, Cursor, Copilot) while remaining clear for human developers45---67## About This Prompt89**Description:** Generates a design handoff document that serves as direct implementation instructions for AI coding agents. Unlike traditional handoff notes that describe how a design "should feel," this document provides machine-parseable specifications with zero ambiguity. Every value is explicit, every state is defined, every edge case has a rule. The document is structured so an AI agent can read it top-to-bottom and implement without asking clarifying questions — while a human developer can also read it naturally.1011**The core philosophy:** If an AI reads this document and has to guess anything, the document has failed.1213**When to use:** After design is finalized, before implementation begins. This replaces Figma handoff, design spec PDFs, and "just make it look like the mockup" conversations.1415**Who reads this:**16- Primary: AI coding agents (Claude Code, Cursor, Copilot, etc.)17- Secondary: Human developers reviewing or debugging the AI's output18- Tertiary: You (the designer), when checking if implementation matches intent1920**Relationship to CLAUDE.md:** This document assumes a CLAUDE.md design system file already exists in the project root. Handoff Notes reference tokens from CLAUDE.md but don't redefine them. If no CLAUDE.md exists, run the Design System Extraction prompts first.2122---2324## The Prompt2526```27You are a design systems engineer writing implementation specifications.28Your output will be read primarily by AI coding agents (Claude Code, Cursor)29and secondarily by human developers.3031Your writing must follow one absolute rule:32**If the reader has to guess, infer, or assume anything, you have failed.**3334Every value must be explicit. Every state must be defined. Every edge case35must have a rule. No "as appropriate," no "roughly," no "similar to."3637## Project Context38- **Project:**39- **Framework:** [Next.js 14+ / React / etc.]40- **Styling:** [Tailwind 3.x / CSS Modules / etc.]41- **Component library:** [shadcn/ui / custom / etc.]42- **CLAUDE.md location:** [path — or "not yet created"]43- **Design source:** [uploaded code / live URL / screenshots]44- **Pages to spec:** [all / specific pages]4546## Output Format Rules4748Before writing any specs, follow these formatting rules exactly:49501. **Values are always code-ready.**51 WRONG: "medium spacing"52 RIGHT: `p-6` (24px)53542. **Colors are always token references + fallback hex.**55 WRONG: "brand blue"56 RIGHT: `text-brand-500` (#2563EB) — from CLAUDE.md tokens57583. **Sizes are always in the project's unit system.**59 If Tailwind: use Tailwind classes as primary, px as annotation60 If CSS: use rem as primary, px as annotation61 WRONG: "make it bigger on desktop"62 RIGHT: `text-lg` (18px) at ≥768px, `text-base` (16px) below63644. **Conditionals use explicit if/else, never "as needed."**65 WRONG: "show loading state as appropriate"66 RIGHT: "if data fetch takes >300ms, show skeleton. If fetch fails, show error state. If data returns empty array, show empty state."67685. **File paths are explicit.**69 WRONG: "create a button component"70 RIGHT: "create `src/components/ui/Button.tsx`"71726. **Every visual property is stated, never inherited by assumption.**73 Even if "obvious" — state it. AI agents don't have visual context.7475---7677## Document Structure7879Generate the handoff document with these sections:8081### SECTION 1: IMPLEMENTATION MAP8283A priority-ordered table of everything to build.84AI agents should implement in this order to resolve dependencies correctly.8586| Order | Component/Section | File Path | Dependencies | Complexity | Notes |87|-------|------------------|-----------|-------------|-----------|-------|88| 1 | Design tokens setup | `tailwind.config.ts` | None | Low | Must be first — all other components reference these |89| 2 | Typography components | `src/components/ui/Text.tsx` | Tokens | Low | Heading, Body, Caption, Label variants |90| 3 | Button | `src/components/ui/Button.tsx` | Tokens, Typography | Medium | 3 variants × 3 sizes × 6 states |91| ... | ... | ... | ... | ... | ... |9293Rules:94- Nothing can reference a component that comes later in the table95- Complexity = how many variants × states the component has96- Notes = anything non-obvious about implementation9798---99100### SECTION 2: GLOBAL SPECIFICATIONS101102These apply everywhere. AI agent should configure these BEFORE building any components.103104#### 2.1 Breakpoints105Define exact behavior boundaries:106107```108BREAKPOINTS {109 mobile: 0px — 767px110 tablet: 768px — 1023px111 desktop: 1024px — 1279px112 wide: 1280px — ∞113}114```115116For each breakpoint, state:117- Container max-width and padding118- Base font size119- Global spacing multiplier (if it changes)120- Navigation mode (hamburger / horizontal / etc.)121122#### 2.2 Transition Defaults123```124TRANSITIONS {125 default: duration-200 ease-out126 slow: duration-300 ease-in-out127 spring: duration-500 cubic-bezier(0.34, 1.56, 0.64, 1)128 none: duration-0129}130131RULE: Every interactive element uses `default` unless132 this document specifies otherwise.133RULE: Transitions apply to: background-color, color, border-color,134 opacity, transform, box-shadow. Never to: width, height, padding,135 margin (these cause layout recalculation).136```137138#### 2.3 Z-Index Scale139```140Z-INDEX {141 base: 0142 dropdown: 10143 sticky: 20144 overlay: 30145 modal: 40146 toast: 50147 tooltip: 60148}149150RULE: No z-index value outside this scale. Ever.151```152153#### 2.4 Focus Style154```155FOCUS {156 style: ring-2 ring-offset-2 ring-brand-500157 applies-to: every interactive element (buttons, links, inputs, selects, checkboxes)158 visible: only on keyboard navigation (use focus-visible, not focus)159}160```161162---163164### SECTION 3: PAGE SPECIFICATIONS165166For each page, provide a complete implementation spec.167168#### Page:169**Route:** `/exact-route-path`170**Layout:**171**Data requirements:** [what data this page needs, from where]172173##### Page Structure (top to bottom)174175```176PAGE STRUCTURE:177├── Section: Hero178│ ├── Component: Heading (h1)179│ ├── Component: Subheading (p)180│ ├── Component: CTA Button (primary, lg)181│ └── Component: HeroImage182├── Section: Features183│ ├── Component: SectionHeading (h2)184│ └── Component: FeatureCard × 3 (grid)185├── Section: Testimonials186│ └── Component: TestimonialSlider187└── Section: CTA188 ├── Component: Heading (h2)189 └── Component: CTA Button (primary, lg)190```191192##### Section-by-Section Specs193194For each section:195196****197198```199LAYOUT {200 container: max-w-[1280px] mx-auto px-6 (mobile: px-4)201 direction: flex-col (mobile) → flex-row (desktop)202 gap: gap-8 (32px)203 padding: py-16 (64px) (mobile: py-10)204 background: bg-white205}206207CONTENT {208 heading {209 text: ""210 element: h2211 class: text-3xl font-bold text-gray-900 (mobile: text-2xl)212 max-width: max-w-[640px]213 }214 body {215 text: ""216 class: text-lg text-gray-600 leading-relaxed (mobile: text-base)217 max-width: max-w-[540px]218 }219}220221GRID (if applicable) {222 columns: grid-cols-3 (tablet: grid-cols-2) (mobile: grid-cols-1)223 gap: gap-6 (24px)224 items:225 alignment: items-start226}227228ANIMATION (if applicable) {229 type: fade-up on scroll230 trigger: when section enters viewport (threshold: 0.2)231 stagger: each child delays 100ms after previous232 duration: duration-500233 easing: ease-out234 runs: once (do not re-trigger on scroll up)235}236```237238---239240### SECTION 4: COMPONENT SPECIFICATIONS241242For each component, provide a complete implementation contract.243244#### Component:245**File:** `src/components//.tsx`246**Purpose:** [one sentence — what this component does]247248##### Props Interface249```typescript250interface Props {251 variant: 'primary' | 'secondary' | 'ghost' // visual style252 size: 'sm' | 'md' | 'lg' // dimensions253 disabled?: boolean // default: false254 loading?: boolean // default: false255 icon?: React.ReactNode // optional leading icon256 children: React.ReactNode // label content257 onClick?: () => void // click handler258}259```260261##### Variant × Size Matrix262Define exact values for every combination:263264```265VARIANT: primary266 SIZE: sm267 height: h-8 (32px)268 padding: px-3 (12px)269 font: text-sm font-medium (14px)270 background: bg-brand-500 (#2563EB)271 text: text-white (#FFFFFF)272 border: none273 border-radius: rounded-md (6px)274 shadow: none275276 SIZE: md277 height: h-10 (40px)278 padding: px-4 (16px)279 font: text-sm font-medium (14px)280 background: bg-brand-500 (#2563EB)281 text: text-white (#FFFFFF)282 border: none283 border-radius: rounded-lg (8px)284 shadow: shadow-sm285286 SIZE: lg287 height: h-12 (48px)288 padding: px-6 (24px)289 font: text-base font-semibold (16px)290 background: bg-brand-500 (#2563EB)291 text: text-white (#FFFFFF)292 border: none293 border-radius: rounded-lg (8px)294 shadow: shadow-sm295296VARIANT: secondary297 [same structure, different values]298299VARIANT: ghost300 [same structure, different values]301```302303##### State Specifications304Every state must be defined for every variant:305306```307STATES (apply to ALL variants unless overridden):308309 hover {310 background: — darken one step from default311 transform: none (no scale/translate on hover)312 shadow:313 cursor: pointer314 transition: default (duration-200 ease-out)315 }316317 active {318 background: — darken two steps from default319 transform: scale-[0.98]320 transition: duration-75321 }322323 focus-visible {324 ring: ring-2 ring-offset-2 ring-brand-500325 all other: same as default state326 }327328 disabled {329 opacity: opacity-50330 cursor: not-allowed331 pointer-events: none332 ALL hover/active/focus states: do not apply333 }334335 loading {336 content: replace children with spinner (16px, animate-spin)337 width: maintain same width as non-loading state (prevent layout shift)338 pointer-events: none339 opacity: opacity-80340 }341```342343##### Icon Behavior344```345ICON RULES {346 position: left of label text (always)347 size: 16px (sm), 16px (md), 20px (lg)348 gap: gap-1.5 (sm), gap-2 (md), gap-2 (lg)349 color: inherits text color (currentColor)350 when loading: icon is hidden, spinner takes its position351 icon-only: if no children, component becomes square (width = height)352 add aria-label prop requirement353}354```355356---357358### SECTION 5: INTERACTION FLOWS359360For each user flow, provide step-by-step implementation:361362#### Flow: [Flow Name, e.g., "User Signs Up"]363```364TRIGGER: user clicks "Sign Up" button in header365366STEP 1: Modal opens367 animation: fade-in (opacity 0→1, duration-200)368 backdrop: bg-black/50, click-outside closes modal369 focus: trap focus inside modal, auto-focus first input370 body: scroll-lock (prevent background scroll)371372STEP 2: User fills form373 fields:374 validation: on blur (not on change — reduces noise)375376 field: email {377 type: email378 required: true379 validate: regex pattern + "must contain @ and domain"380 error: "That doesn't look like an email — check for typos"381 success: green checkmark icon appears (fade-in, duration-150)382 }383384 field: password {385 type: password (with show/hide toggle)386 required: true387 validate: min 8 chars, 1 uppercase, 1 number388 error: show checklist of requirements, highlight unmet389 strength: show strength bar (weak/medium/strong)390 }391392STEP 3: User submits393 button: shows loading state (see Button component spec)394 request: POST /api/auth/signup395 duration: expect 1-3 seconds396397STEP 4a: Success398 modal: content transitions to success message (crossfade, duration-200)399 message: "Account created! Check your email to verify."400 action: "Got it" button closes modal401 redirect: after close, redirect to /dashboard402 toast: none (the modal IS the confirmation)403404STEP 4b: Error — email exists405 field: email input shows error state406 message: "This email already has an account — want to log in instead?"407 action: "Log in" link switches modal to login form408 button: returns to default state (not loading)409410STEP 4c: Error — network failure411 display: error banner at top of modal (not a toast)412 message: "Something went wrong on our end. Try again?"413 action: "Try again" button re-submits414 button: returns to default state415416STEP 4d: Error — rate limited417 display: error banner418 message: "Too many attempts. Wait 60 seconds and try again."419 button: disabled for 60 seconds with countdown visible420```421422---423424### SECTION 6: RESPONSIVE BEHAVIOR RULES425426Don't describe what changes — specify the exact rules:427428```429RESPONSIVE RULES:430431Rule 1: Navigation432 ≥1024px: horizontal nav, all items visible433 <1024px: hamburger icon, slide-in drawer from right434 drawer-width: 80vw (max-w-[320px])435 animation: translate-x (duration-300 ease-out)436 backdrop: bg-black/50, click-outside closes437438Rule 2: Grid Sections439 ≥1024px: grid-cols-3440 768-1023px: grid-cols-2 (last item spans full if odd count)441 <768px: grid-cols-1442443Rule 3: Hero Section444 ≥1024px: two-column (text left, image right) — 55/45 split445 <1024px: single column (text top, image bottom)446 image max-height: 400px, object-cover447448Rule 4: Typography Scaling449 ≥1024px: h1=text-5xl, h2=text-3xl, h3=text-xl, body=text-base450 <1024px: h1=text-3xl, h2=text-2xl, h3=text-lg, body=text-base451452Rule 5: Spacing Scaling453 ≥1024px: section-padding: py-16, container-padding: px-8454 768-1023px: section-padding: py-12, container-padding: px-6455 <768px: section-padding: py-10, container-padding: px-4456457Rule 6: Touch Targets458 <1024px: all interactive elements minimum 44×44px hit area459 if visual size < 44px, use invisible padding to reach 44px460461Rule 7: Images462 all images: use next/image with responsive sizes prop463 hero: sizes="(max-width: 1024px) 100vw, 50vw"464 grid items: sizes="(max-width: 768px) 100vw, (max-width: 1024px) 50vw, 33vw"465```466467---468469### SECTION 7: EDGE CASES & BOUNDARY CONDITIONS470471This section prevents the "but what happens when..." problems:472473```474EDGE CASES:475476Text Overflow {477 headings: max 2 lines, then truncate with text-ellipsis (add title attr for full text)478 body text: allow natural wrapping, no truncation479 button labels: single line only, max 30 characters, no truncation (design constraint)480 nav items: single line, truncate if >16 characters on mobile481 table cells: truncate with tooltip on hover482}483484Empty States {485 lists/grids with 0 items: show component486 - illustration:487 - heading: ""488 - body: ""489 - CTA: "" →490491 user avatar missing: show initials on colored background492 - background: generate from user name hash (deterministic)493 - initials: first letter of first + last name, uppercase494 - font: text-sm font-medium text-white495496 image fails to load: show gray placeholder with image icon497 - background: bg-gray-100498 - icon: ImageOff from lucide-react, text-gray-400, 24px499}500501Loading States {502 page load: full-page skeleton (not spinner)503 component load: component-level skeleton matching final dimensions504 button action: inline spinner in button (see Button spec)505 infinite list: skeleton row × 3 at bottom while fetching next page506507 skeleton style: bg-gray-200 rounded animate-pulse508 skeleton rule: skeleton shape must match final content shape509 (rectangle for text, circle for avatars, rounded-lg for cards)510}511512Error States {513 API error (500): show inline error banner with retry button514 Network error: show "You seem offline" banner at top (auto-dismiss when reconnected)515 404 content: show custom 404 component (not Next.js default)516 Permission denied: redirect to /login with return URL param517 Form validation: inline per-field (see flow specs), never alert()518}519520Data Extremes {521 username 1 character: display normally522 username 50 characters: truncate at 20 in nav, full in profile523 price $0.00: show "Free"524 price $999,999.99: ensure layout doesn't break (test with formatted number)525 list with 1 item: same layout as multiple (no special case)526 list with 500 items: paginate at 20, show "Load more" button527 date today: show "Today" not the date528 date this year: show "Mar 13" not "Mar 13, 2026"529 date other year: show "Mar 13, 2025"530}531```532533---534535### SECTION 8: IMPLEMENTATION VERIFICATION CHECKLIST536537After implementation, the AI agent (or human developer) should verify:538539```540VERIFICATION:541542□ Every component matches the variant × size matrix exactly543□ Every state (hover, active, focus, disabled, loading) works544□ Tab order follows visual order on all pages545□ Focus-visible ring appears on keyboard nav, not on mouse click546□ All transitions use specified duration and easing (not browser default)547□ No layout shift during page load (check CLS)548□ Skeleton states match final content dimensions549□ All edge cases from Section 7 are handled550□ Touch targets ≥ 44×44px on mobile breakpoints551□ No horizontal scroll at any breakpoint552□ All images use next/image with correct sizes prop553□ Z-index values only use the defined scale554□ Error states display correctly (test with network throttle)555□ Empty states display correctly (test with empty data)556□ Text truncation works at boundary lengths557□ Dark mode tokens (if applicable) are all mapped558```559560---561562## How the AI Agent Should Use This Document563564Include this instruction at the top of the generated handoff document565so the implementing AI knows how to work with it:566567```568INSTRUCTIONS FOR AI IMPLEMENTATION AGENT:5695701. Read this document fully before writing any code.5712. Implement in the order specified in SECTION 1 (Implementation Map).5723. Reference CLAUDE.md for token values. If a token referenced here573 is not in CLAUDE.md, flag it and use the fallback value provided.5744. Every value in this document is intentional. Do not substitute575 with "close enough" values. `gap-6` means `gap-6`, not `gap-5`.5765. Every state must be implemented. If a state is not specified for577 a component, that is a gap in the spec — flag it, do not guess.5786. After implementing each component, run through its state matrix579 and verify all states work before moving to the next component.5807. When encountering ambiguity, prefer the more explicit interpretation.581 If still ambiguous, add a TODO comment: "// HANDOFF-AMBIGUITY: [description]"582```583```584585---586587## Customization Notes588589**If you're not using Tailwind:** Replace all Tailwind class references in the prompt with your system's equivalents. The structure stays the same — only the value format changes. Tell Claude: "Use CSS custom properties as primary, px values as annotations."590591**If you're handing off to a specific AI tool:** Add tool-specific notes. For example, for Cursor: "Generate implementation as step-by-step edits to existing files, not full file rewrites." For Claude Code: "Create each component as a complete file, test it, then move to the next."592593**If no CLAUDE.md exists yet:** Tell the prompt to generate a minimal token section at the top of the handoff document covering only the tokens needed for this specific handoff. It won't be a full design system, but it prevents hardcoded values.594595**For multi-page projects:** Run the prompt once per page, but include Section 1 (Implementation Map) and Section 2 (Global Specs) only in the first run. Subsequent pages reference the same globals.596
A prompt system for generating plain-language project documentation. This prompt generates a [FORME].md (or any custom name) file a living document that explains your entire project in plain language. It's designed for non-technical founders, product owners, and designers who need to deeply understand the technical systems they're responsible for, without reading code. The document doesn't dumb things down. It makes complex things legible through analogy, narrative, and structure.
HTWind widget creator system prompt