
shipwithai-mobile-ui-harness
Self-improving Compose Multiplatform UI harness. Inspection tests render every screen across a stress matrix; a deterministic Tier-1 asserter plus a vision evaluator grade them in a separate lane; recurring findings ratchet into permanent gates via a compounding feedback ledger. Ships Konsist architecture rails and a setup skill that scaffolds it all into a project.
- version
- 0.1.0
- GitHub stars
- 9
Install
/plugin install shipwithai-mobile-ui-harness@shipwithaiRun it inside Claude Code after adding the marketplace with /plugin marketplace add ShipWithAI/shipwithai-plugins.
Contents
Discovered from sourceSkills 3
Konsist architecture tests
Overview
Enforce module-boundary invariants as plain JVM unit tests with Konsist, which parses Kotlin source straight from disk. Each violation turns the suite red the moment a forbidding import is written — before review, before the dependency graph is even wired. The check is on imports (source-level), the right altitude: a stray dependencies {} edge can sit unnoticed, but the first illegal import that relies on it fails.
Why Konsist — not ArchUnit or Detekt
This is the non-obvious decision; get it right first.
- ArchUnit reads compiled bytecode off a classpath. A pure
commonMain/iosMainKMP module never hands a JVM test task its bytecode, so ArchUnit can't see that code at all. Konsist reads source, so it sees every source set. - Detekt wants a Gradle plugin per module; on
com.android.kotlin.multiplatform.library(AGP 9) plugin-compat lags and KMP source-set wiring is awkward. - Konsist needs no plugin and no classpath:
Konsist.scopeFromProject()walks the whole repo from a single host test — the same "rule as a host test" shape as other structural checks. One prevention mechanism, not two.
Where it lives + wiring
Put it in one JVM test source set that runs testDebugUnitTest — conventionally the app module (it already depends on everything, but Konsist scans the whole project from disk regardless of which module hosts the test):
app/src/test/kotlin/<base.package>/architecture/ArchitectureTest.kt
Add the dependency to that module: testImplementation(libs.konsist) (catalog: konsist = { module = "com.lemonappdev:konsist", version.ref = "konsist" }). Run just these rules:
./gradlew :app:testDebugUnitTest --tests "<base.package>.architecture.ArchitectureTest"
Survey the graph, then write one rule per edge
Read settings.gradle(.kts) and the module folders. For each intended dependency direction (core ← feature, api is a seam over impl, domain ↛ data, …), write one @Test. Don't invent rules the project doesn't hold.
The canonical scaffold
Rules key on the on-disk Gradle module path (core/audio, feature/foo/api) derived from each file's projectPath, over production source only — never on bytecode, and never only on package names. Three helpers carry that; copy them verbatim:
package com.example.app.architecture
import com.lemonappdev.konsist.api.Konsist
import com.lemonappdev.konsist.api.declaration.KoFileDeclaration
import com.lemonappdev.konsist.api.verify.assertFalse
import org.junit.Test
class ArchitectureTest {
private val files: List<KoFileDeclaration> = Konsist.scopeFromProject().files
/** Core modules are foundational — they must never depend on a feature. */
@Test
fun `core does not depend on feature`() {
files
.filter { it.isProductionSource() && it.modulePath().startsWith("core/") }
.assertFalse { file ->
file.hasImport { it.name.startsWith("com.example.app.feature.") }
}
}
/** A feature's public `api` contract must not leak its own `impl` internals. */
@Test
fun `feature api does not depend on feature impl`() {
files
.filter {
it.isProductionSource() &&
it.modulePath().startsWith("feature/") &&
it.modulePath().endsWith("/api")
}
.assertFalse { file ->
file.hasImport {
it.name.startsWith("com.example.app.feature.") && it.name.contains(".impl.")
}
}
}
}
/** Source-set folder (the path segment after `src/`); null for build/generated or non-source files. */
private fun KoFileDeclaration.sourceSet(): String? {
val segs = projectPath.trimStart('/').split('/')
if ("build" in segs) return null
val i = segs.indexOf("src")
return if (i >= 0) segs.getOrNull(i + 1) else null
}
/** True for main/production source sets; excludes test, commonTest, androidHostTest, etc. */
private fun KoFileDeclaration.isProductionSource(): Boolean {
val ss = sourceSet() ?: return false
return ss != "test" && !ss.endsWith("Test")
}
/** Gradle module path = everything before /src/, e.g. feature/chord-smoother/impl. */
private fun KoFileDeclaration.modulePath(): String =
projectPath.trimStart('/').substringBefore("/src/")
Adding a rule (the recipe)
filtertoisProductionSource()and the modules the rule governs, bymodulePath().assertFalse { file.hasImport { it.name.startsWith("<forbidden import prefix>") } }.- Name the
@Testafter the invariant, in backticks.
The .impl. import-substring check is enough when packages encode the module (the common case: feature/foo/impl → …feature.foo.impl.*). Only if packages don't encode the module — or you must forbid importing another feature's impl — pair api↔impl by module-path feature name. Don't reach for that extra machinery by default; it's complexity the simple check doesn't need.
Verify the rule BITES — required
A green suite proves nothing until you have watched it go red. After adding a rule, plant a violation: add the forbidden import in a governed production file, run the test, and confirm it FAILS naming that file. Then revert and confirm green. Skip this and a misfiltered rule (wrong modulePath prefix, scanning test source, a typo'd package prefix) silently filters to zero files and passes forever — enforcing nothing while looking enforced.
Back the one-time check with a permanent guard. The planted-violation test is manual and runs once; add a rule that stays in the suite and fails the day a selector silently matches zero files:
@Test
fun `boundary selectors match real files (guard against vacuous pass)`() {
val core = files.filter { it.isProductionSource() && it.modulePath().startsWith("core/") }
val featureApi = files.filter {
it.isProductionSource() && it.modulePath().startsWith("feature/") && it.modulePath().endsWith("/api")
}
assert(core.isNotEmpty()) { "core/ selector matched 0 files — prefix or source-set filter is wrong" }
assert(featureApi.isNotEmpty()) { "feature/**/api selector matched 0 files — selector is wrong" }
}
Common mistakes
| Mistake | Symptom | Fix |
|---|---|---|
| Scanning all files | test-only imports trip the rule | filter isProductionSource() |
| Keying on package names only | misses kebab-case modules, wrong pairing | derive modulePath() from projectPath |
| Never planting a violation | rule filters to 0 files, passes forever | the BITES step above |
| ArchUnit on a KMP module | commonMain/iosMain code invisible | Konsist (reads source, not bytecode) |
| Reinventing api↔impl pairing | fragile extra helpers | the .impl. substring check suffices when packages encode the module |
Mobile UI design evaluation
This skill is a rubric for an evaluator, not a generator. Given a rendered screen (a screenshot, ideally one per device config), grade it against the criteria below and return a verdict plus specific, element-level fixes.
The ordering is deliberate and matches how mobile agent output actually fails: most defects are structural (clipped, overlapping, off-grid) before they are tasteless. Catch broken layouts first — they are hard fails — then judge polish.
How to use this skill
- When: reviewing a mobile UI screenshot, or after the implementer edits any
@Composableand re-renders. Pair it with the screenshot harness (Roborazzi / emulator capture). Anything a deterministic layout assertion already caught does not need re-judging here; this skill covers what assertions can't see plus all of taste. - Two passes: Tier 1 (structural integrity) → any violation is a blocker. Tier 2 (visual quality) → weighted issues, reported but not auto-failing unless they pile up.
- Output: a verdict (
pass/fail), violations grouped by tier, each naming the element, the config it appears in, and a concrete fix. Never return "looks off" — always say what and where.
Evaluation protocol — render the matrix
Most "broken" only shows under stress. Evaluate each screen across this matrix and grade the worst case, not the happy path:
- Default — reference device (e.g. Pixel-class, ~411dp wide).
- Compact width — ~360dp or narrower (small phones, split screen).
- Large font scale —
fontScale1.5 and 2.0 (accessibility text size). This is where overflow and truncation surface. - Dark mode — both light and dark.
- Long content — longest realistic strings, large numbers, missing images.
- RTL — only if the app localizes to RTL.
A defect in any config is a defect.
Tier 1 — Structural integrity (blockers)
Each item is a hard fail. Fix before evaluating taste. These are the "is it broken?" checks, severity-ranked.
- Overflow & clipping — content cut off at a screen or container edge; rows wider than
the viewport; text or controls pushed off-screen. Check first at
fontScale1.5+. - Unintended truncation — labels, buttons, prices, or numbers showing
…or cut digits where the full value must be visible. Prefer wrap or resize over ellipsis for critical text. - Overlap / z-fighting — composables drawn on top of one another; text over text; FAB or bottom bar covering actionable content; shadows bleeding into neighbors.
- Zero-size / collapsed elements — a node that measured to 0 width or height (missing
size, a
weightwith no space, an empty image slot). Invisible content and untappable targets. - Inset / safe-area violations — content under the status bar, notch/cutout, or home
indicator; not consuming
WindowInsets(status bars, navigation bars, IME). Header text under the clock; the last list item hidden behind the nav bar. - Touch target size — interactive elements smaller than 48×48 dp (Android) / 44×44 pt (iOS). Icon buttons and chips are the usual offenders.
- Keyboard (IME) handling — focused field obscured by the keyboard; form not scrollable while the IME is open; submit button trapped behind the keyboard.
- Misalignment — elements off the spacing grid; ragged left/right edges where items should share a margin; inconsistent margins on the same screen.
- Readability-breaking contrast — text or essential icons below WCAG AA (4.5:1 body text, 3:1 large text and UI components). Light-gray-on-white, low-contrast placeholder mistaken for a value.
- Scroll / viewport failures — content taller than the screen with no scroll; bottom actions clipped; nested scroll conflicts; sticky elements that cover content.
- Missing core states — list with no empty state; screen with no loading and no error state; a permanent skeleton or spinner.
If any Tier-1 item is present → VERDICT: fail. Stop and return fixes.
Tier 2 — Visual quality (weighted polish)
The "is it tasteless?" axis. Report every issue; fail only if several stack up on one screen.
Hierarchy & focus
- Exactly one clear primary action per screen. Not three filled buttons competing.
- A single focal point; the eye knows where to land first.
- Type scale carries hierarchy (display / headline / title / body / label) — not medium-weight-everything.
- Visual weight (size, color, position) matches importance.
Spacing & rhythm
- Spacing comes from a scale (4 / 8 dp grid). No stray 13 dp, 17 dp, 23 dp values.
- Intentional whitespace: not cramped edge-to-edge, not adrift in a void.
- Padding is consistent within a component and between sibling components.
- Related items grouped (proximity); unrelated items separated.
Color & theming
- Colors come from the Material 3 theme color roles (
primary,secondary,surface,onSurface,surfaceVariant, …), not hardcoded hex. - Restrained palette; color signals meaning (state, action), it doesn't decorate.
- Real tonal/elevation hierarchy between surfaces. Dark mode is purpose-built, not a broken inversion (no pure-black-on-pure-white, no glowing shadows).
- The default seed-purple theme is not left untouched.
Typography
- One type family; a limited, deliberate ramp.
- Body text ≥ 14–16 sp; no walls of dense small text.
- Line height and letter spacing follow M3; lines not jammed together.
- Start-aligned by default; centering used sparingly and on purpose (never center every block of text).
Components & platform idiom
- Correct M3 components and variants (
ButtonvsOutlinedButtonvsTextButton,Card,TopAppBar,NavigationBar,ListItem) instead of hand-rolled lookalikes. - Elevation used meaningfully — not heavy shadows on every card.
- States are designed: pressed, disabled, focused, selected, error.
- Iconography consistent in style, weight, and size; aligned to text baselines.
- Platform conventions respected where they matter (back navigation, system bars, edge gestures, native pickers/sheets).
Content & resilience
- Realistic content, not placeholder/lorem leaking into the render.
- Graceful with edge content: very long names, empty strings, 0 and 7-digit numbers, missing avatars/thumbnails.
- Images keep aspect ratio (no stretch/squish), cropped and rounded per theme.
Affordance & feedback (inferred from a still)
- Tappable things look tappable; disabled things look disabled.
- Skeleton/placeholder over a blank screen during load.
Anti-patterns — the "mobile AI-slop" tells
Fast signals that an agent generated the screen without looking at it. Flag any present:
- Everything center-aligned.
- One uniform medium font weight; no hierarchy.
- Untouched default purple Material theme.
- Identical heavy elevation on every card.
- 16-dp-on-everything cramming, or huge arbitrary gaps with no rhythm.
- Stacks of full-width filled buttons with no grouping or primary/secondary distinction.
- Content under the status bar or nav bar (insets ignored).
- No empty, loading, or error state.
- Emoji used as UI icons.
- Critical text truncated with
…instead of wrapped or resized. - Pure
#000/#FFFbackgrounds and shadows that glow in dark mode.
Verdict format
Return exactly this shape:
VERDICT: fail # fail if any Tier-1 violation, else pass
Tier-1 violations (blockers):
- [overflow] "Continue" button row clipped at right edge @ fontScale 1.5 (LoginScreen).
Fix: let the label wrap, or make the row horizontally scrollable, or shorten the label.
- [insets] App bar title overlaps the status bar (HomeScreen, default).
Fix: apply Modifier.windowInsetsPadding(WindowInsets.statusBars) or use a Scaffold TopAppBar.
Tier-2 issues (polish):
- [hierarchy] Three filled buttons compete; no clear primary (SettingsScreen).
Fix: one filled primary, others OutlinedButton/TextButton.
- [spacing] Mixed 12/16/20 dp gaps in the list (FeedScreen).
Fix: snap to the 8 dp scale (8/16/24).
Score: 2 blockers → re-render after fixes. Taste re-check deferred until Tier-1 clears.
When pass, still list Tier-2 issues as suggestions, but mark the screen shippable.
Quick checklist (fast pass)
Structural (any ✗ = fail): edges not clipped · no truncated critical text · nothing overlapping · no 0-size nodes · insets respected · targets ≥ 48 dp · keyboard doesn't cover the field · aligned to grid · text contrast ≥ AA · scrolls when it must · empty/ loading/error states exist.
Taste (weighted): one clear primary · hierarchy via type scale · 8 dp spacing · theme colors not hex · dark mode real · M3 components used right · realistic + edge content · not center-everything · not default-purple.
UI Harness — Setup
Installs the per-repo half of the harness so it is committed and shared with the team: the
ledger, the Python tools beside it, and the Kotlin substrate. The agentic half (the mobile-design
skill, the mobile-design-evaluator agent, and /ui-iterate · /ui-distill · /ui-metrics)
ships with the plugin and is already available.
Bundled sources live under ${CLAUDE_PLUGIN_ROOT}/assets/.
0. Prerequisite probe + interview
- Confirm this is Compose Multiplatform + Roborazzi + Robolectric (the substrate's
assumptions). If not, stop and point at
${CLAUDE_PLUGIN_ROOT}/assets/INTEGRATION.md. - Base package =
$1, else infer it from an existingpackagedeclaration and confirm. - Target module = the
--modulevalue, elseGlobfor a featureimplmodule and ask which one. Derive itsandroidHostTestsource root.
1. Lay down the ledger + tools (verbatim)
mkdir -p harness/bin harness/ledger
cp "${CLAUDE_PLUGIN_ROOT}/assets/harness/bin/"*.py harness/bin/
cp "${CLAUDE_PLUGIN_ROOT}/assets/harness/ledger/README.md" harness/ledger/README.md
cp "${CLAUDE_PLUGIN_ROOT}/assets/harness/ledger/screen-aliases.json" harness/ledger/screen-aliases.json
: > harness/ledger/findings.jsonl # committed, append-only; starts empty
Confirm the tools run here: python3 harness/bin/test_aggregate_ledger.py (and the two sibling
test_*.py) should all pass.
2. Install the deterministic asserter
Copy Tier1Assertions.kt.tmpl into the target module's androidHostTest testing package,
replacing the token with the real package. Substitute the §0 interview values into the shell
vars below and validate them first — never splice an unvalidated package/path into the shell,
and don't feed the package to sed (a / in it breaks the s/// delimiter):
BASE_PKG="<base.package>" # from §0, e.g. com.acme.app
MODULE="<module>" # from §0, e.g. feature/foo/impl
MODULE_SUFFIX="<module-suffix>" # package tail under BASE_PKG, e.g. feature.foo.impl
# reject anything that isn't a plain Java package / module path
case "$BASE_PKG" in *[!A-Za-z0-9._]*|"") echo "invalid base package"; exit 1;; esac
case "$MODULE_SUFFIX" in *[!A-Za-z0-9._]*|"") echo "invalid module suffix"; exit 1;; esac
case "$MODULE" in *[!A-Za-z0-9._/-]*|/*|*..*) echo "invalid module path"; exit 1;; esac
TESTING_PKG="${BASE_PKG}.${MODULE_SUFFIX}.testing"
DEST="$MODULE/src/androidHostTest/kotlin/${TESTING_PKG//.//}" # pure-shell '.'→'/', no sed
mkdir -p "$DEST"
# literal token replacement — TESTING_PKG never enters a regex
TESTING_PKG="$TESTING_PKG" python3 - \
"${CLAUDE_PLUGIN_ROOT}/assets/substrate/Tier1Assertions.kt.tmpl" "$DEST/Tier1Assertions.kt" <<'PY'
import os, re, sys
src, dst = sys.argv[1], sys.argv[2]
text = open(src, encoding="utf-8").read()
open(dst, "w", encoding="utf-8").write(re.sub(r"__TESTING_PACKAGE__.*", os.environ["TESTING_PKG"], text))
PY
3. Install the convention plugin
Copy ComposeScreenshotTestingConventionPlugin.kt.tmpl into build-logic (replacing
__BUILDLOGIC_PACKAGE__), then register it and apply id("<prefix>.compose-screenshot-testing")
in each module that renders screens. See ${CLAUDE_PLUGIN_ROOT}/assets/INTEGRATION.md for the exact
build-logic registration block and the version-catalog aliases it expects.
4. Seed one inspection test
Copy ${CLAUDE_PLUGIN_ROOT}/assets/substrate/ScreenInspection.kt.tmpl next to Tier1Assertions,
replace __PACKAGE__ / __TESTING_PACKAGE__ / __SCREEN__ / __screen__ (the lowercase
single-token screen id), and wire the TODOs to render your stateless screen content. Add a
"<ComposableName>": "<screen-id>" row to harness/ledger/screen-aliases.json.
5. Wire the build + gitignore
Follow ${CLAUDE_PLUGIN_ROOT}/assets/INTEGRATION.md §"Build wiring" and §"gitignore": add the
Roborazzi plugin + version-catalog aliases, register the convention plugin, and gitignore
harness/ledger/promotions.md, harness/ledger/metrics.md, and the
build/outputs/roborazzi/_inspect_*.png / *_findings.jsonl sidecars (keep
harness/ledger/findings.jsonl committed).
6. Smoke-test the loop
Run /ui-iterate <YourScreen> once. It should render the matrix, run Tier-1, dispatch the
evaluator in a fresh lane, and fold findings into harness/ledger/findings.jsonl. If it produces a
_verdict.md, the harness is live.
The six coupling points (package, module coords, ledger root, sidecar glob, catalog aliases, screen-alias map) are all touched above. Everything else is project-agnostic.
Commands 3
Turn recurring ledger findings into permanent gates. The deterministic part (cluster → threshold → map to the durability ladder) is the script; the judgment part (approve → implement → delete soft guidance) is you + the human. Never auto-implement a promotion — approval gates everything.
1. Analyze (deterministic)
python3 harness/bin/distill_ledger.py $ARGUMENTS # writes harness/ledger/promotions.md
Read harness/ledger/promotions.md. Each candidate is a category seen ≥ threshold (default 3) times, with its durability-ladder rung + concrete deposit, breadth (screens/configs), and sample findings.
If there are no candidates over threshold, report the watchlist and stop — nothing has recurred enough to harden yet.
2. Propose to the human (approval required)
Present each candidate: category, count/breadth, the recommended deposit, and 2–3 sample findings. Human approval is required for every Tier-2/3 deposit (a new assertion, a Konsist rule, a component, an API change). Surface them; do not implement anything yet. Let the human pick which to promote (and they may downgrade a rung — e.g. "keep it a rubric line for now").
3. Implement the approved deposit — push it as far down the ladder as it goes
Per the candidate's rung:
- T2 gate (
touch-target,zero-size,out-of-bounds,insets,overflow,truncation,contrast): add/extend the deterministic assertion inTier1Assertions.kt(or tag criticalTextwithModifier.testTag("noTruncate")). Verify it bites: run an inspection test that exhibits the finding and confirm Tier-1 now fails on it, then fix so it passes. - T3 structural (
reuse, raw-material3, hardcoded values): either promote the reinvented component intocore:designsystem(+ catalog entry perdocs/components/, + golden), or tighten a Konsist rule inArchitectureTest.kt. Verify the gate fails on a planted violation (the negative-test discipline from the Konsist work). - T1 soft (
color,typography,hierarchy,affordance,state, non-mechanizablespacing): add ONE concise line to.claude/skills/mobile-design/SKILL.md. Keep it minimal — soft guidance is a staging area, not storage.
A deposit isn't done until you've seen it catch the finding (gate runs red on the bad case, green after the fix). Don't mark deposited on faith.
4. Close out the ledger
python3 harness/bin/distill_ledger.py --deposit <category> --label "<what you added, incl. file/commit>"
This sets resolved=true + deposit=<label> on that category's open findings (in place), so they stop surfacing as candidates and feed /ui-metrics' recurrence-after-deposit signal.
5. Promote-and-delete (the ratchet's point)
Once a finding is enforced upstream, delete the now-redundant soft guidance — the matching rubric line in mobile-design/SKILL.md or rail in CLAUDE.md. A healthy harness's soft guidance shrinks as gates accrete; if you only ever add, you've built a second pile of advice, not a ratchet. Note what you deleted in the promotion record.
6. Confirm
Re-run step 1 and confirm the promoted category dropped out of candidates (it will, once --deposit closed it out). The durable record is the ledger deposit label — point it at the file/commit you added — plus the committed gate itself; promotions.md is a regenerated worksheet, not the record.
The threshold is a default, not a law. A single
blockerthat will obviously recur is worth promoting at count 1; pass--threshold 1or just use judgment. Conversely, three taste nits that aren't mechanizable may never deserve more than a rubric line.
Iterate on $ARGUMENTS until it passes, then stop. Hard cap: 4 iterations, then escalate to the human.
Two lanes, kept apart. You are the executor: you edit the @Composable and run the gates. The evaluator is a separate subagent in a fresh context (step 4) — never grade your own edits, that's the self-review this loop exists to prevent.
Commands below use placeholders (
<app-module>,<module>,<your.pkg>) ande.g.examples. Derive the real values from this project in step 0 — never run the example coordinates verbatim.
0. Locate + resolve target
Globfor the screen's inspection test:**/*$ARGUMENTS*Inspection.kt(convention:<Screen>Inspection, seeded by thesetupskill). From its path derive three things: the Gradle module (e.g.:feature:foo:impl), the test FQN (e.g.com.acme.feature.foo.impl.presentation.<Screen>Inspection), and the PNG dir (<module>/build/outputs/roborazzi/).- No inspection test yet? Create one from the template the
setupskill installs (assets/substrate/ScreenInspection.kt.tmpl; see INTEGRATION.md) — width {360,411} × fontScale {1.0,1.5,2.0} × {light,dark} × content {default,long,empty,error}, each capturing to_inspect_*.pngthen callingTier1Assertions.assertAll. - Target: if
harness/targets/$ARGUMENTS.pngexists → Fidelity mode (evaluator reports deltas vs target). Else → absolute rubric mode.
1. Implement / edit (executor lane)
Edit the @Composable for $ARGUMENTS. Rails (apply whichever your project has):
- Reuse your design system — check your component catalog before building anything new.
- Tokens, not literals — use your theme's color/spacing/type/shape tokens (keep raw
MaterialTheme.*inside the design-system module). - Insets: top-level screens consume
WindowInsets(status/nav bars, IME). - Boundary gate: if your project enforces a design-system / Material-3 boundary (e.g. via the
konsist-architecture-testsskill or a Konsist rule), satisfy it — add or reuse a wrapper rather than importing the gated API directly.
2. Cheap gate — boundaries (deterministic, no render)
If your project has an architecture/boundary test (e.g. installed via the konsist-architecture-tests skill), run it first — it's fast and catches reuse/boundary mistakes a vision pass shouldn't waste effort on. Substitute your own app module + architecture-test FQN:
# e.g. — replace <app-module> and <your.pkg> with this project's values
./gradlew :<app-module>:testDebugUnitTest --tests "<your.pkg>.architecture.ArchitectureTest"
On failure: the message names the offending file/import. Fix it and repeat step 1. (No such gate in this project? Skip to step 3.)
3. Render + Tier-1 (one Gradle task)
Record the matrix for the screen — substitute the module + FQN from step 0:
./gradlew :<module>:testAndroidHostTest \
--tests "<your.pkg>.<Screen>Inspection" \
-Proborazzi.test.record=true
This writes <module>/build/outputs/roborazzi/_inspect_*.png and runs Tier1Assertions (capture happens before the assert, so PNGs land even when Tier-1 fails). A Tier-1 failure = a structural blocker (zero-size, touch-target, out-of-bounds, truncation); its message names the element and it drops a _findings.jsonl sidecar — leave the sidecar, step 5 collects it. Fix structural blockers (back to step 1) until Tier-1 is clean before spending a vision pass.
4. Evaluate (separate lane)
Dispatch the evaluator subagent — Task with subagent_type: "mobile-design-evaluator" — pointed at the PNG dir. It reads every PNG, grades against the mobile-design rubric (Tier-1 structural → Tier-2 taste, or fidelity-vs-target), writes _verdict.md + _eval_findings.jsonl beside the PNGs, and returns a pass/fail verdict with element-level fixes. Do not grade the screen yourself.
The evaluator keys each finding's screen on the PNG's leading filename token — matching the Tier-1 lane — so don't hand it a single screen name to stamp; one inspection dir may mix components.
5. Aggregate the ledger
Fold this iteration's Tier-1 + evaluator findings into the durable ledger:
python3 harness/bin/aggregate_ledger.py --iteration <N>
(<N> = current iteration number.) See harness/ledger/README.md.
6. Decide
pass(Tier-1 clean and rubric pass / fidelity diff < tolerance): done. If the screen has a committed regression golden, re-record it to bless the intentional change (-Proborazzi.test.record=true); inspection-only screens have no golden to promote. Stop.failand iteration < 4: apply the verdict's Tier-1 fixes first, then Tier-2; loop from step 1 with the iteration incremented.- iteration == 4 and still failing: stop and escalate — report the outstanding findings and the
_verdict.mdpath to the human. Do not loop further.
Stop conditions: Tier-1 clean AND (fidelity diff < tolerance OR rubric pass).
Heavy work (Gradle render, evaluator dispatch) lives here, not in an edit hook — the gates are Gradle tests, far too slow to run per keystroke. Run
/ui-iterate $ARGUMENTSafter a batch of@Composableedits, not after each one.
Show whether the harness is getting better over time. This is read-only analysis — the work is in the deterministic script; you just run it and interpret.
1. Compute
python3 harness/bin/metrics_ledger.py # writes harness/ledger/metrics.md (gitignored)
Read harness/ledger/metrics.md.
2. Interpret the three numbers
- Iterations-to-pass per screen (↓): how many loop iterations a screen needed before it stopped surfacing findings. Falling over time means prevention (rails, gates, reused components) is catching things earlier. A screen that needs 4 every time is a candidate for a structural fix.
- First-pass yield (↑): share of screens that came in with zero Tier-1 structural blockers on the first render. Rising means the upstream rails (Konsist boundaries, tokens, designsystem reuse) are working — fewer broken-before-tasteless first drafts.
- Recurrence after deposit (→ 0): for each promoted category, how many findings appeared after it was deposited. This is the key health signal. Zero = the promotion stuck. Non-zero (flagged ⚠️) = the deposit isn't holding — the finding slipped past the gate you added, so harden it further down the ladder (rubric line → deterministic assertion → structural impossibility). Recurrence rising after a promotion is the cue to re-open it in
/ui-distill.
3. Act on it
If any category is flagged ⚠️, that's the most valuable thing the metrics surfaced: re-run /ui-distill for it and push the deposit one rung deeper. Everything else is trend-watching — re-run after each batch of /ui-iterate work; the ledger is the durable history, this report is the current snapshot.
These need data to be meaningful — they read what
/ui-iterate(capture) and/ui-distill(deposit) write. On an empty ledger the report just says so.
Agents 1
You are the mobile-design evaluator for this Compose Multiplatform project. You grade
already-rendered UI screenshots. You are the critic half of an executor-evaluator loop:
a separate lane edited the @Composable and rendered it; your job is to judge the result.
The one rule
You evaluate, you do not generate. Never edit a @Composable, a theme file, or any
source. Your only write is the verdict file. If you are tempted to "just fix it," stop — the
fix belongs to the executor; you describe it precisely so they can. Judging code you also wrote
is self-review, which this loop exists to prevent.
Inputs
Your dispatch prompt gives you one or both of:
- a directory of rendered PNGs (default:
feature/*/build/outputs/roborazzi/), and/or an explicit list of PNG paths; - optionally, what changed (the screen, the edit) — use it to focus, but still grade every config.
If you were given only a directory, Glob it for _inspect_*.png. If you find no PNGs, do not
guess — return a verdict of fail stating the harness has not been run, and give the exact command
(./gradlew :<module>:testAndroidHostTest --tests "...<Screen>Inspection" -Proborazzi.test.record=true).
Protocol
-
Load the rubric.
Read.claude/skills/mobile-design/SKILL.md— it is the source of truth for Tier-1 (structural blockers), Tier-2 (weighted taste), the anti-patterns, and the verdict format. Do not grade from memory; the rubric evolves. Follow its ordering: structural first. -
Enumerate the matrix. Filenames are
_inspect_<screen>_<config>.png. Decode each into its screen id and its config so you can attribute every defect precisely.- screen id: the FIRST token after
_inspect_(songs,field,picker) — the component under test. Use it verbatim as thescreenfield so your rows cluster with the deterministic Tier-1 findings. One inspection dir can mix components (e.g.field+picker), so read this per-PNG — never stamp one screen name across the whole dir. - width:
360= compact (~360dp),411= reference (~411dp),compact/defaultsynonyms; - font scale:
font1_5= 1.5,font2_0= 2.0, otherwise 1.0; - theme: a
_darksuffix = dark mode, else light; - content:
long,empty,errorname the state, otherwise the default/happy path. If a name is ambiguous, infer the config from the rendered image (text size, width) instead.
- screen id: the FIRST token after
-
Read every image. You are multimodal — actually
Readeach PNG; never skip one or grade from the filename alone. The worst case (compact width +font2_0, long/empty/error states) is where blockers hide; weight your attention there. -
Tier 1 — structural integrity (per config). For each image, walk the rubric's Tier-1 list: overflow/clipping, truncation of critical text, overlap/z-fighting, zero-size/collapsed nodes, inset/safe-area violations, touch targets < 48dp, IME handling, misalignment/off-grid, AA contrast, scroll/viewport failures, missing empty/loading/error states. A defect in any config is a defect. Any Tier-1 hit ⇒ overall
VERDICT: fail. -
Tier 2 — visual quality. Judge hierarchy/focus, spacing rhythm (4/8dp grid), color/theming (M3 roles not hex; real dark mode; not default-purple), typography, M3 component idiom, content resilience, affordance. Report every issue; these fail only if several stack on one screen. Also scan the rubric's "mobile AI-slop" anti-patterns and flag any present.
-
Write the verdict, then return it. Use the rubric's exact verdict shape. Every violation must name the element, the config it appears in (from step 2), and a concrete fix — never "looks off." Write the verdict to
_verdict.mdin the same directory as the PNGs (per-directory if several), and return the identical content as your final message. The written file is the durable deliverable; the final message is your hand-back to the dispatcher. -
Emit the ledger sidecar. In the same directory, (over)write
_eval_findings.jsonl— one compact JSON object per violation (Tier-1 and Tier-2 alike), so your findings feed the durable feedback ledger the same way the deterministic assertions do. The deterministic Tier-1 sidecar (_findings.jsonl) is a different file; never touch it. Skip the file only if you found zero violations. Schema per row (match it exactly —harness/bin/aggregate_ledger.pyfolds these intoharness/ledger/findings.jsonl; seeharness/ledger/README.md):{"ts":"<ISO8601 UTC>","screen":"<screen id — the filename's leading token, e.g. songs/field/picker>","config":"<from step 2, e.g. long_compact_font1_5_dark>","loop":"impl","role":"evaluator","tier":1,"category":"<the DEFECT, see vocab below>","severity":"blocker|warn|nit","element":"<element>","finding":"<what's wrong, where>","fix":"<concrete fix>","iteration":null,"resolved":false,"deposit":null}Get the timestamp with
date -u +%Y-%m-%dT%H:%M:%SZ(Bash). Usetier1 for structural blockers, 2 for taste; setseveritytoblockerfor any Tier-1 hit. Leaveiterationnull — the aggregator stamps it. Do not run the aggregator yourself; the dispatcher owns that.categorynames the DEFECT, not the fix. Pick from the controlled vocabulary:touch-target · zero-size · out-of-bounds · overflow · truncation · overlap · insets · contrast · spacing · hierarchy · color · typography · state · affordance · reuse · fidelity. An undersized tap target istouch-targeteven when the fix is "wrap inAppIconButton"; reservereusefor a reinvented component andfidelityfor a delta vs a design target. Categorizing by defect keeps the ledger's per-category recurrence — the signal/ui-distillpromotes on — meaningful.
Discipline
- Be specific or say nothing. "[truncation] 'Play Progression' button label clipped to 'Play Progr…' @ 360dp/font2.0 (SongsScreen, dark)" — not "the button looks cramped."
- Don't re-litigate what an assertion already owns. If the dispatcher says a deterministic test already checked a mechanical property (touch size, not-clipped), don't burn effort re-judging it; cover what assertions can't see plus all of taste.
- One verdict for the screen, synthesized across configs — not one verdict per image. List which config each violation came from.
- No false green. A clean happy-path render with a broken
font2_0render is afail. Do not let a pretty default config launder a blocker in a stress config.
Sponsors
Details
- Marketplace
- ShipWithAI/shipwithai-plugins
- Source
- plugins/mobile-ui-harness
- Author
- ShipWithAI
- Category
- Productivity