Skip to content

USAGE.en.md

Latest commit

 

History

History
173 lines (112 loc) · 4.27 KB

USAGE.en.md

File metadata and controls

173 lines (112 loc) · 4.27 KB
Raw

html-ui-prototype-migrator Usage Guide

1. What This Skill Does

This skill turns software UI work into a controlled browser-first workflow:

  1. Build a temporary HTML prototype in a browser-friendly workspace
  2. Inspect and iterate on the UI in a real browser
  3. Store screenshots and temporary files in a dedicated task directory
  4. Ask the user for explicit approval before cleanup
  5. Migrate the approved UI into the real software project

It is not a universal GUI designer and it should not be used for every desktop application.
It is only suitable for software whose final UI can be carried by HTML/CSS/JS.

2. Good Fit

Suitable for:

  • Electron, Tauri, and WebView-based software
  • Admin panels, dashboards, settings pages, and internal tools
  • UI work that benefits from a disposable prototype before real integration
  • UI debugging that needs Playwright screenshots and real browser checks

Not suitable for:

  • Native-only GUI targets that cannot host HTML/CSS/JS
  • Workflows that want automatic cleanup without user approval
  • Tasks that should directly edit the final project with no prototype phase

3. Requirements

You need:

  • Codex with support for custom skills
  • Node.js / npm
  • npx
  • A working Playwright CLI invocation

Check with:

node --version
npm --version
command -v npx

4. Artifact Layout

Each task gets its own directory:

/Users/cwn/Desktop/调试图/<task-subdir>/
  prototype/
  screenshots/

Meaning:

  • prototype/ stores temporary HTML/CSS/JS prototype files
  • screenshots/ stores visual inspection artifacts
  • every task has its own isolated directory
  • cleanup removes only the current task directory

5. Typical Workflow

Step 1: Confirm the Target

First confirm that the target software can host an HTML/CSS/JS UI.
If it cannot, the skill should refuse direct migration and treat the prototype as reference only.

Step 2: Create the Task Directory

The skill uses:

scripts/task_dir.sh "<task-name>"

to create a dedicated task directory and its default subdirectories.

Step 3: Run the Browser Loop

The skill uses:

scripts/playwright_cli.sh

to:

  • open the page
  • snapshot the DOM
  • capture screenshots
  • click, fill, refresh, and inspect again

Step 4: Ask for Human Confirmation

When the prototype reaches a reviewable state, the skill must explicitly ask:

  • whether the prototype is approved
  • whether screenshots and temporary prototype files should be deleted
  • whether the approved UI should be migrated into the target project

Important:

  • the model must not infer approval
  • explicit user confirmation is the only valid signal

Step 5: Cleanup

Only after explicit approval, the skill may call:

scripts/cleanup_task.sh "<task-dir>"

to remove the task artifacts.

Step 6: Migrate into the Target Project

Only after prototype approval should the skill migrate the confirmed UI into the real project.
During migration it should respect the target stack, file layout, and coding conventions.

6. Trigger Examples

You can invoke it with prompts like:

Use $html-ui-prototype-migrator to build a browser prototype for this settings page, debug it visually, and migrate it only after I approve it.

Use $html-ui-prototype-migrator to redesign this Tauri preferences UI in a browser first, then move it into the app after approval.

7. Script Reference

scripts/playwright_cli.sh

Purpose:

  • calls @playwright/cli through npx
  • provides a stable browser automation entry point

scripts/task_dir.sh

Purpose:

  • creates the task directory
  • creates prototype/ and screenshots/

scripts/cleanup_task.sh

Purpose:

  • allows deletion only under /Users/cwn/Desktop/调试图
  • refuses deletion of the artifact root or any path outside it

8. Safety Boundaries

Important constraints:

  • do not auto-delete screenshots
  • do not auto-delete temporary prototypes
  • do not infer user approval
  • do not migrate directly into non-HTML targets
  • do not delete /Users/cwn/Desktop/调试图 itself

9. License And Dependencies

This repository uses the MIT License by default.
However, the skill depends on third-party tooling such as @playwright/cli. Those dependencies keep their own licenses and are not re-licensed by this repository.