# UI Consistency Guard

> Use when generating, editing, or reviewing user-facing UI in an existing codebase — a new screen, page, component, modal, form, list, card, empty/loading/error state, or any visual change — in React, React Native, Vue, Svelte, Angular, Flutter, SwiftUI, or plain HTML/CSS. Makes new UI reuse the app's existing colours, spacing, radii, type, and components instead of inventing new ones, and can review a diff for visual drift. Trigger even when the user never says "consistency", "design system", or "style". Do NOT trigger for copy/text-only edits, logic or data changes with no visual output, build/config files, or tests.

- Skill: `kashyap-savaliya/ui-consistency-guard` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add kashyap-savaliya/ui-consistency-guard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kashyap-savaliya/ui-consistency-guard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- License: MIT
- Author: kashyap-savaliya (https://skillmd.com/u/kashyap-savaliya)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kashyap-savaliya/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

| Situation | Mode | Read |
|---|---|---|
| No `UI-PATTERNS.md` for this surface yet | **A — Learn** | `references/learn.md` |
| Writing or changing UI | **B — Build** | `references/build.md` |
| Reviewing a diff, PR, or existing screen for drift | **C — Review** | `references/review.md` |

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.