Refactor UI

🪄 refactor-ui — Atomic UI Design & Interface Refactoring Engine

Systematically evaluate, refine, and refactor user interfaces using the 10 atomic heuristics of Wathan & Schoger's Refactoring UI, extended with modern techniques (container queries, WCAG 2.2, theming parity, z-scale discipline) distilled from a 127-source corpus of production UI skills. Design treated as deterministic, engineering-grade visual decisions — routed through six execution modes so the agent loads only what the task needs.

When to Use

Triggers (mode chosen by phrase, default review):

• "Review this UI / screen / component" — verdict + severity table, no edits.
• "Audit this UI for contrast, spacing, anti-patterns" — scripted scan + scored report.
• "Refactor this UI / make it look professional / improve this design" — the 5-step refactor.
• "Make all pages consistent / refactor the whole dashboard" — multi-page sweep.
• "Extract design tokens / too many grays / set up a type scale" — rename-and-centralize.
• "Final pass before launch / ship-readiness" — polish triage.

Anti-triggers:

• Extracting tokens from a live URL or screenshot without refactoring existing code — use designscope.
• Motion choreography, easings, entrance/exit sequences — use the animate skill (this skill owns only the static-cue rule).
• Backend logic, state architecture, or novel branding/illustration from scratch.

Quick Reference

Mode router (full contracts in references/modes.md)

The Atomic Heuristics

v1.1.0 additions (details in references/modern-techniques.md)

Concentric radius law (inner = outer − padding) · optical alignment & icon-stroke matching · container-aware responsive doctrine (components adapt to their container; logical properties; safe areas) · modern typography mechanics (60–75ch measure, line-height by role, size-specific tracking, tabular-nums, 16px mobile inputs) · named z-scale tokens (no raw 9999) · surface ladder via lightness steps in dark mode · theme parity (verify light AND dark) · static-cue rule (motion routes to animate).

Procedure

The 5-step sequence below is the improve mode. Every other mode has its own scoped procedure in references/modes.md — load only the mode you're running.

┌─────────────────┐     ┌─────────────────────┐     ┌──────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│ 1. Triage &     │ ──▶ │ 2. Structural &     │ ──▶ │ 3. Polish &      │ ──▶ │ 4. Verification &   │ ──▶ │ 5. Anti-Slop        │
│    Hierarchy    │     │    Spacing System   │     │    Visual Weight │     │    Contrast Oracle  │     │    5-State Coverage │
└─────────────────┘     └─────────────────────┘     └──────────────────┘     └─────────────────────┘     └─────────────────────┘

Step 1 — Element Inventory & Hierarchy Triage

1. Identify the Single Primary Focal Point: the one action or data point that matters most in this viewport section.
2. Assign Tiers (1 to 3): Tier 1 (key metric, main CTA, primary header) · Tier 2 (supporting text, inputs, table rows) · Tier 3 (timestamps, labels, breadcrumbs, hints).
3. Execute De-emphasis: tone down all Tier 3 elements before increasing the size of Tier 1.

Step 2 — Spatial Grid & Whitespace Architecture

1. Strip Border Soup: delete interior 1px borders dividing cards, rows, sidebar items.
2. Establish Proximity: label↔input gap-1.5 (4–6px) · between fields gap-4 (16px) · between sections gap-8–gap-12 (32–48px). Enforce the 2× grouping ratio.
3. Increase Breathing Room: cramped container → double inner padding (p-3 → p-6).

Step 3 — Typography, Color & Elevation Systematization

1. Apply the stepped type scale (page titles text-2xl–text-3xl bold/track-tight · section headers text-lg–text-xl semibold · body text-sm–text-base relaxed · metadata text-xs muted). Add the modern mechanics: measure cap, line-height by role, size-specific tracking.
2. Standardize color tokens (text-foreground → text-muted-foreground → /70); accent reserved for actionable targets.
3. Natural elevation: layered 2-part shadows, background surface shifts; concentric radius on nested elements; named z-scale.

Step 4 — Verification & Contrast Oracle

1. Run the mechanical receipts: bun refactor-ui/scripts/audit-ui.ts <paths> then bun refactor-ui/scripts/check-contrast.ts <fg> <bg> for every rendered text pair (normal + large). Paste outputs.
2. Verify WCAG 2.2 AA (≥4.5:1 normal text, ≥3:1 large text/UI components). A failure blocks completion.
3. Theme parity: re-check the surface in light AND dark.

