Design First

An agent with a design system implements well, and an agent without one designs badly .

Define your palette, type scale, and spacing rules before the first UI prompt. Without them, each screen invents a new visual language.

Consistency Rather Than Quality

Individual components look polished, making drift hard to spot until comparing whole screens side by side.

Five kinds of drift account for most problems:

Color. Multiple shades of “the accent color”, each chosen independently.
Hierarchy. Panels with identical weight, or everything competing equally.
Spacing. 12px in one panel, 0.8rem in the next, 14px in the third.
Semantics. Red meaning danger on one screen, decoration on another.
Type. Five sizes two pixels apart, set to suit each component in isolation.

An agent without design constraints invents both the component and its visual language. The second invention is where drift originates.

Encoding the Rules

Settle the decisions that should not be left to an agent before the first UI prompt, so that its judgment applies to layout and behavior rather than to taste.

Color, Type, Spacing, and Layout

Color With Semantics. A palette needs rules attached. Each color must have a defined purpose. Agents apply rules reliably and never originate them. For example: vermilion = danger; ultramarine = sacred; verdigris = alive; gold = earned. Encode these in _variables.scss with semantic comments:

// Accent: emphasis, "give this importance"
$accent: #90E8F1;

// Interactive: controls the player can operate
$interactive: #4B9FFF;

// States
$error: #E05C72;
$warning: #E8A84A;
$success: #59F46B;

// Backgrounds, deepest to nearest
$bg-deep: #06090F;
$bg-surface: #0C1522;
$bg-elevated: #0f1e30;
$bg-overlay: #192C3E;

A token named $accent with “give this importance” is used correctly. A token named $blue2 is used at random.

Typography as Roles. Define what each typeface is for before sizing. Agents told “Cinzel for carved or titled text, EB Garamond for body, IM Fell for labels” place all three correctly in components never described to them. Set a minimum size and floor below which body copy may never drop. See Importing Fonts and Styling Text.

Spacing, Radius, Borders, and Shadow. These four need closed sets, not guidance. Spacing needs a scale covering panel gaps, row padding, and margins. Radius: “0 everywhere except circles”. Borders: 1px hairlines, 2px panels, 3px frames. Shadow: exactly two kinds, no colored glows except in one case. These constraints prevent drift better than per-component review.

Unit and Resolution. Settle fixed canvas or fluid layout, and the unit, before anything is built. Retrofitting is a rewrite. See Building Responsive Game UI.

Storing the System in the Repository

A design system described in a chat message survives until the context is trimmed. Written into _variables.scss, it is read fresh every time the agent opens the file, and it provides something concrete to reference in the instruction “use the existing tokens”.

Keep it where the project already keeps such files and reference it from the project instructions. See Managing Variables and Writing Maintainable CSS.

Starting Without a Design

Four options remain, ordered by how well each performed.

A real design with a written token list outperforms the rest. Use Claude Design or equivalent, with a handoff document covering the palette, semantic rules, type roles, spacing, and recurring ornaments. This reduces the agent’s task to translation rather than invention.

An existing screen to match performs nearly as well. Name it explicitly and point at the file. Agents extrapolate an existing system far more reliably than they originate one.

A reference image conveys layout and hierarchy accurately. Fine visual detail does not transfer.

Asking the agent to propose a system works only as a separate step before any component work. Have it produce a token file, review it, correct it, and commit it.

Starting from nothing and expecting coherence to emerge reliably fails.