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:

Launch the provided HTML app with standalone interactive Playwright scripts.
Discover every route, state, desktop view, mobile view, and important page section through real interaction.
Capture that discovery as a screenshot-backed source corpus plus written inventory and source-quality score.
Build the target UI as authored repo code from the accepted corpus and the design-system JSON.
Run a separate implementation-integrity gate on the authored code before any screenshot-based target verification begins.
Capture target screenshots, grade them against the source corpus, fix mismatches, and loop until the gates pass.
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.
When the accepted source corpus shows a fixed sidebar shell with scrolling content beside it, vertical overflow must belong to the content pane, not the full page, unless the source evidence explicitly proves otherwise.
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.

Work inside the provided target repo.
Treat the accepted source corpus as the design authority.
Do not sign off until every gate in this file has passed in writing.

Required Artifacts

These are mandatory in delivery mode:

```
mocks/source/
```
```
mocks/verification/
```
```
design/spec.json
```
```
design/source-inventory.md
```
```
design/source-quality-review.md
```
```
design/implementation-reading.md
```
```
design/implementation-review.md
```
```
design/implementation-open-gaps.md
```
```
mocks/verification/final-desktop.png
```
```
mocks/verification/final-mobile.png
```

The templates in

assets/templates/

are enforcement artifacts. Copy their structure directly. If a required table is replaced by prose or stripped down until rows are no longer auditable, the run fails.

Multi-Phase Protocol

Phase 0: Start-Up And Artifact Scaffolding

Determine mode: validation or delivery.
Read the target repo
```
AGENTS.md
```
.
Confirm the task includes:
- path to the self-contained source HTML app file
- path to the design-system JSON
Copy or normalize the design-system JSON into
```
design/spec.json
```
.
Create the required artifacts from templates.

Read:

```
references/playwright-interactive.md
```
```
references/phase-1-source-discovery.md
```

Inspect the target repo's real route, layout, theme, and test structure.
Decide how the source HTML app will be launched with interactive Playwright.
Do not edit target app UI files yet.
Do not treat HTML reading as a substitute for the discovery run.

Phase 0 Gate: Start-Up Gate

This gate is recorded in

design/source-quality-review.md

Score this phase as

10/10

Pass rule:

all
```
10/10
```
items above are complete
no target UI implementation files have been edited yet

If the phase scores below

10/10

, remain in Phase 0.

Phase 1: Source Discovery And Acceptance Loop

Read
```
references/playwright-interactive.md
```
again before writing the discovery scripts.
Write dedicated interactive Playwright discovery scripts for the source app.
Open the source HTML app with those scripts.
Capture the default desktop and mobile views.
Discover every route and meaningful state through real UI interaction.
Capture desktop and mobile screenshots for every discovered route/state.
Capture focused section crops for shell, navigation, header, dense workflow surfaces, dialogs, drawers, and any section that later needs section-level grading.
Fill
```
design/source-inventory.md
```
.
Fill
```
design/source-quality-review.md
```
.
If coverage is incomplete, rerun the interactive scripts from clean Node.js processes and capture more evidence.
Keep looping until the written source-quality gate passes.

HTML reading, DOM inspection, and script inspection may clarify behavior, but they do not replace interactive Playwright discovery and cannot satisfy this phase on their own.

Phase 1 Gate: Source Promotion Gate

This gate is owned by

design/source-quality-review.md

Pass rule:

score is at least
```
48/50
```
every critical discovery item passes
every discovered route/state has desktop evidence
every discovered route/state has mobile evidence unless a real source limitation is recorded
every visible page section has screenshot evidence and a written contract
every route/state row in
```
design/source-inventory.md
```
cites actual screenshot paths

If this gate fails, implementation is blocked. Stay in Phase 1.

Phase 2: Implementation Reading And Build Plan

Read:

```
design/spec.json
```
```
design/source-inventory.md
```
```
design/source-quality-review.md
```

references/phase-2-5-target-implementation.md

Write
```
design/implementation-reading.md
```
before coding.
Map the accepted source corpus into target files, routes, sections, and interaction families.
Map the design-system foundation work into the repo's real theme entry points, starting with
```
app/app.css
```
, then
```
tailwind.config.ts
```
, then the shared
```
app/components/ui/*
```
primitives.
Cite the exact source screenshots the implementation will build from.
List the visual and behavioral risks most likely to drift.
Fill the ordered implementation checklist in
```
design/implementation-reading.md
```
and keep the steps in strict execution order.
If the corpus is ambiguous, return to Phase 1, rerun the source interactive Playwright scripts, capture more evidence, and re-pass the source gate.

Phase 2 Gate: Planning Gate

This gate is owned by

design/implementation-reading.md

Pass rule:

