Build UI Screens

Build UI Screens

Invoke as $build-ui-screens.

Build the visual UI screens for one approved UI branch. Use this skill after $ui-interview [specific-ux-variation] approves a UI experiment branch and the branch needs concrete screens before the clickable, state-backed prototype exists. This is the visual half of the build leaf; $logic-wiring is the wiring half that makes these screens reachable and interactive.

This skill builds screens as an ordered element-batch loop: one flow step at a time, adding the elements that step needs, pausing at a per-batch visual checkpoint, and stopping at the minimum UI that lets the flow step read as real. It uses fake, fixture, local, or in-memory data. It must not introduce durable database/storage, auth, payments, analytics, deployment, admin tooling, multi-tenancy, production observability, or other production infrastructure — that wiring belongs to $logic-wiring and later production planning.

Follow DESIGN-TREE-LOOP.md for design-tree routing, state storage, branch decisions, approval boundaries, and task classification. UI experiment branch state belongs in design/**/flow-tree-*.yaml, not tasks/todo.md.

Gate

Before building, verify the approved branch is explicit:

• Read design/**/flow-tree-*.yaml and resolve the named ui_experiments[] branch. If $ARGUMENTS is missing, choose the first approved UI experiment branch that has no visual screens yet (no build_ledger[] past minimum-ui-reached and no experiment_path/review_evidence), honoring any recorded branch-order override.
• Read the branch packet from design/ui-[topic].md, design/ui-requirements-[topic].md, or product-path-scoped equivalents.
• Read the parent design/ux-variations-[topic].md, design/user-flow-[topic].md, and any relevant design/brainstorm-inspirations-{topic}.md or design/take-inspiration-{topic}-*.md when present.
• Stop if no UI branch has an explicit approve decision. Route back to $ui-interview [specific-ux-variation].
• Stop if the requested work needs production infrastructure. Record the deferred infrastructure and route to prototype evidence first.

Process

1. Resolve scope. Identify the product path, topic, parent user-flow branch, UX variation branch, and approved UI experiment branch. Preserve branch IDs from the flow-tree manifest. Read the batch plan authored by $ui-interview when present.
2. Define the first-value journey. Name the first-value moment, the primary task path, the entry route, the exit/success state, and the evidence needed before moving deeper.
3. Choose the screen home. Prefer a project-native lightweight route when the app already has a safe local experiment surface. Otherwise create a disposable route under experiments/{topic}/{ui-experiment-id}/. Keep the screens easy to remove.
4. Walk the element-batch loop. Treat each flow step as one batch (build_ledger[] entry = one flow_step). For each batch, in flow order:
   • Add only the visual elements that flow step needs. Use fake, fixture, local, or in-memory data.
   • Pause at a per-batch visual checkpoint: render the screen and confirm it reads as the intended moment before moving to the next batch.
   • Apply the minimum-UI stop rule: stop adding elements once the flow step reads as real. Do not over-build secondary controls, alternate states, or dense admin surfaces in this pass.
   • Record the batch in the ui_experiments[].build_ledger[] array: id, flow_step, elements_added[], status minimum-ui-reached once the stop rule fires (or parked if the batch is deferred out of this pass), and a short notes.
5. Progressive reveal. Introduce first value and the primary task path before dense secondary controls. Hide, defer, or stub secondary controls until the screens prove the core journey.
6. Review evidence. Produce a concise review note naming what the user should look at, what the screens establish, what worked, what remains unknown, and which deferred infrastructure stays out of scope.
7. Update branch state. Write the build_ledger[] entries and add experiment_path and review_evidence to the relevant ui_experiments[] branch in the flow-tree manifest. Keep artifacts[] for canonical design and review files. Do not create or update the prototype build plan from here.
8. Build the alignment page. Render the per-batch screens, first-value journey, fake-data boundary, build ledger, deferred infrastructure, and review gate in alignment/build-ui-screens-{topic}.html.

Output

The skill may create or update:

experiments/{topic}/{ui-experiment-id}/
design/**/flow-tree-*.yaml
alignment/build-ui-screens-{topic}.html

When using a project-native route instead of experiments/, record the exact route path in experiment_path and the concise note or repo-relative review artifact in review_evidence in the flow-tree manifest and in the alignment page.

Next Work

After the screens exist and the build ledger is written, choose the next route from filesystem state:

• $user-flow-map --prototype-build-plan [topic] is the default next step when no valid prototype build plan exists. Use this when design/**/prototype-build-plan-*.md is missing, or when present build-plan artifacts do not include the approved ui_experiment_id for the UI experiment just built.
• $logic-wiring [topic] may be recommended only when design/**/prototype-build-plan-*.md exists and includes the approved ui_experiment_id as a build item. This makes the built screens clickable and state-backed by advancing the matching build item and build_ledger[] entries from minimum-ui-reached to wired.
• $logic-wiring [topic] may also be used as an explicit untracked ad hoc bypass only when the user knowingly accepts skipping the prototype build-plan ledger for this run. Name that bypass in the handoff and do not imply it is the tracked default.
• $uat --variant-evaluation when the screens themselves are being used as the evaluated variant artifact.

Recommended next command: $user-flow-map --prototype-build-plan [topic].

If a valid prototype build-plan item already references the approved ui_experiment_id, the terminal handoff may instead recommend the resolved $logic-wiring [topic] or $logic-wiring [topic] --variant N command for that item.

Invoke With YAML

Emit agent_routing only after resolving prototype-build-plan state:

• Missing or invalid build plan: approved_next_skill: "$user-flow-map --prototype-build-plan [topic]".
• Valid build plan with the approved ui_experiment_id: set approved_next_skill to the resolved wiring command for the matching item, such as $logic-wiring [topic] or $logic-wiring [topic] --variant N.
• Explicit user-accepted untracked ad hoc bypass: set approved_next_skill to the resolved wiring command and include routing_note: "untracked ad hoc bypass accepted by user; no prototype build-plan item exists".

Do not emit an unconditional wiring value in approved_next_skill from this skill.

Do not route to production planning, roadmap work, or durable infrastructure until experiment review evidence explicitly promotes the branch.

Constraints

• Use fake, fixture, local, or in-memory data only.
• Build one approved UI experiment branch per run.
• Build one flow-step batch at a time; stop each batch at the minimum UI that lets the step read as real.
• Use progressive reveal; do not expose dense secondary controls before the primary task path reads.
• Do not wire clickable navigation, state transitions, or runnable logic — that is $logic-wiring's job.
• Do not build production infrastructure, external account integrations, deployment automation, or durable storage.
• Do not skip the review evidence gate before handing off to $user-flow-map --prototype-build-plan, $logic-wiring, or $uat --variant-evaluation.
• Do not route to $logic-wiring before the prototype build-plan slice exists and includes the approved ui_experiment_id, unless the user explicitly accepts an untracked ad hoc bypass.
• When recommending a skill from another pack, verify the pack is installed via .agents/project.json enabled_packs. If not installed, recommend npx skillpacks install <pack-name> from the project shell before the target skill.

Alignment Page

Follow the shared alignment-page convention via the packaged convention resolver; output path is alignment/build-ui-screens-{topic}.html.

The page must show the per-batch screens, first-value journey, primary task path, build ledger, fake-data boundary, deferred infrastructure, review evidence, and the exact downstream handoff gate.

Default Shipping Contract

Follow the shared shipping contract convention in CLAUDE.md.