mobile-visual-self-review
Use when you are about to hand off any change to a screen or component on a mobile repository - the size, text-scale and dark-mode matrix, the exact tool calls to see your own build, and the checklist that decides whether the screen is done.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 122
- Forks
- 18
01 前言 Front Matter
- name
- mobile-visual-self-review
- source
- ehmo/platform-design-skills (MIT), flutter/agent-plugins (BSD-3-Clause), android/skills (Apache-2.0), wshobson/agents (MIT), adapted
- category
- mobile
- description
- Use when you are about to hand off any change to a screen or component on a mobile repository - the size, text-scale and dark-mode matrix, the exact tool calls to see your own build, and the checklist that decides whether the screen is done.
03 SKILL.md 正文
Mobile Visual Self-Review
Overview
A green build and a passing widget test say the code compiles and the tree is what the test asserted. Neither says the screen looks right on a 360 phone at 200% text, on a tablet, in landscape, or in dark mode. Default assumption: the change is NOT done until you've looked at it rendered — be the skeptic here, not the advocate.
Core principle: two layers, always both. A matrix test in the suite catches overflow mechanically on every future change; looking at the rendered screen catches what a test assertion can't (a placeholder glyph, a clipped icon, invisible text in dark mode).
The matrix
360×640 (phone) · 430×932 (large phone) · 640×360 landscape · 768×1024 (tablet) — each at text scale 1.0 and 2.0, and in dark mode.
Layer 1 — a matrix test in the repo's test suite
Flutter (verified, Flutter 3.41.6 — 11/11 green after the fix below):
const sizes = <String, Size>{
'phone 360x640': Size(360, 640),
'large phone 430x932': Size(430, 932),
'landscape 640x360': Size(640, 360),
'tablet 768x1024': Size(768, 1024),
};
for (final e in sizes.entries) {
for (final scale in [1.0, 2.0]) {
testWidgets('PriceRow at ${e.key}, text x$scale, dark', (tester) async {
tester.view.physicalSize = e.value * 3;
tester.view.devicePixelRatio = 3;
tester.platformDispatcher.textScaleFactorTestValue = scale;
addTearDown(tester.view.reset);
addTearDown(tester.platformDispatcher.clearAllTestValues);
final handle = tester.ensureSemantics();
await tester.pumpWidget(host(PriceRow(title: longRealisticTitle, price: '1.299,00 TL', onAdd: () {}),
brightness: Brightness.dark));
expect(tester.takeException(), isNull); // overflow = FlutterError here
await expectLater(tester, meetsGuideline(androidTapTargetGuideline));
await expectLater(tester, meetsGuideline(iOSTapTargetGuideline));
await expectLater(tester, meetsGuideline(labeledTapTargetGuideline));
handle.dispose();
});
}
}
Verified result: Row[Expanded(title), price, IconButton] passes every case at text 1.0. At text 2.0 it fails — "A RenderFlex overflowed by 82 pixels on the right" at 360 (122 at 320, 12 at 430). The fix that passes all cases: wrap in LayoutBuilder; if constraints.maxWidth < 280 * MediaQuery.textScalerOf(context).scale(1), render Column[title, Row[Expanded(price), IconButton]] instead of the single Row. This is the ❌/✅ worked example for both this skill and mobile-ui-ux.
Compose: DeviceConfigurationOverride(ForcedSize(DpSize(360.dp, 640.dp)) then FontScale(2f) then DarkMode(true)) { ... } around the composable under test, repeated per matrix cell.
SwiftUI: #Preview with .environment(\.dynamicTypeSize, .accessibility3), .preferredColorScheme(.dark) and traits: .landscapeLeft (typechecks against the iOS 18 simulator SDK — verified) — plus snapshot tests if the repo already has them.
Layer 2 — look at the rendered screen
Pick the first path that applies:
(a) Host-local emulator/simulator — your own build.
mobile_launch_app {repository_id}— this takes the device lease and installs the build registered on the deploy target (the stage build), not your branch.- Put your own build on the device:
- Android, local emulator:
Native Android:flutter build apk --debug adb devices adb -s <serial> uninstall <pkg> # only needed on INSTALL_FAILED_UPDATE_INCOMPATIBLE adb -s <serial> install build/app/outputs/flutter-apk/app-debug.apk adb -s <serial> shell monkey -p <pkg> -c android.intent.category.LAUNCHER 1ANDROID_SERIAL=<serial> ./gradlew installDebug. - iOS, local simulator:
Native iOS:flutter build ios --simulator --debug xcrun simctl install <udid> build/ios/iphonesimulator/Runner.app xcrun simctl launch <udid> <bundle-id>xcodebuild -scheme <S> -destination 'id=<udid>' -derivedDataPath build build, thensimctl installthe.app.
- Android, local emulator:
mobile_wait_forthe new element →mobile_screenshot→mobile_rotate {orientation: landscape}→mobile_screenshot→mobile_rotate {orientation: portrait}.- Large text and dark mode, local only:
- Android:
adb shell settings put system font_scale 2.0andadb shell cmd uimode night yes; reset withfont_scale 1.0andnight no. - iOS:
xcrun simctl ui <udid> content_size accessibility-extra-extra-extra-largeandxcrun simctl ui <udid> appearance dark(simctl options verified). Reset withcontent_size largeandappearance light.
- Android:
- TalkBack proxy:
mobile_read_ui {filter: "clickable=\"true\""}— see below. mobile_release_deviceas your last mobile step.
(b) Remote/shared phone with no local install path. It shows the stage build only — use (c) or (d) to see your own change; say so in the closing message.
(c) Flutter widget previewer (no device needed, verified). Add @Preview(name: 'phone dark 2x', size: Size(360, 640), brightness: Brightness.dark, textScaleFactor: 2.0) beside the widget (import 'package:flutter/widget_previews.dart'). Run mkdir -p /tmp/tt-<task key> && flutter widget-preview start --web-server > /tmp/tt-<task key>/preview.log 2>&1 &. The log prints lib/main.dart is being served at http://localhost:<port>; then browser_navigate → browser_screenshot. The previewer runs on the web: a widget touching dart:io or a plugin needs a fake in the preview.
(d) Native screenshots over loopback. Start a loopback server over the screenshot directory, e.g. mkdir -p /tmp/tt-<task key> && python3 -m http.server 8799 --bind 127.0.0.1 -d <dir> > /tmp/tt-<task key>/shots.log 2>&1 & (py -3 instead of python3 on Windows). Then browser_navigate http://127.0.0.1:8799/<file>.png → browser_screenshot. file:// is refused by the browser guard; loopback http is allowed by default.
If a device call reports the device busy, stop: the task is parked and resumes by itself — do not retry in a loop.
TalkBack/VoiceOver proxy on device
mobile_read_ui {filter: "clickable=\"true\""}. Every line needs a non-empty text or content-desc; bounds ≥48dp × (dpi/160) px on Android, ≥44pt on iOS. Verify the line-per-node shape on first use — the exact field names can differ by platform.
Checklist (yes/no, each with a threshold)
- Overflow / clipping: none in any cell of the matrix.
- Insets: essential content clear of the status bar, notch, home indicator and keyboard.
- Targets: touch targets ≥48dp / 44pt.
- Text: essential text not truncated at 2.0; scales with the system setting (no hard-coded sizes).
- States: loading, empty and error all reachable and designed.
- Dark mode: intentional (no black-on-dark, no invisible icons); status-bar icons legible.
- Consistency: one primary action; the same control looks identical everywhere (built from the same atom).
- Copy: in the locale; no placeholder text.
- Navigation: landscape keeps the primary action reachable; tablet doesn't stretch text past ~600–840dp (constrain or use two panes).
Batch, then fix, then one re-check
Collect every finding from every matrix cell before touching code. Fix everything from the batch in one pass, then re-run the full matrix once. At most two rounds total — whatever is still open after round two goes into the closing message, honestly, rather than triggering a third silent pass.
Closing message
Name the render path used (device-own-build / device-stage-only / previewer / simulator) and, for each matrix size checked, what you saw. A known gap reported honestly is not a failure; an unverified claim of "done" is.
Common Mistakes
- Treating a screenshot taken right after
mobile_launch_app(with no own-build install) as proof of your change — it's the stage build. - Skipping the 2.0 text-scale cell because 1.0 looked fine — the overflow in the worked example only appears at 2.0.
--update-goldensor regenerating a snapshot to make a red matrix test green.- More than two rounds of screenshot → fix → screenshot on the same screen.
Red Flags
- A closing message that names no render path.
- "Looks fine" without ever having set text scale to 2.0 or dark mode.
- A device-busy result retried instead of treated as parked.
04 同仓库更多 Skills
visual-craft
暂无简介
ux-copy
Use when you write any words a user reads in a mockup or a hand-off - content language and voice, buttons, labels, errors, empty states, confirmations, numbers and dates, and the longest-string check
screen-mockup-html
Use when you draw screens as the design task's HTML mockup - ONE canvas document holding every screen and every variant side by side, the sanitizer-safe recipe, phone and wide frames, the states grid, static control states, and the loopback self-check with screenshots at 375, 768 and 1440 attached to the task
performance-awareness
How the performance score moves for your role. Use when the score context shows a declining trend, or before handing off work you have not self-checked against every criterion.
design-variants
Use when a screen design needs variants - how many, variants as side-by-side rows on the one canvas, what makes two variants genuinely different, recommending one, how the human's choice is read, and narrowing to the chosen one in revision
design-system-authoring
Use when you derive, change or extend a design system - where tokens live per stack, the DTCG token tree, role-based names for both themes, base vs layer vs drift, the DESIGN.md section order, the inventory format, the contrast check and the lint every proposal returns