mr-tbot/bot-code-mods/auto-ui-ux

/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.

1. Recency — git log the design files. The newest coherent idiom is usually the intended one.
2. Load-bearing-ness — the component with the most imports and the widest route coverage wins over

the prettier one used twice.

1. 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.

1. Offer to correct it, with the specific fix named: which handler, which target, what it should

reach.

1. 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: