How to Turn an AI Website Design Into Production Code With Claude Code or Codex

Create a complete **developer handoff document** for the design you have created in this project.
 
The handoff will be given to an AI coding agent such as **OpenAI Codex or Claude Code inside VS Code**, which will be responsible for implementing the design as a production application.
 
Your job is NOT to redesign the interface and NOT to simplify it.
 
Your job is to inspect the design you created and document it precisely enough that another coding agent can reproduce it with extremely high visual fidelity.
 
Create a file named:
 
`DESIGN_HANDOFF.md`
 
## 1. Project Overview
 
Explain:
 
* What the interface/product is
* The purpose of the design
* Overall visual direction
* Major pages/screens
* Primary user flows represented by the design
* Important UX decisions that should be preserved
 
## 2. Design System
 
Document the complete visual system.
 
### Colors
 
For every color used, provide:
 
* HEX
* RGB if useful
* Intended usage
* Background colors
* Surface/card colors
* Text colors
* Muted text
* Borders/dividers
* Accent colors
* Hover colors
* Active/selected colors
* Success/warning/error colors if applicable
 
Use semantic names where possible, such as:
 
`--background`
`--surface`
`--foreground`
`--muted-foreground`
`--border`
`--primary`
`--primary-hover`
 
Do not approximate colors if the exact values are available.
 
### Typography
 
Document:
 
* Font families
* Font weights
* Font sizes
* Line heights
* Letter spacing
* Heading hierarchy
* Body text
* Labels
* Navigation text
* Buttons
* Captions
* Any monospace usage
 
Explain which typography treatment belongs to which UI element.
 
### Spacing
 
Document the spacing system used throughout the design.
 
Include:
 
* Page margins
* Container widths
* Section spacing
* Card padding
* Component gaps
* Navigation spacing
* Form spacing
* Grid gaps
 
Identify reusable spacing values/tokens rather than describing everything vaguely as "small," "medium," or "large."
 
### Borders and Shape
 
Document:
 
* Border widths
* Border colors
* Border radius values
* Card radius
* Button radius
* Input radius
* Pill/badge radius
* Dividers
* Shadows
* Blur effects
* Transparency
 
## 3. Layout Architecture
 
Explain how the overall interface should be structured.
 
For example:
 
* Application shell
* Header
* Sidebar
* Main content area
* Secondary panels
* Footer
* Drawers
* Modals
* Overlays
 
Specify:
 
* Fixed vs sticky vs normal positioning
* Maximum widths
* Full-width regions
* Grid structure
* Flex behavior
* Alignment rules
* Vertical and horizontal spacing
* Scrolling behavior
* Overflow behavior
 
Do not merely describe what the layout looks like. Explain how it should behave.
 
## 4. Responsive Behavior
 
Document the expected behavior for:
 
* Large desktop
* Desktop
* Tablet
* Mobile
 
Include appropriate breakpoints if they can be determined from the design.
 
For each major component explain:
 
* What resizes
* What wraps
* What stacks
* What collapses
* What disappears
* What becomes a drawer
* What becomes horizontally scrollable
* How padding changes
* How typography changes
* How navigation behaves
 
The coding agent should not have to invent the mobile behavior.
 
## 5. Component Inventory
 
Identify every reusable UI component in the design.
 
Examples may include:
 
* Header
* Sidebar
* Navigation item
* Breadcrumb
* Button
* Icon button
* Card
* Input
* Select
* Search field
* Tabs
* Dropdown
* Badge
* Table
* Modal
* Drawer
* Tooltip
* Toast
* Pagination
* Empty state
* Loading state
 
For every component document:
 
### Purpose
 
What the component does.
 
### Anatomy
 
What elements make up the component.
 
### Variants
 
Different versions of the component.
 
### States
 
Document applicable states such as:
 
* Default
* Hover
* Focus
* Active
* Selected
* Disabled
* Loading
* Error
* Empty
 
### Dimensions
 
Provide important:
 
* Heights
* Widths
* Padding
* Gaps
* Border radius
* Icon sizing
 
### Behavior
 
Explain interactions and transitions.
 
## 6. Page-by-Page Specifications
 
Create a section for EVERY screen/page represented in the design.
 
For each page document:
 
### Route / Suggested Route
 
If appropriate, recommend a logical URL route.
 
### Purpose
 
Explain what the page is for.
 
### Structure
 
Describe the page hierarchy from top to bottom.
 
### Components Used
 
