First-run onboarding — welcome flow, interface presentation, and first animation

[Flow-Fly]

Parent initiative: #72
Depends on activation baseline: #401
Related guided drawing capability: #128
Related first-run behavior: #320
Related mobile capability: #382

Outcome

Help a new user understand Pixel Forge and complete a small, playable animation without requiring an account or replacing the normal editor with a mandatory tour.

This is a capability-level roadmap issue, not one delivery slice. It must be split after the tutorial story, presentation pattern, and Guided Drawing role are approved and playtested.

Product experience

On a fresh or explicitly requested start, offer clear choices:

• Create a blank project
• Create your first animation
• Start a Guided Drawing
• Open an existing file or project
• Continue the previous project when one exists

The welcome experience is optional. Skipping it enters the normal editor, matching the intent of #320. It remains available later from Help.

First-animation tutorial

Use a small disposable project—for example a 16×16 bouncing ball—and guide the artist through meaningful actions:

1. Understand the canvas and select a drawing color/tool.
2. Draw or complete a simple first pose.
3. Add or duplicate a frame.
4. Turn on onion skinning and explain what it shows.
5. Change the next pose.
6. Add a final frame if the approved tutorial needs it.
7. Start playback.
8. Save or export the result.
9. Leave the tutorial project as a normal editable project or delete it.

Progress should follow real editor/project state instead of assuming that a particular DOM element was clicked. The artist may experiment, undo, use keyboard shortcuts, or complete a step through another valid control.

Guided Drawing role

Guided Drawing (#128) can provide a second approachable entry path and may be reused for a constrained tutorial asset, but it must not become the generic tutorial engine by accident.

Guided mode intentionally changes palette and project structure behavior. The onboarding design must decide explicitly between:

• a normal animation tutorial that teaches the complete editor;
• a Guided Drawing introduction that lowers the drawing barrier;
• two separate optional learning paths.

If Guided Drawing is used inside the animation tutorial, verify that its frame/layer restrictions do not conflict with teaching animation. Do not widen Guided Drawing's product contract only to make onboarding easier.

Presentation / interface-highlight component

Create one reusable, accessible presentation pattern for explaining the interface. A likely implementation is a semantic modal or popover paired with an optional visual spotlight/anchor, but the final element choice must follow the interaction.

The component must support:

• a title, concise explanation, progress, Back, Next, Skip, and Finish;
• highlighting or pointing to an actual editor control when useful;
• repositioning when the viewport, timeline, or side panels change size;
• scrolling/revealing an off-screen target without trapping the user;
• keyboard operation, visible focus, and screen-reader instructions;
• Escape/cancel behavior with progress preservation;
• reduced-motion behavior;
• missing or temporarily hidden targets;
• mobile/touch layouts from Mobile apps — adaptive touch editor and cross-device projects #382;
• no opaque overlay blocking the editor when the step expects an editor action.

Prefer native dialog or popover behavior and CSS positioning where they fit. Avoid a bespoke global tour state machine tied to fragile selectors.

State and safety

• Tutorial work lives in a separately named project and never changes an existing project implicitly.
• The guide works offline and while signed out.
• Start, skip, resume, restart, and completion states are explicit.
• A stale tutorial version can restart safely after the interface changes.
• Completion is celebratory but not correctness-gated.
• The user can keep the result as normal artwork.
• Product events follow Product observability — activation funnel, client errors, and backend telemetry boundaries #401 and contain no artwork.

Delivery outline

1. Approve the tutorial story and whether Guided Drawing is a separate path.
2. Specify the presentation/highlight component and accessibility contract.
3. Build the reusable presentation component in isolation.
4. Add welcome entry, persistence, Skip/Resume/Restart, and Help-menu access.
5. Add the disposable tutorial project and state-based step recognition.
6. Add the first-animation flow.
7. Integrate the optional Guided Drawing entry.
8. Instrument and playtest the complete funnel at desktop and compact viewports.

Capability acceptance

• A first-time user can skip onboarding and immediately use the normal editor.
• A user can start, leave, resume, restart, and replay the tutorial.
• The tutorial produces a small animation that can be played and exported.
• Valid alternate controls and keyboard shortcuts can satisfy state-based steps.
• Highlighted controls remain usable, visible, and correctly associated with the explanation.
• Focus, screen-reader semantics, Escape behavior, reduced motion, and small viewports are verified.
• Existing projects are never mutated or replaced by tutorial startup.
• Guided Drawing is offered intentionally without confusing its restricted interface with the full editor.
• Tutorial events integrate with Product observability — activation funnel, client errors, and backend telemetry boundaries #401 without collecting artwork.
• A human playtest confirms that the guide helps rather than obstructs.

Decisions required before slicing

• Exact tutorial subject and number of frames.
• Normal editor tutorial, Guided Drawing tutorial, or both.
• Whether tutorial progress persists per browser or per future account.
• Modal, popover, or hybrid presentation pattern.
• Whether the tutorial creates a normal project immediately or begins from a prepared template.
• Desktop-first versus simultaneous mobile presentation behavior.

Non-goals

• No mandatory account creation.
• No forced, non-dismissible first-run gate.
• No pixel-perfect grading of the user's drawing.
• No full documentation system in this capability.
• No automatic modification of existing projects.
• No redesign of Guided Drawing unrelated to onboarding.