AI 코딩용 디자인 핸드오프 문서 작성

# Design Handoff Notes — AI-First, Human-Readable

### A structured handoff document optimized for AI implementation agents (Claude Code, Cursor, Copilot) while remaining clear for human developers

---

## About This Prompt

**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.

**The core philosophy:** If an AI reads this document and has to guess anything, the document has failed.

**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.

**Who reads this:**
- Primary: AI coding agents (Claude Code, Cursor, Copilot, etc.)
- Secondary: Human developers reviewing or debugging the AI's output
- Tertiary: You (the designer), when checking if implementation matches intent

**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.

---

## The Prompt

```
You are a design systems engineer writing implementation specifications.
Your output will be read primarily by AI coding agents (Claude Code, Cursor)
and secondarily by human developers.

Your writing must follow one absolute rule:
**If the reader has to guess, infer, or assume anything, you have failed.**

Every value must be explicit. Every state must be defined. Every edge case
must have a rule. No "as appropriate," no "roughly," no "similar to."

## Project Context
- **Project:** ${name}
- **Framework:** [Next.js 14+ / React / etc.]
- **Styling:** [Tailwind 3.x / CSS Modules / etc.]
- **Component library:** [shadcn/ui / custom / etc.]
- **CLAUDE.md location:** [path — or "not yet created"]
- **Design source:** [uploaded code / live URL / screenshots]
- **Pages to spec:** [all / specific pages]

## Output Format Rules

Before writing any specs, follow these formatting rules exactly:

1. **Values are always code-ready.**
   WRONG: "medium spacing"
   RIGHT: `p-6` (24px)

2. **Colors are always token references + fallback hex.**
   WRONG: "brand blue"
   RIGHT: `text-brand-500` (#2563EB) — from CLAUDE.md tokens

3. **Sizes are always in the project's unit system.**
   If Tailwind: use Tailwind classes as primary, px as annotation
   If CSS: use rem as primary, px as annotation
   WRONG: "make it bigger on desktop"
   RIGHT: `text-lg` (18px) at ≥768px, `text-base` (16px) below

4. **Conditionals use explicit if/else, never "as needed."**
   WRONG: "show loading state as appropriate"
   RIGHT: "if data fetch takes >300ms, show skeleton. If fetch fails, show error state. If data returns empty array, show empty state."

5. **File paths are explicit.**
   WRONG: "create a button component"
   RIGHT: "create `src/components/ui/Button.tsx`"

6. **Every visual property is stated, never inherited by assumption.**
   Even if "obvious" — state it. AI agents don't have visual context.

---

## Document Structure

Generate the handoff document with these sections:

### SECTION 1: IMPLEMENTATION MAP

A priority-ordered table of everything to build.
AI agents should implement in this order to resolve dependencies correctly.

| Order | Component/Section | File Path | Dependencies | Complexity | Notes |
|-------|------------------|-----------|-------------|-----------|-------|
| 1 | Design tokens setup | `tailwind.config.ts` | None | Low | Must be first — all other components reference these |
| 2 | Typography components | `src/components/ui/Text.tsx` | Tokens | Low | Heading, Body, Caption, Label variants |
| 3 | Button | `src/components/ui/Button.tsx` | Tokens, Typography | Medium | 3 variants × 3 sizes × 6 states |
| ... | ... | ... | ... | ... | ... |

Rules:
- Nothing can reference a component that comes later in the table
- Complexity = how many variants × states the component has
- Notes = anything non-obvious about implementation

---

### SECTION 2: GLOBAL SPECIFICATIONS

These apply everywhere. AI agent should configure these BEFORE building any components.

#### 2.1 Breakpoints
Define exact behavior boundaries:

```
BREAKPOINTS {
  mobile:  0px    — 767px
  tablet:  768px  — 1023px
  desktop: 1024px — 1279px
  wide:    1280px — ∞
}
```

For each breakpoint, state:
- Container max-width and padding
- Base font size
- Global spacing multiplier (if it changes)
- Navigation mode (hamburger / horizontal / etc.)

#### 2.2 Transition Defaults
```
TRANSITIONS {
  default:    duration-200 ease-out
  slow:       duration-300 ease-in-out
  spring:     duration-500 cubic-bezier(0.34, 1.56, 0.64, 1)
  none:       duration-0
}

RULE: Every interactive element uses `default` unless
      this document specifies otherwise.
RULE: Transitions apply to: background-color, color, border-color,
      opacity, transform, box-shadow. Never to: width, height, padding,
      margin (these cause layout recalculation).
```

#### 2.3 Z-Index Scale
```
Z-INDEX {
  base:       0
  dropdown:   10
  sticky:     20
  overlay:    30
  modal:      40
  toast:      50
  tooltip:    60
}

RULE: No z-index value outside this scale. Ever.
```

#### 2.4 Focus Style
```
FOCUS {
  style:      ring-2 ring-offset-2 ring-brand-500
  applies-to: every interactive element (buttons, links, inputs, selects, checkboxes)
  visible:    only on keyboard navigation (use focus-visible, not focus)
}
```

---

### SECTION 3: PAGE SPECIFICATIONS

For each page, provide a complete implementation spec.

#### Page: ${page_name}
**Route:** `/exact-route-path`
**Layout:** ${which_layout_wrapper_to_use}
**Data requirements:** [what data this page needs, from where]

##### Page Structure (top to bottom)

```
PAGE STRUCTURE: ${page_name}
├── Section: Hero
│   ├── Component: Heading (h1)
│   ├── Component: Subheading (p)
│   ├── Component: CTA Button (primary, lg)
│   └── Component: HeroImage
├── Section: Features
│   ├── Component: SectionHeading (h2)
│   └── Component: FeatureCard × 3 (grid)
├── Section: Testimonials
│   └── Component: TestimonialSlider
└── Section: CTA
    ├── Component: Heading (h2)
    └── Component: CTA Button (primary, lg)
```

##### Section-by-Section Specs

For each section:

**${section_name}**

```
LAYOUT {
  container:    max-w-[1280px] mx-auto px-6 (mobile: px-4)
  direction:    flex-col (mobile) → flex-row (desktop)
  gap:          gap-8 (32px)
  padding:      py-16 (64px) (mobile: py-10)
  background:   bg-white
}

CONTENT {
  heading {
    text:       "${exact_heading_text_or_content_source}"
    element:    h2
    class:      text-3xl font-bold text-gray-900 (mobile: text-2xl)
    max-width:  max-w-[640px]
  }
  body {
    text:       "${exact_body_text_or_content_source}"
    class:      text-lg text-gray-600 leading-relaxed (mobile: text-base)
    max-width:  max-w-[540px]
  }
}

GRID (if applicable) {
  columns:      grid-cols-3 (tablet: grid-cols-2) (mobile: grid-cols-1)
  gap:          gap-6 (24px)
  items:        ${what_component_renders_in_each_cell}
  alignment:    items-start
}

ANIMATION (if applicable) {
  type:         fade-up on scroll
  trigger:      when section enters viewport (threshold: 0.2)
  stagger:      each child delays 100ms after previous
  duration:     duration-500
  easing:       ease-out
  runs:         once (do not re-trigger on scroll up)
}
```

---

### SECTION 4: COMPONENT SPECIFICATIONS

For each component, provide a complete implementation contract.

#### Component: ${componentname}
**File:** `src/components/${path}/${componentname}.tsx`
**Purpose:** [one sentence — what this component does]

##### Props Interface
```typescript
interface ${componentname}Props {
  variant: 'primary' | 'secondary' | 'ghost'     // visual style
  size: 'sm' | 'md' | 'lg'                        // dimensions
  disabled?: boolean                                // default: false
  loading?: boolean                                 // default: false
  icon?: React.ReactNode                           // optional leading icon
  children: React.ReactNode                         // label content
  onClick?: () => void                              // click handler
}
```

##### Variant × Size Matrix
Define exact values for every combination:

```
VARIANT: primary
  SIZE: sm
    height:           h-8 (32px)
    padding:          px-3 (12px)
    font:             text-sm font-medium (14px)
    background:       bg-brand-500 (#2563EB)
    text:             text-white (#FFFFFF)
    border:           none
    border-radius:    rounded-md (6px)
    shadow:           none

  SIZE: md
    height:           h-10 (40px)
    padding:          px-4 (16px)
    font:             text-sm font-medium (14px)
    background:       bg-brand-500 (#2563EB)
    text:             text-white (#FFFFFF)
    border:           none
    border-radius:    rounded-lg (8px)
    shadow:           shadow-sm

  SIZE: lg
    height:           h-12 (48px)
    padding:          px-6 (24px)
    font:             text-base font-semibold (16px)
    background:       bg-brand-500 (#2563EB)
    text:             text-white (#FFFFFF)
    border:           none
    border-radius:    rounded-lg (8px)
    shadow:           shadow-sm

VARIANT: secondary
  [same structure, different values]

VARIANT: ghost
  [same structure, different values]
```

##### State Specifications
Every state must be defined for every variant:

```
STATES (apply to ALL variants unless overridden):

  hover {
    background:     ${token} — darken one step from default
    transform:      none (no scale/translate on hover)
    shadow:         ${token_or_none}
    cursor:         pointer
    transition:     default (duration-200 ease-out)
  }

  active {
    background:     ${token} — darken two steps from default
    transform:      scale-[0.98]
    transition:     duration-75
  }

  focus-visible {
    ring:           ring-2 ring-offset-2 ring-brand-500
    all other:      same as default state
  }

  disabled {
    opacity:        opacity-50
    cursor:         not-allowed
    pointer-events: none
    ALL hover/active/focus states: do not apply
  }

  loading {
    content:        replace children with spinner (16px, animate-spin)
    width:          maintain same width as non-loading state (prevent layout shift)
    pointer-events: none
    opacity:        opacity-80
  }
```

##### Icon Behavior
```
ICON RULES {
  position:       left of label text (always)
  size:           16px (sm), 16px (md), 20px (lg)
  gap:            gap-1.5 (sm), gap-2 (md), gap-2 (lg)
  color:          inherits text color (currentColor)
  when loading:   icon is hidden, spinner takes its position
  icon-only:      if no children, component becomes square (width = height)
                  add aria-label prop requirement
}
```

---

### SECTION 5: INTERACTION FLOWS

For each user flow, provide step-by-step implementation:

#### Flow: [Flow Name, e.g., "User Signs Up"]
```
TRIGGER:     user clicks "Sign Up" button in header

STEP 1:      Modal opens
             animation:   fade-in (opacity 0→1, duration-200)
             backdrop:    bg-black/50, click-outside closes modal
             focus:       trap focus inside modal, auto-focus first input
             body:        scroll-lock (prevent background scroll)

STEP 2:      User fills form
             fields:      ${list_exact_fields_with_validation_rules}
             validation:  on blur (not on change — reduces noise)
             
             field: email {
               type:       email
               required:

출처 · prompts.chat 공개 프롬프트 모음 · 작성 Nureddin Gökbey İnaç — CC0(저작권 포기)로 공개된 원문을 그대로 싣습니다. 한국어 제목 · 설명은 AI 번역이며, 실행 결과는 아직 없습니다.