Instruction Language

Mission

This is a human-factors subsystem, not an animation library. Every guided screen should answer three questions within two seconds: where am I, what do I do, and how do I do it?

If the user must read a paragraph to act correctly, the screen should be simplified.

Operating Principle

• Before ADB authorization, PPSM guides the installer and waits for human action.
• After ADB authorization, PPSM takes over and advances automatically wherever verification is possible.
• The user should always know whose turn it is: user waiting, PagePoint working, or completed.

Gesture And Target

The language separates two ideas:

• Gesture teaches how: swipe, scroll, tap, repeated tap, toggle, checkbox, back button, USB cable, waiting.
• Target teaches where: Settings, About Phone, Developer Options, Build number, ALLOW, Always allow.

Gesture assets should stay generic. Target drawings should resemble Android only enough for recognition.

Instruction Layout

• Instruction pages use a vertical split.
• Left side is a short checklist of physical actions.
• Right side is the large demonstration/action panel.
• The highlighted checklist action drives the right-side demonstration.
• If no finished animation exists, the right panel shows a large action fallback instead of becoming empty.

Text Standard

• Use short action phrases: Swipe down twice, Tap Settings gear, Tap Build number 7 times.
• Avoid explanatory paragraphs during physical phone steps.
• The animation teaches how; text identifies what.

Visual Standard

• Clean line art, black outlines, thick strokes, rounded corners, and rounded line caps.
• Use the existing PagePoint accent color only.
• Use one reusable minimal phone illustration as context.
• The finger is the teacher and should receive more visual attention than the phone.
• No shadows, gradients, 3D, textures, tiny text, realistic Android detail, or decorative motion.

Motion Standard

• Loop forever.
• Last about 2 to 3 seconds.
• Move slowly and deliberately.
• Pause briefly before restarting.
• Avoid bounce, flourish, or marketing-style easing.

Technical Decision

The current PPSM implementation uses local animated SVG assets rendered by the touchscreen UI. SVG remains preferred for the foundation because PPSM operates offline, the first primitives are simple, and no player dependency is required. Lottie remains acceptable later if the library becomes complex enough to justify bundling a local player.

Current Implementation

• Mully's 20 canonical SVG primitives live under provisioning-graphics/ and are copied unchanged into the offline touchscreen asset directory.
• Compositions use a 240 x 120 internal canvas matching the right-hand demonstration panel.
• The renderer layers the approved phone, finger, gesture, control, navigation, USB, and status primitives without redrawing them.
• All 28 provisioning screens map to tap, repeated tap, swipe, scroll, checkbox, back, home, waiting, or USB scenes.
• Action timing and emphasis follow motion_spec_v1.md.
• The system was deployed to the live PPSM on 2026-07-15; no PPSM main screen changes were made.