/auto-ui-ux

Bring a codebase's interface to a finished, coherent, professional state — correctness, completeness, and cohesion — and keep iterating until a full pass finds nothing.

The failure this exists for: a project built in phases, each phase by a different hand with a different idea of what the UI should be. Two button components, three greys that are nearly the same grey, one screen with empty states and five without. Nothing is broken enough to file, and the whole thing reads as unfinished.

Step 0 — Mode, Scope, Freeze

Pick a mode. Ask once, then commit:

• INTERACTIVE (default) — you ask before each decision that has taste in it: palette, type, assets, which idiom wins. Best when the user has opinions, brand assets, or a client.
• AUTO — you derive the target system from what is already in the codebase and align everything to it on your own judgment, asking nothing. Best for a backlog of drift, or an unattended pass. AUTO still reports every judgment call it made, and still stops for anything on the freeze list.

Establish the freeze list before touching anything: screens, components, or brand elements that must not change. Anything the user is proud of, anything a client signed off, anything with an established visual identity. Absent instruction, the freeze list includes the logo, brand colors, and any screen the user names.

Cohesion beats novelty. You are extending an existing design language, not inventing one. Small feature-driven tweaks are yours to make. A new design system, a font change, a palette change, or restyling components that already work is a proposal, not an action — even in AUTO mode.

Pass 1 — Inventory And Drift

Enumerate the whole surface before changing any of it: every screen/route/view, every component, and every entry point. Then extract every hardcoded design value:

# colors: hex, rgb/rgba, hsl, and platform literals
rg -n --no-heading -e '#[0-9a-fA-F]{3,8}\b' -e 'rgba?\(' -e 'hsla?\(' -e 'Color\(0x' -e 'UIColor\(' -e 'Color\.[a-z]'
# spacing, radius, shadow, z-index
rg -n -e '\b(margin|padding|gap|inset)[^:]*:\s*[0-9]' -e 'border-radius|cornerRadius|clipShape' -e 'box-shadow|elevation|shadowRadius' -e 'z-index'
# type
rg -n -e 'font-family|fontFamily|FontFamily|\.font\(' -e 'font-size|fontSize|textSize|\.sp\b|\.dp\b'

Tally, don't just list. Forty distinct greys and six near-identical blues is the finding. Then hunt the structural drift:

• Two components doing one job (two buttons, two modals, two date pickers, two toast systems)
• Mixed idioms in one product — Tailwind beside styled-components, Material widgets beside Cupertino, two icon sets, two date formats, two casing conventions in labels
• Screens that never got the treatment the others did
• Components with no dark, hover, pressed, focus, or disabled variant while their siblings have them

Exclude before you count: generated files, vendored UI kits, dead code that no route reaches, per-brand theming that is intentional, and dark-mode variants — a second color set is not drift.

Record the inventory in .audit/ui-inventory.md. It is the checklist every later pass runs against.

Pass 2 — Choose The Target System

INTERACTIVE: ask, with concrete options rather than open questions. A non-designer cannot answer "what look do you want" but can absolutely pick between two rendered choices. Ask for:

• References and anti-references ("nothing like X" is the more useful answer)
• Brand assets: logo (SVG if it exists — raster logos cap the quality ceiling), icon set, fonts and whether they are licensed for embedding, imagery and its rights
• Palette direction, or approval of a palette you derived
• Density and tone: compact/comfortable, playful/serious

When the user has no assets, say what you will use instead and get one confirmation — do not stall the whole pass on a logo.

AUTO: derive the target from evidence, in this order:

1. Frequency and prominence — the color/type/spacing values that appear most, weighted toward the screens users actually reach.
2. Recency — git log the design files. The newest coherent idiom is usually the intended one.
3. Load-bearing-ness — the component with the most imports and the widest route coverage wins over the prettier one used twice.
4. Brand invariants survive regardless — brand colors and logo are never "outvoted" by frequency.

State the derived system and the reason each choice won, then apply it.

Consolidating values — the actual math, so this is defensible rather than vibes:

• Cluster colors by perceptual distance, not RGB distance. Use a real implementation — culori's differenceCiede2000() (a curried factory: differenceCiede2000()(a, b)) or colorjs.io's deltaE(c, '2000'). Do not hand-implement CIEDE2000 — the hue-wrap and rotation terms are where implementations diverge. Note chroma-js before v2.2.0 named a different metric deltaE, so old comparisons are not comparable.
• Snap spacing to a scale, but never snap a hairline — a 1px border is not a 4px border.
• Type: pick a scale and keep the existing hierarchy's relationships, not just its values.

