Ui Audit

---
name: ui-audit
description: >-
  Audit the app's visual design — colour, layout, spacing, typography, depth,
  iconography, imagery and motion polish — against a maintained criteria list, and
  drive it toward being genuinely beautiful and characterful while staying within
  the brand. Use when asked to improve the UI, make the app prettier/fancier/more
  polished/stunning, review the visual design, or tighten the look and feel. Plain
  UI only — never UX (no flows, steps, screen order or copy); accessibility is the
  accessibility-audit skill's job, and rethinking ONE screen at every width is
  screen-deep-dive's. Drives the real app in a browser over generated data.
  Produces a ranked report with before/after evidence; files issues only with
  your approval.
---

# UI audit

Two jobs: keep `criteria.md` current with what visual quality means for *this*
app, then judge the running UI against it and drive it toward something people
genuinely enjoy looking at — beautiful, polished, characterful — **within the
brand**.

**Read `.claude/skills/audit/audit-loop.md` first** — it owns the loop (research
gating, the critique test, how criteria change, the report format, and the rule
that findings only become issues with the user's approval). This file owns the
domain: what "good-looking" means here and how to see it truthfully.

Pass `--research` to force a research pass; otherwise the cadence in `criteria.md`
decides (90 days).

## The three fences (internalize these before anything else)

Everything this skill does lives inside three lines it must not cross. They are
the whole reason it can be trusted to touch a live product's look:

1. **Visual, never UX.** In scope: colour, layout, spacing, type, depth,
   radii/borders, iconography, imagery treatment, motion-as-polish, empty-state
   *visuals*. Out of scope: flows, step order, information architecture,
   navigation, what a control *does*, and copy/wording. Test: *does the fix
   change what the user sees, or what the user does?* Only the first is yours
   (U-R03). **This fence bounds the kind of change, not its size:** recomposing
   the *same* content — its size, weight, placement, framing, backdrop — is
   visual and in scope however dramatic the visual difference; changing *which*
   content or controls a screen has, or their order of use, is UX.
2. **Evolution, never rebrand.** Stay within the worn design's own tokens — Klassisch's `--brand`
   (`#c2410c`) and its markers, Der Tisch's felt/brass/paper (`public/js/designs.js`,
   `public/css/designs/tisch.css`) — and the `color-mix`-derived token families. The app must be
   recognizably itself tomorrow. Refine a ramp; never swap a design's palette (U-R02, U-R05). Which
   design is the default is the design programme's call (`docs/design/`), never an audit's.
3. **Above the accessibility floor, always.** `accessibility-audit` owns contrast,
   focus, target size, ARIA, keyboard and reduced-motion *compliance*
   (A-001..A-016). Never re-report those, and never propose a change that would
   fail one of them — beauty is achieved *above* the floor, not by lowering it
   (U-R04).

The goal is *more* character executed well, not the trendy minimalism that would
flatten a warm, playful board-game app into generic SaaS (U-013).

## Research sources (phase B)

Ask what has moved in **visual** design since `last-researched`:

- **Design-system and craft references** — Refactoring UI's visual principles
  (hierarchy, spacing, depth, colour), Material 3 and Apple HIG for their *visual*
  guidance (elevation, type scale, motion feel — not their component libraries or
  interaction patterns, which are UX), and current design-token practice.
- **Modern CSS that raises visual quality with no framework** — `color-mix`
  (already used), `oklch` for smoother ramps, `:has()`, subgrid. These fit the
  no-build-step architecture; a technique that needs a bundler does not. Container
  queries, view transitions and scroll-driven animation are settled (U-R07, U-R08).
- **Type and colour craft** — pairing, scale, optical sizing, harmonious accent
  ramps.

Then run the critique in `audit-loop.md` §C, filtered hard through U-013: for each
trend, ask *does this fit a warm, friendly, playful game companion, or is it
generic?* Settled conflicts are pre-recorded as the `U-R*` rejected criteria
(framework, rebrand, UX, a11y trade, hardcoded hex, illustration pipeline, among
others) — if research proposes one again, that is the ledger working.

