A UI consistency checklist you can actually run

The standard list asks questions like "is the look and feel of the interface consistent?" and "are labels used consistently?". Those are restatements of the goal. The person running the audit has to convert each one into something checkable, and they will do it differently every time — which makes the audit itself inconsistent.

A check needs three things to be worth having: a specific thing to look at, a way to look at it, and a condition that decides pass or fail. Everything below has all three.

Five minutes, no judgement required, and it finds a surprising share of real drift. Each of these should end up in CI once it passes; a check that only runs during audits lets drift accumulate between them.

1. 1

   Literal colour values outside the token file

   The single highest-yield check. Any hex in a component means the token layer was bypassed, and it means that colour cannot be changed centrally.

   Copy

   grep -rn --include='*.tsx' --include='*.css' -E '#[0-9a-fA-F]{3,8}\b' src \
     | grep -v 'tokens\|globals.css'

2. 2

   Font weights outside your band

   Weight is where hierarchy silently reverts to framework defaults. If your system says 400 and 600, anything heavier is drift regardless of how it looks.

   Copy

   grep -rn --include='*.tsx' -E 'font-(bold|extrabold|black)|font-weight:\s*[78]00' src

3. 3

   Spacing values off the scale

   Arbitrary-value escape hatches are where the rhythm dies. One p-[13px] is nothing; forty of them is a second spacing system nobody agreed to.

   Copy

   grep -rn --include='*.tsx' -E '\b(p|m|gap|space)-\[[0-9]+px\]' src

4. 4

   Radius values

   Radius drifts more than anything else because every component author picks what looks right in isolation. Count the distinct values in use; more than three or four is a finding.

   Copy

   grep -rhoE 'rounded-[a-z0-9]+|border-radius:\s*[0-9]+px' src -r \
     --include='*.tsx' --include='*.css' | sort | uniq -c | sort -rn

5. 5

   Properties your system forbids

   Whatever your prohibition list names. If it says elevation is never a shadow, this check enforces that. If you have no prohibition list, that is the finding — write one first.

   Copy

   grep -rn --include='*.tsx' --include='*.css' -E 'box-shadow|shadow-(sm|md|lg|xl)|gradient' src

The fourth check has a wrinkle worth naming: counting distinct radius values tells you about consistency, not correctness. Three values used deliberately — 6px on controls, 12px on containers, full on avatars — is a system. Three values that happen to be 6, 8 and 10 is drift that has not been noticed.

Here is the thing every audit process gets wrong. Reviewing a screen on its own tells you whether it is internally coherent. It tells you nothing about whether it matches the other screens, because you cannot hold the other screens in your head accurately enough.

So open three finished screens from the same surface side by side — three application screens, or three marketing pages, never a mix. Comparing a dashboard to a landing page produces differences that are supposed to be there.

The bottom three rows are where consistency work is nearly always weakest, and it is not carelessness — empty, loading and error states are written under time pressure, individually, by whoever happened to be in that file. They are also disproportionately what a frustrated user sees.

The six rows above are where drift concentrates. This is the complete list, grouped so you can work through it in one sitting. Each item has a pass condition rather than a question.

• Every colour in every screen resolves to a named role. Fails if any component contains a literal value.
• The accent appears on the same kinds of element across screens. Fails if it is a button on one screen and a heading on another.
• Status colours appear only for status. Fails if the success colour is used decoratively anywhere.
• Every light-mode colour has a dark-mode counterpart that was chosen, not derived. Fails if any surface is a straight inversion.

• Every size on screen is a step in the scale. Fails if you find a size that is not.
• Weights stay inside the declared band. Fails on any weight above it, however good it looks.
• The same semantic level looks the same everywhere — every page title matches every other page title. Fails if two screens distinguish their title differently.
• Numbers in columns are tabular and aligned. Fails if digits do not line up between rows.

• Every spacing value is a scale step. Fails on any arbitrary value.
• Distinct radius values are few and each has a stated purpose. Fails if you cannot say why 8px exists alongside 6px.
• Elevation is indicated the same way everywhere. Fails if shadows and borders are both in use for the same job.
• Section rhythm is consistent — the gap between a heading and its content is the same on every screen. Fails on any variation without a reason.

• One implementation per component. Fails if two files define a card.
• Primary actions look identical and sit in the same relative position. Fails if one screen puts it left and another right.
• Destructive actions are visually distinct and consistently so. Fails if delete looks like save anywhere.
• Interactive elements have a visible focus state, and it is the same state everywhere. Fails on any missing or divergent focus ring.
• Disabled states are visually distinct from muted content. Fails if a user cannot tell an unavailable control from de-emphasised text.

• Empty states use one treatment across the product. Fails on an illustration here and a sentence there.
• Loading uses one mechanism. Fails on a skeleton, a spinner and a blank flash across three screens.
• Errors appear in the same place with the same treatment. Fails on inline here, toast there.
• Error text says what went wrong and what to do. Fails on anything that only apologises.
• Long content truncates the same way everywhere. Fails if one place wraps and another ellipsises with no rule behind it.

• The same concept has one name everywhere. Fails if the interface says "project" in one place and "workspace" in another for the same thing.
• Buttons name the action they perform, and the confirmation echoes it. Fails on "Submit" followed by "Your changes were saved".
• Capitalisation follows one rule for labels, headings and buttons. Fails on mixed title case and sentence case.
• Dates, times and numbers use one format. Fails on two date formats in one product.

The first item in that group causes more real user confusion than any visual inconsistency in this article. Two names for one concept means the user maintains two mental models and cannot tell whether they are the same thing.

Once a quarter, audit the system rather than the interface. The question is not whether people followed the rules but whether the rules could be followed.

The first row is the one to check hardest, because a hedged rule looks like a thorough rule. If your guidance has caveats in it, the surfaces those caveats describe want separate documents — governance covers the structural version of this.

Two things, in opposite directions, and both change how you should run this checklist.

The mechanical pass becomes more important, because the volume of code has gone up and review capacity has not. An agent producing forty screens between reviews will reproduce any drift forty times before anyone looks. Automated checks are the only thing that scales with that.

The comparative pass becomes more important too, and for a subtler reason. An agent is extremely consistent *within* a file and has no memory across sessions, so its output is a set of internally-coherent screens that differ from each other. That is precisely the failure mode per-file review cannot see.

The root cause is usually upstream. We sampled 299 DESIGN.md files written to give agents design guidance: 86% specify colours as raw hex with no semantic role, 76% state no prohibitions of any kind, 69% define no dark mode, 57% name no motifs, and 44% contain no concrete size value anywhere. 54% rely on at least one vague adjective — "clean" in 39%, "modern" in 36%.

A file like that leaves the density, hierarchy, elevation and empty-state decisions unmade, so the model makes them fresh on every screen. Consistency findings against that guidance are real, and fixing them one screen at a time will not hold. How to write guidance that does.

If you have twenty minutes rather than a day:

1. Grep for hex values outside the token file. Every hit is a finding.
2. Grep for font weights above your band. Every hit is a finding.
3. Count distinct radius values. More than four, look at why.
4. Open three screens from one surface. Compare density, hierarchy, elevation.
5. Look specifically at their empty, loading and error states. This is where it will be worst.
6. Check whether your guidance has a prohibition list. If not, that is the fix that prevents the next round.

Steps one to three are automatable today and should never need running by hand again. Steps four and five need a person and are worth a recurring half-hour. Step six is the one that decides whether you are doing this again next quarter.