Skip to main content
skill CX Codex

source-html-to-app-ui — Claude Code skill: rebuild HTML as app UI

source-html-to-app-ui turns an approved HTML mockup into a working app UI: real routes, components, local state, responsive behaviour, and paired Playwright evidence for source and target.

MIT 233 installs ★ 2 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add customware-ai/skills --skill source-html-to-app-ui -a claude-code
Open on GitHub

What source-html-to-app-ui does

The skill takes an approved HTML mockup and rebuilds it inside your target repository as a normal app: real routes, components, styles, assets and local UI state. Backend, API, database, auth and business logic stay out of scope. Work runs in gated phases, and until the source contract (Phase 0) passes, the agent does not touch the target repository at all.

The order is fixed. Copy the source HTML into task-workflow/, write CURRENT_PHASE.txt, capture a desktop and a mobile screenshot through the lifecycle helper, then read the full HTML, inline CSS and JS to the end. Next comes an inventory of pages and states, a walk through every image in the manifest, implementation, and a Playwright comparison of source and target at matching routes, themes and viewports. progress.md and open-gaps.md carry state across sessions and compactions.

Playwright and the lifecycle helper are part of the loop, not an add-on. Without them there is no paired evidence and the last phase never closes. A loose “make it look similar” pass does not survive the audit either: every screen, state and interaction family found in the source gets checked.

What it helps with

  • rebuild an approved HTML mockup as real routes and components
  • compare source and target at the same routes and viewports
  • catch sections and states lost during a design port
  • check mobile, short-height, theme and overflow behaviour
  • keep workflow state across sessions with progress.md

Example prompts for the agent

  • Rebuild approved-mock.html as real routes and components in our app, UI only.
  • Capture paired Playwright screenshots of source and target on desktop and mobile, then list where the layout drifts.
  • Run the audit before the task-completion command and repair the states and themes that were missed.

How to install source-html-to-app-ui

1Skills CLI (Vercel)

npx skills add customware-ai/skills --skill source-html-to-app-ui -a claude-code

2Manually: put the files in place

~/.claude/skills/source-html-to-app-ui/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/source-html-to-app-ui/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about source-html-to-app-ui

How do I install source-html-to-app-ui in Claude Code?

Run npx skills add customware-ai/skills --skill source-html-to-app-ui -a claude-code. The skill file lands at ~/.claude/skills/source-html-to-app-ui/SKILL.md.

What does source-html-to-app-ui do?

It turns an approved HTML mockup into a working interface in your repository: routes, components, styles and local state. It also gathers paired Playwright evidence and runs a final audit.

Does it add a backend?

No. The task is UI-only, so no API, database, persistence, auth or server code is part of it.

Source text

SKILL.md · MIT
---
name: source-html-to-app-ui
description: Rebuild an approved source HTML application as a real, high-fidelity UI in the target repository. Use for source-to-app design tasks requiring interactive source discovery, authored routes and components, local UI behavior, responsive/theme adaptation, and paired Playwright evidence.
---

# Source HTML To App UI

## Objective

Reproduce the approved source HTML as a real target application. The finished experience is the primary measure of success:

- every source page, meaningful state, visible section, and interaction family is represented;
- the target preserves source content, hierarchy, layout, styling, controls, and behavior wherever evidence exists;
- desktop, mobile, short-height, theme, drawer, and overflow behavior remain usable;
- paired Playwright evidence shows the source and target at matching routes, states, themes, viewports, and sections;
- the final audit finds and repairs missing quality work before the exact task-completion command runs.

Use the source HTML for discovery and comparison. Author the target as a normal application with real routes, components, styles, assets, and local UI state. Keep the task UI-only: do not add backend, API, database, persistence, authentication, server, or business logic.

## Strict execution contract

<execution_contract>

This is an end-to-end implementation workflow, not optional advice. A passing phase unlocks the next phase; it is not a successful stopping point. Do not stop after source discovery, Phase 0, target research, implementation, or a partial verification run. If the next phase is locally unblocked, continue into it automatically. The task is not complete until Phase 4 passes and the exact task-completion command has run successfully.

The Agent owns every gate. Browser scripts collect evidence; the Agent reviews the evidence, scores the phase, repairs failures, and promotes the marker. A normal packet failure is a repair loop: inspect the helper-owned failure, fix the same packet, rerun it through the lifecycle helper, and refresh invalidated evidence. A process violation or an unproven gate is a failed run, not permission to continue or sign off.

