140 lines
8.1 KiB
Markdown
140 lines
8.1 KiB
Markdown
Run systematic **technical** quality checks on a native app (`ios` / `android` / `adaptive`) and generate a comprehensive report. Don't fix issues; document them for other commands to address.
|
|
|
|
This is a code-level audit, not a design critique. Audit from source (SwiftUI / UIKit / Compose / React Native / Flutter); no browser tooling or `detect.mjs` applies. Score against the platform reference(s): [ios.md](ios.md) / [android.md](android.md), both for `adaptive`. Read them before scoring if Setup hasn't already. The report skeleton mirrors [audit.md](audit.md); keep the two in sync when changing it.
|
|
|
|
## Diagnostic Scan
|
|
|
|
Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below.
|
|
|
|
### 1. Accessibility (VoiceOver / TalkBack)
|
|
|
|
**Check for**:
|
|
- **Missing labels**: interactive elements without accessibility labels, traits/roles, or state announcements
|
|
- **Reading and focus order**: illogical traversal, unreachable controls, focus lost on navigation
|
|
- **Text scaling**: fixed point sizes defeating Dynamic Type (iOS) or px instead of sp (Android); layouts that clip or overlap at large sizes
|
|
- **Touch targets**: below 44 pt (iOS) / 48 dp (Android), or crammed without spacing
|
|
- **Reduce Motion ignored**: parallax and large slides with no crossfade alternative
|
|
- **Contrast**: text failing contrast in either appearance, light or dark
|
|
|
|
**Score 0-4**: 0=Screen reader unusable, 1=Major gaps (unlabeled controls, no scaling), 2=Partial (labels exist, order or scaling breaks), 3=Good (minor gaps), 4=Excellent (labeled, ordered, scales cleanly, Reduce Motion honored)
|
|
|
|
### 2. Performance
|
|
|
|
**Check for**:
|
|
- **Slow startup**: heavy work on launch before first frame
|
|
- **Unvirtualized lists**: long content without FlatList / LazyColumn / List recycling
|
|
- **Main-thread jank**: synchronous work in scroll or gesture paths, dropped frames on 60/120 Hz
|
|
- **Wasted rendering**: unnecessary re-renders (React Native) or recompositions (Compose); missing memoization/keys
|
|
- **Image handling**: full-size images decoded for thumbnails, no caching
|
|
- **App weight**: bloated JS bundle or binary, unused dependencies
|
|
|
|
**Score 0-4**: 0=Janky everywhere, 1=Major problems (unvirtualized lists, slow launch), 2=Partial, 3=Good (minor improvements possible), 4=Excellent (fast launch, smooth scroll, lean)
|
|
|
|
### 3. Appearance & Theming
|
|
|
|
**Check for**:
|
|
- **Hard-coded colors**: raw hex instead of semantic system colors (iOS) / Material color roles (Android) / design tokens
|
|
- **Broken dark appearance**: missing dark variants, poor contrast in dark, quick inverts
|
|
- **Dynamic Color** (Android 12+): no static fallback scheme, or ignored where it fits
|
|
- **Off-platform materials**: hand-rolled blur/glassmorphism instead of system materials or tonal elevation
|
|
|
|
**Score 0-4**: 0=Hard-coded everything, 1=Minimal tokens, 2=Partial (tokens exist, inconsistently used), 3=Good (minor hard-coded values), 4=Excellent (semantic throughout, both appearances first-class)
|
|
|
|
### 4. Platform Conformance (CRITICAL)
|
|
|
|
Score against the loaded platform reference(s), including their slop tests. **Check for**:
|
|
- **Broken system gestures**: edge-swipe back disabled (iOS), predictive Back hijacked (Android)
|
|
- **Inset violations**: content under the notch, Dynamic Island, home indicator, status bar, or keyboard
|
|
- **Off-platform navigation**: custom global nav, overloaded tab bars, iOS patterns on Android or vice versa
|
|
- **Web-shaped controls**: HTML-style buttons, custom toggles, hover-dependent affordances
|
|
- **Icon drift**: mixed icon sets instead of SF Symbols / Material Symbols
|
|
- **AI tells**: the shared absolute bans still apply (AI palette, gradient text, hero metrics)
|
|
|
|
**Score 0-4**: 0=Web port (nothing native), 1=Heavy violations (3-4 kinds), 2=Some (1-2 noticeable), 3=Mostly conformant (subtle issues), 4=Fully native (a fluent user trusts every screen)
|
|
|
|
### 5. Adaptivity
|
|
|
|
**Check for**:
|
|
- **Stretched phone layouts**: tablet/iPad rendering a scaled-up phone UI instead of using size classes / window size classes
|
|
- **Orientation breakage**: landscape clipping, ignored, or locked without reason
|
|
- **Keyboard/IME handling**: inputs hidden behind the keyboard, no inset adjustment
|
|
- **Multitasking**: iPad Split View / Android multi-window breaking layout
|
|
- **Foldables**: hinge-unaware layouts on posture change (Android)
|
|
|
|
**Score 0-4**: 0=One screen size only, 1=Major breakage (landscape or tablet broken), 2=Partial, 3=Good (minor edge cases), 4=Excellent (adapts across sizes, orientations, and windowing)
|
|
|
|
## Generate Report
|
|
|
|
### Audit Health Score
|
|
|
|
| # | Dimension | Score | Key Finding |
|
|
|---|-----------|-------|-------------|
|
|
| 1 | Accessibility | ? | [most critical issue or "--"] |
|
|
| 2 | Performance | ? | |
|
|
| 3 | Appearance & Theming | ? | |
|
|
| 4 | Platform Conformance | ? | |
|
|
| 5 | Adaptivity | ? | |
|
|
| **Total** | | **??/20** | **[Rating band]** |
|
|
|
|
**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues)
|
|
|
|
### Platform Conformance Verdict
|
|
**Start here.** Pass/fail: does this read as a native app or a ported website? List specific violations. Be brutally honest.
|
|
|
|
### Executive Summary
|
|
- Audit Health Score: **??/20** ([rating band])
|
|
- Total issues found (count by severity: P0/P1/P2/P3)
|
|
- Top 3-5 critical issues
|
|
- Recommended next steps
|
|
|
|
### Detailed Findings by Severity
|
|
|
|
Tag every issue with **P0-P3 severity**:
|
|
- **P0 Blocking**: Prevents task completion. Fix immediately
|
|
- **P1 Major**: Significant difficulty or platform-guideline violation. Fix before release
|
|
- **P2 Minor**: Annoyance, workaround exists. Fix in next pass
|
|
- **P3 Polish**: Nice-to-fix, no real user impact. Fix if time permits
|
|
|
|
For each issue, document:
|
|
- **[P?] Issue name**
|
|
- **Location**: Screen, file, line
|
|
- **Category**: Accessibility / Performance / Theming / Conformance / Adaptivity
|
|
- **Impact**: How it affects users
|
|
- **Guideline**: The HIG / Material rule it violates (if applicable)
|
|
- **Recommendation**: How to fix it
|
|
- **Suggested command**: Which command to use (prefer: $impeccable adapt, $impeccable animate, $impeccable audit, $impeccable bolder, $impeccable clarify, $impeccable colorize, $impeccable critique, $impeccable delight, $impeccable distill, $impeccable document, $impeccable harden, $impeccable layout, $impeccable onboard, $impeccable optimize, $impeccable overdrive, $impeccable polish, $impeccable quieter, $impeccable shape, $impeccable typeset)
|
|
|
|
### Patterns & Systemic Issues
|
|
|
|
Identify recurring problems that indicate systemic gaps rather than one-off mistakes:
|
|
- "Hard-coded colors appear in 15+ screens, should use semantic colors"
|
|
- "Touch targets consistently below 44 pt throughout the tab bar and list rows"
|
|
|
|
### Positive Findings
|
|
|
|
Note what's working well: good practices to maintain and replicate.
|
|
|
|
## Recommended Actions
|
|
|
|
List recommended commands in priority order (P0 first, then P1, then P2):
|
|
|
|
1. **[P?] `$command-name`**: Brief description (specific context from audit findings)
|
|
2. **[P?] `$command-name`**: Brief description (specific context)
|
|
|
|
**Rules**: Only recommend commands from: $impeccable adapt, $impeccable animate, $impeccable audit, $impeccable bolder, $impeccable clarify, $impeccable colorize, $impeccable critique, $impeccable delight, $impeccable distill, $impeccable document, $impeccable harden, $impeccable layout, $impeccable onboard, $impeccable optimize, $impeccable overdrive, $impeccable polish, $impeccable quieter, $impeccable shape, $impeccable typeset. Map findings to the most appropriate command. End with `$impeccable polish` as the final step if any fixes were recommended.
|
|
|
|
After presenting the summary, tell the user:
|
|
|
|
> You can ask me to run these one at a time, all at once, or in any order you prefer.
|
|
>
|
|
> Re-run `$impeccable audit` after fixes to see your score improve.
|
|
|
|
**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters.
|
|
|
|
**NEVER**:
|
|
- Report issues without explaining impact (why does this matter?)
|
|
- Provide generic recommendations (be specific and actionable)
|
|
- Skip positive findings (celebrate what works)
|
|
- Forget to prioritize (everything can't be P0)
|
|
- Report false positives without verification
|