score is at least
```
19/20
```
every planned route/state cites source evidence
every planned build region maps to concrete target files or extension points
the design-system foundation plan maps token work to
```
app/app.css
```
, theme mapping to
```
tailwind.config.ts
```
, and shared reusable control work to concrete
```
app/components/ui/*
```
files or equivalent repo-native extension points
the ordered implementation checklist is filled and shows the intended build order through shell, routes, sections, states, and mobile
no source-critical ambiguity remains unresolved

If this gate fails, implementation is blocked. Stay in Phase 2 or return to Phase 1 if evidence is missing.

Phase 3: Theme And Shell Reproduction Loop

Translate
```
design/spec.json
```
into the target repo's real theme entry points.
Update
```
app/app.css
```
first so the shared CSS variables and global design tokens become the styling source of truth.
Update
```
tailwind.config.ts
```
after that so Tailwind theme values consume those shared CSS variables.
Inspect the repo's component demo or reference surface and existing
```
app/components/ui/*
```
primitives before changing route or page files.
Update shared component wrappers or primitives where the source app requires custom treatment.
Do not create fake global reusable component classes such as
```
.btn
```
,
```
.btn-primary
```
,
```
.input
```
, or
```
.badge
```
in
```
app/app.css
```
; put reusable component styling in the corresponding shared primitive instead.
Rebuild the shell so the target owns the viewport as the actual product UI.
Mark the Phase 3 ordered-checklist rows as
```
Done
```
,
```
Failed
```
, or
```
Blocked
```
in
```
design/implementation-review.md
```
and cite exact file evidence.

Capture

mocks/verification/01-theme-shell-desktop.png

Update
```
design/implementation-review.md
```
.
Update
```
design/implementation-open-gaps.md
```
.
Fix shell, theme, shared-component, or checklist-order drift before moving on.
Do not implement route or page UI until this phase passes in writing.

Phase 3 Gate: Theme And Shell Gate

This gate is owned by

design/implementation-review.md

Pass rule:

score is at least
```
19/20
```
the design-system foundation is visibly established in
```
app/app.css
```
and
```
tailwind.config.ts
```
shared reusable controls are adapted in
```
app/components/ui/*
```
or the repo's equivalent primitive layer before route/page implementation begins
reusable component styling is not being introduced through fake global component classes in
```
app/app.css
```
every Phase 3 ordered checklist row is marked
```
Done
```
with evidence and none are marked
```
Failed
```
no critical shell-ownership issue remains

mocks/verification/01-theme-shell-desktop.png

exists

open gaps for shell/theme are explicitly recorded or resolved

If this gate fails, route and page implementation is blocked. Stay in Phase 3.

Phase 4: Route, State, And Section Reproduction Loop

Implement every accepted primary page or view from
```
design/source-inventory.md
```
as a real router route or repo-native route module, not as an in-memory page-state switch.
Build route and page UI from the adapted shared primitives as the default path.
Implement every listed page section, not just the outer page layout.
Use real local state and real interactions for tabs, filters, dialogs, drawers, menus, row selection, and mobile navigation.
If the source shell exposes nav items that do not have accepted source pages or states behind them, render them as disabled or unavailable rather than inventing fake destinations.
If the source shell has a sidebar plus scrolling content pane, keep the sidebar shell stable and scope vertical overflow to the content region instead of the whole page unless source evidence proves full-page scroll.
Custom CSS is allowed where needed for fidelity, but reusable design-system concerns must flow through the shared CSS variables and primitive layer instead of one-off global component classes.
Update
```
app/routes.ts
```
or the repo's equivalent route registration entrypoint and create the required route files before adding page-state logic inside route modules.
Mark the Phase 4 ordered-checklist rows as
```
Done
```
,
```
Failed
```
, or
```
Blocked
```
in
```
design/implementation-review.md
```
and cite exact route-file evidence.
After each meaningful pass, capture matching target screenshots.
Update
```
design/implementation-review.md
```
.
Update
```
design/implementation-open-gaps.md
```
.
If a source route, state, or section is still missing, generic, fake, or out of order in the checklist, keep iterating.

Phase 4 Gate: Route And State Gate

This gate is owned by

design/implementation-review.md

Pass rule:

score is at least
```
28/30
```
every critical route/state item passes
every primary route exists as real target route UI
no primary route is implemented as a page-state machine inside one large component
every source interaction family exists as real target interaction
every source-listed page section has a target counterpart and review row
shell nav items without accepted source destinations are disabled instead of routing to invented pages
when the source shell shows sidebar-plus-content scrolling, vertical overflow is scoped to the content region instead of the whole page unless source evidence says otherwise
reusable controls are implemented through shared primitives or component-local styling, not fake global component classes
mobile route/state coverage exists for the accepted mobile corpus
every Phase 4 ordered checklist row is marked
```
Done
```
with evidence and none are marked
```
Failed
```