Identify reusable components rather than treating everything as page-specific markup.
 
### Exact Layout
 
Describe:
 
* Containers
* Columns
* Alignment
* Padding
* Gaps
* Section dimensions
* Card arrangements
* Grid behavior
 
### Interactions
 
Explain:
 
* Buttons
* Menus
* Tabs
* Forms
* Expand/collapse behavior
* Navigation
* Modals
* Drawers
* Hover behavior
 
### Responsive Behavior
 
Explain exactly how this page changes across screen sizes.
 
## 7. Navigation and Routing
 
Document:
 
* Main navigation
* Secondary navigation
* Sidebar navigation
* Breadcrumb behavior
* Active navigation states
* Expected routes
* Back-navigation behavior where applicable
* Mobile navigation behavior
 
## 8. Icons and Assets
 
Inventory the visual assets used.
 
Include:
 
* Logos
* Icons
* Illustrations
* Images
* Background graphics
* Decorative assets
 
For icons, identify the icon library if one was used or recommend the closest appropriate library.
 
Do NOT substitute emoji for interface icons.
 
If custom assets exist, provide their filenames or explain what assets the implementation agent will need.
 
## 9. Interaction and Motion
 
Document any:
 
* Hover transitions
* Button transitions
* Menu animations
* Drawer animations
* Modal animations
* Loading animations
* Expand/collapse behavior
* Micro-interactions
 
Provide approximate timing and easing when identifiable.
 
Avoid unnecessary animation that isn't represented by the design.
 
## 10. Accessibility Requirements
 
Identify implementation requirements including:
 
* Semantic HTML
* Keyboard navigation
* Focus states
* Form labels
* ARIA requirements where appropriate
* Color contrast
* Accessible modal behavior
* Accessible navigation
* Screen-reader considerations
 
Do not sacrifice accessibility merely to reproduce the visual design.
 
## 11. Suggested Component Architecture
 
Based on the design, propose a sensible reusable component hierarchy for implementation.
 
Example:
 
```text
AppShell
├── Header
├── Sidebar
│   └── NavigationItem
└── MainContent
    ├── PageHeader
    ├── ContentSection
    └── CardGrid
        └── Card
```
 
Avoid unnecessary component fragmentation.
 
Identify which components should be:
 
* Global
* Layout-level
* Reusable
* Page-specific
 
## 12. Design Tokens
 
At the end, provide a consolidated token reference that the coding agent can translate into CSS variables, Tailwind configuration, or another styling system.
 
Include tokens for:
 
* Colors
* Typography
* Spacing
* Radius
* Borders
* Shadows
* Container widths
* Breakpoints
* Z-index layers where applicable
 
## 13. Implementation Constraints
 
Create a section called:
 
`NON-NEGOTIABLE DESIGN REQUIREMENTS`
 
List the design characteristics that the coding agent MUST preserve.
 
This should include anything that could easily be accidentally changed during implementation, such as:
 
* Overall visual hierarchy
* Navigation structure
* Container dimensions
* Sidebar proportions
* Header dimensions
* Typography hierarchy
* Spacing rhythm
* Border treatment
* Card treatment
* Responsive behavior
* Important interaction patterns
 
## 14. Ambiguities / Decisions Needed
 
If something cannot be determined confidently from the design, DO NOT invent a specification.
 
Instead create a section:
 
`AMBIGUITIES / IMPLEMENTATION DECISIONS`
 
Clearly identify:
 
1. What is ambiguous
2. What can be observed from the design
3. What decision the implementation agent will need to make
4. Your recommended implementation, if appropriate
 
## 15. Visual Fidelity Checklist
 
Finish the document with a checklist the coding agent can use after implementation.
 
Include checks for:
 
* Layout fidelity
* Typography
* Colors
* Spacing
* Borders
* Radius
* Icons
* Desktop responsiveness
* Tablet responsiveness
* Mobile responsiveness
* Hover states
* Focus states
* Navigation
* Forms
* Empty/loading/error states
* Accessibility
 
# IMPORTANT HANDOFF RULES
 
This document is intended to act as the **source of truth for implementation**.
 
Therefore:
 
* Be precise.
* Use actual measurements and values whenever available.
* Do not use vague descriptions when exact specifications can be determined.
* Do not redesign anything.
* Do not "improve" the design unless an issue is explicitly documented as a recommendation.
* Preserve the existing visual language.
* Distinguish observed design facts from your implementation recommendations.
* Do not assume the implementation agent has access to this design or this conversation.
* The handoff must be completely understandable as a standalone document.
* Include every screen represented in the project.
* Document responsive behavior instead of leaving it for the developer to guess.
* Prefer reusable components and design tokens over duplicated page-specific styling.
* Do not generate the production application itself.
* Do not omit details because they seem obvious.
 