After compaction, resume, retry, reconnect, or a new session, reread this skill, the current phase reference, the current artifact, `progress.md`, `open-gaps.md`, and the task-owned evidence needed for the next action before doing any work. Never rely on conversation memory or an old `Pass` label as the next-step decision.

</execution_contract>

## First-action lock

<first_action_lock>

The first task turn is source-only. Do not inspect the target repository to orient yourself, confirm its routes, find a logo, check its build, or choose an asset before the source checkpoint below. A target path present in the task message is an input boundary, not permission to read that path. Do not run `ls`, `find`, `tree`, `rg --files`, `git status`, or an equivalent command against the target root; even listing target directory names is target inspection and is forbidden until the unlock. Before orientation, the only allowed skill reads are this `SKILL.md` and the exact Phase 0/lifecycle reference paths named below; never list, glob, search, or inspect the skill root, `references/`, or `assets/` directories to discover files.

Follow this exact order:

1. Read this skill and only the Phase 0 and lifecycle references required for the current marker, using their exact paths from the reference map. Do not list, glob, search, or read any other path under `.agents/skills/source-html-to-app-ui/`, including `references/`, `assets/templates/`, and `assets/scripts/`, before orientation. Use only the exact asset paths named in this skill when copying later; do not enumerate the skill package to discover them. Templates and the helper are copy-only until then, and the helper command contract is already authoritative.
2. Create a fresh `task-workflow/` and set `CURRENT_PHASE.txt` to `phase-0-source-contract`.
3. Copy the approved source HTML and design input byte-for-byte into `task-workflow/`. You may read the design input for setup, but do not open or read the copied/source HTML, inline CSS, or JavaScript yet.
4. Run the first source orientation through the lifecycle helper at desktop and mobile, passing the exact served HTML URL to the packet (for example `--env SOURCE_URL=http://127.0.0.1:5192/approved-mock.html`). The orientation packet produces exactly one desktop image and one mobile image. After the successful helper result, the next two tool calls must be exactly: read the desktop orientation image, then read the mobile orientation image. Record a concrete finding for each. No source/design read, packet write, search, shell command, or other tool call may occur between those two image reads or before them. If either image has not been read, source inspection has not started and reading source/design content is an automatic Phase 0 failure. It must assert a successful response, that the final response URL exactly equals `SOURCE_URL`, and non-directory document content. If task metadata supplies an expected title or identity, assert it; otherwise record the title and reconcile it after the complete HTML read. Helper readiness or a non-empty title alone is not sufficient.
5. Read the approved HTML, inline CSS, and JavaScript completely to EOF.
6. Create and run the complete source inventory through the lifecycle helper. Then perform an image-by-image manifest walk: read the complete manifest, open every referenced full-view, section, state, desktop, and mobile image, and record one concrete finding for each image. Continue until the opened-image count exactly equals the manifest count; a key-image pass, one-image-per-route pass, representative sample, manifest-only review, or one-viewport review is a failed Phase 0 step.
7. Write and reopen `task-workflow/phase-0-source-contract.md`, reconcile `progress.md` and `open-gaps.md`, score at least `48/50`, and pass every critical row.
8. Set `CURRENT_PHASE.txt` to `phase-1-ui-implementation`, reopen the Phase 0 artifact, and only then inspect target architecture, existing assets, routes, packages, configuration, build output, or runtime files.

The target-inspection unlock requires all of step 7, not merely captured screenshots, a completed inventory, a plan, or a claim that the source is understood. If any part of the checkpoint is missing, stay source-only. If you are uncertain whether it passed, treat it as not passed. The first source orientation also has an ordering lock: before step 4 completes and its desktop/mobile images are opened, do not open/read the source HTML or any inline CSS/JavaScript, even to plan the orientation packet. A failed lifecycle invocation does not complete step 4. Treat that failure as a hard pause in Phase 0: the only legal next action is to inspect the helper-owned failure, repair the bounded invocation (for example choose another explicit port), read the repaired packet, and rerun through the lifecycle helper. Do not read source HTML/CSS/JavaScript or design JSON, write the Phase 0 handoff, or treat helper logs/partial screenshots as orientation evidence until a helper-owned rerun succeeds and every successful orientation image has been opened.