If this gate fails, stay in Phase 4.

Phase 5: Implementation Integrity Gate Loop

Read

references/phase-2-5-target-implementation.md

again before running the gate.

Review the authored target code and confirm the design-system foundation is actually in place:
- ```
app/app.css
```
  is the shared CSS-variable source of truth
- ```
tailwind.config.ts
```
  maps theme values to those variables
- shared
```
app/components/ui/*
```
  primitives or repo-native equivalents own reusable control styling
Review route architecture and confirm primary pages or views are implemented as real route modules or repo-native route boundaries.
Review interaction truth and confirm visible controls are implemented as real behavior rather than static markup or decorative state.
Review state distinction and confirm distinct source states are still distinct in the target implementation.
Review shell ownership and confirm sidebar usage, scroll ownership, and disabled-nav behavior match the accepted source shell.
Run the dedicated Phase 5 implementation-integrity checklist in
```
design/implementation-review.md
```
and mark every row
```
Done
```
,
```
Failed
```
, or
```
Blocked
```
with evidence.
Run the required non-visual repo checks for the implementation, including code checks, build checks, and targeted tests needed for the changed behavior.
Update
```
design/implementation-review.md
```
.
Update
```
design/implementation-open-gaps.md
```
.
Fix implementation-architecture, primitive-ownership, route, state, interaction, shell, or test-integrity failures.
Rerun the implementation gate until it passes in writing.

Phase 5 Gate: Implementation Integrity Gate

This gate is owned by

design/implementation-review.md

Pass rule:

score is at least
```
28/30
```
every critical implementation-integrity item passes
the design-system foundation is visibly established in
```
app/app.css
```
and
```
tailwind.config.ts
```
shared reusable controls are adapted in
```
app/components/ui/*
```
or the repo's equivalent primitive layer before page-level styling takes over
no reusable component styling is being introduced through fake global component classes
every primary page or view exists as a real route boundary
no major page architecture is implemented as a single in-memory page-state machine
source interaction families are implemented as real target interactions
distinct source states are not collapsed into one generic target state
if the source shell has a sidebar, the repo's shared sidebar component or equivalent shared shell layer is actually used
shell nav items without accepted source destinations are disabled instead of linking to invented pages
vertical overflow belongs to the source-matching content pane rather than the full page when the accepted shell shows a fixed sidebar plus scrolling content
required implementation artifacts are filled with real content, not template placeholders
required repo checks for the changed implementation have passed
every Phase 5 integrity checklist row is marked
```
Done
```
with evidence and none are marked
```
Failed
```

If this gate fails, visual verification is blocked. Stay in Phase 5.

Phase 6: Visual Verification Loop

Read:

```
references/playwright-interactive.md
```

references/phase-6-7-visual-verification.md

Start the target app using the repo's normal command.
Write dedicated interactive Playwright verification scripts for the target app.
Capture target screenshots that mirror the accepted source inventory.
Capture focused section evidence where full-page screenshots are not enough.
Compare source and target route by route, state by state, and section by section.
Update
```
design/implementation-review.md
```
.
Update
```
design/implementation-open-gaps.md
```
.
Fix mismatches.
Rerun the interactive Playwright verification scripts from clean Node.js processes.
Keep looping until the written verification gate passes.

Phase 6 Gate: Visual Fidelity Gate

This gate is owned by

design/implementation-review.md

Pass rule:

score is at least
```
49/50
```
desktop fidelity score is at least
```
48/50
```
mobile fidelity score is at least
```
48/50
```
every critical verification item passes
every source route/state row has target evidence
every source-listed page section has target evidence and a passing section-review row
```
design/implementation-open-gaps.md
```
contains no unresolved ordinary drift
final desktop and mobile screenshots exist

If this gate fails, stay in Phase 6. If either desktop or mobile fidelity is below

48/50

, fix the weaker viewport, rerun the interactive verification scripts, rescore, and keep looping until both pass.

Phase 7: Adversarial And Functional Proof Loop

Assume the implementation is still wrong.
Find at least five serious possible mismatches.
Check each against the accepted source corpus.
Fix true mismatches.
Record defended non-blocking differences with concrete reasoning.
Exercise each visible interaction family with real user input.
Capture at least one proof screenshot per interaction family.
Update the adversarial and functional sections of
```
design/implementation-review.md
```
.

Phase 7 Gate: Adversarial Proof Gate

This gate is owned by

design/implementation-review.md

Pass rule:

score is at least
```
19/20
```
at least five serious suspected mismatches were checked
every checked mismatch was either fixed or explicitly defended
every visible interaction family has functional proof
mobile is included in the adversarial pass