Before completing the handoff, systematically inspect the entire design and make sure every major page, component, state, layout pattern, and responsive behavior represented in the project has been documented.

You are acting as a **senior software engineer responsible for implementing an approved UI/UX design into a production-quality codebase**.
 
A design handoff file named:
 
`DESIGN_HANDOFF.md`
 
has been provided.
 
Your job is to inspect the existing project, read the complete handoff, understand the application's existing architecture, and implement the design accurately without introducing unnecessary technical debt.
 
The goal is not merely to make the application "look like" the design.
 
The goal is to implement the design with:
 
* High visual fidelity
* Clean architecture
* Maintainable code
* Reusable components
* Proper separation of concerns
* Responsive behavior
* Accessibility
* Security
* Performance
* Compatibility with the existing project
* Production-quality engineering practices
 
# PHASE 1 — INSPECT BEFORE CODING
 
Before modifying any files:
 
1. Read `DESIGN_HANDOFF.md` completely.
2. Inspect the existing project structure.
3. Identify the framework, language, styling system, build system, dependencies, and architectural conventions already in use.
4. Identify existing reusable components, utilities, layouts, styles, design tokens, and functionality that should be preserved.
5. Identify the pages/routes affected by the handoff.
6. Identify any potential conflicts between the handoff and the existing architecture.
7. Determine the cleanest implementation strategy.
 
Do NOT immediately start rewriting files.
 
Do NOT assume the application architecture based solely on the handoff.
 
The existing codebase must be inspected first.
 
# PHASE 2 — CREATE AN IMPLEMENTATION PLAN
 
Before implementation, formulate a concise implementation plan covering:
 
* Files that need to be created
* Files that need to be modified
* Components that should be created or reused
* Styling changes
* JavaScript/TypeScript changes
* Routes/pages affected
* Responsive implementation
* Accessibility considerations
* Existing functionality that must remain intact
 
Prefer modifying and extending the existing architecture over replacing working systems unnecessarily.
 
# PHASE 3 — IMPLEMENT THE DESIGN
 
Implement the specifications in `DESIGN_HANDOFF.md` as faithfully as reasonably possible.
 
Treat the handoff as the primary design specification.
 
Preserve:
 
* Layout hierarchy
* Typography
* Colors
* Spacing
* Container dimensions
* Navigation
* Component proportions
* Borders
* Border radius
* Icons
* Responsive behavior
* Interactive states
* Visual hierarchy
 
Do not redesign the interface.
 
Do not arbitrarily "improve" the design.
 
If something is genuinely ambiguous, choose the implementation that best matches:
 
1. The handoff
2. Existing project conventions
3. Established UX patterns
4. Accessibility requirements
5. Maintainability
 
# CODE QUALITY REQUIREMENTS
 
Write code as if it will be maintained for years by a professional development team.
 
The implementation must be:
 
* Readable
* Modular
* Maintainable
* Consistent
* Reusable
* Secure
* Well organized
 
Avoid:
 
* Quick hacks
* Temporary workarounds
* Duplicate logic
* Duplicate styling
* Excessive abstraction
* Giant monolithic files
* Unnecessary dependencies
* Dead code
* Commented-out obsolete code
* Unexplained magic values
* Fragile selectors
* Unnecessary specificity
* Copy/pasted components
 
Follow the conventions of the existing codebase whenever those conventions represent sound engineering practices.
 
# SEPARATION OF CONCERNS
 
Maintain clear separation between:
 
* Structure
* Presentation
* Behavior
* Data
* Business logic
 
Do NOT mix unrelated responsibilities simply because doing so is faster.
 
For traditional HTML, PHP, WordPress, or similar projects:
 
* Keep CSS in appropriate stylesheet files.
* Keep JavaScript in appropriate JavaScript files.
* Keep reusable PHP/application logic in appropriate modules, classes, functions, templates, or components.
* Avoid embedding large CSS or JavaScript blocks directly inside templates.
 
For component-based frameworks such as React, Next.js, Vue, Svelte, or similar systems:
 
Follow the framework's established architecture and the conventions already present in the project.
 
