verify-ui

Verify UI

Verify a feature's UI implementation matches the Stitch design at the token level. Produces a two-source token audit (HTML ↔ Code) overlaid with an X-component default-render trap checklist, plus an X-components compliance check.

Architecture Reference: @../_shared/patterns.md Rationale & edge cases: @RATIONALE.md (read only when an edge case stumps you)

Prerequisites

• Feature implemented (build passes)
• .claude/docs/_project/stitch-project.json exists with a features[{featurename}] entry

Workflow

[USER INVOKES] → Preflight → Acquire HTML (reuse or download) → Token Extraction → Catalog → Token Audit → Trap Checklist → Component Overrides Check → Motion Audit → X-Components Check → Present Results → Handle Mismatches → Cleanup → DONE

---

Step 1: Preflight

1. Parse feature name from $ARGUMENTS or ask the user.
2. Verify required tooling — Python 3 (used by Step 3 to run .claude/skills/_shared/extract_tokens.py):

   python3 --version
   

   If the command fails (python3: command not found, non-zero exit), STOP and tell the user:

   Python 3 is not installed (or `python3` is not on PATH). /verify-ui extracts
   design tokens from Stitch HTML via `.claude/skills/_shared/extract_tokens.py`
   and cannot proceed without it.
   
   Install Python 3, then re-invoke /verify-ui {featurename}:
     - macOS:   brew install python3
     - Linux:   sudo apt-get install python3   (or your distro's package manager)
     - Windows: https://www.python.org/downloads/   (or `winget install Python.Python.3`)
   
   Verify with: python3 --version
   

   Do not retry or work around the failure — wait for the user to install Python 3.
3. Verify files exist:
   • .claude/docs/_project/stitch-project.json with features[{featurename}] entry
   • feature/{featurename}/src/commonMain/kotlin/**/presentation/ui/
4. Verify build passes: ./gradlew :feature:{featurename}:assembleAndroidMain.

Read .claude/docs/_project/stitch-project.json to load:

• projectId and shared state screen IDs (sharedStateScreens.loading.screenId, sharedStateScreens.failed.screenId)
• Per-feature screen IDs (features[featurename].successScreenId, .emptyScreenId)
• Per-feature state selections (features[featurename].states = { loading, failed, empty }). False flags mean the state was skipped at design time and is not audited below.
• Secondary screens (features[featurename].secondaryScreens[] — each { kind, screenId, role, label, htmlPath, tokensPath, dimensions }, written by /design-ui Step 1.13b). Each is an additional audit unit keyed by its role; kind: surface = an overlay (bottom sheet / dialog / modal / drawer / panel), kind: screen = a full sibling screen of the same feature (own Route, reached via callback). Empty/absent → the feature has none; audit nothing extra.
• Backward compatibility: if states is absent on a legacy feature entry, derive it from observable state — { loading: true, failed: true, empty: (emptyScreenId != null) }. Pre-optional-states features had loading/failed always present and empty only when an emptyScreenId was recorded. If secondaryScreens is absent, the feature has no secondary screens.