Do not over-tokenize. A genuinely one-off value stays a one-off value.

If the project has a token format, use it. The W3C DTCG format has no concept of theme or mode — multi-mode is handled outside the format with parallel files sharing a key structure. Do not invent a $modes property.

Pass 3 — Correctness

Exact thresholds, cited. WCAG 2.2 Level AA is the operative benchmark — APCA is not the WCAG 3 contrast method (visual contrast was removed from WCAG 3 drafts in 2023 and its algorithm is undetermined), so do not audit against it.

Contrast ratio is (L1 + 0.05) / (L2 + 0.05) with L1 the lighter relative luminance; range 1:1–21:1.

Platform minimums are separate obligations from WCAG: Apple 44×44 pt; Android/Material 48×48 dp (≈9mm physical). Android states its contrast guidance in sp: below 18sp, or bold below 14sp, requires 4.5:1.

Measure every theme. There is no dark-mode success criterion because every contrast criterion applies independently to each color scheme you ship. Light-mode-only checking is the classic miss.

Automate what automates:

npx --yes @axe-core/cli http://localhost:3000 --tags wcag2a,wcag2aa,wcag21aa,wcag22aa
npx --yes pa11y-ci --sitemap http://localhost:3000/sitemap.xml

Valid axe tags include wcag2a, wcag2aa, wcag21a, wcag21aa, wcag22aa, best-practice, and per-criterion tags like wcag258. There is no wcag22a and no wcag21aaa. axe returns incomplete rather than pass when it cannot resolve a background (image, layered transparency) — those are manual checks, not passes.

Native: Flutter encodes the platform minimums directly (androidTapTargetGuideline 48×48, iOSTapTargetGuideline 44×44, textContrastGuideline), though its contrast check partitions colors naively and should be treated as a smoke test. iOS has XCUIApplication.performAccessibilityAudit() (Xcode 15+), which fails the test on findings with no explicit assertion. Android's Accessibility Scanner runs the same Accessibility Test Framework as the Espresso/Compose checks.

State the honest coverage in the report: automation catches roughly 20–30% of WCAG success criteria, or ~57% of issue instances on real pages by Deque's measurement — the two numbers have different denominators and neither means "mostly covered". Keyboard order, focus management, labeling sense, and whether the flow is usable are manual.

Pass 4 — Wiring: Does The Control Actually Do Anything?

A UI audit that only judges appearance will pass a screen full of buttons that do nothing. Every interactive element gets traced from the control to the effect.

For each control, name the handler, then name what the handler actually reaches — a state change, a network call, a file write, a rendered frame. A control whose trace ends in nothing is broken, no matter how good it looks. The recurring shapes:

• An onClick / onPress bound to an empty lambda, a TODO(), a no-op, or a handler that only logs
• A handler wired to the wrong target — the copy of the function that is no longer called, an older duplicate component, a stale route
• A control bound to state nothing reads, or reading state nothing writes (the config-parity diff in the previous pass finds the settings version of this)
• A form that validates and never submits; a submit that posts to a dead endpoint
• A feature flag defaulting off, so the control renders and is inert
• A navigation target that no longer exists, or a deep link no route claims
• A callback parameter left null, defaulted, or dropped through a refactor
• A control disabled by a condition that can never become true

Find them by tracing, not by looking:

# handlers that are empty, TODO, or log-only
rg -n -B2 'on(Click|Press|Tap|Change|Submit)\s*=\s*\{\s*\}' 
rg -n 'on(Click|Press|Tap)\s*=\s*\{[^}]*\b(TODO|FIXME|Log\.|console\.log|print)\b[^}]*\}'
# declared-but-never-referenced handlers and routes
rg -n 'fun handle[A-Z]\w*|const handle[A-Z]\w*' -o | sort -u   # then grep each name for a call site

Then drive it. Static tracing finds the obvious cases; the subtle ones only appear when you click the control and read the logs. Anything that survives Pass 6's capture step gets exercised, not just photographed.

When a break is found:

1. Report it as a wiring defect, separate from cosmetic findings — it is a different severity and a different fix.
2. Offer to correct it, with the specific fix named: which handler, which target, what it should reach.
3. Then run /auto-audit before continuing the loop. A disconnected control is rarely alone — it means a wiring pass was skipped somewhere, and auto-audit is the skill that traces runtime paths end to end across the whole project rather than screen by screen. Fold its findings back in and re-enter this loop at Pass 1.

A UI pass that fixes the paint on a dead button has made the product worse: it now looks finished.

