source-html-to-app-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Source HTML To App UI

从源HTML到应用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.

本文件为严格执行指令，而非宽松指南或可选参考资料。

如果Agent阅读了本Skill，必须严格按照书面内容依次执行，一字不差。

不得重新解读步骤。不得调整步骤顺序。不得跳过步骤。不得用更简单的方法替代步骤。不得做出违背本文件的假设。不得将大致相似、直觉或以往习惯视为偏离指令的许可。

如果Agent存在疑问，必须在本文件定义的工作流内解决，不得自行创建工作流。如果Skill要求执行某一步骤、关卡、检查清单、评审或循环，该步骤为强制性要求。如果Skill表明后续阶段被阻塞，Agent必须将其视为阻塞状态。如果Agent无法通过所需工件证明某阶段已通过，必须将该阶段视为失败。

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.

每次压缩后继续工作前，重新阅读本

SKILL.md

。同时重新加载阶段参考资料。不得依赖对话记忆。

本Skill为门控执行协议，而非松散的建议集合。源HTML文件仅用于通过交互式Playwright浏览器脚本生成完整的视觉和行为参考语料库。最终应用必须基于该已接受的语料库及提供的设计系统JSON，在目标仓库（repo）中构建。如果Agent已阅读本Skill，必须严格遵循其要求的工作流、关卡、工件、顺序和阻塞规则，不得偏离。

假设本Skill可完全自主运行。无需人工逐行监控运行过程。因此，工件文件即为执行保障系统。某阶段的完成并非基于Agent的自我信心，只有当所需工件显示真实的合格分数且所有关键项均通过时，该阶段才算完成。

绝不能基于乐观预期、部分证据或大致视觉相似性，将工作从一个阶段推进到下一个阶段。

当本Skill提及

Playwright

时，指的是独立的交互式Node.js Playwright脚本，可直接打开源HTML应用或构建后的目标应用、驱动浏览器并保存截图工件。并非指仓库常规的Playwright端到端测试套件。

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.

以下工作流框架为必选内容：

使用独立交互式Playwright脚本启动提供的HTML应用。
通过真实交互发现所有路由、状态、桌面视图、移动端视图及重要页面区域。
将发现结果保存为带截图的源语料库，同时生成书面清单和源质量评分。
基于已接受的语料库和设计系统JSON，在目标仓库中编写代码构建目标UI。
在开始任何基于截图的目标验证前，对编写的代码运行独立的实现完整性关卡检查。
捕获目标截图，与源语料库对比评分，修复不匹配项，循环执行直至关卡通过。
签核前执行对抗性验证和功能验证。

如果工作跳过任一阶段边界，则运行流程偏离正轨。

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.

以下规则始终生效：

每个阶段必须以客观关卡结束。
每个关卡必须记录在该阶段专属的工件文件中。
每个关卡必须同时具备数值阈值和关键项通过要求。
如果关卡失败，停留在当前阶段并持续迭代。
如果后续工作发现前期阶段缺少证据，返回该前期阶段，补全证据并重新通过关卡。
每个阶段关卡为内部控制点，而非用户确认检查点。
如果阶段关卡通过，直接进入下一阶段，无需询问是否继续。
如果阶段关卡失败，重新处理该阶段，重新运行关卡，持续循环，无需请求用户许可。
关卡、重做、验证和重工作循环的目的是消除执行过程中对用户确认的依赖，让Agent可自主完成运行。
如果依赖项、启动细节或本地设置问题阻碍进度，采用最直接的合理解决方案解决问题并继续；例如，如果需要使用交互式Playwright方法但缺少依赖项，安装依赖项后继续。
不得因沙箱内可解决的环境问题降低Skill的严格性、跳过关卡或改变方向。
当沙箱可直接解决阻碍时，不得停止运行请求用户选择替代环境或手动设置路径。
不得在任一阶段结束后总结进度并询问是否继续。
不得假设用户会发现捷径。Agent必须主动阻止捷径。

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.

以下为硬性约束：

目标应用必须为真实的交互式应用，而非静态视觉副本。
目标应用必须在目标仓库中编写为真实的路由、布局、组件、状态、样式和交互逻辑。
目标应用必须与已接受的源语料库近乎一对一复刻。
开始实现路由或页面之前，必须先更新目标仓库的设计系统基础：首先更新
```
app/app.css
```
中的共享CSS变量，其次更新
```
tailwind.config.ts
```
中的主题映射，最后更新共享UI基础组件。
如果已接受的源语料库包含侧边栏框架，目标应用必须更新并使用仓库的共享侧边栏组件或等效的共享框架层，而非单独创建页面级侧边栏系统。
布局保真度和样式保真度为独立的硬性关卡。
路由覆盖范围和状态覆盖范围为独立的硬性关卡。
源应用中的可见控件必须成为具备匹配状态的真实目标控件。
目标应用必须作为真实产品UI占据视口。
如果已接受的源语料库显示固定侧边栏框架及侧边的滚动内容，垂直溢出必须属于内容面板，而非整页，除非源证据明确证明为整页滚动。
提供的源HTML文件仅作为发现输入。最终应用在运行时不得依赖该文件。
可复用组件样式应放在对应的共享基础组件或组件本地样式路径中，而非
```
app/app.css
```
中的伪全局组件类（如
```
.btn
```
或
```
.input
```
）。
优先使用Tailwind，但并非强制要求。为保证保真度可使用自定义CSS，但可复用设计系统相关内容必须通过
```
app/app.css
```
中定义的共享CSS变量实现。
主页面或视图必须实现为真实的路由或仓库原生路由模块，而非在单个大型组件内通过内存页面状态切换实现。
如果框架中存在可见导航项，但无对应的已接受源路由/状态，目标应用应禁用该导航项，而非创建虚假目标页面。
常规UI结构必须与源应用完全一致：导航、页眉、控件、筛选器、表格、面板、间距和区域顺序。
常规UI样式也必须与源应用完全一致：排版字重、表面色调、边框强度、圆角、阴影、密度和控件样式。
Agent必须逐部分、逐路由、逐状态、逐区域评审应用。
如果仍存在可见的常规偏差，则运行未通过。

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

仅加载与当前阶段相关的参考资料，但完整交付运行时需使用全部四份：