If this gate fails, stay in Phase 7 and keep iterating.

Phase 8: Final Signoff

Before signoff:

Re-check that every earlier phase gate passed in writing.
Re-check that required artifacts still use their required tables.
Re-check that the app is authored repo code rather than source-file reuse.
Re-check that final screenshots exist.
Run the target repo's required checks when code changed.
If any ordinary mismatch remains, return to the failing phase.

Phase 8 Gate: Signoff Gate

This gate is owned by

design/implementation-review.md

Score this phase as

12/12

Pass rule:

all earlier gates passed and remain current
all required artifacts exist
final desktop and mobile screenshots exist
open gaps contain no unresolved ordinary drift
required review tables remain intact
repo checks required for code changes have been run
the app is interactive
the app does not depend on the provided source HTML file at runtime
the app owns the viewport as the product UI
no placeholder or generic route remains
no ordinary section remains unreviewed
no critical item remains failing

If the phase scores below

12/12

, signoff is blocked.

Disallowed Shortcuts And Automatic Fails

These shortcuts automatically fail the run:

moving to implementation before the source gate passes
moving past planning before the planning gate passes
moving past theme/shell before the theme gate passes
moving past route/state build before the route/state gate passes
moving to visual verification before the implementation-integrity gate passes
signing off before the implementation-integrity, visual, and adversarial gates pass
stopping after any phase to ask the user whether to continue
treating any passed phase gate as a user handoff point instead of an automatic promotion into the next phase
filling the implementation checklist out of order and then treating the later steps as valid
skipping the checklist evidence columns or leaving checklist rows in placeholder state while claiming the phase passed
reading the HTML file and inferring the app without interactive Playwright discovery
using repo Playwright E2E tests as a substitute for the interactive Playwright discovery or verification scripts
embedding, fetching, or rendering the provided source HTML file at runtime
using
```
iframe
```
,
```
srcDoc
```
,
```
object
```
,
```
embed
```
,
```
webview
```
, or injected raw HTML as the product UI
building a screenshot viewer, design board, gallery shell, poster shell, or device frame around the app
treating route existence as proof of route fidelity
treating a green test suite or a successful build as proof of visual fidelity
replacing required audit tables with prose
leaving ordinary mismatches undocumented in the open-gaps ledger
treating visible interactive controls as static markup
skipping mobile discovery, mobile implementation, or mobile grading
approving work from overall vibe rather than row-by-row evidence

Reference Map

```
references/phase-1-source-discovery.md
```
: Phase 1 discovery and source acceptance.
```
references/phase-2-5-target-implementation.md
```
: Phase 2 planning plus Phase 3, Phase 4, and Phase 5 implementation integrity.
```
references/phase-6-7-visual-verification.md
```
: Phase 6 visual QA plus Phase 7 adversarial and functional proof.
```
references/playwright-interactive.md
```
: how this skill uses interactive Playwright scripts for discovery and verification.

assets/templates/phase-1-source-inventory.md

assets/templates/phase-0-1-source-quality-review.md

assets/templates/phase-2-implementation-reading.md

assets/templates/phase-3-8-implementation-review.md

assets/templates/phase-3-8-implementation-open-gaps.md

Non-Negotiables

Use the phase gates exactly.
Keep the artifacts auditable.
Return to earlier phases when evidence is weak.
Do not let the provided source HTML leak into the finished runtime.

source-html-to-app-ui

NPX Install

Tags

SKILL.md Content

Source HTML To App UI

Strict Instruction Contract

Core Idea

Mandatory Process Shape

Autonomous Run Contract

Critical Output Invariant

Required References

Operating Modes

Validation Mode

Delivery Mode

Required Artifacts

Multi-Phase Protocol

Phase 0: Start-Up And Artifact Scaffolding

Phase 0 Gate: Start-Up Gate

Phase 1: Source Discovery And Acceptance Loop

Phase 1 Gate: Source Promotion Gate

Phase 2: Implementation Reading And Build Plan

Phase 2 Gate: Planning Gate

Phase 3: Theme And Shell Reproduction Loop

Phase 3 Gate: Theme And Shell Gate

Phase 4: Route, State, And Section Reproduction Loop

Phase 4 Gate: Route And State Gate

Phase 5: Implementation Integrity Gate Loop

Phase 5 Gate: Implementation Integrity Gate

Phase 6: Visual Verification Loop

Phase 6 Gate: Visual Fidelity Gate

Phase 7: Adversarial And Functional Proof Loop

Phase 7 Gate: Adversarial Proof Gate

Phase 8: Final Signoff

Phase 8 Gate: Signoff Gate

Disallowed Shortcuts And Automatic Fails

Reference Map

Non-Negotiables