A prompt for standardizing vibe-coded apps. Give it to your AI coding agent — it audits your UI, diagnoses inconsistencies, and builds a phased plan to fix everything.

FOR-HUMANS.md

Design System Retrofit

This file is for you. The file you paste into your AI agent is PROMPT.md.

An idea file for AI coding agents. Give it to Claude Code, Cursor, Codex — it audits your UI for inconsistencies, diagnoses root causes, and builds a phased fix plan custom to your codebase.

How to use

1. Copy PROMPT.md
2. Paste into your AI coding tool at the root of your project
3. The agent audits, diagnoses, and builds a plan
4. You approve, then execute phase by phase in fresh sessions

What the agent does

1. Audits — Scans every page for spacing drift, hardcoded colors, component drift, typography inconsistency, broken responsive grids, inconsistent interactive/empty/loading states
2. Diagnoses — Primitives problem, composition problem, tokens problem, or all three? How many files? What breaks if you change your theme?
3. Plans — 4 phases: fix primitives → define patterns → migrate pages → enforce with lint + AI rules
4. Documents — Creates a design system doc, AI agent rules, and lint rules that cross-reference each other
5. Asks about tooling — Optionally splits heavy lifting (Codex) from config/hooks (Claude Code)

Before & after

Before: "Add a summary section." The AI looks at 3 existing pages, picks values from each, produces something subtly different from all of them. p-4 here, p-6 there. bg-white instead of bg-card.

After: "Add a summary section." The AI reads the design system, imports the right components. 30 lines, looks exactly like every other section. One way to do it right, and it's the easiest path.

After implementation

• Theme changes — One file. Change CSS variables, everything updates.
• New pages — Compose from shared components. Visual structure is handled.
• Adding features — Content decisions, not style decisions. Components enforce the rest.
• Onboarding — Human or AI reads the design system doc and knows what to use.
• Catching drift — ESLint fails on bg-white instead of bg-card. CI catches it, not code review.

What this doesn't solve

• Design taste — Enforces consistency, not beauty. Ugly theme = consistently ugly.
• Complex one-offs — The system has an escape hatch for these.
• Backend issues — UI layer solution only.

Tips

• Run each phase separately. Verify with git diff before starting the next.
• ESLint rules are the strongest enforcement. AI rules are a complement, not a replacement.
• Delete the plan file when done. The design system doc is the permanent artifact.
• Works best with Next.js + Tailwind + shadcn/ui, but adapts to any React + CSS framework.

PROMPT.md

Design System Retrofit

Copy everything below into your AI coding agent. For context on what this does, see FOR-HUMANS.md.

Audit my codebase for UI inconsistencies, diagnose root causes, and build a phased plan to fix them. Planning only — don't implement anything.

Step 1: Audit

Scan every page and the app shell. Check:

• Spacing — page gaps, grid gaps, card padding, section spacing. List every variation with file:line.
• Colors — hardcoded (bg-white, text-gray-500) vs semantic tokens (bg-card, text-foreground). List each with its replacement.
• Component drift — multiple implementations of the same pattern (stat cards, KPI displays, badges, containers).
• Card/container overrides — pages fighting default shadows, padding, borders. If pages fight defaults, the defaults are wrong.
• Typography — heading sizes, weights, text colors inconsistent across same hierarchy level.
• Responsive — grids hardcoding column counts without mobile fallbacks.
• Interactive states — inconsistent hover, focus, transition patterns across similar elements.
• Empty/loading states — per-page implementations vs shared pattern.
• Badges/tags — inline hardcoded colors vs shared component.

Output as table: Pattern | Where (file:line) | What it should be.

Step 2: Diagnose

1. Root cause — primitives problem, composition problem, tokens problem, or all three?
2. Scope — how many files need changes?
3. Severity — what breaks on theme change? What looks wrong today?

Step 3: Plan

4 phases in this order:

1. Primitives + tokens — fix base component defaults, replace hardcoded colors with semantic tokens in shared components and app shell.
2. Patterns + layout components — create wrappers only if used 3+ times and encoding non-obvious decisions. Document sanctioned patterns. Build component gallery page if enough components exist.
3. Page migration — sweep pages to new patterns, ordered by visibility. Per-page checklist.
4. Enforcement — lint rules for CI, AI agent instructions (CLAUDE.md/.cursorrules), optional advisory hook.

Per phase list: exact files, what changes, the decision and why.

Step 4: Documentation

Create and cross-reference:

1. Design system doc (src/DESIGN_SYSTEM.md) — philosophy, pattern inventory, token map, spacing scale, anti-patterns.
2. AI agent rules (~10 terse lines referencing the doc).
3. Lint rules for programmatic enforcement.

Step 5: Ask about tool split

Before implementing, ask:

Split work between Codex (bulk: primitives, components, migrations, lint rules) and Claude Code (config, hooks, verification)? Yes → PLAN_CODEX.md + PLAN_CLAUDE.md. No → single DESIGN_SYSTEM_PLAN.md.

Wait for answer before proceeding.

Step 6: Write plan to file

Plan files must be self-contained (executable without other context), include exact prompts to paste into each tool, and marked as temporary (delete after implementation).

Rules

• Planning only. Don't implement.
• Be specific. File paths, line numbers, exact class names. Not "some pages" — dashboard/page.tsx:42.
• Fix primitives over wrappers. Wrong defaults → fix the base, don't wrap it.
• Don't over-engineer. 3+ uses AND non-obvious decisions required. Three repeated lines > premature abstraction.
• Include the app shell. Layout, sidebar, nav are part of the system.
• Respect the framework. Work within existing conventions. Don't introduce competing systems.