Do NOT force a traditional `style.css` / `script.js` architecture onto a framework where that would be inappropriate.
 
The objective is **proper separation of concerns for the technology being used**, not separation merely for its own sake.
 
# CSS / STYLING STANDARDS
 
Do NOT use inline CSS such as:
 
```html
<div style="margin-top: 20px; color: #fff;">
```
 
unless there is a legitimate technical reason that cannot reasonably be handled through the project's styling architecture.
 
Use the project's established styling system where appropriate, such as:
 
* CSS
* CSS Modules
* SCSS
* Tailwind CSS
* Design tokens
* Component styling systems already established by the project
 
Prefer reusable classes, variables, tokens, and components.
 
Centralize repeated design values.
 
For example, recurring values such as:
 
* Colors
* Spacing
* Border radius
* Shadows
* Container widths
* Typography
* Breakpoints
 
should use the project's design-token system or CSS variables where appropriate.
 
Example:
 
```css
:root {
  --color-background: #ffffff;
  --color-foreground: #111111;
  --color-border: #e5e5e5;
 
  --radius-sm: 4px;
  --radius-md: 8px;
 
  --space-sm: 0.5rem;
  --space-md: 1rem;
  --space-lg: 1.5rem;
}
```
 
Do not create dozens of arbitrary one-off values when the design clearly uses a consistent system.
 
# JAVASCRIPT / TYPESCRIPT STANDARDS
 
Keep client-side behavior organized and maintainable.
 
For traditional projects, place JavaScript in appropriate external files rather than embedding large scripts directly into templates.
 
For framework-based applications, follow the framework's component/module architecture.
 
Avoid:
 
* Global namespace pollution
* Duplicate event listeners
* Unnecessary DOM manipulation
* Large inline scripts
* Hardcoded application state
* Unnecessary client-side JavaScript
* Functions with multiple unrelated responsibilities
 
Prefer small, clearly named functions and modules.
 
If TypeScript is already being used, maintain proper typing and avoid unnecessary use of `any`.
 
# COMPONENT ARCHITECTURE
 
Identify repeated UI patterns and implement them as reusable components where appropriate.
 
Examples include:
 
* Buttons
* Navigation items
* Cards
* Inputs
* Modals
* Dropdowns
* Headers
* Sidebars
* Page headers
* Tables
* Badges
* Alerts
* Empty states
 
However, do NOT over-engineer the project by turning every small piece of markup into its own component.
 
Create abstractions when they improve:
 
* Reuse
* Consistency
* Readability
* Maintainability
 
# RESPONSIVE DESIGN
 
Implement the responsive behavior defined in `DESIGN_HANDOFF.md`.
 
The interface must work properly across:
 
* Large desktop
* Desktop
* Tablet
* Mobile
 
Do not implement desktop only and treat mobile responsiveness as an afterthought.
 
Verify:
 
* Navigation
* Sidebars
* Grids
* Cards
* Tables
* Forms
* Typography
* Images
* Modals
* Drawers
* Overflow
* Touch targets
 
Avoid horizontal page scrolling unless explicitly required by the design.
 
# ACCESSIBILITY
 
Implement accessible UI patterns.
 
Use:
 
* Semantic HTML
* Proper heading hierarchy
* Accessible form labels
* Keyboard navigation
* Visible focus states
* Appropriate ARIA attributes where necessary
* Accessible modal/dialog behavior
* Appropriate button and link semantics
* Alternative text for meaningful images
 
Do not use clickable `<div>` elements when a semantic `<button>` or `<a>` is appropriate.
 
Accessibility should be built into the implementation rather than patched in afterward.
 
# SECURITY
 
Do not weaken existing security controls to implement the design.
 
Follow appropriate security practices for the detected technology.
 
Examples include:
 
* Escape output where required
* Sanitize untrusted input
* Validate data
* Protect privileged operations
* Respect authentication and authorization boundaries
* Avoid exposing secrets
* Avoid placing credentials or API keys in client-side code
* Preserve CSRF protections where applicable
* Do not introduce unsafe HTML rendering unnecessarily
 
Never hardcode credentials, secrets, tokens, passwords, or private keys.
 
# WORDPRESS-SPECIFIC REQUIREMENTS
 
If this project is WordPress, follow professional WordPress development standards.
 
Use WordPress APIs instead of reinventing functionality that WordPress already provides.
 
Where applicable:
 
