ui-style-consistency

name	ui-style-consistency
description	Use when auditing a frontend codebase for duplicated UI components, inconsistent design-system usage, or hand-rolled variants of existing primitives. Triggers on "find duplicated components", "audit design system consistency", "find UI drift", or reviewing a component library for gaps.
license	CC-BY-NC-4.0

UI Unification Audit

Overview

Systematically find UI components and layouts that were intended to be unified but diverged. The core distinction: necessary layout variants (justified by different data/interaction needs) vs actual mismatches (shared primitive exists but is bypassed or duplicated).

When to Use

• Codebase has a components/ui/ or design-system layer but pages still hand-roll equivalent markup
• Multiple files import a shared component AND re-declare its base styles
• Components live under a domain folder but are imported cross-domain
• You see repeated style/class clusters across route files (cards, badges, buttons, empty states)
• Before a design-system refactor to identify highest-impact targets

Not for: Greenfield projects without existing primitives, pure CSS audits, accessibility-only reviews.

Core Pattern

1. INVENTORY  → Map shared primitives (components/ui/*, CSS utilities, global classes)
2. SEARCH     → Find all usages AND hand-rolled equivalents across routes/components
3. CLASSIFY   → For each candidate: necessary variant or actual mismatch?
4. RANK       → By confidence (primitive exists + bypassed = highest) and blast radius

Quick Reference

Signal	Likely Mismatch	Likely Justified Variant
File imports primitive AND re-declares its base classes	✅ Mismatch
Component in domain folder imported by other domains	✅ Misplaced
Decorative wrapper markup rendered manually when a wrapper primitive exists	✅ Bypass
Detail page header is richer than list page header		✅ Needs variant
Loading skeleton has different grid columns per page		✅ Geometry is page-specific
Empty state uses smaller padding in inline context		✅ Needs size variant
Selectable card in picker looks like button but isn't		✅ Different interaction model
Two components share 80%+ markup but differ in slots/regions	✅ Extract shell

Implementation

All commands use <...> placeholders. Adapt to your project:

Placeholder	Description	Examples
<ui-dir>	Design-system component directory	components/ui/, src/lib/components/, src/shared/
<src-dirs>	Directories with pages/routes/features	app/ pages/, src/pages/, src/routes/
<component-glob>	Component file extension glob	*.tsx, *.vue, *.svelte, *.component.ts
<import-prefix>	Import path to UI primitives	@/components/ui/, ~/components/ui/, $lib/components/

Phase 1: Inventory Shared Primitives

# List all UI primitives
ls <ui-dir>

# Find CSS design tokens / utility classes in your global stylesheet
# Match your framework's pattern: @apply/@layer (Tailwind), composes: (CSS Modules),
# styled.` (CSS-in-JS theme), or class selectors for design tokens
rg "<css-pattern>" <global-css-file>

# Find component exports — adapt regex to your framework's export convention:
# React: export (function|const), Vue: export default, Angular: @Component
rg "<export-pattern>" <ui-dir> -g '<component-glob>'

Phase 2: Search for Bypasses and Duplicates

Run all searches in parallel for maximum throughput.

A. Imports of each primitive — Identifies consumers. Files that import a primitive AND re-declare its styles are the strongest mismatch signal.

rg "from \"<import-prefix>" <src-dirs> -g '<component-glob>'

B. Hand-rolled equivalents — For each primitive identified in Phase 1, extract its signature class/style cluster (the 3-5 most distinctive CSS properties, utility classes, or styled definitions that define its visual identity) and grep for those patterns. Files that render these clusters WITHOUT importing the primitive are bypasses.

How to construct the grep for each primitive:

1. Read the primitive's source to identify its core visual classes (layout, border, typography, spacing)
2. Build a regex that matches the key classes in proximity, using .* between tokens to allow ordering variation
3. Exclude the primitive's own file from results
4. Also search for the primitive's CSS-in-JS equivalent if the codebase mixes approaches (e.g., makeStyles, styled.div, sx={{)

# Template — fill in per primitive:
rg "<key-class-1>.*<key-class-2>.*<key-class-3>" <src-dirs> -g '<component-glob>' -g '!<ui-dir>/*'

C. Structural bypasses via AST — Use ast_grep_search to find raw HTML elements that map to existing primitives. For each primitive, derive the HTML tag it renders and search for raw instances of that tag in page/component code.

# Templates — adapt per primitive:
pattern: <button $$$>$BODY</button>       # Potential button primitive bypasses
pattern: <dialog $$$>$BODY</dialog>       # Potential modal primitive bypasses
pattern: <table $$$>$BODY</table>         # Potential table primitive bypasses
pattern: <input $$$>                      # Potential input primitive bypasses

D. Cross-domain imports — Find components in domain/feature folders that are imported by other domains (misplaced shared components).

# For each domain folder, find its exports that are imported elsewhere.
# Adapt the path pattern to your project's domain/feature structure:
rg "from \"<import-root>/<domain>/components/" <src-dirs> -g '<component-glob>' --files-with-matches

Fuzzy match policy: Non-exact matches are included, not ignored. If a pattern is close but not identical to a known primitive (e.g., a card with slightly different padding, a button missing one hover variant) and the signal is strong that it was intended to use the existing component, include it in the candidate list. Err on the side of inclusion. If you cannot determine whether a candidate is a real divergence or an intentional difference, flag it and ask the user before dropping it.

Phase 3: Classify Each Candidate

For each divergence found, ask:

1. Does a shared primitive already exist for this role? If yes → likely mismatch.
2. Does the file already import the primitive? If yes → strong mismatch signal.
3. Is the divergence in styling or in structure/behavior? Styling-only → mismatch. Different slots/interactions → may need variant.
4. Is the component in the wrong directory? Domain component imported cross-domain → misplaced.
5. Would adding a variant parameter/prop to the existing primitive cover this? If yes → mismatch (missing variant). If no → may be justified separate component.

Phase 4: Rank and Report

Order by:

1. Primitive exists + bypassed (highest confidence)
2. Primitive exists + needs variant (high confidence)
3. No primitive exists + pattern repeated 3+ times (medium confidence)
4. Architectural misplacement (cross-domain imports)

Common Mistakes

• Treating all visual differences as defects. A detail page header being richer than a list page header is not a bug — it needs a variant, not flattening.
• Ignoring unused props/parameters on existing primitives. Parameters like color/size defined but never wired up indicate abandoned unification intent.
• Only searching imports. The worst mismatches are files that DON'T import the primitive — they hand-roll it entirely.
• Conflating loading skeletons with real components. Skeleton geometry is page-specific by nature; only the primitive toolkit location and bracket/overlay reuse are audit targets.
• Reporting without classification. A flat list of "these look similar" is not actionable. Always classify: mismatch vs justified variant vs needs-new-primitive.