```
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.

改进或测试Skill本身时使用此模式。

使用临时目标应用副本。
保留所有源、目标和评分工件。
评估多次全新运行的可重复性。
如果重复出现相同故障，先改进可复用Skill再重新运行。

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.

交付模式下必须生成以下工件：

```
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
```

assets/templates/

中的模板为强制执行工件。直接复制其结构。如果所需表格被替换为 prose（散文式文本）或简化至无法审计行内容，则运行失败。

Multi-Phase Protocol

多阶段协议

Phase 0: Start-Up And Artifact Scaffolding

阶段0：启动与工件搭建

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.

确定运行模式：验证模式或交付模式。
阅读目标仓库的
```
AGENTS.md
```
。
确认任务包含：
- 独立源HTML应用文件的路径
- 设计系统JSON的路径
将设计系统JSON复制或标准化至
```
design/spec.json
```
。
从模板创建所需工件。

阅读：

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

检查目标仓库的真实路由、布局、主题和测试结构。
确定如何使用交互式Playwright启动源HTML应用。
暂不编辑目标应用UI文件。
不得将HTML读取替代发现运行。

Phase 0 Gate: Start-Up Gate

阶段0关卡：启动关卡

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.

此关卡记录在

design/source-quality-review.md

中。

本阶段评分为

10/10

。

通过规则：

上述所有项均完成，评分为
```
10/10
```
尚未编辑任何目标UI实现文件

如果本阶段评分低于

10/10

，停留在阶段0。

Phase 1: Source Discovery And Acceptance Loop

阶段1：源发现与接受循环

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.

编写发现脚本前，重新阅读
```
references/playwright-interactive.md
```
。
为源应用编写专用的交互式Playwright发现脚本。
使用这些脚本打开源HTML应用。
捕获默认桌面端和移动端视图。
通过真实UI交互发现所有路由和有意义的状态。
为每个发现的路由/状态捕获桌面端和移动端截图。
为框架、导航、页眉、密集工作流界面、对话框、侧边栏及后续需区域级评分的任何区域捕获聚焦区域截图。
填写
```
design/source-inventory.md
```
。
填写
```
design/source-quality-review.md
```
。
如果覆盖范围不完整，从干净的Node.js进程重新运行交互式脚本并捕获更多证据。
持续循环直至书面的源质量关卡通过。

HTML读取、DOM检查和脚本检查可明确行为，但无法替代交互式Playwright发现，仅凭这些无法完成本阶段要求。

Phase 1 Gate: Source Promotion Gate

阶段1关卡：源准入关卡

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.

此关卡由

design/source-quality-review.md

管理。

通过规则：

评分至少为
```
48/50
```
所有关键发现项均通过
每个发现的路由/状态均有桌面端证据
每个发现的路由/状态均有移动端证据，除非记录了真实的源限制
每个可见页面区域均有截图证据和书面契约
```
design/source-inventory.md
```
中的每个路由/状态行均引用了实际截图路径

如果此关卡失败，实现工作被阻塞。停留在阶段1。

Phase 2: Implementation Reading And Build Plan

阶段2：实现理解与构建计划

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.

阅读：

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

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

编码前编写
```
design/implementation-reading.md
```
。
将已接受的源语料库映射到目标文件、路由、区域和交互类型。
将设计系统基础工作映射到仓库的真实主题入口点，首先是
```
app/app.css
```
，其次是
```
tailwind.config.ts
```
，然后是共享的
```
app/components/ui/*
```
基础组件。
引用实现将基于的精确源截图。
列出最可能出现偏差的视觉和行为风险。
填写
```
design/implementation-reading.md
```
中的有序实现检查清单，并严格按执行顺序排列步骤。
如果语料库存在歧义，返回阶段1，重新运行源交互式Playwright脚本，捕获更多证据并重新通过源关卡。

Phase 2 Gate: Planning Gate

阶段2关卡：规划关卡

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.

此关卡由

design/implementation-reading.md

管理。

通过规则：

评分至少为
```
19/20
```
每个规划的路由/状态均引用了源证据
每个规划的构建区域均映射到具体的目标文件或扩展点
设计系统基础计划将令牌工作映射到
```
app/app.css
```
、主题映射到
```
tailwind.config.ts
```
、共享可复用控件工作映射到具体的
```
app/components/ui/*
```
文件或等效的仓库原生扩展点
有序实现检查清单已填写，并显示了从框架、路由、区域、状态到移动端的预期构建顺序
无未解决的源关键歧义

如果此关卡失败，实现工作被阻塞。停留在阶段2，若缺少证据则返回阶段1。

Phase 3: Theme And Shell Reproduction Loop

阶段3：主题与框架复刻循环

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.

将
```
design/spec.json
```
转换为目标仓库的真实主题入口点。
首先更新
```
app/app.css
```
，使共享CSS变量和全局设计令牌成为样式的唯一来源。
之后更新
```
tailwind.config.ts
```
，使Tailwind主题值使用这些共享CSS变量。
修改路由或页面文件前，检查仓库的组件演示或参考界面及现有
```
app/components/ui/*
```
基础组件。
源应用需要自定义样式时，更新共享组件包装器或基础组件。
不得在
```
app/app.css
```
中创建伪全局可复用组件类（如
```
.btn
```
、
```
.btn-primary
```
、
```
.input
```
或
```
.badge
```
）；可复用组件样式应放在对应的共享基础组件中。
重构框架，使目标应用作为实际产品UI占据视口。
在
```
design/implementation-review.md
```
中将阶段3的有序检查清单行标记为
```
Done
```
（完成）、
```
Failed
```
（失败）或
```
Blocked
```
（阻塞），并引用精确的文件证据。

捕获

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

。

更新
```
design/implementation-review.md
```
。
更新
```
design/implementation-open-gaps.md
```
。
解决框架、主题、共享组件或检查清单顺序偏差后再继续。
本阶段书面通过前，不得实现路由或页面UI。

Phase 3 Gate: Theme And Shell Gate

阶段3关卡：主题与框架关卡

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.

此关卡由

design/implementation-review.md

管理。

通过规则：

评分至少为
```
19/20
```
设计系统基础已在
```
app/app.css
```
和
```
tailwind.config.ts
```
中明确建立
开始实现路由/页面之前，
```
app/components/ui/*
```
或仓库等效基础层已适配共享可复用控件
未通过
```
app/app.css
```
中的伪全局组件类引入可复用组件样式
阶段3的所有有序检查清单行均标记为
```
Done
```
并附有证据，无标记为
```
Failed
```
的行
无未解决的关键框架归属问题

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

已存在

框架/主题的未解决缺口已明确记录或解决

如果此关卡失败，路由和页面实现工作被阻塞。停留在阶段3。

Phase 4: Route, State, And Section Reproduction Loop

阶段4：路由、状态与区域复刻循环

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.

将
```
design/source-inventory.md
```
中的每个已接受主页面或视图实现为真实的路由或仓库原生路由模块，而非通过内存页面状态切换实现。
默认使用适配后的共享基础组件构建路由和页面UI。
实现每个列出的页面区域，而非仅实现页面外层布局。
为选项卡、筛选器、对话框、侧边栏、菜单、行选择和移动端导航使用真实的本地状态和交互逻辑。
如果源框架显示的导航项背后无已接受的源页面或状态，将其渲染为禁用或不可用状态，而非创建虚假目标页面。
如果源框架包含侧边栏和滚动内容面板，保持侧边栏框架稳定，将垂直溢出范围限定在内容区域而非整页，除非源证据证明为整页滚动。
为保证保真度可使用自定义CSS，但可复用设计系统相关内容必须通过共享CSS变量和基础组件层实现，而非一次性全局组件类。
更新
```
app/routes.ts
```
或仓库等效的路由注册入口点，创建所需路由文件后再在路由模块内添加页面状态逻辑。
在
```
design/implementation-review.md
```
中将阶段4的有序检查清单行标记为
```
Done
```
、
```
Failed
```
或
```
Blocked
```
，并引用精确的路由文件证据。
每次有意义的迭代后，捕获匹配的目标截图。
更新
```
design/implementation-review.md
```
。
更新
```
design/implementation-open-gaps.md
```
。
如果源路由、状态或区域仍缺失、通用、虚假或检查清单顺序错误，持续迭代。

Phase 4 Gate: Route And State Gate

阶段4关卡：路由与状态关卡

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.

此关卡由

design/implementation-review.md

管理。

通过规则：

评分至少为
```
28/30
```
所有关键路由/状态项均通过
每个主路由均作为真实的目标路由UI存在
无主路由通过单个大型组件内的页面状态机实现
每个源交互类型均作为真实的目标交互存在
每个源列出的页面区域均有对应的目标区域和评审行
无已接受源目标的框架导航项已被禁用，而非路由到虚构页面
当源框架显示侧边栏加内容滚动时，垂直溢出范围限定在内容区域而非整页，除非源证据另有说明
可复用控件通过共享基础组件或组件本地样式实现，而非伪全局组件类
已接受移动端语料库的移动端路由/状态覆盖已完成
阶段4的所有有序检查清单行均标记为
```
Done
```
并附有证据，无标记为
```
Failed
```
的行

如果此关卡失败，停留在阶段4。

Phase 5: Implementation Integrity Gate Loop

阶段5：实现完整性关卡循环

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.

运行关卡前，重新阅读

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

。

评审编写的目标代码，确认设计系统基础已实际到位：
- ```
app/app.css
```
  为共享CSS变量的唯一来源
- ```
tailwind.config.ts
```
  将主题值映射到这些变量
- 共享
```
app/components/ui/*
```
  基础组件或仓库等效组件负责可复用控件样式
评审路由架构，确认主页面或视图已实现为真实的路由模块或仓库原生路由边界。
评审交互真实性，确认可见控件已实现为真实行为，而非静态标记或装饰性状态。
评审状态区分度，确认源中的不同状态在目标实现中仍保持区分。
评审框架归属，确认侧边栏使用、滚动归属和禁用导航行为与已接受的源框架一致。
运行
```
design/implementation-review.md
```
中的专用阶段5实现完整性检查清单，将每行标记为
```
Done
```
、
```
Failed
```
或
```
Blocked
```
并附上证据。
运行实现所需的非视觉仓库检查，包括代码检查、构建检查和针对更改行为的定向测试。
更新
```
design/implementation-review.md
```
。
更新
```
design/implementation-open-gaps.md
```
。
修复实现架构、基础组件归属、路由、状态、交互、框架或测试完整性故障。
重新运行实现关卡直至书面通过。

Phase 5 Gate: Implementation Integrity Gate

阶段5关卡：实现完整性关卡

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.

此关卡由

design/implementation-review.md

管理。

通过规则：

评分至少为
```
28/30
```
所有关键实现完整性项均通过
设计系统基础已在
```
app/app.css
```
和
```
tailwind.config.ts
```
中明确建立
页面级样式开始前，
```
app/components/ui/*
```
或仓库等效基础层已适配共享可复用控件
未通过伪全局组件类引入可复用组件样式
每个主页面或视图均作为真实的路由边界存在
无主要页面架构通过单个内存页面状态机实现
源交互类型已实现为真实的目标交互
源中的不同状态未合并为单一通用目标状态
如果源框架包含侧边栏，实际使用了仓库的共享侧边栏组件或等效共享框架层
无已接受源目标的框架导航项已被禁用，而非链接到虚构页面
当已接受框架显示固定侧边栏加滚动内容时，垂直溢出属于与源匹配的内容面板而非整页
所需实现工件已填充真实内容，而非模板占位符
更改实现所需的仓库检查已通过
阶段5的所有完整性检查清单行均标记为
```
Done
```
并附有证据，无标记为
```
Failed
```
的行

如果此关卡失败，视觉验证工作被阻塞。停留在阶段5。

Phase 6: Visual Verification Loop

阶段6：视觉验证循环

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.

阅读：

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

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

使用仓库常规命令启动目标应用。
为目标应用编写专用的交互式Playwright验证脚本。
捕获与已接受源清单匹配的目标截图。
全页截图不足以证明时，捕获聚焦区域证据。
逐路由、逐状态、逐区域对比源和目标。
更新
```
design/implementation-review.md
```
。
更新
```
design/implementation-open-gaps.md
```
。
修复不匹配项。
从干净的Node.js进程重新运行交互式Playwright验证脚本。
持续循环直至书面验证关卡通过。

Phase 6 Gate: Visual Fidelity Gate

阶段6关卡：视觉保真度关卡

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.

此关卡由

design/implementation-review.md

管理。

通过规则：

评分至少为
```
49/50
```
桌面端保真度评分至少为
```
48/50
```
移动端保真度评分至少为
```
48/50
```
所有关键验证项均通过
每个源路由/状态行均有目标证据
每个源列出的页面区域均有目标证据且区域评审行通过
```
design/implementation-open-gaps.md
```
中无未解决的常规偏差
最终桌面端和移动端截图已存在

如果此关卡失败，停留在阶段6。如果桌面端或移动端保真度低于

48/50

，修复表现较差的视口，重新运行交互式验证脚本，重新评分，持续循环直至两者均通过。

Phase 7: Adversarial And Functional Proof Loop

阶段7：对抗性与功能验证循环

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
```
.

假设实现仍存在错误。
找出至少五个严重的潜在不匹配项。
对照已接受的源语料库检查每个不匹配项。
修复真实的不匹配项。
记录有具体理由的非阻塞性差异。
使用真实用户输入测试每个可见交互类型。
为每个交互类型捕获至少一张验证截图。
更新
```
design/implementation-review.md
```
中的对抗性和功能验证部分。

Phase 7 Gate: Adversarial Proof Gate

阶段7关卡：对抗性验证关卡

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.

此关卡由

design/implementation-review.md

管理。

通过规则：

评分至少为
```
19/20
```
已检查至少五个严重的潜在不匹配项
每个检查的不匹配项已修复或明确说明理由
每个可见交互类型均有功能验证证据
对抗性验证已覆盖移动端

如果此关卡失败，停留在阶段7并持续迭代。

Phase 8: Final Signoff

阶段8：最终签核

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

阶段8关卡：签核关卡

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.

此关卡由

design/implementation-review.md

管理。

本阶段评分为

12/12

。

通过规则：

所有前期关卡均已通过且状态有效
所有所需工件均已存在
最终桌面端和移动端截图已存在
未解决缺口清单中无未解决的常规偏差
所需评审表格保持完整
代码更改所需的仓库检查已运行
应用具备交互性
应用运行时不依赖提供的源HTML文件
应用作为产品UI占据视口
无占位符或通用路由残留
无常规区域未评审
无关键项失败

如果本阶段评分低于

12/12

，签核被阻塞。

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

以下捷径将导致运行自动失败：

源关卡通过前进入实现阶段
规划关卡通过前跳过规划阶段
主题/框架关卡通过前跳过主题/框架阶段
路由/状态构建关卡通过前跳过路由/状态构建阶段
实现完整性关卡通过前进入视觉验证阶段
实现完整性、视觉和对抗性关卡通过前完成签核
任一阶段结束后停止运行并询问用户是否继续
将已通过的阶段关卡视为用户交接点，而非自动进入下一阶段
乱序填写实现检查清单并将后续步骤视为有效
跳过检查清单证据列或检查清单行仍为占位符状态时声称阶段已通过
仅读取HTML文件并推断应用，未执行交互式Playwright发现
使用仓库Playwright端到端测试替代交互式Playwright发现或验证脚本
运行时嵌入、获取或渲染提供的源HTML文件
使用
```
iframe
```
、
```
srcDoc
```
、
```
object
```
、
```
embed
```
、
```
webview
```
或注入原始HTML作为产品UI
在应用周围构建截图查看器、设计面板、图库框架、海报框架或设备框架
将路由存在视为路由保真度的证明
将测试套件通过或构建成功视为视觉保真度的证明
用散文式文本替代所需审计表格
未解决的常规偏差未记录在未解决缺口清单中
将可见交互式控件视为静态标记
跳过移动端发现、移动端实现或移动端评分
基于整体感觉而非逐行证据批准工作

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

```
references/phase-1-source-discovery.md
```
：阶段1发现与源接受。
```
references/phase-2-5-target-implementation.md
```
：阶段2规划及阶段3、阶段4、阶段5实现完整性。
```
references/phase-6-7-visual-verification.md
```
：阶段6视觉QA及阶段7对抗性与功能验证。
```
references/playwright-interactive.md
```
：本Skill如何使用交互式Playwright脚本进行发现和验证。

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.

严格使用阶段关卡。
保持工件可审计。
证据不足时返回前期阶段。
不得让提供的源HTML泄露到最终运行时环境。