Design Process: UX principle for coding agents

Start with a Feature, Not a Layout

DO NOT start by designing the shell (navigation, sidebar, containers)
START with actual functionality and features first
Design one piece of functionality at a time (e.g., a search form, a login screen)
The navigation structure will emerge naturally once you have features designed

The Three-Second Test

A screen should communicate three things within three seconds of landing on it: what it's for, what the primary action is, and where the user is in the product. If a fresh viewer can't answer those after a glance, the screen is underdefined, not just unpolished.

Purpose — what is this screen for? If it takes reading to know, the layout isn't carrying the message.
Primary action — what's the one thing the user came to do? It should be the most visually prominent element (see ui/hierarchy.md — the three-level action hierarchy; cognitive-laws.md — Von Restorff Effect).
Context — where am I, and how did I get here? The navigation chrome answers this (see navigation.md — Always Show Where You Are).

Use it as a fast diagnostic: show the screen to someone for three seconds, take it away, and ask what it was for. A vague answer is a design problem, not a user problem.

One Screen, One Purpose

Every screen earns its existence by serving one primary job. A screen that tries to be several things at once dilutes all of them and leaves the user unsure what to do.

One reason to exist. If you can't state a screen's single purpose in a sentence, it's probably two screens wearing one coat.
One true primary action. Aim for a single primary action per screen; secondary and tertiary actions exist but read quieter (see ui/hierarchy.md). When several actions compete as co-equal primaries and the surface piles on more than a handful with no hierarchy, that's the kitchen-sink anti-pattern: the screen hybridizes until nothing leads (see anti-patterns.md — Structure & Architecture; cognitive-laws.md — Hick's Law).
Supporting tasks are fine; they sit below the primary one in the hierarchy, not beside it as equals.

Screens Are Not User Stories

A common architecture mistake is minting one screen per user story. Stories and screens don't map one to one: several stories usually converge on a single screen, and many "features" are really states or components, not destinations.

Stories converge. "View my orders," "filter my orders," and "see an order's status" are one screen with states, not three screens.
A filter, a validation, a notification, a piece of feedback is a state or a component, not a screen. Promoting each to its own destination explodes the navigation and fractures the flow.
Consolidate, don't explode. Start from the jobs, then collapse them onto the fewest screens that serve them well.
Settle the macro-structure before detailing screens. Define navigation (sidebar / top bar / tabs / breadcrumbs) before laying out individual screens, so each screen slots into a coherent shell (see navigation.md).

Prioritize What's Visible (P0 / P1 / P2)

Not every action deserves to be on screen at rest. Rank them and let the ranking decide visibility, so the primary job isn't buried under options.

P0 — the screen's primary job. Immediately visible, unmissable.
P1 — secondary actions. Present but quieter; they don't compete with P0 (see ui/hierarchy.md — Emphasize by De-emphasizing).
P2 — rare or advanced actions. Deferred behind a menu, a "More," or progressive disclosure (see forms.md — Progressive Disclosure).

This is the antidote to the kitchen sink: instead of showing everything and hoping the user finds the important thing, decide what's important and design the rest to step back. Hidden P0 actions are a named anti-pattern (see anti-patterns.md).

Detail Comes Later

Avoid premature detail: Don't obsess over typefaces, shadows, icons too early
Design in grayscale first: Use spacing, contrast, and size to create hierarchy before adding color
Stay low-fidelity initially: Use sketches or wireframes to explore ideas quickly
Sketches are disposable - move to implementation as soon as you have direction

Don't Design Too Much

Work in short cycles: Design → Build → Iterate
Don't try to design every feature and edge case upfront
Build simple versions first, discover complexity during implementation
Be a pessimist: Only design features you're ready to build
Design the smallest useful version you can ship

Think Like a Design Engineer

The design file is a snapshot. The product is a system. That difference is where design engineering lives.

Read every design as an incomplete spec:

A mockup shows one moment. Production UI handles every moment the mockup never showed.
If you read a design as finished truth, missing states show up late as bugs. If you read it as an incomplete specification, they show up early as part of the build.

Ask immediately — what are all the states?