## Seeing the UI truthfully (phase E) — this is most of the value

A UI audit that only reads CSS is nearly worthless; the finding *is* what the
screen looks like. So this runs in a real browser, and three things will each
ruin it if ignored.

### 1. Never audit against production data

`.claude/launch.json`'s default/`production-data` config points at the real
`data/` folder — the group's private rounds and members. A screenshot of that is a
data leak (`.claude/rules/no-reading-production-data.md`). Launch the committed
**`dev-temp-data`** config instead (`preview_start {name: "dev-temp-data"}`): port
3100, gitignored `.devdata/`, accounts + admin on. Seed it with generated data
(`test-data` skill) covering every screen you mean to judge — an empty Pokale tab
renders an empty state and tells you nothing about the populated one. Leave
`launch.json` unmodified; the `dev-temp-data` entry is permanent.

The dataset must be *pretty enough to judge*: a round with ~12 games across several
tags (some with real provider covers, some on the placeholder gradient), archived
and completed games, a finished session with a podium, an abandoned draw, and a
couple of rounds on different colour markers — viewed under **every design** in
`public/js/designs.js` (production serves the `enabled` ones; a dev instance offers
all of them, on Konto or via `?design=<id>`), never just one.

### 2. The Browser pane lies in ways that look like design bugs

All documented, none are app defects (`preview-pane-paint-artifacts.md`):

- `innerWidth`/`innerHeight` can be `0` after a navigation → everything measures
  `width: 0`. `resize_window` to a real size and re-probe.
- **Screenshots go blank after any programmatic scroll** — and screenshots are
  your primary instrument here, so capture **only right after a fresh `navigate`**,
  and navigate again rather than scrolling to reach a lower section.
- Lazy covers never load — the pane fires no IntersectionObserver at any viewport
  size — so the Regal grid can look empty: judge covers on the game-detail hero and
  the vote screen, which set `background-image` inline, not on the lazy grid.
- Clear the service worker after any `styles.css` edit or you are looking at stale
  bytes (`pwa-service-worker.md`, "Verifying a shell-asset change").

### 3. Judge at all three presentations

Walk every screen at **390 / 1024 / 1440** so you see the phone dock (<860), the
strip (860–1279) and the desktop rail (≥1280) — they are three different visual
compositions (`responsive-hub-tabs.md`, `responsive-content-width.md`), and a
change that flatters one can break another. Use `resize_window`.

## What to walk

Every surface, because inconsistency between them is the commonest finding:

Derive the list rather than trusting this one — the SPA screens from `resolveRoute`
in `public/js/router.js`, the standalone pages from `public/*.html` and the
server-rendered routes in `lib/app.js`. On 2026-10-04 it was:

- **Lobby & entry:** home/round list, new round, the first-start design chooser.
- **Round hub:** Start, Regal, Chronik, Pokale — and the dock, the strip and the
  rail as three separate looks.
- **Sub-screens:** game detail (the cover hero is a showcase surface), member, tags,
  the colour-marker picker, Einstellungen, move games, both archives, the
  wishlist, recommendations, the shelf profile.
- **Account & social:** Konto (with the design picker), profile, Freunde, inbox,
  „Was ist neu", Entdecken.
- **Session flow (visual only):** setup, a vote card, the finale/reveal, the
  results podium, the shared-vote page — judge the *look* of each; do **not**
  touch the flow (U-R03).
- **Sheets & popovers:** add game, link provider, support, the editors — one
  overlay language across all of them.
- **Empty / loading / error states** — the first impression surfaces (U-009).
- **Auth & standalone pages:** login/register (need accounts env on your throwaway
  instance), `kontakt.html` (feedback lands here), the legal pages, `/faq` and the
  guide pages — they carry their own token copy
  (`shared-constants-across-the-stack.md`), so check they still match the app.

## The big-picture pass — mandatory, after the walk

