source-html-to-app-ui

What this skill does

# Source HTML To App UI

## Strict Instruction Contract

This file is strict implementation instruction, not loose guidance and not optional reference material.

If the Agent reads this skill, it must execute it exactly as written, in order, to the letter.

Do not reinterpret the steps.
Do not reorder the steps.
Do not skip the steps.
Do not replace the steps with a simpler approach.
Do not make assumptions that override this file.
Do not treat broad similarity, intuition, or prior habits as permission to deviate.

If the Agent is uncertain, it must resolve that uncertainty inside the workflow defined here and not invent its own workflow.
If the skill says to perform a step, gate, checklist, review, or loop, that step is mandatory.
If the skill says a later phase is blocked, the Agent must treat it as blocked.
If the Agent cannot prove a phase passed in the required artifact, it must treat that phase as failed.

## Core Idea

Re-read this `SKILL.md` after every compaction before continuing work. Re-load the phase references too. Do not rely on conversational memory.

This skill is a gated execution protocol, not a loose set of suggestions. The source HTML file exists only to produce a complete visual and behavioral reference corpus through interactive Playwright browser scripts. The finished app must then be authored in the target repo from that accepted corpus plus the supplied design-system JSON.
If the Agent has read this skill, it must follow it strictly to a T and must not deviate from its required workflow, gates, artifacts, order, or blocking rules.

Assume this skill may run fully autonomously. No human is expected to watch the run line by line. The artifact files are therefore the enforcement system. A phase is not complete because the Agent feels confident. A phase is complete only when its required artifact shows a real passing score and all critical items pass.

Never promote work from one phase to the next on optimism, partial evidence, or broad visual similarity.

When this skill says `Playwright`, it means standalone interactive Node.js Playwright scripts that directly open the source HTML app or the built target app, drive the browser, and save screenshot artifacts. It does not mean the repo's normal Playwright end-to-end test suite.

## Mandatory Process Shape

This workflow shape is not optional:

1. Launch the provided HTML app with standalone interactive Playwright scripts.
2. Discover every route, state, desktop view, mobile view, and important page section through real interaction.
3. Capture that discovery as a screenshot-backed source corpus plus written inventory and source-quality score.
4. Build the target UI as authored repo code from the accepted corpus and the design-system JSON.
5. Run a separate implementation-integrity gate on the authored code before any screenshot-based target verification begins.
6. Capture target screenshots, grade them against the source corpus, fix mismatches, and loop until the gates pass.
7. Run adversarial and functional proof before signoff.

If the work skips one of those phase boundaries, the run is off track.

## Autonomous Run Contract

Treat these rules as always active:

- Every phase must end with an objective gate.
- Every gate must be recorded in the phase-owned artifact file.
- Every gate must have both a numeric threshold and critical-item pass requirement.
- If a gate fails, remain in that phase and keep iterating.
- If later work reveals missing evidence from an earlier phase, return to that earlier phase, repair it, and re-pass the gate.
- Every phase gate is an internal control point, not a user confirmation checkpoint.
- If a phase gate passes, continue directly into the next phase without asking whether to continue.
- If a phase gate fails, rework the phase, rerun the gate, and keep looping without asking the user for permission to continue.
- The purpose of the gate, redo, verification, and rework loop is to remove the need for user confirmation during execution and let the Agent complete the run autonomously.
- If a dependency, launch detail, or local setup issue blocks progress, resolve it with the most direct logical solution that preserves the workflow and continue; for example, if the interactive Playwright method is required and its dependency is missing, install it and keep going.
- Do not lower the skill's strictness, skip gates, or change direction because of an environment issue that can be solved inside the sandbox.
- Do not stop to ask the user to choose an alternate environment or manual setup path when the sandbox can solve the blocker directly.
- Do not stop after any phase to summarize progress and ask whether to continue.
- Do not assume the user will catch a shortcut. The Agent must prevent the shortcut itself.

## Critical Output Invariant

These are hard constraints:

- The target app must be a real interactive app, not a static visual copy.
- The target app must be authored in the target repo as real routes, layouts, components, state, styling, and interactions.
- The target app must be a near one-to-one reproduction of the accepted source corpus.
- The target repo's design-system foundation must be updated before route or page implementation begins: shared CSS variables in `app/app.css` first, theme mapping in `tailwind.config.ts` second, shared UI primitives next.
- If the accepted source corpus shows a sidebar shell, the target must update and use the repo's shared sidebar component or equivalent shared shell layer instead of inventing a separate page-local sidebar system.
- Layout fidelity and style fidelity are separate hard gates.
- Route coverage and state coverage are separate hard gates.
- Visible controls in the source must become real target controls with matching states.
- The target app must own the viewport as the real product UI.
- If the target UI has a sidebar shell of any kind, vertical overflow must belong only to the content pane and not to the full page. The sidebar stays stable while the content beside it scrolls.
- The provided source HTML file is discovery input only. The finished app must not depend on it at runtime.
- Reusable component styling belongs in the corresponding shared primitive or component-local styling path, not in fake global component classes such as `.btn` or `.input` inside `app/app.css`.
- Tailwind is preferred but not mandatory. Custom CSS is allowed when needed for fidelity, but reusable design-system concerns must flow through the shared CSS variables defined in `app/app.css`.
- Primary pages or views must be implemented as real router routes or repo-native route modules, not as an in-memory page-state switch inside one large component.
- If a visible nav item exists in the shell but no accepted source route/state exists for it, the target should disable that item instead of inventing a fake destination.
- Ordinary UI structure must be exact across the screen: navigation, headers, controls, filters, tables, panels, spacing, and section order.
- Ordinary UI styling must also be exact: typography weight, surface tone, border strength, radii, shadows, density, and control treatment.
- The Agent must review the app part by part, route by route, state by state, and section by section.
- If ordinary visible drift remains, the run has not passed.

## Required References

Load only the phase-relevant references, but use all four during a full delivery run:

- `references/playwright-interactive.md`
- `references/phase-1-source-discovery.md`
- `references/phase-2-5-target-implementation.md`
- `references/phase-6-7-visual-verification.md`

## Operating Modes

### Validation Mode

Use this when improving or testing the skill itself.

- Use a throwaway target app copy.
- Preserve all source, target, and grading artifacts.
- Judge repeatability across fresh runs.
- If the same failure repeats, improve the reusable skill before running again.

### Delivery Mode

Use this when the user wants the real target app built.