A button is not a rectangle with text. It's default, hover, active, focus-visible, disabled, loading, success, and error.
A table is not "data loaded." It's loading, empty, filtered-empty, partial-error, dense, selected, bulk-action mode.
A modal is not just open and closed. It has entrance, exit, scroll-lock, focus management, and failure states during submission.

See constraints before they happen:

Translated text that is 40% longer
User-generated names that don't fit the space
Empty values where fake data existed in the design
Narrow viewports, slow networks
Tables with 3 rows or 3,000 rows
A browser zoomed to 125%

Encode taste into structure:

Spacing tokens instead of random gaps
Text styles instead of one-off font sizes
Reusable card and panel patterns
Button variants with clear rules
Layout primitives for stacks, clusters, and split rows

Bridge the gap between design and code:

Shared vocabulary (both people know what a "stack" is, what "intrinsic sizing" means)
Working in the browser for interaction design (hover states, transitions, scroll behavior, responsive breakpoints) — prototyping in Figma is guesswork, in code is proof
Design tokens as a shared contract (same 8px scale in design and code eliminates "it's 2px off" conversations)
Co-design sessions for edge cases (designer shares screen while you build — no handoff document needed)

Mental model: Core intent → all reachable states → constraints that pressure layout → reusable rules instead of local decisions → tradeoffs in fidelity/complexity/accessibility/performance

The Four Mandatory States

The previous section asked "what are all the states?" Four of them are non-negotiable: every component that loads or acts on data handles empty, loading, error, and success, explicitly. The happy path is the one state you can't ship alone.

Empty — name what's missing and give the first action; never a silent blank (see ui/polish.md — Don't Overlook Empty States, which splits empty into five sub-types).
Loading — skeleton when the structure is known, spinner for process work, nothing when the current UI stays useful (see interactions.md — Choosing a Loading Pattern). Keep it honest and under the Doherty threshold where you can (see cognitive-laws.md — Doherty Threshold).
Error — a clear cause and a corrective action, never a bare "Error" (see errors.md).
Success — perceptible, contextual feedback ("Project created"), not a mute "OK" (see notifications.md).

And the cases that hide inside those: lists handle 0, 1, and N items; forms run validation, submission, then feedback with the submit disabled during the request; mutations update optimistically and roll back on failure (see interactions.md — Optimistic Updates); transitions don't flash or shift layout.

Choose a Personality

Consider these factors when establishing personality:

Font Choice:

Serif = elegant, classic, traditional
Rounded sans-serif = playful, friendly, approachable
Neutral sans-serif = plain, modern, let other elements provide personality

Color:

Blue = safe, familiar, trustworthy
Gold = expensive, sophisticated, premium
Pink = fun, playful, less serious

Border Radius:

Small radius = neutral, professional
Large radius = playful, friendly
No radius = serious, formal
Stay consistent - don't mix square and rounded corners

Language/Copy:

Formal tone = professional, official
Casual tone = friendly, approachable

Fun Can Be the Differentiator (in the Right Context)

Sometimes "fun" is the smartest competitive advantage. A month before launching FigJam, the team realized the product felt soulless and chose to differentiate through fun rather than through more conventional features. A focused design sprint produced ideas like cursor chat, which went on to become definitional to the product.

The lesson is not "always add fun." It is that personality can be a strategy, not just decoration, when it fits the job the user hired the product for.

Context decides whether fun helps or hurts:

It worked for a brainstorming tool, where you want people to loosen up, open up, and play. Low-friction delight pulls hesitant collaborators in.
It would backfire in professional design software, where users want zero interference and every playful flourish reads as a thing standing between them and their work.

How to apply it:

Ask what emotional state the task wants. Exploratory and social work tolerates (and benefits from) playfulness; focused, high-stakes, or repetitive work wants to disappear.
Treat a personality bet as a real product decision with a target and a way to tell if it landed, not a coat of paint added at the end.
When in doubt for tools used heads-down all day, default to invisible over playful.

Limit Your Choices

Define Systems in Advance:

Create a constrained set of options for all design decisions
Define systems for: font sizes, font weights, colors, spacing, sizing, shadows, border radius, opacity

Decision-Making:

Pick an initial value from your system
Compare with adjacent values
Choose by process of elimination

Systems to Define:

Font size scale (8-10 options)
Font weight (usually just 2: normal 400-500, bold 600-700)
Color palettes (8-10 shades per color)
Spacing scale
Sizing scale
Shadow styles
Border radius options
Opacity levels

Decide Between Options

Design decisions are choices between alternatives, and the choice should be reasoned, not intuited. A recommendation with no alternatives weighed is a guess wearing a confident face.

Explore at least two solutions before converging, and document each with its pros, cons, and development complexity. One option isn't a decision; it's a default.
Run the lean filter before validating a design: single clear objective, clear CTAs, no over-design, minimal flow (≤ ~5 steps on the happy path), design-system consistency, reasonable development cost. A design that fails the filter goes back, not forward.
Weigh value against complexity. When the build cost outstrips the user value, simplify or defer. Irreducible complexity is fine (see cognitive-laws.md — Tesler's Law); self-inflicted complexity is not.
Check the design system before inventing. Does the pattern already exist? If not, is adding it justified (see interaction-patterns.md — Avoid Franken-Patterns)?
Block progression when the foundations are missing. No spec without agreed screens and flows; no "validated" spec carrying TBD/TODO/open questions; no design built on unresolved, contradictory assumptions (see understanding-users.md — Contradictions Are Signals).
Delegate the expansion, keep the choice. An agent is fast at widening the option space and poor at closing it. Variations on a layout, the same screen at three breakpoints, every empty and error state, copy in another language: that is volume work with a checkable result. What to emphasize, what to cut, and what the product promises stay with the person accountable for the outcome, so picking the top generated result automatically fails this step as surely as never generating alternatives.

Speed Does Not Remove the Review

Generating more work per hour raises the amount that has to be checked; it does not lower the standard. Decide in advance which surfaces get line-by-line human review, and hold that line when volume goes up. Core product paths, anything handling money, health, or identity, and anything a user cannot undo belong on that list. Throwaway explorations and internal tooling do not.

The failure is quiet. Generated work is fluent, so it reads as finished, and a reviewer skimming for obvious errors will pass code and screens that are subtly wrong about the domain. Review for what the work claims and what it does to the user, not for whether it looks plausible.

Map the Customer Journey

When the roadmap needs journey priorities, reduce the current experience to five or six memorable moments. Mark:

Peak: the highest-value emotional moment.
Pit: the lowest-value emotional moment.
Jump: the largest relative improvement.
Drop: the largest relative decline.
Transition: a meaningful milestone beginning or ending.

Build the current journey from observed behavior and product data, then compare it with the customer story in understanding-users.md. Inspect the moments before a visible drop, because the cause often appears earlier than the abandonment.

Prioritize four moves: mark an important transition, elevate the strongest peak, fix the deepest pit, and reorder steps so value arrives sooner. Do not spend the roadmap smoothing every minor inconvenience while the defining moments remain weak. The Peak-End Rule in cognitive-laws.md explains why peaks and endings deserve disproportionate attention.

Communicate Decisions to Stakeholders

Before presenting a solution, understand the stakeholder's desired future, largest current challenge, and barrier to progress. Then structure the decision around shared evidence:

Customer story: what is happening in the user's context?
Gap: where does the current experience fail?
Principle: which mental model explains the gap?
Intervention: what is the smallest change that addresses it?
Outcome: how should the customer's experience improve?
Measure: which success metric and harm guardrail reveal the effect?
Unknowns: what remains an assumption?

State the decision the review must make and the feedback needed before showing the work. When feedback arrives, acknowledge it, restate the concern and underlying risk, then confirm the shared intent before responding with evidence or alternatives. This lowers defensiveness without requiring agreement.

Leveling Up: Continuous Improvement

Look for Decisions You Wouldn't Have Made

When you see a design you really like, ask yourself: "Did the designer do anything here that I never would have thought to do?"

Pay attention to unintuitive decisions:

Inverted background colors in unexpected places (e.g., dark datepicker on light page)
Unusual positioning (e.g., button inside a text input instead of outside)
Creative typography (e.g., two different font colors for a single headline)
Unexpected use of spacing or alignment
Novel interaction patterns

Why this works:

Helps you discover new techniques beyond conventional patterns
Expands your design vocabulary
Reveals creative solutions to common problems
Builds intuition for when to break rules effectively

Action items:

Create a swipe file of inspiring designs
Note specific techniques, not just "looks nice"
Try applying these techniques to your own projects
Understand the "why" behind each decision

Rebuild Your Favorite Interfaces

The absolute best way to notice design details:

Pick an interface you admire
Try to rebuild it pixel-perfect
You'll discover dozens of subtle details you didn't notice at first
Learn spacing, sizing, color, and hierarchy decisions

What you'll learn:

Exact spacing values used
Color palette relationships
How hierarchy is established
Typography pairings and scales
Shadow and depth techniques
Responsive behavior patterns

Practice approach:

Start with components (buttons, cards, forms)
Progress to full pages
Don't look at the code - use your eyes
Compare your result with the original
Iterate until it matches

Rebuilding is a study method, not a claim of authorship. Record the source and name the detail you are learning. Attribution does not grant permission: do not ship or distribute substantially similar work without an applicable license or the creator's permission. For product work, introduce real constraints and combine lessons from several references until the result solves your problem in its own way.

Learn Through Runnable Prototypes

A static mock shows an intended result. A runnable prototype exposes whether the interaction actually feels right. Use code for the uncertain part early, then learn by changing one variable at a time.

Isolate one interaction before placing it inside a full product shell. Remove surrounding layout and state that do not affect the question you are testing.
Play with the result instead of only watching it. Interrupt it, resize it, repeat it quickly, and try the keyboard and touch paths.
Change one variable at a time. When a change improves the feel, record the principle behind it rather than only preserving the final value.
Keep useful experiments easy to revisit. See Build Complex Examples as Standalone Components in ui/component-architecture.md.
Treat failed versions as evidence. The gap between the idea and the behavior is where the most reusable design knowledge appears.
Save snapshots of useful iterations as code, screenshots, or short videos. A discarded direction may become scaffolding for a later one.
Put high-frequency state on screen while debugging. A compact <pre> with positions, velocity, active index, and gesture state is often more useful than a console stream.
Bind hard-to-reach states to temporary keyboard shortcuts. Toggle loading, error, expanded, interrupted, and rapid-update cases until the interaction tolerates repeated input.
Inspect complex motion in slow motion and frame by frame. Keep before and after captures framed identically so reviewers can compare the changed behavior directly.

Debugging "This Feels Off"

"This feels off" is one of the most common pieces of design feedback and one of the least actionable if you take it literally. But most of the time it points to something very concrete. The problem is that the diagnosis hasn't been translated yet.

Debug in this order:

Layout: Is the structure or grouping unclear?
Spacing: Are relationship patterns inconsistent? (same gap used for unrelated relationships, or different gaps for the same type of relationship)
Type hierarchy: Is it strong enough? (title and body text too similar in weight/size, primary and secondary actions have equal visual emphasis)
Color & emphasis: Is secondary information too loud? (helper text visually louder than the control it supports, metadata competing with primary content)
Motion: Does the transition match the interaction? (dropdown fading instead of sliding from trigger, spring overshoot in a serious admin tool, skeletons pulsing too aggressively on fast-loading surfaces)
States & affordance: Does the component behave the way it visually suggests? (tight hit area, wrong shadow depth implying a depth system nothing else follows, mismatched radius vs rest of product)

Common culprits:

Spacing inconsistency — the most common one. The eye notices before the brain names it.
Wrong alignment anchor — elements aligning to different baselines makes the list feel wobbly
Weak hierarchy — multiple claims about what matters most. Fix often means reducing emphasis, not adding more.
Motion-language mismatch — animation technically smooth but contextually wrong
Copy length breaking balance — real content no longer fits the assumptions of the composition

"This feels off" is not bad feedback. It's compressed feedback. The job is to decompress it into something you can actually change.

Run a Five-Pass Clarity Audit

When a screen is difficult to evaluate as a whole, review it through five separate questions:

Copy: is the benefit obvious, the language specific and conversational, predictable doubts answered, and every remaining line necessary?
Layout: are related elements grouped, zones legible, alignment anchors consistent, and the reading path obvious without hunting?
Emphasis: does the first thing noticed match the screen's goal, and does that hierarchy survive a blur or squint test?
Accessibility: is the key action visible without searching, operable without precision, understandable without guessing, and robust under permanent, temporary, and situational constraints?
Reward: after a meaningful moment, does the interface confirm what happened and create the right sense of control, competence, or recognition without overdoing it?

Treat the passes as a loop, not a waterfall. Removing copy may reveal a layout opportunity; changing placement may break proximity; adding a reward may compete with the primary action. After every major change, re-scan the earlier passes.

Score to Align, Not to Pretend at Precision

A quick score can turn "I don't like it" into a useful design conversation. Give each audit pass a rough 0–5, then use the numbers as prompts rather than truth.

Prioritize: start with the lowest pass or the one most critical to the user's current goal.
Align: compare scores across the team. A large disagreement exposes different assumptions worth discussing.
Improve by one: ask what concrete change would raise the weakest pass by one point. This produces a smaller and more testable next iteration than "make it better."
Re-score: repeat after the change to catch regressions and decide whether the next pass now matters more.
Let the work rest: revisit after 15–30 minutes for a small task or a day or two for consequential work. Distance makes weak copy, misplaced emphasis, and unnecessary decoration easier to see.

The score is a map of strengths and weaknesses, not a quality grade. The more useful closing question is: what observable change would make this pass excellent for this specific user and context?

When to Break These Rules

These are guidelines, not laws. Break them when:

You have a good reason
User experience benefits
You're intentionally creating contrast or tension
Your specific use case demands it
Testing shows users prefer something different

But always break them intentionally, not accidentally.

Noticing

Good taste begins with sustained attention. Instead of deciding that something is simply good or bad, stay with it long enough to identify the exact decision that produced your reaction.

Notice moments such as:

hesitation before an action;
a result that differs from what you expected;
an unexplained change in emotion;
an element that feels missing, assumed, or out of place;
a detail whose visual quality or physical feel changes the whole experience.

Treat each observation as evidence. A useful critique explains the relationship between a detail and its effect: “The action feels uncertain because its label describes the process rather than the outcome” is more actionable than “The button is confusing.”

Practice by choosing a familiar product and spending ten uninterrupted minutes with one flow. Record what you expected, what occurred, how the difference felt, and which detail caused it. Familiarity makes this harder—and therefore more valuable—because the mind normally stops seeing what it already knows.

Conceptual Range

The first plausible solution is usually a restatement of the existing problem. Before refining it, generate alternatives that change the structure of the experience, not merely its color, shape, or arrangement.

For example, a prompt about choosing photos to back up may initially produce faster selection controls. A wider exploration asks whether selection should happen at all: perhaps backup is automatic, based on confidence, or triggered by meaningful events. The more important move is questioning the premise.

Ways to widen the search space:

add a constraint, then remove a presumed constraint;
borrow a model from a different field;
ask what the experience would be if a step disappeared;
combine two incompatible ideas and inspect the tension;
make several deliberately extreme proposals before returning to a practical one.

Range is not ten visual variants of one concept. It is ten different explanations of what the product could be.

Conceptual Depth

Once a direction is chosen, stay with it beyond the first few respectable iterations. Early passes repair obvious omissions. Later passes reveal the decisions that make the work coherent, distinctive, and complete.

Imagine a ten-step quality scale. Moving from one to five often means correcting structure and hierarchy. Moving from five to eight means challenging each remaining assumption. The last increments tend to come from details that were never required but make the whole feel inevitable.

Four productive moves are:

zoom in until a broad concern becomes a specific decision;
remove anything whose role cannot be explained;
generate more versions of the weakest part, not the easiest part;
critique the work against its intended qualities rather than personal preference.

Depth is not polishing a weak concept forever. It begins after range has produced a direction worth pursuing.

Separation of Concerns

Architecture, content, visual style, and interaction each demand a different kind of attention. Trying to solve all four at once makes every decision noisy.

Name the question before choosing the artifact. A sketch can settle information order. A text document can settle language. A small coded playground can establish interaction feel. A high-fidelity composition can resolve material, typography, and optical balance.

The artifact should have only enough fidelity to answer the current question. When an unfamiliar interaction carries significant risk, build a breakable toy before placing it inside the product. It is faster to discover the right behavior in isolation than to disentangle it from a finished screen.

Define the qualities the product should project to the people using it. These are not generic aspirations such as “good” or “modern”; they are observable attributes such as calm, trustworthy, focused, supportive, fast, precise, or playful.

A lightweight quality model:

Choose four to seven qualities relevant to the product and context.
Rank them so tradeoffs have a clear direction.
Describe what each quality looks and feels like in behavior, language, and form.
Rate the current experience on a small scale.
Revisit the ratings after meaningful iterations.

The model creates a shared language for critique. Instead of debating whether a screen is attractive, the team can ask whether it feels calmer, whether it increased trust, and which decision caused the change.

Recreate Everything

When a detail prompts “How did they make that?”, rebuild it. Recreation converts admiration into a working mental model.

Use a rough playground, isolate the mechanism, and set a precise learning goal. Recreate the motion curve, masking technique, layout behavior, shader, control, or typographic treatment—not necessarily the surrounding product. Stop once the mechanism is understood and can be varied deliberately.

The point is not to produce a perfect replica. It is to shorten the distance between seeing an idea and being able to work with it. Share the experiment when doing so will sharpen the explanation or help someone else learn.

Industry Standards

People arrive with expectations formed by the products they use every day. Platform conventions, familiar navigation, readable hierarchy, responsive feedback, accessible controls, and reliable recovery form an invisible minimum.

An unfamiliar idea delivered below that minimum loses trust before its novelty can be appreciated. Start from established platform and product conventions where they remove cognitive effort. Depart from them when the alternative creates a meaningful advantage and is taught clearly.

The standard is a floor, not the ambition. Meet it consistently, then invest originality where it changes the experience.

Designing Library Cards

The card designer needs expressive range without exposing a wall of parameters. Presets provide strong starting points, while a few high-leverage controls reveal meaningful variation.

Color options are paired with one understandable intensity control. Graphic choices use recognizable shape primitives instead of unreadable miniature previews. Several wave parameters—frequency, phase, and amplitude—are coordinated so users can explore complexity without needing to understand the mathematics.

A two-dimensional curve can traverse a rich space of combinations; on a narrow screen, the same exploration can be mapped back to a linear control. The final compact toolbar is successful because it carries many outcomes through few decisions.

Archive Record

Founding member: Marvin Rudasingwa
Issued on: 01/13/26

Start with a Feature, Not a Layout

The Three-Second Test

One Screen, One Purpose

Screens Are Not User Stories

Prioritize What's Visible (P0 / P1 / P2)

Detail Comes Later

Don't Design Too Much

Think Like a Design Engineer

The Four Mandatory States

Choose a Personality

Fun Can Be the Differentiator (in the Right Context)

Limit Your Choices

Decide Between Options

Speed Does Not Remove the Review

Map the Customer Journey

Communicate Decisions to Stakeholders

Leveling Up: Continuous Improvement

Look for Decisions You Wouldn't Have Made

Rebuild Your Favorite Interfaces

Learn Through Runnable Prototypes

Debugging "This Feels Off"

Run a Five-Pass Clarity Audit

Score to Align, Not to Pretend at Precision

When to Break These Rules

Noticing

Conceptual Range

Conceptual Depth

Separation of Concerns

Facets of Quality

Recreate Everything

Industry Standards

Designing Library Cards

Further Reading Notes

The Princess Rescuing Application

Inventing on Principle

You Have Not Yet Heard Your Favourite Song

Magic Ink: Information Software and the Graphical Interface

What 'The Best' Looks Like

A Brief Rant on the Future of Interaction Design

First of Kind

Learnable Programming

The Power of Beauty in Communicating Complex Ideas

What Screens Want

The Web Hasn't Happened Yet

Dive Club

When We Build

Design Q&A, Charles Eames (1972)

Archive Record

Checklist

Use this guidance in your coding agent