flutter-pro-ux-review

Files (19)

• SKILL.md
• findings-template.md · assets/
• plan-template.md · assets/
• a11y.md · references/
• charts-numbers.md · references/
• data-display.md · references/
• example-run.md · references/
• experts.md · references/
• feedback-async.md · references/
• forms-keyboard.md · references/
• motion.md · references/
• performance-feel.md · references/
• platform-chrome.md · references/
• rule-catalog.md · references/
• scroll-layout.md · references/
• surfaces.md · references/
• touch.md · references/
• trust-safety.md · references/
• vs-official.md · references/

SKILL.md (first lines)

# Flutter pro UX review

**Version:** 1.1

**Job:** Find **user-visible** Flutter polish failures with grep-backed evidence.
Do not redesign brand, refactor architecture, or restate framework tutorials.

## Hard stops (other skills own these)

| User ask | Do this instead |
|----------|-----------------|
| Project structure / MVVM / layers | Official **flutter-apply-architecture-best-practices** |
| RenderFlex / unbounded height only | **flutter-fix-layout-issues** |
| Widget/integration tests only | **flutter-add-widget-test** / integration skills |
| React/web density / sticky CSS | **product-ui-craft** / **mobile-product-ux** |
| Full e2e device farm | **quality-check** |

If the message is clearly one of the above, **do not** run a full UX catalog pass.

## Modes

Read the user message; default **`review`**.

| Mode | Do | Stop when |
|------|-----|-----------|
| **`review`** | Hunt → ranked findings | After report; **do not implement** unless asked |
| **`plan`** | Selected finding(s) → `PLAN.md` | Plans written |
| **`fix`** | One plan or one slug | Diff done + re-Detect that rule |

Say the mode in the first line of your reply: `Mode: review | scope: lib/… | budget: 12`.

## Scope & budget (required defaults)

| Knob | Default | Notes |
|------|---------|--------|
| **scope** | User paths, else primary product UI under `lib/` (prefer `features/`, `ui/`, `screens/`, `pages/` over generated/test) | Never require boiling the whole monorepo |
| **budget** | **12** findings (Critical+Noticeable first) | Subtle only if budget remains or user asked `taste` / `strictness: taste` |
| **passes** | See default pass set below | User may name passes: `touch,a11y,forms` |
| **strictness** | `release` | `release` = Critical+Noticeable; `taste` = include Subtle |

**Primary path first:** prefer home, auth, checkout, pay, search, core tabs over settings chrome.

## Decision principles

1. **User cost** — flag taps, trust, and time lost; not style nits without effect  
2. **Primary path first** — core journeys before admin/settings  
3. **Prevent ≤ punish** — block bad input; don’t only error on submit  
4. **Stable layout** — images, numbers, async must not jump under the finger  
5. **Acknowledge intent** — press / success / error get feedback  
6. **Platform expectations** — back, swipe-dismiss, keyboard, status bar  
7. **Honesty under failure** — empty, offline, error, retry  
8. **A11y is polish** — unusable for some users → Critical  
9. **Budget attention** — top N by severity then effort; stop at budget  
10. **One fix, one verify** — no drive-by architecture in `fix` mode  

## Severity (with decision rules)

| Severity | When |
|----------|------|
| **Critical** | Broken primary interaction, trust failure, or blocker for some users (dead primary tap, “null” on primary UI, stuck modal, missing Semantics on primary icon button, no error/retry on primary async) |
| **Noticeable** | Every-session friction on common paths (layout jump, raw phones/dates, weak keyboard flow, missing haptics on primary actions, no bottom inset) |
| **Subtle** | Taste / secondary (exit timing, changelog, list edge fade) — omit under `strictness: release` unless budget allows and user wants taste |

If a rule lists two severities: **Critical on primary path / core widget; else Noticeable** (or Subtle when the rule says so).

| Effort | Meaning |
|--------|---------|
| **S** | Local one-liner / small helper |
| **M** | Cross-widget or shared util |
| **L** | Product surface (analytics, changelog, design-system) |

## Progressive disclosure (load only what you need)

| File | Load when |
|------|-----------|
| `references/surfaces.md` | **Always** in `review` (index + pass order) |
| `references/touch.md` | Pass `touch` |
| `references/data-display.md` | Pass `data` |
| `references/forms-keyboard.md` | Pass `forms` |
| `references/scroll-layout.md` | Pass `scroll` |
| `references/feedback-async.md` | Pass `feedback` |
| `references/a11y.md` | Pass `a11y` (default on) |
| `references/motion.md` | Pass `motion` (default off in `release` unless user asks) |
| `references/platform-chrome.md` | Pass `platform` |
| `references/performance-feel.md` | Pass `perf` (default off; on for `taste` or user asks jank) |
| `references/trust-safety.md` | Pass `trust` (default on — empty states, destructive confirm, permission priming) |
| `references/charts-numbers.md` | Pass `charts` (on when scope has charts/tables/signed numbers) |
| `assets/findings-template.md` | Emitting the report — see `references/example-run.md` for a good-vs-bad worked example |
| `assets/plan-template.md` | `plan` mode |
| `references/vs-official.md` | Only if tempted to refactor architecture |
| `references/experts.md` | **Never** during audit (attribution only) |
| `references/rule-catalog.md` | Legacy monolith — **prefer surface files**; load only if you need one-file search |

### Default passes

- **`strictness: release`:** `touch` → `a11y` → `data` → `forms` → `scroll` → `feedback` → `platform` → `trust` → `charts` (if scope has charts/tables/signed numbers)  
- **`strictness: taste`:** above + `motion` + `perf`  
- Skip `platform` analytics/changelog noise if no analytics SDK and budget is tight.  
- Skip `charts` entirely if scope has no data-viz/numeric surfaces.

## Workflow

### Mode `review`

1. Confirm Flutter app (`pubspec.yaml` with `flutter:`).  
2. Set scope, budget, passes (defaults above).  
3. Read `references/surfaces.md`, then **only** the pass files for this run.  
4. Hunt primary-path files first; record `slug`, severity, effort, `file:line`, evidence, why.  
5. Dedupe (see rules below); sort Critical → Noticeable → Subtle, then effort S → L.  
6. Cap at **budget**.  
7. **Self-validate report** (below).  
8. Emit findings. **Stop.**

### Mode `plan`

1. For each selected ID/slug: use `assets/plan-template.md`.  
2. Prefer existing project helpers; no new state-management library.  
3. One plan per finding.

From Evan-Kim2028/agent-skills, MIT.

More from Evan-Kim2028/agent-skills