oimiragieo UI fix — observe first
Rules
- Never diagnose a UI change from code alone — render, measure, cite. Runtime defects (contrast, overflow, wrap, responsive, hover/focus, layout shift, stacking) do not exist in the JSX. No measurement = not a finding.
- Fix correctness directly; settle taste with evidence. Prefer competitive pattern research (Vercel / Linear / Stripe and similar) over asking the user to invent aesthetic direction mid-fix.
Flow A — fix / improve an existing UI
- RENDER the live page at the layout’s target widths (typically 375 + 1440). Public pages → browser / DevTools MCP. Authed apps → a session that can see the real UI (logged-in browser automation when needed).
- OBSERVE with layered tools (automation alone misses a large share of issues;
Lighthouse is a floor, not conformance):
- axe-core for contrast, labels, ARIA, duplicate IDs.
- Computed-style WCAG contrast when axe cannot run (AA normal ≥4.5, large/UI ≥3.0).
- A11y tree, console errors, full-page screenshot.
- Keyboard pass: Tab from the top — visible focus, order, no traps, focus not obscured (WCAG 2.2).
- Reflow at ~320px / 200% zoom; 24px tap targets where relevant.
- Judge the whole page, not only your widget. Green per-control metrics do not mean the surface is done. Ask what the nearest sibling control offers that yours does not. Check fail-soft / session-scoped state / label wrap across navigation, not only at rest.
- PIN the defect with a cited measurement (ratio, px, element, axe rule).
- Split findings:
- Correctness (contrast, a11y, CLS, overflow, tokens, focus) → fix on
design tokens (
var(--*)), one class at a time; avoid raw one-off hex. - Aesthetic direction → research comparable products, pick a clear direction, ship quick wins.
- Correctness (contrast, a11y, CLS, overflow, tokens, focus) → fix on
design tokens (
- GATE with the project’s full typecheck / lint / test suite (not a scoped run that hides breakage). Prefer static a11y (e.g. eslint-plugin-jsx-a11y).
- SHIP via normal PR + CI.
- RE-RENDER to verify the fix and no regressions (dark/light/mobile as applicable). Track axe violations, contrast ratios, keyboard pass.
- Optionally score with
frontend-audit’s rubric; do not inflate scores.
Flow B — new UI
Declare design tokens first → generate (Claude Design / Figma / Stitch as appropriate) → assets → build on tokens → then Flow A observe steps.
Cross-references
frontend-audit— rubric after fixesai-wayfinders/ai-trust-builders/ai-governors— AI product UX patternsreal-user-qa— upstream QA scenarios when present