Design Handoff Notes - AI First, Human Readable

1# Design Handoff Notes — AI-First, Human-Readable
2
3### A structured handoff document optimized for AI implementation agents (Claude Code, Cursor, Copilot) while remaining clear for human developers
4
5---
6
7## About This Prompt
8
9**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.
10
11**The core philosophy:** If an AI reads this document and has to guess anything, the document has failed.
12
13**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.
14
15**Who reads this:**
16- Primary: AI coding agents (Claude Code, Cursor, Copilot, etc.)
17- Secondary: Human developers reviewing or debugging the AI's output
18- Tertiary: You (the designer), when checking if implementation matches intent
19
20**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.
21
22---
23
24## The Prompt
25
26```
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.
30
31Your writing must follow one absolute rule:
32**If the reader has to guess, infer, or assume anything, you have failed.**
33
34Every value must be explicit. Every state must be defined. Every edge case
35must have a rule. No "as appropriate," no "roughly," no "similar to."
36
37## Project Context
38- **Project:** name
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]
45
46## Output Format Rules
47
48Before writing any specs, follow these formatting rules exactly:
49
501. **Values are always code-ready.**
51   WRONG: "medium spacing"
52   RIGHT: `p-6` (24px)
53
542. **Colors are always token references + fallback hex.**
55   WRONG: "brand blue"
56   RIGHT: `text-brand-500` (#2563EB) — from CLAUDE.md tokens
57
583. **Sizes are always in the project's unit system.**
59   If Tailwind: use Tailwind classes as primary, px as annotation
60   If CSS: use rem as primary, px as annotation
61   WRONG: "make it bigger on desktop"
62   RIGHT: `text-lg` (18px) at ≥768px, `text-base` (16px) below
63
644. **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."
67
685. **File paths are explicit.**
69   WRONG: "create a button component"
70   RIGHT: "create `src/components/ui/Button.tsx`"
71
726. **Every visual property is stated, never inherited by assumption.**
73   Even if "obvious" — state it. AI agents don't have visual context.
74
75---
76
77## Document Structure
78
79Generate the handoff document with these sections:
80
81### SECTION 1: IMPLEMENTATION MAP
82
83A priority-ordered table of everything to build.
84AI agents should implement in this order to resolve dependencies correctly.
85
86| 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| ... | ... | ... | ... | ... | ... |
92
93Rules:
94- Nothing can reference a component that comes later in the table
95- Complexity = how many variants × states the component has
96- Notes = anything non-obvious about implementation
97
98---
99
100### SECTION 2: GLOBAL SPECIFICATIONS
101
102These apply everywhere. AI agent should configure these BEFORE building any components.
103
104#### 2.1 Breakpoints
105Define exact behavior boundaries:
106
107```
108BREAKPOINTS {
109  mobile:  0px    — 767px
110  tablet:  768px  — 1023px
111  desktop: 1024px — 1279px
112  wide:    1280px — ∞
113}
114```
115
116For each breakpoint, state:
117- Container max-width and padding
118- Base font size
119- Global spacing multiplier (if it changes)
120- Navigation mode (hamburger / horizontal / etc.)
121
122#### 2.2 Transition Defaults
123```
124TRANSITIONS {
125  default:    duration-200 ease-out
126  slow:       duration-300 ease-in-out
127  spring:     duration-500 cubic-bezier(0.34, 1.56, 0.64, 1)
128  none:       duration-0
129}
130
131RULE: Every interactive element uses `default` unless
132      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```
137
138#### 2.3 Z-Index Scale
139```
140Z-INDEX {
141  base:       0
142  dropdown:   10
143  sticky:     20
144  overlay:    30
145  modal:      40
146  toast:      50
147  tooltip:    60
148}
149
150RULE: No z-index value outside this scale. Ever.
151```
152
153#### 2.4 Focus Style
154```
155FOCUS {
156  style:      ring-2 ring-offset-2 ring-brand-500
157  applies-to: every interactive element (buttons, links, inputs, selects, checkboxes)
158  visible:    only on keyboard navigation (use focus-visible, not focus)
159}
160```
161
162---
163
164### SECTION 3: PAGE SPECIFICATIONS
165
166For each page, provide a complete implementation spec.
167
168#### Page: page_name
169**Route:** `/exact-route-path`
170**Layout:** which_layout_wrapper_to_use
171**Data requirements:** [what data this page needs, from where]
172
173##### Page Structure (top to bottom)
174
175```
176PAGE STRUCTURE: page_name
177├── Section: Hero
178│   ├── Component: Heading (h1)
179│   ├── Component: Subheading (p)
180│   ├── Component: CTA Button (primary, lg)
181│   └── Component: HeroImage
182├── Section: Features
183│   ├── Component: SectionHeading (h2)
184│   └── Component: FeatureCard × 3 (grid)
185├── Section: Testimonials
186│   └── Component: TestimonialSlider
187└── Section: CTA
188    ├── Component: Heading (h2)
189    └── Component: CTA Button (primary, lg)
190```
191
192##### Section-by-Section Specs
193
194For each section:
195
196**section_name**
197
198```
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-white
205}
206
207CONTENT {
208  heading {
209    text:       "exact_heading_text_or_content_source"
210    element:    h2
211    class:      text-3xl font-bold text-gray-900 (mobile: text-2xl)
212    max-width:  max-w-[640px]
213  }
214  body {
215    text:       "exact_body_text_or_content_source"
216    class:      text-lg text-gray-600 leading-relaxed (mobile: text-base)
217    max-width:  max-w-[540px]
218  }
219}
220
221GRID (if applicable) {
222  columns:      grid-cols-3 (tablet: grid-cols-2) (mobile: grid-cols-1)
223  gap:          gap-6 (24px)
224  items:        what_component_renders_in_each_cell
225  alignment:    items-start
226}
227
228ANIMATION (if applicable) {
229  type:         fade-up on scroll
230  trigger:      when section enters viewport (threshold: 0.2)
231  stagger:      each child delays 100ms after previous
232  duration:     duration-500
233  easing:       ease-out
234  runs:         once (do not re-trigger on scroll up)
235}
236```
237
238---
239
240### SECTION 4: COMPONENT SPECIFICATIONS
241
242For each component, provide a complete implementation contract.
243
244#### Component: componentname
245**File:** `src/components/path/componentname.tsx`
246**Purpose:** [one sentence — what this component does]
247
248##### Props Interface
249```typescript
250interface componentnameProps {
251  variant: 'primary' | 'secondary' | 'ghost'     // visual style
252  size: 'sm' | 'md' | 'lg'                        // dimensions
253  disabled?: boolean                                // default: false
254  loading?: boolean                                 // default: false
255  icon?: React.ReactNode                           // optional leading icon
256  children: React.ReactNode                         // label content
257  onClick?: () => void                              // click handler
258}
259```
260
261##### Variant × Size Matrix
262Define exact values for every combination:
263
264```
265VARIANT: primary
266  SIZE: sm
267    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:           none
273    border-radius:    rounded-md (6px)
274    shadow:           none
275
276  SIZE: md
277    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:           none
283    border-radius:    rounded-lg (8px)
284    shadow:           shadow-sm
285
286  SIZE: lg
287    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:           none
293    border-radius:    rounded-lg (8px)
294    shadow:           shadow-sm
295
296VARIANT: secondary
297  [same structure, different values]
298
299VARIANT: ghost
300  [same structure, different values]
301```
302
303##### State Specifications
304Every state must be defined for every variant:
305
306```
307STATES (apply to ALL variants unless overridden):
308
309  hover {
310    background:     token — darken one step from default
311    transform:      none (no scale/translate on hover)
312    shadow:         token_or_none
313    cursor:         pointer
314    transition:     default (duration-200 ease-out)
315  }
316
317  active {
318    background:     token — darken two steps from default
319    transform:      scale-[0.98]
320    transition:     duration-75
321  }
322
323  focus-visible {
324    ring:           ring-2 ring-offset-2 ring-brand-500
325    all other:      same as default state
326  }
327
328  disabled {
329    opacity:        opacity-50
330    cursor:         not-allowed
331    pointer-events: none
332    ALL hover/active/focus states: do not apply
333  }
334
335  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: none
339    opacity:        opacity-80
340  }
341```
342
343##### Icon Behavior
344```
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 position
351  icon-only:      if no children, component becomes square (width = height)
352                  add aria-label prop requirement
353}
354```
355
356---
357
358### SECTION 5: INTERACTION FLOWS
359
360For each user flow, provide step-by-step implementation:
361
362#### Flow: [Flow Name, e.g., "User Signs Up"]
363```
364TRIGGER:     user clicks "Sign Up" button in header
365
366STEP 1:      Modal opens
367             animation:   fade-in (opacity 0→1, duration-200)
368             backdrop:    bg-black/50, click-outside closes modal
369             focus:       trap focus inside modal, auto-focus first input
370             body:        scroll-lock (prevent background scroll)
371
372STEP 2:      User fills form
373             fields:      list_exact_fields_with_validation_rules
374             validation:  on blur (not on change — reduces noise)
375             
376             field: email {
377               type:       email
378               required:   true
379               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             }
383             
384             field: password {
385               type:       password (with show/hide toggle)
386               required:   true
387               validate:   min 8 chars, 1 uppercase, 1 number
388               error:      show checklist of requirements, highlight unmet
389               strength:   show strength bar (weak/medium/strong)
390             }
391
392STEP 3:      User submits
393             button:      shows loading state (see Button component spec)
394             request:     POST /api/auth/signup
395             duration:    expect 1-3 seconds
396
397STEP 4a:     Success
398             modal:       content transitions to success message (crossfade, duration-200)
399             message:     "Account created! Check your email to verify."
400             action:      "Got it" button closes modal
401             redirect:    after close, redirect to /dashboard
402             toast:       none (the modal IS the confirmation)
403
404STEP 4b:     Error — email exists
405             field:       email input shows error state
406             message:     "This email already has an account — want to log in instead?"
407             action:      "Log in" link switches modal to login form
408             button:      returns to default state (not loading)
409
410STEP 4c:     Error — network failure
411             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-submits
414             button:      returns to default state
415
416STEP 4d:     Error — rate limited
417             display:     error banner
418             message:     "Too many attempts. Wait 60 seconds and try again."
419             button:      disabled for 60 seconds with countdown visible
420```
421
422---
423
424### SECTION 6: RESPONSIVE BEHAVIOR RULES
425
426Don't describe what changes — specify the exact rules:
427
428```
429RESPONSIVE RULES:
430
431Rule 1: Navigation
432  ≥1024px:    horizontal nav, all items visible
433  <1024px:    hamburger icon, slide-in drawer from right
434              drawer-width: 80vw (max-w-[320px])
435              animation: translate-x (duration-300 ease-out)
436              backdrop: bg-black/50, click-outside closes
437
438Rule 2: Grid Sections
439  ≥1024px:    grid-cols-3
440  768-1023px: grid-cols-2 (last item spans full if odd count)
441  <768px:     grid-cols-1
442
443Rule 3: Hero Section
444  ≥1024px:    two-column (text left, image right) — 55/45 split
445  <1024px:    single column (text top, image bottom)
446              image max-height: 400px, object-cover
447
448Rule 4: Typography Scaling
449  ≥1024px:    h1=text-5xl, h2=text-3xl, h3=text-xl, body=text-base
450  <1024px:    h1=text-3xl, h2=text-2xl, h3=text-lg, body=text-base
451
452Rule 5: Spacing Scaling
453  ≥1024px:    section-padding: py-16, container-padding: px-8
454  768-1023px: section-padding: py-12, container-padding: px-6
455  <768px:     section-padding: py-10, container-padding: px-4
456
457Rule 6: Touch Targets
458  <1024px:    all interactive elements minimum 44×44px hit area
459              if visual size < 44px, use invisible padding to reach 44px
460
461Rule 7: Images
462  all images: use next/image with responsive sizes prop
463  hero:       sizes="(max-width: 1024px) 100vw, 50vw"
464  grid items: sizes="(max-width: 768px) 100vw, (max-width: 1024px) 50vw, 33vw"
465```
466
467---
468
469### SECTION 7: EDGE CASES & BOUNDARY CONDITIONS
470
471This section prevents the "but what happens when..." problems:
472
473```
474EDGE CASES:
475
476Text Overflow {
477  headings:     max 2 lines, then truncate with text-ellipsis (add title attr for full text)
478  body text:    allow natural wrapping, no truncation
479  button labels: single line only, max 30 characters, no truncation (design constraint)
480  nav items:    single line, truncate if >16 characters on mobile
481  table cells:  truncate with tooltip on hover
482}
483
484Empty States {
485  lists/grids with 0 items: show emptystate component
486    - illustration: describe_or_reference_asset
487    - heading: "exact_text"
488    - body: "exact_text"
489    - CTA: "exact_text" → action
490  
491  user avatar missing: show initials on colored background
492    - background: generate from user name hash (deterministic)
493    - initials: first letter of first + last name, uppercase
494    - font: text-sm font-medium text-white
495  
496  image fails to load: show gray placeholder with image icon
497    - background: bg-gray-100
498    - icon: ImageOff from lucide-react, text-gray-400, 24px
499}
500
501Loading States {
502  page load:      full-page skeleton (not spinner)
503  component load: component-level skeleton matching final dimensions
504  button action:  inline spinner in button (see Button spec)
505  infinite list:  skeleton row × 3 at bottom while fetching next page
506  
507  skeleton style: bg-gray-200 rounded animate-pulse
508  skeleton rule:  skeleton shape must match final content shape
509                  (rectangle for text, circle for avatars, rounded-lg for cards)
510}
511
512Error States {
513  API error (500):     show inline error banner with retry button
514  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 param
517  Form validation:     inline per-field (see flow specs), never alert()
518}
519
520Data Extremes {
521  username 1 character:   display normally
522  username 50 characters: truncate at 20 in nav, full in profile
523  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" button
527  date today:             show "Today" not the date
528  date this year:         show "Mar 13" not "Mar 13, 2026"
529  date other year:        show "Mar 13, 2025"
530}
531```
532
533---
534
535### SECTION 8: IMPLEMENTATION VERIFICATION CHECKLIST
536
537After implementation, the AI agent (or human developer) should verify:
538
539```
540VERIFICATION:
541
542□ Every component matches the variant × size matrix exactly
543□ Every state (hover, active, focus, disabled, loading) works
544□ Tab order follows visual order on all pages
545□ Focus-visible ring appears on keyboard nav, not on mouse click
546□ 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 dimensions
549□ All edge cases from Section 7 are handled
550□ Touch targets ≥ 44×44px on mobile breakpoints
551□ No horizontal scroll at any breakpoint
552□ All images use next/image with correct sizes prop
553□ Z-index values only use the defined scale
554□ Error states display correctly (test with network throttle)
555□ Empty states display correctly (test with empty data)
556□ Text truncation works at boundary lengths
557□ Dark mode tokens (if applicable) are all mapped
558```
559
560---
561
562## How the AI Agent Should Use This Document
563
564Include this instruction at the top of the generated handoff document
565so the implementing AI knows how to work with it:
566
567```
568INSTRUCTIONS FOR AI IMPLEMENTATION AGENT:
569
5701. 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 here
573   is not in CLAUDE.md, flag it and use the fallback value provided.
5744. Every value in this document is intentional. Do not substitute
575   with "close enough" values. `gap-6` means `gap-6`, not `gap-5`.
5765. Every state must be implemented. If a state is not specified for
577   a component, that is a gap in the spec — flag it, do not guess.
5786. After implementing each component, run through its state matrix
579   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```
584
585---
586
587## Customization Notes
588
589**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."
590
591**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."
592
593**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.
594
595**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