The new empty state looks “almost” like the others. Then you notice text-[17px], or font-size: 15px, or a line-height: 1.4375 next to a heading that should have been text-lg / font-size-300. The scale already had a step. The agent made a new one.

I’ve started treating magic font-size values in agent UI diffs as a scale violation, not a visual preference. One-off sizes are how products grow four “body” sizes that nobody can name.

Why agents invent sizes

  • The screenshot or mock was 17px, and the model copied the number
  • It didn’t have the scale (tokens, Tailwind theme, or type.css)
  • It “split the difference” between text-sm and text-base
  • A previous file already used a magic number, and the agent matched that file

Pixels in a design file are a hint. The scale is the contract.

What to hand the agent

Paste the scale, not a lecture. A compact table is enough:

Use only these typography steps (Tailwind / token): - caption: text-xs / font-size-100 (12/16) - body: text-sm / font-size-200 (14/20) - body-lg: text-base / font-size-300 (16/24) - title: text-lg / font-size-400 (18/28) - display: text-xl / font-size-500 (20/28) No text-[Npx], no font-size in px/rem unless you are extending the scale in the token file (out of scope). Pick the nearest step. Do not invent a 17px body.

If your scale lives in CSS variables or a typography.ts file, paste that slice. If you have a “banned CSS patterns” list, this rule belongs there too — this prompt is for typography specifically, even when the rest of CSS is looser.

A simple policy

  • UI copy and headings use the existing steps only
  • If a mock is off-grid by 1px, snap to the nearest step; don’t add a token in a feature PR
  • Line-height, letter-spacing, and font-weight should come from the same step (or the paired utility), not a one-off
  • Exceptions: a legal third-party embed you don’t style, or a canvas / chart label outside the design system — name them in the PR

Don’t turn this into a typography redesign. The goal is to keep the agent inside the scale you already ship.

How to catch it in review 

git diff -U0 -- '*.tsx' '*.css' '*.scss' | rg -n "text-\[.+\]|font-size:\s*[0-9]|line-height:\s*[0-9]|tracking-\[|leading-\["

For each hit: is it a scale utility / token, or a raw number? If it’s raw, ask the agent to replace it with the nearest named step and show which one.

If your lint already flags magic numbers (stylelint on font-size, or a custom ESLint rule for text-[), keep that on. The prompt still helps the first draft land clean.

Reject / send back

Reject

  • text-[17px], text-[13.5px], or font-size: 15px on product UI
  • A new heading style that’s just text-base plus a custom line-height
  • A feature PR that adds a one-off typography token “for this card”
  • Matching a stale magic number in a neighboring file instead of the scale

Accept

  • An existing step, even if the mock was 1px off
  • A documented exception at a true boundary
  • A separate design-token PR when the scale itself needs a new step

Tiny habit

When you ask an agent to build or restyle UI, paste the typography scale and forbid magic font-size values. Snap to the nearest step. The page will look like the rest of the product, and you won’t spend review time arguing about 17px.