The task message may require real brand logos. That requirement still applies, but its “one and only exception” wording is an asset-selection instruction, not an early-inspection exception. Record the requirement in the Phase 0 contract and inspect or copy the real logo only after the source checkpoint unlocks target research. Never open `public/`, `build/`, or another target asset path early to locate it.

Before the first lifecycle orientation, do not run any read, listing, existence check, environment probe, or availability probe in the target repository or in `task-workflow/`. The only permitted pre-orientation actions are direct scaffold/copy writes into `task-workflow/**`, followed by one orientation-packet write, one mandatory orientation-packet readback, and the lifecycle-helper invocation. Setup is write-only: every shell command that creates directories or copies files must end at its last write. `cp <anything> task-workflow/... && ls ...`, `mkdir ... && cp ... && ls ...`, a separate `ls` after setup, a trailing `echo`/`printf` that only announces setup, or any appended `cat`, `test`, `stat`, `git status`, `find`, `rg`, or other verification is a hard process failure. A final `printf 'phase-0-source-contract' > task-workflow/CURRENT_PHASE.txt` is a valid setup write when it is the last write and is immediately followed by the orientation-packet write. Do not use a second shell command to verify or announce setup. After the last setup write, the next tool action must write the orientation packet; after that write, the next tool action must read the complete orientation packet; only that read may be followed by the first lifecycle invocation. You may copy templates and the lifecycle helper for later phases, but do not list, reopen, or read any copied helper, template, source file, ledger, or other task-workflow artifact before the orientation packet readback; **reading the copied `playwright-lifecycle.mjs` to learn its flags or parameters is forbidden because the command contract below is authoritative**. Do not list `task-workflow/`, reopen a template, inspect a ledger, or check an existence/metadata state first. The exact forms `test -d`, `test -e`, `test -f`, `stat`, `file`, `wc`, `du`, `head`, `tail`, `sed`, `grep`, and `rg` are forbidden before the first helper, including when they are used only to check whether cleanup is needed or to learn source-file size. Do not run `ls`, `find`, `tree`, `git status`, `which`, `command -v`, `python --version`, `node --version`, `--help`, or similar commands. Use a known bounded server command directly in the helper; do not test whether Python, Node, Playwright, or a port exists first.

</first_action_lock>

### Pre-orientation read allowlist — hard cutoff

Before the first successful lifecycle orientation, the only files the Agent may read are this `SKILL.md`, `references/phase-0-source-contract.md`, and `references/playwright-lifecycle.md` at their exact mapped paths, plus the task message. Reading any other path is a run-invalidating Phase 0 failure. This explicitly includes `assets/scripts/playwright-lifecycle.mjs`, every file under `assets/templates/`, any copied helper or template, `task-workflow/**`, the source HTML, inline CSS, JavaScript, design JSON, target repository, package files, and runtime files. The helper and templates may be copied as blind byte-for-byte writes, but they must not be opened to learn flags, structure, or content. The command contract in this skill is sufficient; do not read the helper to verify or understand it. If this cutoff is broken, stop, reset the fixture, and restart Phase 0.

Before the first orientation, copy the helper and templates byte-for-byte when setup requires them, using only the exact paths in the Asset Map. Do not list, glob, search, or read `.agents/skills/source-html-to-app-ui/references/`, `.agents/skills/source-html-to-app-ui/assets/scripts/`, `.agents/skills/source-html-to-app-ui/assets/templates/`, or any copied helper/template to discover flags, structure, or parameters. The lifecycle command contract and mapped references are authoritative; copying is allowed, directory enumeration and asset inspection are not.

## Non-negotiable test gates

<hard_stop_rules>

This run is testing whether the workflow is followed. The following actions are not harmless investigation; each one invalidates the current run and requires a reset before continuing:

| Never execute | Correct action |
| --- | --- |
| `ls`, `find`, `cat`, or any equivalent inspection of `/ms-playwright`, `~/Library/Caches/ms-playwright`, `node_modules/playwright-core`, `browsers.json`, browser executable paths, revisions, or process/port state; `which`, `command -v`, `--version`, `--help`, or similar server/runtime availability probes before the first helper run | Write the task-owned packet and invoke the real lifecycle helper; its first packet is the only availability test |
| `node -e`, `node --eval`, a heredoc browser program, `node task-workflow/**/<packet>.mjs`, or any direct `chromium.launch()` process | Run the packet only as the helper's `--run` payload |
| `page.waitForTimeout(`, `waitForTimeout(`, `setTimeout(`, `setInterval(`, shell `sleep`, or timer/arbitrary polling used to settle UI | Wait for visible DOM, URL, response, geometry, or assertion state |
| a manual/background server, `curl`/`wget` readiness probe, `pkill`, `lsof`, or broad process cleanup | Give server startup, readiness, logs, and PID cleanup to the helper |
| a task-message asset/logo exception, required brand-logo path, target-root path, or implementation requirement used to justify early target inspection | Record the requirement and defer every target read until the literal Phase 0 checkpoint passes |
| opening, counting, or reading the approved source HTML, inline CSS, or JavaScript before the first lifecycle orientation has completed and its desktop/mobile images have been opened—including `wc`, `stat`, `file`, `du`, `head`, `tail`, `sed`, `grep`, or `rg` against the source file | Copy the source file only; run the orientation packet through the lifecycle helper immediately, open its images, then read the source to EOF |
| allowing the orientation packet to navigate to a directory listing, wrong route, blank document, or unrelated page; treating the helper readiness URL alone as proof that the approved HTML was opened | Pass the exact HTML URL into the packet, assert the exact final URL and non-directory content, assert task-supplied identity when available, record the title for later source reconciliation, and invalidate/recapture any wrong-page image through the lifecycle helper |
| listing, searching, reading, or inspecting target `app/`, `public/`, `server/`, packages, config, package files, `node_modules`, build/dist, tests, runtime logs, target assets, or the skill's `assets/scripts/` and `assets/templates/` before the Phase 0 source checkpoint—or verifying `task-workflow/` setup before the first helper with `ls`, `find`, `test -d`, `test -e`, `test -f`, `stat`, `file`, `wc`, `du`, `head`, `tail`, `sed`, `grep`, or `rg`, including a trailing `ls` in the scaffold command or reading the copied helper first | Stay source-only: create/copy the task-owned scaffold in a write-only command, write and read only the orientation packet, invoke the lifecycle orientation, open its images, read HTML/CSS/JavaScript to EOF, run/open the complete source inventory, then update and pass the Phase 0 artifact |

After instruction/reference setup, and before the Phase 0 source checkpoint, the only allowed workspace work is direct creation/copying of `task-workflow/**`, reading the approved design metadata, writing the orientation packet, reading that packet for audit, running it through the lifecycle helper, opening its source evidence, and updating the Phase 0 artifact. Do not list or read the target root or probe the target environment to decide what to do; the task prompt already supplies the target boundary, and target research begins only at the literal unlock. The mandatory order is: source orientation at desktop/mobile → open orientation images → complete HTML/CSS/JavaScript read to EOF → complete source inventory and opened evidence → Phase 0 artifact checkpoint → target research. After scaffold/template/source copying, do not read the copied helper or any other task-workflow artifact; write and read only the orientation packet, then invoke the first lifecycle orientation. Before every later packet, read the packet and remove the prohibited constructs above; do not execute a knowingly invalid packet “once” to see what happens. The lifecycle helper does not legalize an invalid payload. If any prohibited action occurs, stop immediately, record the failure in the current task-workflow artifact, reset the fixture, and restart from Phase 0.

</hard_stop_rules>

## Managed verification lock after Phase 0

<managed_verification_lock>

Passing Phase 0 does not relax lifecycle ownership. From Phase 1 through completion, every target browser check, screenshot, layout measurement, scroll test, or runtime inspection must be a lifecycle-owned packet. Do not run `pnpm run dev`, `npm run dev`, `vite`, or `react-router dev` directly; do not background a server; do not use shell `sleep`, `curl`, `wget`, port probes, or manual process cleanup to start, wait for, inspect, or stop it. A successful build or typecheck is not browser verification.

The only legal target-browser flow is the lifecycle helper with the target server, readiness URL, runtime directory, and packet supplied explicitly:

```bash
cd <target-repository>
node task-workflow/scripts/playwright-lifecycle.mjs \
  --server "<target-start-command>" \
  --ready-url "<target-readiness-url>" \
  --runtime-dir "task-workflow/runtime/target" \
  --run "node task-workflow/target-playwright/<packet>.mjs"
```

