mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-11 21:57:14 +03:00
Paul BakausandGitHub
19786e7a22
* Give the verify-and-review pipeline a native leg The build-verify-review loop assumed a browser end to end while the comp side of the system was already platform-aware: new-work.md, visualize.md, and the asset producer all comp a native app portrait at its device viewport, and then the verification steps asked for desktop and mobile browser screenshots of it. Concretely: - new-work.md step 7 ordered detect.mjs on every hookless build with no platform guard. routing.md declares the detector web-only and the design hook skips native projects, so a native build was always hookless and always ordered to run an HTML rule engine over Swift/Kotlin/RN code. The playbook now guards it: web-only, and on native the reviewer's floor check is the named slop gate. - The inspection round and the SKILL.src.md batched-round principle named desktop and mobile as the only viewports. Both now map per platform: web keeps desktop and mobile; native inspects the shipped device classes per OS, captured from the simulator or emulator. - ios.md and android.md carried no verification guidance at all, so nothing told a native run how to produce the screenshots the evidence chain depends on. Each gains a Verifying the build section: simctl / adb capture commands, dark-appearance and type-scale checks, and the simulator-vs-hardware honesty line. - The finish reviewer judged native builds blind: it never runs context.mjs and its packet carried no platform guidance. On native the packet now includes the platform reference path(s) and a no-detector-ran line, and the reviewer's Input Contract says to judge in the platform's conventions. Assisted-by: Claude Code * fix: address PR review bot findings - greptile: carry the capture's device selector through the state-changing verification commands (simctl appearance, adb uimode and font_scale); unqualified forms fail with several targets attached - Copilot: align new-work.md's cross-reference with the actual heading (Verifying the build) - Copilot: give the finish reviewer's Input Contract the native filename example new-work.md establishes (phone.png / tablet.png, suffixed per OS on adaptive) Assisted-by: Claude Code * fix: identify simulators by UDID, not display name greptile follow-up: display names can collide across booted simulators, so the capture and appearance commands now both key on the UDID from simctl list devices booted. Assisted-by: Claude Code
4.8 KiB
4.8 KiB
Android platform
For native Android apps: Jetpack Compose, Android Views, React Native, Expo, Flutter shipping to Android hardware.
On native, the visitor mode narrows what expression may override. Material Design 3 governs structure, navigation, and interaction in every mode; brand expresses through Material's theming (color roles, type scale, shape, motion). A Material-everywhere cross-platform app that also ships to iPhone still owes iOS its OS guarantees on that hardware: safe-area insets, Reduce Motion, edge-swipe back.
The Android slop test
Would a fluent Android user trust this app, or trip on off-spec components? The most common tell is an iOS app wearing Android's skin: a bottom-only navigation copied from iPhone, a back arrow that ignores the system Back gesture, Cupertino-shaped switches and dialogs. Material 3 is the rulebook; follow its components and theme the brand through it.
Layout & structure
- Material navigation, matched to size. Navigation bar (bottom, 3–5 destinations) on compact width; navigation rail or drawer on expanded width. Never ship a phone bottom-bar untouched on a tablet.
- System Back always works. Honor the predictive Back gesture and Back button; never trap the user or hijack the gesture.
- Edge-to-edge with window insets. Apply the status bar, navigation bar, display cutout, and IME insets so content never hides behind system bars or the keyboard.
- Top app bar for screen context; pair with a FAB when the screen has a single primary action.
Touch targets
- 48×48 dp minimum for every touch target, with at least 8 dp between them.
Typography
- Material type scale. Display, Headline, Title, Body, Label roles (large/medium/small each). Map text to roles; never hand-pick sizes per screen.
- Roboto is the system face; theme a brand face in through the type scale, keeping body, labels, and controls legible and consistent.
- sp units, never fixed px, so type follows the system font-size setting.
Color & theming
- Material color roles (primary, on-primary, surface, surface-variant, secondary-container, outline, error). Role tokens resolve light/dark and contrast variants automatically; raw hex breaks there.
- Dynamic Color (Material You) where it fits: derive the scheme from the user's wallpaper on Android 12+, with a static fallback.
- Dark theme is a first-class scheme. Design and test it; never a quick invert.
- Tonal elevation. Convey elevation through the standard surface tonal levels (plus shadow where appropriate); no arbitrary drop shadows.
Components & motion
- Material components. Buttons (filled / tonal / outlined / text), FAB, switches, chips, snackbars, bottom sheets, Material dialogs, navigation bar/rail/drawer. Never port iOS controls or invent equivalents.
- One FAB, one primary action. Never stack FABs or spend one on a secondary task.
- Snackbars for transient feedback (actionable when useful, never a toast for that); dialogs only for decisions that must interrupt.
- Material motion patterns. Container transform, shared-axis, fade-through, with standard easing and durations; honor the system Remove animations setting with a crossfade or instant cut.
Verifying the build
- Screenshots come from the emulator or a connected device, never a browser. Build and install, then capture with
adb exec-out screencap -p > <path>(pick a device withadb -s <serial>when several are attached). Capture every device class the app ships to, at least one phone and, when tablets are a target, one tablet, and write the files where the review flow expects them. - Dark theme and font scale belong in the pass.
adb shell cmd uimode night yesflips the theme;adb shell settings put system font_scale 1.3(restore1.0after) catches the clipped labels a fixed layout hides; with several targets attached, the capture's-s <serial>goes on these commands too. - Emulators give breadth; gestures, refresh rates, and performance need hardware. Say which one produced the evidence.