# Figma Handoff Rules

This file defines how Codex should translate Figma into code inside `shop-starter`.

## Purpose

The goal is not to blindly copy pixels.
The goal is to implement Figma with:
- visual fidelity
- reusable structure
- minimal client-side cost
- scalable section and component architecture

---

## 1. Always inspect the right frame

When a Figma task exists:
- prefer the exact frame link over the file root
- inspect the specific section being built
- do not rely on memory of previous screens

If the user provides only a broad file link:
- inspect the relevant node before coding

---

## 2. Translate sections into section components

A meaningful Figma section should usually become:
- one file in `components/sections/`
or
- one section wrapper plus a few reusable UI components

Do not:
- dump several unrelated sections into one route file
- inline large section trees into `app/page.tsx`

---

## 3. Repeated UI must become reusable UI

If Figma repeats elements like:
- product cards
- category cards
- buttons
- filter chips
- field rows
- stat badges
- summary rows

then implement them as reusable UI in `components/ui/` when appropriate.

Do not hardcode the same markup multiple times.

---

## 4. Preserve visual hierarchy

Keep:
- heading order
- section rhythm
- spacing hierarchy
- emphasis and contrast
- grouping of controls and content

Do not flatten a carefully layered Figma layout into generic stacked blocks.

---

## 5. Respect state design

If Figma shows or strongly implies states such as:
- hover
- focus
- active
- selected
- disabled
- loading
- empty
- no results
- sale
- out of stock

the implementation should support those states cleanly.

Do not implement only the ideal happy path.

---

## 6. Do not guess values when inspectable

Do not invent:
- colors
- spacing
- radii
- shadows
- type scales
- alignment behavior
- responsive shifts

If a value can be inspected in Figma, inspect it.

If it cannot be clearly determined:
- say what is unclear
- use the closest existing token only when appropriate

---

## 7. Keep the starter generic

When translating a design into the starter:
- keep it reusable
- avoid one-brand naming in component APIs
- avoid baking one project's content assumptions into the base

If a design has very brand-specific treatments:
- preserve the visual direction
- but keep code structure generic and adaptable

---

## 8. Server/client split must survive Figma work

Even if the design is detailed, do not forget architecture:
- static sections stay server-rendered
- only interactive slices become Client Components

Examples:
- product gallery controls can be client
- full product detail page should not become client
- archive filter drawer can be client
- archive page composition should remain server

---

## 9. Accessibility is part of fidelity

Faithful implementation also includes:
- semantic headings
- real buttons for interactive controls
- labels for form fields
- visible focus states
- alt text
- keyboard reachability

Do not treat accessibility as separate from design quality.

---

## 10. Review after implementation

After implementing a Figma task:
- compare hierarchy
- compare spacing rhythm
- compare states
- compare responsiveness
- check whether the component split still makes architectural sense

If the code matches Figma visually but the structure is wrong, the task is not done.