If this flow fails, repair the task-owned packet or the bounded helper invocation and rerun it through the helper. Never substitute a manual smoke test. A direct target server, shell wait, readiness probe, or browser check is a hard process failure: stop, record it, reset the fixture, and restart from Phase 0.

</managed_verification_lock>

## Operating Contract

<operating_contract>

Treat this file as the canonical five-phase execution protocol. Read it before work, reread it at every phase boundary, and reread it after compaction, resume, retry, reconnect, or a new coding session. Load the reference mapped to the current phase before doing that phase's work.

### Phase 0 write lock — read before any command

Until `task-workflow/phase-0-source-contract.md` has been written, reopened, scored at least `48/50`, all critical rows pass, and `task-workflow/CURRENT_PHASE.txt` is set to `phase-1-ui-implementation`, this is a source-only run. You may write only `task-workflow/**`, including source runtime files, source payloads, manifests, screenshots, and logs. Do not write `app/**`, `public/**`, `server/**`, packages, configuration, package files, build/dist, tests, or any target asset. Do not run `curl` or any download command whose output is a target path. Keep downloaded source assets inside `task-workflow/`; move or copy them to a target path only after the Phase 0 gate. The brand-logo exception changes the Phase 1 asset choice only; it never permits a pre-gate `public/` write. Any pre-gate target write is a hard Phase 0 failure: remove or revert it, record the repair, and restart Phase 0 before implementation.

For every browser, server, readiness, runtime, or evidence command, the lifecycle helper is the only process owner. Before and during the task, never run a browser or Playwright preflight through `node -e`, `node --eval`, a heredoc, a standalone script, cache/executable inspection, or an availability probe; never probe a server runtime with `which`, `command -v`, `--version`, `--help`, or similar; never manually start a server, background a server with `&`, use `nohup`, use shell `sleep`, probe with `curl`/`wget`, or clean up with `pkill`, `lsof`, or broad process hunting. Use the helper's real packet to discover whether the existing browser and server work. A `curl` used only to download the approved brand asset after the Phase 0 gate is the sole exception; it is never a readiness or UI-proof mechanism. Any direct browser/preflight command or manual server/probe/cleanup command is a hard process failure: stop the packet, record the failure, and rerun the packet through `playwright-lifecycle.mjs` before scoring or promoting the phase.

There is no exploratory-browser exception. A selector check, animation diagnosis, screenshot investigation, console probe, layout measurement, or one-off reproduction is still browser evidence work. Do not create `/tmp` diagnostics, shell-generated browser files, inline browser programs, or temporary Playwright scripts outside `task-workflow/`; do not run a task-owned packet directly just because it is short. Add the diagnostic to the appropriate task-workflow packet, keep its outputs under task-workflow, and invoke that packet through the lifecycle command shape below. `chromium.launch()` is permitted only inside a packet that the helper is currently running. Running it any other way is a hard failure even when the packet is read-only or only prints computed styles.

The first lifecycle packet is also the only browser-availability check. Never inspect `/ms-playwright`, `~/Library/Caches/ms-playwright`, `node_modules/playwright-core`, `browsers.json`, executable paths, browser revisions, `.runtime.logs`, or process/port state to decide whether Playwright works. Never use `ls`, `find`, `cat`, `ps`, `lsof`, or a package/runtime probe for that purpose. Invoke the real helper packet; if it fails, inspect only the helper-owned runtime output and repair the packet or bounded invocation. Cache, executable, revision, and availability inspection is a hard process failure.

Before invoking the helper, read back the complete custom packet from line 1 through EOF. After every packet write or edit, the very next tool call must be that complete line-1-through-EOF read; do not run `grep`/`rg`, make another edit, invoke the helper, or use any other tool between the edit and the read. A targeted slice may confirm a local edit only after that mandatory complete read; it never replaces the audit. The write response, diff preview, grep/ripgrep result, or remembered contents is not evidence that the whole packet was audited. Record the complete-read and fixed-wait review in the packet or phase artifact. A packet is invalid and must not be run if it contains `page.waitForTimeout(`, `waitForTimeout(`, `setTimeout(`, `setInterval(`, shell `sleep`, arbitrary polling/timer code used to settle the UI, or a catch/fallback that suppresses a browser wait, navigation, screenshot, console, page-error, or assertion failure. Browser packets must fail loudly: never use `.catch(() => ...)`, broad `try/catch`, ignored promises, or optional fall-through to continue after required browser work fails. Replace timer settling with a visible-state, URL, DOM, response, or geometry condition such as `locator.waitFor`, `waitForSelector`, `waitForURL`, `waitForResponse`, or an assertion. This is a model-owned packet check, not a scoring script; any prohibited construct that reaches the helper is a hard packet failure and the phase cannot be scored or promoted until the packet is rewritten and rerun.

