# ihumane · Front-end build · v0.1 You are an agent about to turn a design into front-end code: a mock-up, a Figma frame, a screenshot, or a written UI brief. This module is written for you, not for a human reader. It turns what experienced front-end developers know by instinct into rules you can follow and checks you can run. Read this file fully. Read the other files when the step below tells you to. --- ## Why this exists A design is a picture of one moment: one width, one length of text, one state, everything going well. The people who use the page will bring the rest: a small phone, a long name, a slow connection, a keyboard instead of a mouse. A front-end developer reads the picture for the rules behind it. You tend to copy the picture. That gives four failures people keep fixing after you: 1. **It matches one width and breaks at the others.** You copied 1440px pixel by pixel, so at 375px the page scrolls sideways and the cards overlap. 2. **It matches the sample content and breaks with real content.** A longer name wraps out of its box, an empty list leaves a hole, an error message pushes the button away. 3. **It looks right but isn't built right.** A `div` with a click handler where a button should be, a field with no label, the same button built three ways in three sections. 4. **Nobody looked.** The code was written, the screenshot in your head looked fine, and the first person to open it on a phone found the bugs. This module works with two others. **UI design** decides what a screen should be: tokens, spacing, states, the human rules. **Code craft** decides how code fits the codebase. This module is where the two meet: building a design so it holds up for people. It refers to their rules by ID ("UI design 2.2", "Code craft B1") instead of repeating them. --- ## Size the job first | Size | Looks like | Do | |---|---|---| | **Small** | One component, one section, a fix to an existing screen, a restyle | Name the parts and find the existing components for them (D1, D2). Build with real elements and fluid layout (M1, R2, R3). Look at it at 375 and 1280 next to the design, and run `checks/layout.js` at both (K1, K2). | | **Large** | A full page or screen, a flow of several screens, a new set of components, a design handed over from a designer | The full workflow below, every step. Before writing code, write down the parts list and the states the design doesn't show (D1, D4). | If unsure, treat it as small. The check step is never skipped: it's the only place you find out what a person on a phone will see. --- ## The workflow | Step | What you do | File | |------|-------------|------| | 1. Read the design | Name the parts, find what the project already has, read sizes as rules, and list what the design doesn't show. | `1-read-the-design.md` | | 2. Structure | Pick the right element for each part, build one component per thing, and keep styles in a shape the next person can follow. | `2-structure.md` | | 3. Responsive | Build from the smallest width up, with fluid layout, text that wraps on purpose, and nothing that jumps. | `3-responsive.md` | | 4. States and forms | Build every interactive state, fields that work with the browser, and focus that goes where people expect. | `4-states-and-forms.md` | | 5. Check | Open it in a real browser at real widths next to the design, run the checks, break it with real content and a keyboard, then report. | `5-check.md` | --- ## The format of every rule Rules in this module use the same fields: - **Rule:** what to do, as specifically as possible. - **Why:** what happens to a real person if you don't. This lets you handle cases no rule covers. - **Agent trap:** the specific way agents like you get this wrong. - **Check:** how to verify it, ideally something you can run or count. - **Limit:** where the rule stops, when there's a common exception. Runnable checks live in `checks/`. Run them on the rendered page in a real browser; don't trust your reading of the code. | Check | Finds | |---|---| | `checks/layout.js` | Sideways scrolling and the element that causes it; text cut off or spilling out of a fixed height; tap targets under 44×44px at touch widths; images stretched, blurry, far too large or with no size set; divs and spans used as buttons; fields with no label or the wrong type; headings that skip a level | The UI design checks (`spacing.js`, `contrast.js`, and in Pro `affordance.js` and `stability.js`) apply here too. Run them in step 5. --- ## Five rules that matter most If you remember nothing else: 1. **Read the design as rules, not pixels.** A 343px card on a 375px frame means "full width minus the page margin", not `width: 343px`. (`1-read-the-design.md` D3) 2. **Use what the project has.** Its components and tokens first; one component per thing, with variants. (`1-read-the-design.md` D2, `2-structure.md` M3) 3. **Real elements.** A button for an action, a link for a place, a label for every field. (`2-structure.md` M1, `4-states-and-forms.md` F2) 4. **Smallest width first, and content decides the size.** No fixed widths copied from the design, no fixed heights on anything with text. (`3-responsive.md` R1 to R3) 5. **Look at it in a browser at 320, 375, 768 and 1280, next to the design.** Run `checks/layout.js` at each. (`5-check.md` K1, K2) --- ## Precedence The person's instructions and the project's own conventions come first: its components, its tokens, its CSS approach, its framework. If the project does something these rules advise against, match it in the code you write and mention the conflict once in your report (Code craft B2). The design is the person's decision, not yours. When it breaks a rule here or in UI design (a 30px tap target, faint grey text), fix it only where the fix can't be seen: a larger hit area made with padding looks the same. If the fix would change the look, build it as designed and name the conflict in your report, with the fix you'd suggest.