Step 5 — The 5-State Anti-Slop Coverage Gate

1. Empty: dataset empty → soft icon, explanation, direct CTA.
2. Loading: pulse skeleton matching geometry (animate-pulse bg-muted) to kill CLS.
3. Error: inline non-blocking banner with human diagnosis + Retry.
4. Success: immediate confirmation (toast, badge, transient check).
5. Overflow: min-w-0 on flex items, truncate + title, line-clamp-2/3, responsive wrapping.

Pitfalls

• Happy-Path Blindness: shipping against mock data that is always present, short, and error-free.
• Invisible Focus Rings: outline-none without a focus-visible:ring-2 alternative — keyboard navigation must stay visible.
• Mismatched Nested Radii: the most common "feels off" cause — apply the concentric law.
• Viewport-Breakpoint Reflex: reaching for md: when the component should adapt to its container.
• Raw z-Index Values: z-[9999] leaks stacking across surfaces; use the named scale.
• Relying Exclusively on Font Size for Hierarchy: weight and muted color create contrast without size bloat.
• Centering Everything: left-align text by default; centered body copy reads amateur.
• Pure Black on Pure White: harsh optical vibration — use deep slate/zinc neutrals.
• Icons Without Optical Balance: size icons down 1 step and match stroke to text weight.
• Burying Actions in Low-Contrast Grays: never fail WCAG AA for aesthetics.
• Smuggled Redesigns: polish mode refines; it never conceals a redesign — say "recommend redesign" instead.
• Unsupported Findings: search hits are candidates; without Contract + Runtime + Correction proof, discard them.

Verification

Before signing off any mode:

• Mode contract honored: only the mode's reads/writes performed.
• Script receipts pasted: audit-ui.ts and check-contrast.ts outputs included when audit/improve ran.
• WCAG 2.2 AA: all rendered text/UI pairs pass — blocking gate.
• 5-State Anti-Slop Coverage: Empty, Loading, Error, Success, Overflow implemented and verified.
• Theme parity: surface verified in light and dark mode.
• Responsive proof: container/smallest/largest checks (or Not verified declared).
• Visible Focus Rings: all interactive controls have focus-visible states.
• Squint Test Passed: primary action unmistakable when blurred.
• Zero Arbitrary Values: spacing/sizes map 1:1 to scale tokens.
• Single Primary Action per section; proximity law upheld; no border overload.
• Honest verdict: Block if any HIGH or AA failure remains; unrun checks listed as Not verified.

📚 Disclosed Reference Guides

Mode contracts and the research additions live in references/ — load only what the running mode needs:

• modes.md — router table, per-mode procedures, report format, cross-skill routing.
• modern-techniques.md — v1.1.0 corpus-derived rules composing with the heuristics.
• 01-visual-hierarchy.md — Sizing, optical weight, and focal points.
• 02-typography-scale.md — Modular type scales and line-height ratios.
• 03-color-palette.md — Neutrals, primary brand, and semantic state hues.
• 04-spacing-layout.md — 4px/8px spatial rhythm and component layouts.
• 05-button-hierarchy.md — Primary, secondary, tertiary, and destructive button patterns.
• 06-visual-clutter.md — Eliminating border soup, redundant labels, and visual noise.
• 07-empty-states.md — High-value empty states, onboarding patterns, and action CTAs.
• 08-shadows-elevation.md — Directional lighting, layered shadows, and elevation systems.
• 09-contrast-accessibility.md — WCAG contrast formulas and accessible color pairing.
• 10-grouping-alignment.md — Gestalt proximity, alignment grids, and optical balancing.
• 11-five-state-anti-slop.md — Mandatory 5-state lifecycle coverage and anti-slop patterns.

📜 Attribution & Licensing

• Original Principles & Methodology: Derived from the landmark design book Refactoring UI by Adam Wathan and Steve Schoger (© Tailwind Labs Inc.). All conceptual design principles belong to the original authors.
• v1.1.0 Modern-techniques layer: Clean-room synthesis from public agent-skill corpus research (container queries, WCAG 2.2, theming, z-scale discipline); independent formulation, no source text reproduced.
• Skill Formulation & Architecture: Engineered by Harsh Singh for the Muse Skills open-source ecosystem.
• Inspiration: Acknowledgment to George Nurijanian (gnurio/refactoring-ui-plugin) for the initial concept of packaging Refactoring UI rules for agent runtimes.
• License: MIT License. Compatible with all autonomous agent runtimes.