实习日志 / English / UI Refactoring / Turning a design book into rules an Agent can follow: what we took from Refactoring UI

Turning a design book into rules an Agent can follow: what we took from Refactoring UI

中文 | English

By late August, Northwind's two front ends had been written by several Agents taking turns. The code ran, but the interface looked more and more pieced together: colours and corner radii were written directly into individual components, radii ran from 7px all the way to 15px, some buttons were square and some round, and placeholder copy from development had been left on the page. All I could ever say was "this doesn't look good"; the Agent would fix it, and the next feature came out the same as before.

The problem was that there were no rules. People can make trade-offs by taste; an Agent can only follow what has been written down. So I read Adam Wathan and Steve Schoger's Refactoring UI from start to finish, going through all 9 chapters and 42 sections one by one, with a very specific goal: which principles could become clauses in the repository's front-end rules, for Agents to follow and for review to check, and which could not. The rules record only distilled principles, never the book's own text.

Three destinations

Every section ended up in one of three places.

Written as a clause. Anything code review or CI can check went into the front-end design chapter of the repository's governance skill. For example, "no raw values outside the scale in component styles": one look at the diff tells you whether it was broken.

One-off design. Some principles only matter at the moment the tone is set: the interface's personality, whether the Workbench should be a dense layout, how a flat style can still show depth. These do not belong in clauses that are read every time; it is enough to discuss and settle them with me when they come up. The interface personality was later settled as "an oatmeal turtleneck and a good watch", and the rules keep only one line: discuss the tone before designing the look, and once it is settled, the Agent no longer needs to read that section.

Reference only. Learning methods, choosing photos, adding illustrations to marketing pages and the like have nothing to do with this repository's situation, and are only named in the references at the end.

The most useful one: every value comes from a scale

The most useful part of the book for us was "limit your choices" in chapter 1. Arguing over 12px versus 13px is pointless; the right approach is to define a constrained system in advance and pick from it, not from a continuous range of values. The book lists what should be systematised: font size, font weight, line height, colour, margin, padding, width and height, shadows, corner radius, border width and opacity.

This section became the general rule of the front-end standard, governing every visual value after it:

1. every value on that list comes from a predefined CSS variable scale; component styles may not contain raw values outside the scale, and nothing is tuned pixel by pixel;
2. the spacing scale is generated from an 8px base, with 4px allowed in tight spots, and adjacent steps differing by at least 25%;
3. font sizes use a hand-picked scale (12, 14, 16, 18, 20, 24, 30, 36, 48), set as absolute steps in px or rem, never using em to tie elements to each other's proportions;
4. new colours are always written in HSL, with 8 to 10 greys and 5 to 10 shades each for the primary colour and every semantic colour, all defined at once; functions such as lighten() and darken() may not generate shades on the fly;
5. corner radius style is consistent across the site, and mixing square and rounded corners counts as a defect.

Rule 2 had a conflict to reconcile. The repository's existing clause said "8px spacing base", while the book says spacing is perceived relatively: a 2px difference is huge at small values and unnoticeable at large ones, so adjacent steps should differ by more than 25%. The two actually govern different things: the 8px base governs "can this value be used", the 25% governs "how the scale is generated". Taking 4, 8, 12, 16, 24, 32, 48, 64 satisfies both at once.

Rule 3 comes from an example in the book: on a large screen a 45px heading pairs with 18px body text, but on a small screen the right pairing may be 24px with 14px, so the ratio moves from 2.5 to 1.7. The ratio itself is not constant across breakpoints, and binding the two with em only locks in the wrong ratio.

Only what can be checked becomes a clause

For the remaining chapters the test was the same: can you point at a line of code in review and say it breaks the rule?

Hierarchy by subtraction. When the main element does not stand out enough, first tone down its competitors, for example greying out inactive navigation items or removing backgrounds and borders from secondary elements, instead of piling more onto the main element. Buttons come in three levels, solid, outlined and link-style, with at most one solid primary button per view; a destructive action such as delete does not automatically become a big red button, and only in the confirmation dialog is it the main action of that step.

Labels are a last resort. Data that explains itself, such as an email, a phone number or an amount, needs no label; merge where you can, so "12 left in stock" beats "In stock: 12"; when a label is needed it plays a supporting role, smaller and lower in contrast. This rule kept one exception: lookup-style detail pages. The Workbench claim detail page is exactly where staff come to scan field values, so there the labels need to be scannable.

Spacing shows belonging. Space between groups must be larger than space within a group: a label sits close to its input, a section heading sits close to the text below and away from the text above, and list items are further apart than the lines within an item. Evenly spaced floating elements that create ambiguity about what belongs together, then patched with dividers, are what this rule prevents.

Width follows content. Give content the max-width it needs, and do not stretch forms and body text to fill the screen; structural elements such as sidebars get a fixed width, and the main area takes what is left.

Semantic tags and visual hierarchy are separate. Tags are chosen for document semantics, accessibility and SEO; styles are set by visual hierarchy. An h1 does not have to be the largest text on the page.

State is not shown by colour alone. The repository already had this rule, and the book added one line: to tell several lines apart in a chart, use light and dark versions of one colour rather than different hues, so colour-blind users can still tell them apart by lightness. Semantic tags default to dark text on a light background, a light shade of a hue as background and a dark shade of the same hue as text, which meets contrast requirements and looks lighter.

Line height depends on the case. The old clause was a blanket "line height 1.4 to 1.6". The book says line height goes up with line length and down with font size, and a large heading at 1.5 looks loose and awkward. The clause became 1.4 to 1.6 for body text and 1.1 to 1.3 for headings.

The section closest to this product

The part of the book most directly related to Northwind's business is the section in chapter 7 on user-uploaded content. Claimants upload accident photos, staff view them in the Workbench, and we have no control at all over what users upload.

The clause sets two lines of defence. First, a fixed container with centred cropping, using object-fit: cover, never laying images out at their original aspect ratio, which would break the layout. Second, a light photo on a light background blends in, so use a very faint inner shadow:

box-shadow: inset 0 0 0 1px hsla(0, 0%, 0%, .1);

No solid border: a solid line clashes with the colours in the image itself, while the inner shadow is barely noticeable and still works.

A principle that guards against Agents

Chapter 1 also has "design pessimistically": do not hint at features that are not ready to be built in the interface; if comments do not support attachments yet, do not draw an attachment area; always ship the smallest useful version first.

The principle is really about design rhythm, but here it had a use the book never had in mind: it is very effective at stopping models from writing development leftovers into the front end. Placeholder copy such as "coming soon" or "this feature is under development", and a button that does nothing when clicked, all fall under it. It became a clause in the interaction principles.

What was left to people

A few points I deliberately kept for myself. Balancing weight and contrast, where bold adds visual weight and thin lines that are too faint need more weight to make up for low contrast, is only done when there is an explicit request to polish the interface; Agents do not need to deal with it day to day. Decorative accent borders and low-contrast background textures went in as techniques that may be used, not as constraints. Overlapping elements to create layers leans towards marketing pages, and whether it belongs in a claims workbench was something I had not decided at the time; it was left for later discussion.

After these choices, the clauses were merged into the front-end design chapter of the repository's governance skill, organised in three layers, "general rules, standing constraints, triggered and one-off design": the general rules govern every value, the standing constraints are what review and CI can check, and triggered clauses carry their own triggers and do not constrain everyday changes until triggered. A few days later, the claimant visual spec and the front-end refactor were both built on these clauses.