| doc_id | doc_agentskill_0036 |
| name | html-to-ucuf |
| description | HTML -> UCUF (Cocos Creator UI) conversion skill. Use for turning a complete HTML source package with ui-design-tokens.json and colors_and_type.css into Cocos usable layout/skin/screen JSON, then validating with Plan5 final fidelity gates: stale-rule audit, rule guard, visual fidelity risk, runtime interaction smoke, Cocos Editor final gate, and 95% regression matrix. |
| argument-hint | Formal runs need --source-dir, --main-html, --screen-id, --bundle, --editor-screenshot, --capture-protocol, and --capture-report. --input, --skip-editor-compare, --no-runtime-sync, and --no-per-tab-replay are debug only. |
HTML-to-UCUF Skill
This skill converts HTML into UCUF JSON for Cocos Creator UI. The current execution spec is docs/html_skill_plan5.md.
Authority order:
- Plan 2 (
docs/html_skill_plan2.md): historical evidence only.
- Plan 3 (
docs/html_skill_plan3.md): historical transition source.
- Plan 4 (
docs/html_skill_plan4.md): prior execution evidence and Plan 4.1 regression closure.
- Plan 5 (
docs/html_skill_plan5.md): current execution spec for final fidelity, stale-rule cleanup, and 95% Cocos final gate closure.
Rule Source
tools_node/lib/html-to-ucuf/rule-registry.json is the single machine-readable rule source of truth.
tools_node/lib/html-to-ucuf/rule-checkers.js contains rule checker implementations.
docs/html_skill_plan4.md and docs/html_skill_plan5.md are version deltas and decision records, not the formal rule registry.
Unity 對照:這條流程相當於 UI Toolkit importer + Prefab/Scene sync + Play Mode interaction smoke + Game View final compare;不要把 debug 輸出當成正式通過。
⚠️ Spec Authority: docs/html_skill_plan5.md is the only active execution spec.
docs/html_skill_plan.md ~ docs/html_skill_plan4.md are HISTORICAL; do not follow them without consulting docs/html_skill_postmortem.md.
Formal Entry
Formal runs must start from a source package.
node tools_node/run-html-to-ucuf-workflow.js \
--source-dir <source-package-dir> \
--main-html <relative-html> \
--screen-id <screen-id> \
--bundle <bundle> \
--editor-screenshot <cocos-editor-screenshot.png> \
--capture-protocol <final-capture-protocol.json> \
--capture-report <capture-report.json>
Required source package files:
ui-design-tokens.json
colors_and_type.css
- main HTML
Formal flow also requires:
- final replay from source-derived output.
- per-tab replay fragments for tabbed sources.
- runtime sync into
assets/resources/ui-spec.
- Plan5 stale-rule and final-fidelity requirements.
- Plan 4.1 rule guard pass.
- runtime interaction smoke when interaction sidecars exist.
- visual fidelity risk pass for semantic, background, and composite fidelity.
- Cocos Editor final gate pass, using a formal capture report whose
actualScreenId matches the converted screenId and whose adjusted score is at least 0.95.
- If Cocos final gate fails, workflow summary must include blocker taxonomy and non-empty
nextFixes.
Debug Only
These switches always mean debugOnly=true and cannot produce a formal pass verdict:
--input
--skip-editor-compare
--no-runtime-sync
--no-per-tab-replay
--editor-screenshot without the formal source package
--capture-protocol without the formal source package
- missing
--capture-report or a capture report from a legacy product preview target
Required Flow
- Resolve the source package and inject source CSS/tokens.
- Render or annotate HTML only if needed for conversion.
- Generate raw layout/skin from the current HTML source package.
- Optimize layout and auto-fix skin without falling back to old skins.
- Run final replay from the source-derived output.
- Replay each tab and write fragment JSON for tabbed sources.
- Sync final layout/skin/screen into
assets/resources/ui-spec.
- Run Plan 4.1 rule guard.
- Run Plan5 stale-rule checks when touching workflow/converter/runtime/final-gate logic.
- Run visual fidelity risk checks for semantic, background, and composite fidelity.
- Run runtime interaction smoke when interaction sidecars exist.
- Capture Cocos through the formal route:
node tools_node/capture-ui-screens.js --formal-screen-id <screen-id> --uiVersion <workflow-uiVersion> --maxWidth 0.
- Run HTML source vs Cocos Editor screenshot final gate with
--capture-report and 0.95 threshold.
- If the final gate score is below
0.95, classify the failure as CSS extraction, runtime renderer, capture authority, spec authority, or assetization-required, and emit non-empty nextFixes.
- Write workflow summary with
debugOnly, ruleGuard, visualFidelityRisk, interactionRuntime, runtimeAuthority, finalCapture, finalFidelity, blockerTaxonomy, and nextFixes.
Governance Summary
- Formal runs still require source package entry, runtime sync, strict rule guard, interaction smoke when needed, and Cocos Editor final gate.
- Core converter/runtime/validator logic must stay screen-agnostic; fixture-specific behavior belongs in tests, not in production flow.
- When Cocos final gate is below
0.95, the workflow must fail and emit actionable nextFixes; high browser coverage plus low Cocos score must also emit blocker taxonomy.
- Unsupported CSS, degraded visual fallback, capture authority drift, and runtime authority drift must surface as blockers or tracked advisories from the rule registry, not as silent pass paths.
- Read the exact rule metadata from
tools_node/lib/html-to-ucuf/rule-registry.json; do not duplicate the full rule body in this skill document.
Validation Commands
node --check tools_node/run-html-to-ucuf-workflow.js
node --check tools_node/render-html-tab-fragments.js
node --check tools_node/validate-html-to-ucuf-rule-guard.js
node tools_node/test/dom-to-ui-self-test.js --group html-to-ucuf-active-contract
node tools_node/test/dom-to-ui-self-test.js --group html-to-ucuf-fidelity-contract
node tools_node/validate-ui-specs.js --strict --rules tab-fragment-geometry-contract,composite-panel-tab-route-integrity,formal-skin-path,synced-runtime-path-freshness,background-layer-preservation,formal-visual-risk-path,runtime-interaction-smoke-path
node tools_node/validate-html-to-ucuf-rule-guard.js --strict --capture-report <capture-report.json> --expected-screen-id <screen-id>
node tools_node/validate-html-to-ucuf-rule-guard.js --strict --report artifacts/html-to-ucuf-rule-guard.json
node tools_node/compare-html-to-cocos-editor.js --help
node tools_node/check-context-budget.js --changed --emit-keep-note
Notes For Agents
- Do not resurrect Phase B tools as the main path.
generate-tab-childpanels.js, runtime-screen-diff.js, and cutover-screen-variant.js are not the formal Plan5 flow.
- DS3 may be used as a fixture, but core converter/workflow/validator code must stay screen-agnostic.
- If the score is low, keep testing the converted JSON from the current HTML source package. Do not switch to default skins or old runtime files to make the gate easier.
- If browser coverage is high but Cocos final gate is low, treat the run as a Plan5 diagnostic failure until
blockerTaxonomy and nextFixes identify the next tool/runtime fix.
- If final gate reports a low score, inspect
captureAuthority first. A legacy GachaMain/product route mismatch is a blocker, not a converter fidelity result.
- Keep
history-not-story, radial-slide-background, and interaction-carousel style regressions as fixtures.
- When adding logic to
draft-builder.js, first attach it to the registry-backed draftBuilderStageRules mapping and add a self-test tag.
- Add short Traditional Chinese comments at classifier, background fallback, runtime binding, and formal gate boundaries to explain why old fallback paths stay blocked.