* Properly enqueue CSS with `wp_enqueue_style()`
* Properly enqueue JavaScript with `wp_enqueue_script()`
* Use appropriate hooks and filters
* Escape output
* Sanitize input
* Validate data
* Use nonces for protected actions
* Perform capability checks
* Use appropriate template hierarchy
* Keep reusable logic out of presentation templates
* Avoid unnecessary global variables
* Avoid directly modifying WordPress core
* Avoid directly modifying third-party plugins
* Avoid directly modifying parent themes when a child theme or extension architecture is appropriate
 
Do not place large `<style>` or `<script>` blocks throughout PHP templates.
 
JavaScript should normally live in dedicated JS files and CSS should normally live in dedicated stylesheets unless the project's established architecture provides a better standards-compliant mechanism.
 
# PERFORMANCE
 
Avoid unnecessary performance regressions.
 
Consider:
 
* Bundle size
* Image optimization
* Font loading
* JavaScript execution
* Rendering behavior
* Database queries
* API calls
* Repeated computations
* Caching
* Lazy loading where appropriate
 
Do not add a large dependency to solve a trivial problem.
 
# PRESERVE EXISTING FUNCTIONALITY
 
This is critical.
 
Do NOT break working application behavior while implementing the new design.
 
Preserve:
 
* Existing routes
* Authentication
* Forms
* API integrations
* Database operations
* User permissions
* Existing business logic
* SEO metadata
* Analytics
* Accessibility features
* Existing security controls
 
If a visual implementation conflicts with important existing functionality, preserve the functionality and adapt the presentation cleanly.
 
# DO NOT MODIFY UNRELATED CODE
 
Keep the implementation scope focused.
 
Do not:
 
* Refactor unrelated systems
* Rename unrelated files
* Change unrelated APIs
* Rewrite working modules without justification
* Replace dependencies unnecessarily
* Change database schemas unless required
* Modify infrastructure unless required
 
Avoid turning a design implementation into an unrelated application rewrite.
 
# COMMENTS AND DOCUMENTATION
 
Code should generally explain itself through:
 
* Good naming
* Clear structure
* Small focused functions
* Appropriate abstractions
 
Add comments when they explain **why** something exists or document behavior that would not otherwise be obvious.
 
Avoid comments that merely repeat what the code already says.
 
# VALIDATION
 
After implementation, validate the work.
 
Where supported by the project, run appropriate:
 
* Build
* Type checking
* Linting
* Tests
* Unit tests
* Integration tests
 
Resolve errors introduced by your changes.
 
Do not silence legitimate warnings merely to make validation appear successful.
 
# VISUAL QA
 
After implementation, compare the result against `DESIGN_HANDOFF.md` and any supplied design references or screenshots.
 
Review:
 
* Overall layout
* Widths
* Heights
* Alignment
* Typography
* Font weights
* Colors
* Spacing
* Borders
* Radius
* Shadows
* Icons
* Navigation
* Forms
* Interactive states
* Desktop behavior
* Tablet behavior
* Mobile behavior
 
Do not consider the task complete merely because the application builds successfully.
 
**A successful build does not prove visual accuracy.**
 
# FINAL CODE REVIEW
 
Before declaring the implementation complete, review your own changes as if you were the senior engineer reviewing a pull request.
 
Look specifically for:
 
* Duplicate code
* Inline styling
* Hardcoded repeated values
* Oversized components
* Poor naming
* Dead code
* Unused imports
* Unnecessary dependencies
* Accessibility problems
* Security regressions
* Responsive issues
* Inconsistent styling
* Broken existing behavior
* Temporary hacks
* Debugging code
* Console errors
* Build warnings
 
Clean these issues up before finishing.
 
# FINAL REPORT
 
When implementation is complete, provide a concise report containing:
 
## Implemented
 
Summarize what was implemented.
 
## Files Changed
 
List the important files created or modified and their purpose.
 
## Validation
 
Report which builds, tests, linting, type checks, or other validations were run and their results.
 
## Visual QA
 
Describe how the implementation was checked against the handoff.
 
## Remaining Issues
 
List any unresolved problems or discrepancies.
 
If there are none, explicitly state that no known issues remain.
 
## Manual Verification
 
Identify anything the user should manually verify, particularly behavior that could not be tested automatically.
 
# FINAL PRINCIPLE
 
Treat this as a production implementation, not a prototype.
 
Do not optimize for the fewest lines of code or the fastest possible implementation.
 
Optimize for:
 
**correctness, visual fidelity, maintainability, security, accessibility, performance, and long-term code quality.**