Pin the agent to the existing typography scale — no magic font-size values

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.