skills/pbakaus_impeccable
1
0
Fork 0
mirror of https://github.com/pbakaus/impeccable.git synced 2026-09-11 21:57:14 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
f240348cc55755f059c14e2133a38ac7689fed8a
pbakaus_impeccable/skill/reference/android.md
T
Paul BakausandGitHub 19786e7a22 Native leg for the verify-and-review pipeline (#546) 
* 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
2026-08-09 15:09:55 -07:00

47 lines
4.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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. <!-- rule:android-layout-adaptive-nav -->
- **System Back always works.** Honor the predictive Back gesture and Back button; never trap the user or hijack the gesture. <!-- rule:android-layout-system-back -->
- **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. <!-- rule:android-layout-window-insets -->
- **Top app bar for screen context**; pair with a FAB when the screen has a single primary action. <!-- rule:android-layout-top-app-bar -->
## Touch targets
- **48×48 dp minimum** for every touch target, with at least 8 dp between them. <!-- rule:android-touch-target-48dp -->
## Typography
- **Material type scale.** Display, Headline, Title, Body, Label roles (large/medium/small each). Map text to roles; never hand-pick sizes per screen. <!-- rule:android-typo-type-scale -->
- **Roboto is the system face**; theme a brand face in through the type scale, keeping body, labels, and controls legible and consistent. <!-- rule:android-typo-system-font -->
- **sp units, never fixed px**, so type follows the system font-size setting. <!-- rule:android-typo-scalable-sp -->
## 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. <!-- rule:android-color-role-tokens -->
- **Dynamic Color (Material You)** where it fits: derive the scheme from the user's wallpaper on Android 12+, with a static fallback. <!-- rule:android-color-dynamic-color -->
- **Dark theme is a first-class scheme.** Design and test it; never a quick invert. <!-- rule:android-color-dark-theme -->
- **Tonal elevation.** Convey elevation through the standard surface tonal levels (plus shadow where appropriate); no arbitrary drop shadows. <!-- rule:android-color-tonal-elevation -->
## 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. <!-- rule:android-components-material -->
- **One FAB, one primary action.** Never stack FABs or spend one on a secondary task. <!-- rule:android-components-single-fab -->
- **Snackbars for transient feedback** (actionable when useful, never a toast for that); dialogs only for decisions that must interrupt. <!-- rule:android-components-snackbar -->
- **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. <!-- rule:android-motion-material-and-reduce -->
## 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 with `adb -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. <!-- rule:android-verify-emulator-capture -->
- **Dark theme and font scale belong in the pass.** `adb shell cmd uimode night yes` flips the theme; `adb shell settings put system font_scale 1.3` (restore `1.0` after) catches the clipped labels a fixed layout hides; with several targets attached, the capture's `-s <serial>` goes on these commands too. <!-- rule:android-verify-theme-and-scale -->
- **Emulators give breadth; gestures, refresh rates, and performance need hardware.** Say which one produced the evidence. <!-- rule:android-verify-hardware-honesty -->
Reference in New Issue View Git Blame Copy Permalink