The Agent owns each gate. A phase gate is an evidence-backed self-review: inspect the work, calculate the score honestly, identify weak rows, repair them, refresh invalidated evidence, and rescore. A failed gate is a repair loop, not a report to the user. Process details may vary with the task when coverage, evidence quality, and the required outcome remain intact.

Browser scripts collect evidence; they do not score or promote phases. Do not create phase-check, scoring, closeout, receipt, forced-read, or promotion scripts. The only supplied runtime script is `playwright-lifecycle.mjs`, which owns browser/server lifecycle. Custom Playwright scripts are expected for discovery, interaction, capture, measurement, and comparison, and they run through that helper.

Promote only from the current artifacts, opened evidence, readbacks, and actual target files. A summary claim, green build, screenshot path, or prior `Pass` label is not proof by itself. If later work invalidates a gate, return to the earliest affected phase and repass forward.

</operating_contract>

## Phase Map

<phase_map>

| Phase | Marker | Owns | Gate | Outcome |
| --- | --- | --- | ---: | --- |
| 0 | `phase-0-source-contract` | fresh artifacts, managed source discovery, complete inventory, source/design handoff, reproduction contract | `48/50` | every source page/state/section/interaction is understood and evidenced |
| 1 | `phase-1-ui-implementation` | target research, owner mapping, and ordered target-native implementation in reviewed packets | `48/50` | every contracted route/state/section/interaction has a real target owner and authored target UI |
| 2 | `phase-2-paired-responsive-proof` | code integrity, checks/build, paired source-target Playwright proof | `48/50` | responsive, theme, scroll, sidebar, drawer, and paired evidence pass |
| 3 | `phase-3-fidelity-repair-signoff` | section comparison, mismatch repair, adversarial checks, real-input proof | `49/50`; desktop/mobile `48/50` each | one-to-one visual and behavioral signoff |
| 4 | `phase-4-final-audit-completion` | artifact integrity, current evidence, final diff, completion lock | exactly `50/50` | every gate remains valid and completion is unlocked |

</phase_map>

Keep work in the phase that owns it. Each phase has different work; do not use a later phase to avoid an earlier gate. Continue through Phase 4 whenever local repair is possible. An external blocker is a valid stop only when it is proven, recorded in the current artifact and `task-workflow/open-gaps.md`, and has no local recovery.

## Phase Gate Loop

Run this loop for every phase:

1. Set `task-workflow/CURRENT_PHASE.txt` to the phase marker before phase work begins.
2. Reread this file, the mapped reference, the current phase artifact, `progress.md`, and `open-gaps.md`.
3. Record a small work or evidence packet: scope, intended owners, evidence paths, exclusions, and its review action.
4. Perform only that packet, using the required real inputs and managed Playwright lifecycle.
5. Reopen changed files and generated artifacts; inspect focused diffs and complete the packet's image-by-image manifest walk before scoring it.
6. Reconcile browser findings, source declarations, target code, evidence identity, and gap ownership.
7. Update and read back the phase artifact, `progress.md`, and `open-gaps.md`.
8. Score every rubric row from concrete evidence and evaluate every critical item independently.
9. On failure, keep the marker on the phase, record the earliest repair, fix it, refresh invalidated evidence, and repeat from step 2.
10. On pass, record the promotion lock, reopen the artifact trail, verify arithmetic and evidence, set the next marker, and immediately load the next reference.

The artifact trail must agree: marker, phase artifacts, `progress.md`, `open-gaps.md`, evidence ledgers, and actual files must describe the same current phase and next action. `CURRENT_PHASE.txt` is a resume pointer, not proof. `progress.md` is a compact resume ledger, not a substitute for detailed evidence.

