improve-ux · diff
v0.2.0 to v0.3.0
49 added, 72 removed. Audit A to A.
---
name: improve-ux
description: Improve UI/UX of web interfaces by grounding every change in curated example sites and design references. Use when polishing a component, page, or design system - visual hierarchy, spacing, motion, empty states, accessibility, copy.
- version: 0.2.0
+ version: 0.3.0
---
# improve-ux
Improve a UI by grounding each change in concrete patterns from curated reference
- sites — then record which sites earned their keep.
+ sites and numeric standards — then record what helped, so both the reference
+ list and the target's progress get better run over run.
Taste comes **from the references**, not from memory alone. A change you cannot
- cite is an opinion; cut it or find support for it. Wherever a standard or number
- exists (WCAG, Material, DTCG), cite the **number**, not just the vibe.
-
- ## References
+ cite is an opinion; cut it or find support for it. Where a standard exists
+ (WCAG, Material, DTCG), cite the **number**, not the vibe.
- - [references/SITES.md](references/SITES.md) — curated example sites, grouped by focus
- - [references/SOTA.md](references/SOTA.md) — the SOTA baseline: numeric WCAG 2.2 rules,
- DTCG token spec, motion durations/easing, empty-state & a11y-automation guidance
+ ## Topic router — load only what the task needs
- Read **SOTA.md first** on any task — it's the ground truth for "what good looks
- like". Then pick sites from SITES.md for *visual* grounding.
+ | Task | Read first |
+ |------|------------|
+ | Accessibility pass | [references/sota/a11y.md](references/sota/a11y.md) |
+ | Animation / transitions | [references/sota/motion.md](references/sota/motion.md) |
+ | Colors, tokens, theming | [references/sota/tokens.md](references/sota/tokens.md) |
+ | Empty / loading states | [references/sota/states.md](references/sota/states.md) |
+ | Choosing a11y tooling | [references/sota/tooling.md](references/sota/tooling.md) |
+ | Any visual grounding | [references/SITES.md](references/SITES.md) — pick 1–3 sites by focus + `helped` ratio |
+ | Whole-review / deep dive | [references/deep-review.md](references/deep-review.md) — external skill bundle |
- For a whole-review grounding, [jakubkrehel/skills](https://github.com/jakubkrehel/skills)
- (listed in SITES.md) bundles ready-made agent skills — `better-ui`, `better-typography`,
- `better-colors`, `better-accessibility`, `better-layout`, `better-writing`, `interface-review`,
- `break` (render a component in every state) and `variant`. Install with `npx skills add
- jakubkrehel/skills` and drive them for deep, category-specific reviews instead of
- reinventing each checklist.
+ Never load every topic file "to be safe" — route, then read.
## Workflow
### 1. Understand the target
-
- What are you improving — component(s), page(s), flow? Note the stack
- (React/Tailwind/shadcn/vanilla) and the goal: visual polish, motion, clarity,
- accessibility. Ask the user only if genuinely ambiguous.
-
- ### 2. Pick references
-
- Read [references/SITES.md](references/SITES.md) and the ratings file:
-
- ```
- ~/.cache/skale-skills/improve-ux/ratings.json # may not exist yet
- ```
+ Component(s), page(s), flow? Stack, goal? **Check for an existing findings
+ ledger first** ([references/ledger.md](references/ledger.md)) — continue the
+ last pass instead of restarting from zero. Ask only if genuinely ambiguous.
- Choose 1–3 sites whose focus matches the task, preferring sites with a high
- `helped` ratio. On the first run (no ratings yet), any listed site is fine.
- Cross-check the relevant section of SOTA.md for the numeric standards you must
- meet (contrast, target size, focus, motion duration).
+ ### 2. Route & pick references
+ Topic router above → read that one file. Then pick 1–3 sites from SITES.md,
+ preferring high `helped` ratio (ratings protocol lives there).
### 3. Ground in real patterns
-
- Fetch the chosen references (`fetch-url` skill or `curl`) and extract **concrete,
- applicable patterns**: spacing scales, easing curves and durations, focus styles,
- empty states, copy tone. Do not stop at vibes — name the pattern precisely enough
- to implement it. For a11y, prefer automated verification (axe-core) over eyeballing.
-
- ### 4. Improve
+ Fetch the chosen sites (`fetch-url` / curl); extract concrete, applicable
+ patterns — spacing scales, easing curves, focus styles, copy tone. Name each
+ pattern precisely enough to implement it.
- Apply improvements to the actual code. Prefer small, reviewable changes. Each
- change cites its source pattern — and the number where one exists — in one clause:
+ ### 4. Improve — priority ladder, capped
+ Order: **a11y blockers** → **structure & hierarchy** → **interaction & motion**
+ → **copy & polish**. Stop or defer when a pass gets big (≤ ~7 kept changes);
+ deferred items go to the ledger. Every change cites its source in one clause:
> Button target padded to 44×44 CSS px (per WCAG 2.5.5).
- > Drawer slides 200ms ease-out (per emilkowal.ski/ui; exit faster at 150ms).
- Verify visually where possible — screenshot via `rodney` — and run an automated
- a11y check (axe-core) before calling it done.
+ ### 5. Verify
+ [references/verify.md](references/verify.md) — before/after screenshots via
+ `rodney`, plus axe-core for a11y. Not done until verified.
- ### 5. Record
+ ### 6. Record
+ - **Sites:** update ratings (protocol in SITES.md) — `helped` only for changes kept.
+ - **Target:** update the findings ledger — statuses, severities, deferred items
+ become the next pass's starting point.
- Update `~/.cache/skale-skills/improve-ux/ratings.json` (create if missing):
+ ## Keep the list fresh (update feature)
- ```json
- {
- "sites": {
- "emilkowal.ski": { "uses": 3, "helped": 3, "note": "best for motion decisions" },
- "ui.shadcn.com": { "uses": 2, "helped": 1, "note": "shadcn stacks only" }
- }
- }
+ ```bash
+ improve-ux discover [--x] # web-search (and X via peep) for new UX reference sites
+ improve-ux add <url> "<focus>" --group <heading> # verify + append to SITES.md
```
- For each site used this run: `uses += 1`, `helped += 1` only if it produced a
- change you kept. High `helped`-ratio sites get picked first next time. If a site
- keeps failing to help, say so and suggest dropping it from SITES.md.
-
- ## Adding sites
-
- When the user names a new site: fetch it once to verify it loads and matches the
- theme, append it to [references/SITES.md](references/SITES.md) with a one-line
- description, and let it enter the normal rating loop.
+ `discover` prints candidate rows (deduped against SITES.md and the discovery
+ cache, reachability-checked). Curate: pick sites that fill a gap, fetch once,
+ write a one-line focus, `add` them under the fitting group. Queries are
+ editable: [references/discovery-queries.txt](references/discovery-queries.txt).
## Rules
- - **Numbers over vibes.** Where a standard exists, cite the number (WCAG 2.5.8
- target ≥24px, 2.4.13 focus ≥2px perimeter @ 3:1, 1.4.3 contrast 4.5:1, motion
- 150–200ms desktop / ~300ms mobile, exits faster than entrances).
- - **Accessibility is never optional:** contrast, visible focus (`:focus-visible`,
- never `outline: none`), target sizes, `prefers-reduced-motion`. Verify with
- axe-core, not just by eye.
- - **Tokens:** prefer OKLCH for color ramps; express system-wide values as design
- tokens (DTCG format), not hardcoded literals.
- - One source of truth per pattern: cite the site, do not restate its whole doc.
+ - Numbers over vibes; cite the criterion — full tables live in the topic files.
+ - Accessibility is never optional; verify with axe-core, not by eye.
+ - Prefer OKLCH ramps + DTCG tokens over hardcoded literals.
+ - One source of truth per pattern: cite, don't restate.
+ - Small reviewable diffs; defer the rest to the ledger.