Pass 5 — Completeness

Per screen, the state matrix. A screen missing these is unfinished no matter how it looks:

initial · loading · partial · empty · error · offline · permission-denied · unauthenticated · rate-limited · success

Then per flow:

• Navigation — Android back (gesture and hardware), iOS swipe-back, browser back, deep links, state restoration after process death, modal dismissal rules, unsaved-changes guards
• Forms — validation timing, inline errors, error focus management, keyboard types, autofill, submit-on-enter. A disabled submit button is an anti-pattern: it is typically unfocusable, often skipped by screen readers, exempt from contrast rules so it renders illegibly, and it removes the mechanism that would have told the user what is wrong.
• Destructive actions — confirmation, and undo where undo is possible
• Cross-cutting — dark mode, RTL, localization and string expansion, dynamic type / font scaling, safe areas, keyboard avoidance, breakpoints, landscape, tablet, reduced motion, first-run and empty-database states
• Every interactive element has hover, pressed, focus, and disabled states — or a documented reason it does not

Config parity: every config option gets a UI surface in the existing settings pattern, and file-based config stays in sync with it — unless the user says an option is deliberately file-only. An option that exists in a config file and nowhere in the UI is an unfinished feature.

Pass 6 — Apply, In Reviewable Batches

Never one giant diff. Batch by screen or by token — whichever produces a diff a human can actually approve — and checkpoint between batches. Back up before editing per the project's convention, and log what changed so a single change can be reverted on its own.

Token migrations go through codemods where the codebase supports it, staged per directory, verified per batch. A find-and-replace across a design system is how you discover that three of those greys were load-bearing.

Pass 7 — Look At It

A UI change is not done because the code changed. Capture and actually view the result, for every theme and breakpoint you touched:

npx playwright screenshot --viewport-size=390,844 http://localhost:3000/ shot-mobile.png
# in tests: await expect(page).toHaveScreenshot('home-light-1280.png', { fullPage: true, maxDiffPixelRatio: 0.01 })
adb exec-out screencap -p > android.png
xcrun simctl io booted screenshot ios.png   # simulator — use a real device where policy requires it
flutter test --update-goldens

Headless Chrome's --screenshot works only in headless mode — the same command without --headless writes no file and exits silently — and never captures beyond the window box.

Capture from real hardware where it is attached and where the project's device policy requires it — a simulator renders fonts, safe areas and scaling differently enough to hide exactly the bugs this pass is looking for.

Kill the flake sources before diffing: disable animations, mask timestamps and dynamic content, pin device scale factor, install the fonts. A green visual diff where both sides are broken is not a pass.

Lay captures side by side across screens to judge cohesion — that comparison is the only way drift is visible, because each screen looks fine alone.

The Anti-Slop Constraints

An AI "redesign" has a recognizable smell. If the result has these, it is worse than what it replaced:

• System default fonts, or the same three fonts every generated site uses
• Unmotivated gradients, glassmorphism, or a purple-to-blue hero
• Emoji standing in for icons
• Centered hero + three feature cards, regardless of what the product does
• Motion with no purpose, or inconsistent durations and easing
• A palette with no relationship to the brand that was already there
• Cosmetic polish over screens whose actual problem is a missing empty state

The constraint that prevents all of it: derive from what exists, change the minimum that achieves cohesion, and justify every choice against evidence in the codebase or an answer from the user.

Never restyle something that already works to match a preference nobody expressed.

Iterate Until Finished

Loop: inventory → target → correctness → wiring → completeness → apply → look → inventory again. Stop when a full pass finds nothing. One pass never does — the second pass always finds screens the first one changed inconsistently.

If any pass found a wiring break, the loop is not done until /auto-audit has run and its findings are folded back in. A dead control is evidence that something upstream was never connected.

Finished means: one visual language across every screen; the state matrix filled on every screen; AA thresholds met in every theme; platform target minimums met; every interactive element has its full state set and demonstrably does something; and you have looked at every screen you touched, in every theme and breakpoint.

Rationalization Table

Red Flags — Keep Working

• Claiming a UI change works without a screenshot you looked at
• Auditing contrast in one theme only
• Restyling components on the freeze list, or changing fonts/palette without sign-off
• A single enormous diff across the whole design system
• Consolidating tokens without perceptual-distance math behind the clusters
• Reporting "polished" while screens still lack empty, error, or offline states
• Deriving a target system in AUTO mode without stating why each choice won
• Polishing a control without tracing what it actually does
• Finding a wiring break and continuing the loop without running /auto-audit
• Ending after one pass