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)

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

Modes

Read the user message; default review.

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

Scope & budget (required defaults)

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)

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

Progressive disclosure (load only what you need)

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.

Mode fix

1. Implement one plan or slug.
2. Small diff; match ThemeData / tokens.
3. Re-run that rule’s Detect; note residual risk.

Dedupe rules

• Anti-clustering: if one Hunt yields many hits of the same slug, report one systemic finding — state the count and give 2–3 representative file:line samples. Don't spend the findings budget listing every hit.
• Cross-slug dedupe: if two different slugs both flag the same widget instance, keep the higher-severity finding and cross-reference the dropped slug in that finding's evidence line (e.g. "also matches min-touch-target").

Report self-validation (before sending)

• Every finding has existing file:line (or honest “project-wide absence” for opportunity rules)
• Every slug comes from a loaded surface file
• Every finding has Evidence + Why
• Count ≤ budget
• Subtle count is 0 under release unless user asked taste
• Did not implement in review mode
• Did not recommend architecture rewrites

Out of scope (explicit)

• Flutter web / desktop chrome (browser tab titles, OG tags, web-only transitions) unless user opts in with passes: web
• Brand redesign, new design system, package upgrades for their own sake

Hand off