# 1 · Read the design before you code
A front-end developer given a design doesn't start typing. They look at it
for a few minutes and ask: what are the pieces, which of them do we already
have, what is this layout trying to do, and what isn't shown? You start
writing the first element you see, then the next, top to bottom. That is how
one width gets copied pixel by pixel, and how one button becomes three.
Reading takes minutes. Rebuilding a page that was copied instead of read
takes hours.
---
### D1 · Name the parts before you write a line
**Rule:** Before writing code, list the parts of the design: each component
(button, card, field, list row, nav, dialog), how many times it appears, and
its variants (primary and secondary button, card with and without an image).
Things that look nearly the same are the same component unless the
difference means something. Write the list down, short, in your plan.
**Why:** The list is what keeps the page consistent. Without it, each
section gets its own button, and a person moving through the page sees
three slightly different buttons and wonders whether they do different
things. The next developer has to fix the same bug in three places.
**Agent trap:** building top to bottom, section by section, so the hero
button, the card button and the footer button are written separately, each
with its own padding. Or treating a 15px and a 16px gap in a mock-up as two
different values when the designer meant one.
**Check:** your plan has a parts list. Count the distinct visual types of
button, card and field in the design, then count their definitions in your
code after building. The numbers must match.
### D2 · Find the project's components and tokens first
**Rule:** For each part on your list, search the project for a component
that already does the job, and for the tokens (colours, spacing, type,
radius) the design's values map to. Use what exists. If a part nearly fits,
add a variant to the existing component, or say why you didn't. Only build
new what the project truly doesn't have. See UI design 2.1 for where to look
and Code craft B1 for searching by what something does, not only its name.
**Why:** A second button component in a project that has one means two
buttons that drift apart: a fix to focus styles or loading reaches one and
not the other, and people meet both.
**Agent trap:** taking the code a design tool exports, or writing straight
from the picture, so every value is typed by hand:
```jsx
// From the picture: raw values, a new button
Save
// From the project: the existing component and its tokens
```
**Check:** for every new component you create, your report says what you
searched for and why the existing ones didn't fit. Search the files you
wrote for hex colours and arbitrary values (`#[0-9a-fA-F]{3,8}`, `\[\d+px\]`):
each one is either a token or has a reason.
### D3 · Read sizes as rules, not as numbers
**Rule:** Every size in a design is either a rule or a coincidence of the
frame it was drawn in. Work out which before you write it. A card 343px wide
on a 375px frame is "full width, 16px page margin". Three cards side by side
on a 1440px frame is "a grid of cards, as many as fit at about 320px or
more". A tall hero with three lines of text is "as tall as its content plus
padding". Write the rule in CSS (`max-width`, `gap`, `minmax`, padding), not
the number. Snap values that aren't on the project's scale to the nearest
token (UI design 2.2).
**Why:** The design shows one width. People use every width. A layout built
from the rule works at all of them; one built from the numbers works only at
the width it was copied from and breaks for everyone else.
**Agent trap:** copying the frame:
```css
/* Copied from a 1440px frame */
.card { width: 412px; height: 296px; margin-left: 24px; }
/* The rule behind it */
.cards { display: grid; gap: var(--space-6); grid-template-columns: repeat(auto-fill, minmax(min(20rem, 100%), 1fr)); }
```
**Check:** search your CSS for `width:` and `height:` with a px value. For
each one, say what rule it stands for. Icons, avatars, borders and other
things that really are a fixed size are fine; anything holding text or
layout needs a better reason.
**Limit:** if the design comes with frames at two or more widths, read the
rule from all of them together. Where they disagree, the difference is the
responsive behaviour.
### D4 · List what the design doesn't show, and decide it
**Rule:** Before building, list the states and cases the design leaves out,
and decide each one: long text and a short one, empty, one and many, loading,
error, disabled, hover and focus, a phone width if only desktop is shown (or
the reverse), dark mode if the project has it. Use UI design 2.5 for content
states and the state table in UI design 2.3. Decide what follows from the
design and the project's existing patterns. Ask the person only when two
reasonable answers would look or behave quite differently (a wide table on a
phone: scroll sideways, or turn each row into a card), with your
recommendation (Working with your human Q2). Say every assumption in your
report.
**Why:** Real people see the states the designer didn't draw. The empty
state is the first screen every new person sees. The error state is the
moment they most need help. A missing state isn't a blank: it's whatever
your code happens to do, usually something broken.
**Agent trap:** building exactly what's in the frame, with the three tidy
sample items it shows, and calling it done. Or the opposite: asking the
person six questions about states you could have decided from the design's
own patterns.
**Check:** your plan or report lists each missing state with what you
decided and whether it was assumed. Each one exists in the build and you
have looked at it (K3).
---
## Summary checklist
- [ ] A short parts list: each component, how often it appears, its variants.
- [ ] Each part mapped to an existing component and tokens, or a reason it's new.
- [ ] Every fixed px size in your CSS stands for a real rule, or is a truly fixed thing (an icon).
- [ ] The states the design doesn't show are listed, decided, and said in the report.