# UI Fix Observe First

> Use when fixing, auditing, improving, or building ANY web UI — before reading or editing component code. Fires on contrast/a11y/overflow/responsive/hover-focus/layout complaints, "polish the UI", "audit the page/site", "make it premium", or any visual change (including a local authed dashboard).

- Skill: `oimiragieo/ui-fix-observe-first-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oimiragieo/ui-fix-observe-first-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oimiragieo/ui-fix-observe-first-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: oimiragieo (https://skillmd.com/u/oimiragieo)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/oimiragieo/ui-fix-observe-first-2

---


# UI fix — observe first

## The two rules (non-negotiable)
1. **Never diagnose or claim a UI change from code — 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. "It compiles" / "the JSX looks right" is not an observation.
2. **Correctness is yours to fix; taste is decided by evidence + council, not by asking the operator.** Aesthetic direction goes through current competitive research + the thinktank; you bring the operator the *result*, not the question.

## FLOW A — fix / improve an existing UI
0. Prompt fires the ui-observe-first hook → render before you read code.
1. **RENDER** the live page at **375 + 1440**. Public page → chrome-devtools MCP. **Authed dashboard (a local, session-gated app) → claude-in-chrome** with a live session.
2. **OBSERVE quantitatively — layered, not one tool** (automation catches only part of the problem surface; Lighthouse is a *floor*, not conformance):
   - **axe-core** (the engine — Deque, "zero false positives", what Lighthouse wraps a subset of). On a live claude-in-chrome page, inject + run it: `javascript_tool` → load `https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.x/axe.min.js` then `await axe.run()`. Catches contrast, missing labels, ARIA validity, duplicate IDs. Public page: use chrome-devtools Lighthouse + `performance_start_trace` (LCP/INP/CLS).
   - **computed-style WCAG contrast** (fallback / precise pin): `javascript_tool` computes the ratio of an element's `color` vs its effective bg (AA normal ≥4.5, large/UI ≥3.0). Use when axe can't be injected.
   - **a11y tree** (`read_page`) + **console errors** (`read_console`) + a full-page screenshot.
   - **Keyboard pass** (highest-leverage manual step, ~30% of automated-missed issues): Tab from the top — focus visible at all times? logical order? no traps? sticky nav doesn't steal focus (WCAG 2.2 focus-not-obscured)?
   - **Reflow**: check 320px width / 200% zoom for overflow. **24px tap targets** (WCAG 2.2).
3. **PIN** the exact defect — cite the measurement (ratio, px, element, axe rule id). No evidence = not a finding.
4. Split findings:
   - **4a CORRECTNESS** (contrast <4.5 AA, a11y, CLS, overflow, wrong-hex, light-mode, focus/keyboard) → fix directly, **one class at a time, on the design-token `var(--*)`** (e.g. `src/index.css` @theme tokens, never raw hex).
   - **4b AESTHETIC DIRECTION** (premium feel / how bold) → **do NOT ask the operator.** Use available web-research tools to study current authoritative competitive patterns (what Vercel / Linear / Stripe + A/B data actually do) → convene the thinktank / Workflow-council to decide the forks → ship the quick-wins, let the council settle taste; bring the operator the result.
5. **GATE**: check-types + FULL test suite, never a scoped run (e.g. `tsc -b` + `vitest run` + eslint). Add the static a11y layer where possible (eslint-plugin-jsx-a11y — 0 runtime cost).
6. **SHIP**: commit (subject <100 chars, lowercase) → PR → CI green. (a LOCAL-only dashboard has no hosted-preview step; "ship" = PR→CI-green.)
7. **RE-RENDER to verify** — the fix landed AND nothing regressed, at dark + light + mobile. A dashboard that serves a prebuilt static bundle needs a **rebuild first** (e.g. `npm run build` → restart the local server), then re-measure on the running instance. Track 3 numbers per page: axe violations, contrast ratios, keyboard pass.
8. **SCORE**: run the UI-quality rating pass → 9+.

## FLOW B — develop a new UI
Same spine, generate-step in front: 0. Declare the design tokens first → 1. Generate (claude.ai/design default; Figma if a designer must touch it) → 2. Assets (Figma MCP / claude.ai-design — **no aura.build in this env**) → 3. Build in `src/` on the tokens → then Flow A steps 2–8.

## Receipts (this process, proven 2026-07-03)
- Found the tertiary-text token failing WCAG AA (**3.85:1 measured** on cards) → lifted to `#868d99` (**5.56:1**), re-measured green → shipped as a token fix. A GLOBAL token fix that lifted every page at once.
- The AuthGate "low-contrast button" was a screenshot-eyeball **FALSE POSITIVE** — measurement showed **14.47:1 (AAA)**. This is exactly why rule 1 exists: measure, don't eyeball.

## Cross-references
- A peer-review council — for the 4b aesthetic-direction decision.
- Available web-research tools — for the 4b current competitive-pattern research (Vercel/Linear/Stripe).