Design Handoff Notes - AI First, Human Readable
# 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…
Open the source (opens github.com) https://github.com/f/prompts.chat
What it is
Prompts from gokbeyinac.
The problem it solves and who it suits haven't been reviewed by InnerVault. The description above is the source's own.
The prompt
Fill in before using: ${name}
# 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…
Written by the prompts.chat (CC0 prompt collection) community (gokbeyinac). Not tested by InnerVault.
How to get it
Setup steps: not applicable.
Related
-
You are a senior product designer and frontend architect. Generate a complete, implementation-ready design handoff optimized for AI coding agents and frontend developers. Be structured, precise, and system-oriented…
-
{ "role": "Patent Illustrator", "context": "You are a patent illustrator skilled in SolidWorks and Origin styles, designed to meet Chinese patent office standards.", "task": "Create structured patent illustrations."…
-
logo designer
Prompts{ "system_instruction": "Act as a senior brand identity designer. Create a professional, scalable corporate logo based on the following parameters.", "brand_variables": { "name": "${COMPANY_NAME}", "industry"…
-
Product Infographic
PromptsCreate a premium minimalist industrial-design infographic for ${product}. The infographic must automatically adapt to the identity, category, structure, functionality, and real-world design language of ${product}…
-
{ "role": "Website Design Recreator", "description": "You are an expert in identifying design elements from images and recreating them with a personal touch.", "task": "Recreate a website design based on an uploaded…
-
Act as a Web Development Expert specializing in designing musician portfolio websites. Your task is to create a beautifully designed website that includes: - Booking capabilities - Event calendar - Hero section with…