Keep design and code aligned
Carry intent between sketches, Figma, components, and the running product without a separate handoff phase.
Why this matters
Your Figma file compares structures fast. The running product answers harder questions: real content, waiting time (latency), resizing, and interaction. Keep them connected through explicit decisions rather than assuming one can generate the other.
You follow the decision into the product, updating the useful references as the work changes.
What to understand
Say you hand over tomorrow's assignments list. Ask your agent: "What does each element mean, how does it behave, and who owns the decision?"
Name things so someone can find the matching code or design. Do not force every decorative layer into a component or make every design variant a prop.
Watch for
- Recreating pixels without the task.
- A hex value carried across without its theme intent.
- A static frame treated as proof of sizing, focus order, or grid behavior.
- Dozens of happy-path frames instead of the key states.
- Competing copies of a decision with no agreed source of truth.
- A matching screenshot mistaken for settled semantics and data boundaries.
Strong default
Carry purpose, component identity, semantic role, sizing behavior, states, and source of truth — not just visuals. Tokens in code; flow rationale in the brief. Update the durable decision when building reveals a better answer.
When this doesn't apply
Not every layer deserves a component, and not every variant deserves a prop. Absolute positioning suits overlays or artwork; it breaks as a substitute for content flow. You don't need to keep abandoned explorations as a second spec.
In practice
| Carry across | Example | Why it matters |
|---|---|---|
| Purpose | "Compare unresolved requests" | Prevents recreating pixels without the task. |
| Component identity | RequestRow composes Badge and Button | Connects the design to existing behavior. |
| Semantic role | Muted text on a raised surface | Keeps theme intent beyond a hex value. |
| Sizing behavior | Content grows; actions wrap together | Describes what a static frame cannot prove. |
| States | Pending, rejected, no results, read-only | Makes build scope visible. |
| Source of truth | Tokens in code; flow rationale in the brief | Prevents competing copies of a decision. |
You set auto layout on a toolbar and it looks tidy. Now ask: what happens when space runs out? A toolbar wraps, a side panel moves below content, or a comparison table scrolls within its region.
Those choices still need browser checks. Auto layout does not decide meaningful HTML, focus order, or the correct grid implementation. Absolute positioning suits overlays or artwork; it breaks as a substitute for content flow.
Use realistic titles, long names, and missing images before polishing. For each important flow, show the key states rather than dozens of nearly identical happy-path frames.
When building reveals a better answer, update the durable decision and any design reference still used for review. You do not need to keep abandoned explorations as a second spec.
For example, a fixed-width status badge may look tidy in a mockup but truncate a translated label. Let the code wrap or enlarge it, then update the component guidance so the next screen inherits that choice.
Design-to-code tools can help with inspection and mapping. Verify generated components, token references, semantics, data boundaries, and responsive behavior yourself. A matching screenshot does not settle those agreements.
Include the affected route, before and after evidence, reason for the change, relevant states, and remaining uncertainty. Describe what you can see: "The action group wraps below the title without changing reading order."
Verify
Generated components, token references, semantics, data boundaries, and responsive behavior — checked in the browser, not just the mockup. Before and after evidence with the affected route, reason, states, and remaining uncertainty.
Related skills
Use $component for one component's contract, $system for shared conventions, and $craft to judge the rendered interface. Continue with component architecture.
Last updated on