Keep browser work and visual review in bounded packets. A source or target packet should own one route/state family and a coherent viewport/theme set, with a reviewable number of outputs. Do not create one monolithic corpus packet that must be rerun after an unrelated selector or state failure. When a packet passes, preserve its manifest rows; repair and rerun only the failed or invalidated packet, using new revisioned paths when evidence changes.

## Fresh Task Workspace

The first target-repository write creates a clean `task-workflow/` from the supplied assets. Remove stale `task-workflow/` state, then create:

- `CURRENT_PHASE.txt`, `progress.md`, `open-gaps.md`, and `spec.json`;
- one artifact for each of the five phases;
- `source-playwright/`, `source/`, `target-playwright/`, `verification/`;
- `runtime/source/`, `runtime/target/`;
- `scripts/playwright-lifecycle.mjs` copied byte-for-byte from this skill.

Copy the supplied design JSON byte-for-byte to `task-workflow/spec.json`. Keep every generated screenshot, script, manifest, runtime log, note, ledger, and decision under `task-workflow/`. Preserve the supplied templates and their scorecards, critical gates, and promotion locks. Exact wording may be shortened only when the same evidence remains explicit and scorable.

During Phase 0, the opening operating-contract lock above is absolute: keep target implementation, configuration, package, asset, generated, build, and test files read-only and unread. Do not open, list, grep, find, inspect, or research target files, target build output, target runtime logs, target assets, or target dependencies before the source-only evidence sequence has completed. The required order is: (1) create the task-workflow scaffold; (2) run the first source orientation through the lifecycle helper at desktop and mobile; (3) open those orientation images; (4) read the approved HTML, inline CSS, and JavaScript to EOF; (5) run and open the complete source inventory/state/section evidence through the lifecycle helper; (6) record the source/design handoff and score the Phase 0 source contract with all critical rows passing; (7) reopen the artifact, verify the promotion lock, and set `CURRENT_PHASE.txt` to `phase-1-ui-implementation`; only then may target research begin. The Phase 0 handoff names required target roles and adaptations, but it does not invent exact target files before target research. If target files are inspected or written early, Phase 0 has failed; remove or revert only premature writes, record the failure, and repeat the source gate. Never use premature target research or implementation as evidence that Phase 0 passed.

## Evidence Contract

<evidence_contract>

### Source discovery

Follow this source-only order exactly: scaffold task-workflow; start the source through the lifecycle helper; capture exactly one desktop and one mobile orientation image and open both; then read the approved HTML, inline CSS, and JavaScript completely to EOF; then run the complete source inventory through the helper and perform the image-by-image manifest walk; then update and pass the Phase 0 source contract; only after that in...

© customware-ai · MIT · customware-ai/skills

Similar skills

All skills for Frontend and UI →

From the same set12

The whole set →
frontend-design frontend-design is a Claude Code skill that sets visual guidelines for Tailwind and shadcn/ui layouts, banning generic purple SaaS cards, cramped tables, and unneeded sidebars. CX Codex +1 1,600installs crm-builder The crm-builder skill turns a business description in DOMAIN.md into a working CRM prototype: contacts, companies, deals and a kanban pipeline. CX Codex +1 1,400installs cpq-builder cpq-builder turns DOMAIN.md specs into working Configure-Price-Quote prototypes for the Customware SPA, replacing fragile spreadsheets and email quote threads. CX Codex +1 1,200installs trades-builder trades-builder turns a DOMAIN.md spec into a field operations tool for Customware SPA. Generates scope-based estimates, crew schedules, and progress tracking tables. CX Codex +1 1,100installs customware-ai The customware-ai skill guides AI chat, text generation, tools, model selection, and typed JSON in Customware-generated React Router and Hono apps. CX Codex +1 739installs playwright-in-sandbox playwright-in-sandbox — a skill that verifies UI changes in a sandbox browser and writes durable Playwright E2E coverage. Useful when you want screenshot proof, not just DOM state. CX Codex +1 510installs playwright-interactive-sandbox The playwright-interactive-sandbox skill runs iterative web UI checks through a persistent Node.js Playwright workflow. Use it for functional checks, visual QA, and screenshot evidence. CX Codex +1 401installs customware-email customware-email adds Postmark inbound email handling and outbound sending to a React Router and Hono app. Use it to connect customer email flows in an existing Customware project. CX Codex +1 176installs

Project sponsors

Companies that keep this analytics open