Detail findings (a drifted radius, a stray gap, a fifth shadow value) fall out of
the walk on their own; **courage does not**, so it is required explicitly. After
walking the screens, go back over each major surface and answer one question:
*what single change would most lift this screen?* Judge the screen as a
composition — does something lead (U-015)? do its large surfaces do any
atmospheric work, or is the background just there (U-016)? does it carry the
app's character, or could it belong to any app (U-013)? A screen can pass every
consistency criterion and still be dull — that dullness **is a finding**, not a
vibe to swallow because no grep can measure it.

**The report must contain at least one screen-level proposal per run** — or an
explicit, argued statement that no screen currently warrants one. "None
warranted" is a claim to defend screen by screen, never a default reached by
having spent the time on nits.

Two things keep this honest rather than reckless:

- **Bold ≠ out of bounds.** The Rejected ledger rejects *mechanisms* (a
  framework, a palette swap, new JS in the router) — it does not reject
  ambition. A bold recomposition of one screen using the existing tokens,
  existing CSS and existing markup is squarely in scope; the fences bound what
  *kind* of change is allowed, never how much it may improve a screen.
- **A screen-level proposal is a proposal, not a unilateral change.** It ships
  as evidence + mockup for the user to judge (issue via `create-issue`), so
  being ambitious costs the backlog nothing until the user says yes.

## Remedies — a tight polish PR, a token, or an issue

Two co-equal output classes, plus the token/rule fix that serves both:

1. **A polish PR through `implement`** — the default *for detail findings*. Group
   the small, high-confidence fixes (unify the shadow ramp, align the gutters,
   regularize the radii, tighten the type scale) into one reviewable change. Every
   change goes **through the tokens**, never a raw hex (U-001/U-R05), and stays
   inside `styles.css` — no new dependency, no framework.
2. **A design-token or a rule** — when the finding is really "there is no single
   source for X". Adding a `--shadow-1/2/3` elevation ramp or an `--radius-*` set to
   `:root` and migrating components onto it is the highest-leverage kind of fix, and
   a short `.claude/rules/` note keeps the next component on-system. A
   token-adherence assertion (no orphan accent/neutral hex; radii/shadows from the
   set) is a good mechanizable guard in the spirit of `test/content-width.test.js` —
   and if you add one, **break the CSS on purpose once** to watch it go red
   (`break-the-code-on-purpose.md`, `css-text-assertions-strip-comments.md`).
3. **A screen-level proposal through `create-issue`** — the expected vehicle for
   the big-picture pass's output, **not** an escalation path for oversized nits.
   One issue per surface, labelled `audit` and `ui`, deduped against open and
   closed issues first, carrying the mockup evidence below so the user judges a
   picture, not an adjective.

**Every finding carries before/after evidence.** A screenshot of the current state
and either a screenshot of the proposed state (make the edit on your throwaway
instance, clear the SW, capture) or a precise description of the change. An
aesthetic claim with no picture is not reviewable — and a UI change is exactly the
case where a human does the final visual sign-off, so give them something to look
at. For a **screen-level proposal**, a mockup made by injecting CSS overrides into
the throwaway instance (via `javascript_tool`, no source edit needed) is
sufficient "after" evidence — the evidence bar exists to make findings judgeable,
and it must never act as a size filter that lets through only what is cheap to
photograph.

## Do not report these

Settled in the Rejected ledger; re-raising them wastes the user's review: a
framework/Tailwind adoption (U-R01), any rebrand or default dark theme (U-R02), any
flow/UX/copy change (U-R03), anything that trades away the accessibility floor
(U-R04), a hardcoded shade instead of a token (U-R05), and an illustration/stock
pipeline (U-R06). Also do not relitigate the settled layout calls — the single
column width (`responsive-content-width.md`) and the tiles-vs-lists decisions
(`tiles-vs-lists.md`) — those are composition constraints you work within.

**Do not over-read the ledger.** Every entry above rejects a *mechanism* or a
*category of change* — none of them rejects ambition, and none is a precedent for
"keep findings small". Timidity is the failure mode this skill is most prone to:
a run that returns only spacing and radius nits while every screen stays visually
ordinary has not respected the ledger, it has ignored the big-picture pass.