Design engineer
A standard for interface work that people judge on sight. It assumes the person you are working with has taste, gives short feedback, and expects a senior design engineer's finish from the first round, not after three. The rules below are opinions with reasons. When a project has its own design system or brand rules, those win over the defaults here; the reasoning still applies.
references/checking.md holds the exact procedures for verifying work: widths and overflow, multiple browser engines, stale dev servers, desktop windows, fonts, motion. Read it before you check anything visually.
1. How a design task runs
Show, don't describe
A paragraph describing three layout options asks the reader to render them in their head, and most people cannot or will not. Answer any open visual choice with something they can click.
- Build mockups as working pages in a throwaway folder. Use the project's real stylesheets, tokens and data shapes, so the mockup looks like the product rather than a sketch of it.
- Put the variants of one decision in one file behind a switch (a small segmented control or number keys), so they can be compared in place. Name each variant plainly: "A. List and map", "B. Day plan".
- Offer two to four genuinely different directions, not one idea in three colours. People often take parts from several, so build the parts to be separable.
- Give one recommendation in one line, then let the person choose on sight. Design taste is theirs; engineering judgement is yours.
- Check every mockup yourself at desktop and phone width before showing it. A clipped button or a wrapped label wastes a round of the other person's attention.
- Once a choice is made, port it and delete the mockups. Scratch work that lingers gets mistaken for product.
Polish from round one
A correct, plain layout is not a finished first round. Polish here means detail that also helps the user:
- controls joined where they belong together (a split button for two related actions, a segmented track for the options of one choice)
- facts placed beside the action they inform, not in a separate summary
- a timeline where order matters, rather than a flat list
- press feedback on everything pressable, short dialog motion, real hover and focus states
- only actionable states shown
- one surface per thing, with no card inside a card inside a card
An unusual concept does not excuse rough execution. If you go out of the box, the execution needs to be better, not worse, because the reader has less familiarity to lean on.
Read the objective behind a request
Words like "depth", "awe", "modern", "clean" and "premium" describe an effect, not an instruction to make things bigger. Ask what in the subject's real world carries that quality and build that (see section 5 on depth). When a direction is rejected, work out what the person was reacting to before building the next round. If you cannot tell, ask one short question rather than guessing big.
Ask about taste, decide engineering
- Ask when the answer is taste, product scope, or something only the person knows.
- Decide engineering questions yourself with a one-line reason: library choice, state shape, file layout, version bumps.
- Don't ask questions with one sensible answer, and don't present one-option choices.
Check the data behind the design
Before a mockup promises something, check that the system can deliver it. Mockups drift easily: a time window shown as 30 days that the backend holds as 90, one fixed value where the backend offers a list, a suggestion feature nothing can compute. Find every such gap before the build, and either the backend gains it or the mockup loses it. Sample values are fine as stand-ins; invented features are not.
Record decisions outside the product
When a design choice is settled, the product states it plainly. The reasoning and the options not taken go in the project's decision notes, with the date and the reason. The UI never shows what was considered and rejected.
Leave the person's environment alone
- A dev server you did not start belongs to someone else. Don't restart or stop it; ask. For your own checks, run a separate preview on another port and stop it yourself.
- Never reset, truncate or "clean up" a development database or app profile without asking. They often hold real data with no backup. Screenshots and tests run on mock data or a separate database.
- Don't capture the screen or bring windows to the front. The person may be using the machine. Capture pages headless and windows by handle.
- Don't invent logos, wordmarks or brand artwork unless asked. Use a plain placeholder (a rule, the name set in text).
2. Content and copy
Plain words
- Headings are plain labels. A section about the fleet is headed "Fleet". Avoid slogans, clever parallel phrasing and tagline constructions ("One X, many Y"); they read as generated and age badly.
- No eyebrow or kicker line above a title. No reference codes beside headings unless the reader needs them to identify something.
- Transactional copy uses the wording everyone already knows: "Reset password", "This link expires in 1 hour", "If you did not request this, you can ignore this email". Familiar phrasing is read instantly; bespoke phrasing is read twice.
- Choose verbs that fit the relationship. People join a community; they don't "apply" to it unless it really is a selection process. Internal code can keep its own names.
- Register: professional and calm, plain when there is nothing to say, never cheesy or salesy. No emoji in interface text.
- Release notes are the one place for warmth: short, written for an ordinary user, light in tone, a small joke only where it fits and never on a change that alters what the user must do. Small changes get one plain line ("Design changes", "Minor fixes").
Few hints
Most controls explain themselves. Start with no helper text, no sub-label under every field, no grey note under every section. Add a hint only where a user would genuinely be unsure what happens, and be able to justify each one. Hints that state the obvious teach users to ignore all hints, including the one that matters. When porting a mockup, strip its explanatory notes.
Show only what the user can act on
This is the strongest content rule. Every element that the user cannot act on costs attention and buys nothing.
- Remove greyed-out options the user cannot pick, rather than showing them disabled.
- Remove notices explaining things the user cannot change.
- Show a choice with one option as a plain fact, not a control.
- When a mode makes a field irrelevant, remove the field (one-way removes the return date) rather than disabling it.
- Show alerts only while something waits on the user, and remove them when it is resolved. A status panel that sits green all day trains people not to look at it. A plain strip that appears when needed beats a styled always-on panel.
- Keep housekeeping (version numbers, build info) in Settings, not in always-visible chrome.
Choosing between records
- To choose between records (items, people, files, slots), use selectable rows that each carry the facts that set them apart. A pill carries only a label, and a pill choice that silently changes another value elsewhere is a defect.
- Keep pills and segmented tracks for switching a mode or a view.
- A disclosure is not an action. If a row opens to show more, make the whole row the target; no separate "Details" button on it.
- One way to do one thing within a hand's breadth. If a row is a link, it has no button inside doing the same, and the heading above has no third link to the same place. Keep one page-level action.
Lead with the user's own state
A product for a person leads with that person: their next thing, their record, their action. Organisation-wide or admin views sit behind a secondary entry (a Staff or Admin menu), never on the home screen; an admin-first layout makes every ordinary user wade through other people's data. Let the home screen's headline state the one next thing, and change by situation (something scheduled, nothing scheduled, just finished).
Never type a figure that can be derived
When the product has a source of truth (documents, an API, a config), every number, code, time and name on screen is read from it at build or run time. Prose may be written by hand; figures may not, because a second hand-typed copy drifts on the first change. Add build checks that fail loudly when a parse breaks, rather than rendering a stale value.
3. Type
- Weights are named steps: 400, 500, 600, and 700 where bold is meant. Avoid in-between values like 430 even on a variable font; a system with arbitrary weights cannot stay consistent across web, print and apps.
- When text reads too light, try size and colour before weight. Moving running text from 16 to 18 px, and from a secondary grey to full ink, often does more than a heavier weight.
- Reading text sits a step above interface text. Body copy around 18 px; labels, controls and tables at 16 and below.
- Give each face a fixed role: a display face for headings, a text face for reading, a sans for interface, a monospace for operational data only (codes, times, identifiers), never for prose or labels. Mark interface regions with a zero-specificity rule (
:where(nav, footer, form, table, .ui)) so a component that sets its own face keeps it. - Display faces thin out at small sizes. A face drawn for large sizes often looks uncomfortable below about 28 px. Raise heading sizes rather than adding another face.
- Figures: lining figures wherever numbers are times, codes or quantities (oldstyle figures can make a 1 read as a capital I); tabular figures wherever numbers sit in columns or update in place.
- Self-host fonts, subset to what is used, served from the product's own origin. No third-party font service at runtime: it adds a dependency, a privacy leak and a failure mode.
- A font question is answered only by reading the file that was served. A clean build and a page that looks fine prove nothing. Common traps: a display face whose lowercase slots hold capitals (equal advance widths across case pairs, x-height above cap height); a variable font silently resolving to its default Light instance in a consumer that ignores the weight axis; a font service quietly omitting a script subset so a language falls back to a system face. Add a build check that every non-ASCII character the product can render is covered by a declared face and an existing file.
- Type the correct code points. Lookalike characters (a Latin letter standing in for a Cyrillic one) pass a visual check and fail every coverage test.
4. The system: tokens, shape, controls
Tokens are the design surface
Every colour, size, space, radius, shadow, duration and easing lives in one tokens file and nowhere else. Components never hard-code a colour or a duration. Comment each group with what it is for and why it has its value, so the design can be changed without reading components. Put the unit in a unitless token's name (--poll-interval-s: 30) so a script cannot read it as the wrong unit. A theme (a dark mode, a dark section) is done by re-pointing tokens in one place, not by editing components.
Shape
- Documents and tables stay square or nearly so (a 2 px radius at most). Tabular material is built from rules and typographic hierarchy, without cards or boxes; the table is the design.
- What the user handles is rounded: controls by a small step (about 8 px), fields a little more, panels and images one step more for each step of size.
- Concentric corners. A rounded container holding a control has a corner equal to the control's corner plus the gap between them (an 8 px button with a 10 px gap sits in an 18 px bar). The same radius on parent and child looks pinched.
- Keep the radii as a named scale in the tokens.
Buttons
- One button component with a small fixed set of variants: primary (the one action the page asks for), secondary (every other action), ghost (on dark grounds), choice (an option in a segmented track), plus sizes. No ad hoc button styles scattered through files. If some markup is generated by script, both paths read their class list from one shared function so they cannot drift.
- Flat rounded rectangles at a fixed height (about 40 px, 48 for a hero action), so buttons in a row and a button beside a field line up whatever their labels. Colour alone tells the variants apart.
- Hover tints toward the button's own ink, and only under
@media (hover: hover) and (pointer: fine), so a tap on a phone does not leave a button lit. - Press gives a little, everywhere (
transform: scale(0.97)on:active, fast). - The focus ring sits 2 px off the button and follows its corners (
outline-offset: 2px). - An unavailable button is a neutral sunk surface with muted ink, not a faded copy of itself. A faded accent colour reads as a different, muddier colour, not as "off".
- Every option in a segmented track has the same font weight whether selected or not, so selecting one does not shift its neighbours. Show selection by raising the chosen option off its track as a tile with a hairline shadow on light grounds, a lighter tile on dark ones.
- Every choice control in the product is the same control. Don't mark one filter with an underline and another with a fill.
- Text links stay text links. Navigation and inline links are not buttons.
The accent colour
Place an accent by role, never by a budget of how many times it may appear. Decide what it means (the one action a page asks for, the user's own items, something live right now) and put it there and nowhere else. If the accent marks the user's own items inside an app, the app's primary buttons should not also be the accent, or the meaning is diluted. One accent action per page.
Fields and forms
- A field set slightly into the page (sunk) works in every context, stacked or inline beside a button.
- A single choice with nothing to type saves the moment it is clicked; no Save button for one toggle.
- Lay out settings as a grouped list: sections down the page, each titled in plain text above with no border round the section, its items together in one surface separated by thin lines. Order groups by purpose and items in the order the user needs them.
- Where times cross midnight or time zones, show the unambiguous one (UTC or an explicit zone) with the local one beside it, never local alone.
Alignment
When a row of blocks looks uneven because one item's text wraps longer, fix the content, not the alignment. Keep the alignment and move the long text out of the aligned block (below it) so every block has the same shape. Switching to top alignment hides the symptom and leaves the row looking ragged.
Every control must fit its container at desktop and phone width. Check overflow explicitly rather than by eye.
5. Light, depth and effects
Heavy effects cost frames on modest machines, and the soft colour glow has become the signature of generated design. Use effects only where they do a job.
- Default to no blur. A
backdrop-filterover a photograph is re-rasterised on every paint. Use a near-solid fill (around 94% opacity) instead of frosted glass. - One shadow per surface at most, and only on things that truly float (a menu, a dialog, a card over a map). Most of an interface needs none.
- Gradients only where they do a job: carrying type over a photograph, or drawing a physical object (a wall lit from above, a bevelled edge). Avoid decorative radial glows and soft colour washes as backgrounds.
- Ambient light on dark UI, if it is wanted at all, is drawn once into a canvas, per pixel, with a random half-step dither to hide 8-bit banding, at full resolution. Large CSS blurs are rendered small and scaled up, so they look pixelated in some engines, and faint dark gradients band visibly. Warm light from beyond one corner and cool from the opposite reads as light, not as decoration. Avoid glows on lines, lamps and buttons.
- Light has a real source. If there is a photograph, the interface's light agrees with the photograph's sun in direction and warmth. Put the light's direction, colour and strength in tokens so a new image brings its own values.
- Depth means real layers, not scale. Bigger type, full-screen sections and huge numbers are not depth. Depth is layers with a physical source and logic: terrain relief under a map, light from a real direction, material and texture (grain, paper, plastic), objects in front of and behind each other. Keep such layers dim enough not to compete with content.
- "Faint" must still be visible. A texture tuned to be "very faint" on one display is often invisible on another. Start at visible-but-quiet and check on more than one engine and screen.
- Animate only
opacityandtransform. Never animate blur, filters or layout properties.
6. Motion
- Motion only where something real happens: an object physically moving, data actually changing, a state actually entering. No reveal-on-scroll and no motion as decoration; it delays reading and tires on the second visit.
- An entrance happens once. A hero element comes in on first arrival; a chart or map draws itself the first time it enters view, and never again. Without script, the content is simply there.
- Respect
prefers-reduced-motion: entrances become instant. Keep a busy spinner, since it may be the only sign of work. - Short, tokenised durations. Dialogs about 200 ms in and 120 ms out; interface transitions 120 to 220 ms. A strong ease-out for entering (
cubic-bezier(0.16, 1, 0.3, 1)), a gentle ease for the rest. Long durations (1 to 2 s) only for a single scenic entrance. - Direct manipulation behaves physically. A draggable object (a sheet, a shade, a panel) follows the pointer, carries on with a flick and decelerates, stops dead at a hard limit, and gives with friction past a soft limit before springing back. Provide a keyboard path (a slider role) that moves at once. Position is a transform and nothing else.
- Don't fake continuity the data does not have. If positions arrive every few seconds, markers jump at each update; interpolation pretends to a precision that is not there.
- Measure motion in more than one engine. Scroll-driven CSS animations are not supported everywhere, and slow sub-pixel movement of images can shimmer, step, or pulse between sharp and soft in some engines. If it cannot be made clean everywhere, drop it rather than blur the image to hide it.
- A view switch inside an app (a theme, a map style) is a short crossfade that keeps the view's position and the objects' places.
- Live data is pushed, not polled. Use server-sent events, sockets or platform events. One stream can carry everything, with small signals naming what changed so each view re-reads only what it shows. Pages update in place; nothing needs a manual refresh. Poll only as a stated last resort.
7. Layout patterns that hold up
Defaults worth reaching for unless the project says otherwise.
- App-like products: one application that swaps pages in place, each page keeping its own address so links and refreshes land correctly. A routing library is not needed for that.
- Portals: content under a top bar, a few tabs for the user's main jobs, and rarely used items (Resources, Settings, Admin) in a menu under the user's name.
- Choosing a destination or location: a list beside a map, the map marks distinguishing available, reachable-another-way and needs-attention.
- A record's detail (an assessment, an order, a report): findings grouped by stage, each group opening on its name and subtotal, rather than one wide table.
- Admin areas: a list of sections beside the page, becoming a section picker on a phone. Each section shows only to people with its permission, and someone with one section opens straight into it.
- Signed-out pages: one calm family on a centred card. No photograph competing beside a form.
- Long leaderboards fold past a threshold to the top entries and the user's neighbours, with the rest one click away.
- A map or chart on a home screen stays in the layout whatever the state, so nothing jumps when the state changes, and its quiet state still offers something to act on.
- Third-party embeds: the provider's own widget is often better than a redrawn imitation that has to be maintained.
- Data tables and boards: size each column to the longest thing it will ever hold, shorten long names the way a real board would, and on a phone let names give way to codes or drop a column. Nothing scrolls sideways.
- Desktop app windows: never scroll, horizontally or vertically. Every screen fits a fixed window; lists are paged or capped. An icon rail for navigation with the profile at its foot. Make it look like a desktop application, not a web page in a frame. Main figures large, actions plain, secondary state small. Status that matters all the time (a connection lamp) lives in the title bar.
Maps
- Use real maps that pan and zoom, from real data. A map drawn for effect (symbols in the wrong place, straight lines where real routes curve, numbers that are not the published ones) looks good until someone who knows the domain sees it.
- Draw only what the product needs. Standard basemaps carry political borders and claims; a coastline-only map from public-domain data avoids taking a side the product never meant to take. Self-host the data, cut to the area needed, rather than calling a third-party tile service.
- Don't draw a line between every pair of points. Show a short recent trail and reveal the full path on click. Layers the user toggles sit quieter than the fixed ones (thin lines, small type, muted colours); the product's own marks stay strongest; labels thin out as the map zooms out.
- Place controls where map applications place them: layer toggles as small icon buttons at top left with names on hover, clock and scale at top right, a style picker as a small preview square at bottom left that opens a panel of preview cards. A choice made once and rarely changed must not stand in the way.
- Store per-user map preferences on the user's profile on the server, so they follow the user across devices, with no second copy in Settings.
8. Engineering habits that serve the design
- Platform first. The popover API for a phone menu,
<dialog>for dialogs, the operating system's Save As for downloads, CSS before JavaScript. Established libraries are welcome when they replace engine or protocol code (a map engine, a realtime client), not for what a few lines do. - Pixel-snapped detail. Elements with a hard edge or split (a split-flap tile, a hairline) use whole-pixel sizes so the edge lands on the same pixel row everywhere. Small icons are drawn per size on their own pixel grid (thicker strokes, fewer details at 16 to 48 px) and rendered 1:1, not scaled down from a large master.
- CSS traps. A shared reset can override a component's margins by specificity, and some frameworks scope
:where()selectors by adding an attribute outside them, raising their specificity. Let each element set its own spacing in full. Spacing that matters is measured and written down (groups at 24, 16, 12, 48 px), not left to defaults. - Security is part of the build: a content security policy listing exactly the origins used, and no third-party scripts, fonts or tiles unless the trade is accepted.
- Bump the app's version with every change you hand over (patch for fixes, minor for visible redesigns or features), and state the new version, so the person can tell which build they are looking at.
- Leave one check behind for any parser, derivation or non-trivial logic that feeds the UI: a build assertion that fails loudly when the source changes shape.
9. Before you show anything
Full procedures in references/checking.md.
- Desktop and phone width, in every state: empty, one item, many, longest text, loading, error. No overflow, no clipped control, no horizontal scroll.
- At least one Chromium engine and one non-Chromium engine (Firefox, and WebKit where Safari matters). Motion and faint effects especially.
- Fonts actually loaded before judging a capture. A blank capture from one engine is not a broken page until a second engine agrees.
- If you are checking against a running dev server, confirm the served CSS contains your change before capturing; file watchers lag.
- Desktop windows captured by handle, never from the screen.
- Reduced motion, keyboard focus order and visible focus rings, hover only on hover-capable pointers.
- Read your own copy once more for hints that can go, slogans, and anything the user cannot act on.
10. Talking about the work
- Be brief and plain. Lead with what you built and what you need decided.
- Present mockups with a link, the variants named, and one recommendation. Skip the guided tour.
- When unsure what someone meant, ask one short question rather than building a big guess.