UI Consistency Guard

UI Consistency Guard

An agent building a new screen has no picture of the app it is adding to, so it invents: a new shade of blue, its own spacing, a button it wrote inline instead of the one the app already ships. Nothing is wrong locally; the app drifts anyway.

One habit fixes it: look at the existing app first, build from what is already there, and when you must invent, say so.

Modes

Read only the reference for the mode you are in. Mode A runs once per surface; Mode B is the common case.

Routing: if the task writes UI → check for UI-PATTERNS.md (repo root, or the nearest one up the tree from the files you are touching). Missing or its generated_at commit is far behind HEAD → Mode A first, then Mode B. Present and current → straight to Mode B.

Running the scripts

Two zero-dependency Node scripts (Node 16+) ship with this skill: scripts/scan-tokens.mjs (Mode A) and scripts/check-drift.mjs (Modes B/C).

Paths are relative to this skill's directory, not the user's repo — run them from the user's repo root with an absolute or skill-relative path, e.g. node <skill-dir>/scripts/check-drift.mjs. Both take --help. If Node is unavailable, fall back to reading and grepping by hand using the same rules.

Fast path

For a genuinely small change — one style value, one class, one prop — skip the planning ceremony. Read the pattern file's token tables, use a token, done. The full Mode B sequence is for new components and screens.

Non-negotiables

1. Reuse before you create. An existing component that fits wins over a new one, every time. A new component is a last resort that must be built from existing tokens and reported as new.
2. Never hard-code a design value that already exists as a token. Colours, spacing, radii, type sizes come from the app's source of truth.
3. Never block. If nothing existing fits, derive from the nearest existing value, use it, and flag it as NEW: in your report. Do not stop and wait for a human unless the decision is brand-level (a new brand colour, a new type family) — see the decision ladder in references/build.md.
4. Verify before you trust. UI-PATTERNS.md is a cache, not truth. Confirm a token still resolves in source before you use it. If the source moved, fix the pattern file in the same change.
5. Report drift instead of hiding it. Every UI change ends with what was reused and what is new.

When NOT to apply this

Consistency is the default, not a religion. Do not force it when:

• The user explicitly asks for something different — a redesign, a new visual direction, an A/B variant. Say once that it diverges from the current system, then build what was asked.
• Accessibility requires it. A contrast, hit-target, or focus-visibility fix outranks the token. Fix it, and note that the token itself may need to change.
• The surface is deliberately separate — a marketing/landing page, an embedded partner widget, an internal debug screen. Match that surface's patterns.
• The repo already enforces a real system — a tokens package, Tailwind config, MUI/Chakra theme, shadcn registry. Defer to it and point at it. Do not build a competing summary; UI-PATTERNS.md becomes a thin index over it.
• Greenfield. If there is almost no existing UI, there is no system to conform to. Say so plainly rather than extrapolating one from three files.

The one rule

Before you write a raw colour, a spacing number, or a brand-new component, ask: does this already exist in the app? Almost always it does. Reaching for the existing thing instead of inventing a slightly different new thing is the entire job.