jiapuapp/docs/superpowers/plans/2026-07-16-a01-scroll-skins-v3.md

A01 Scroll Skins V3 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. The user forbids subagents, worktrees, commits, and all Git mutation commands, so execution stays inline in the current worktree and every commit step is intentionally omitted.

Goal: Replace A01's current button, Toast, and verification-panel visuals with the user-approved option-2 scroll-and-cloud family while preserving live text, exact slot ratios, interaction behavior, and old assets.

Architecture: Keep the approved board as the immutable visual target. Generate one clean master per surface, then use the existing Node/Pillow pipeline to remove presentation backgrounds, preserve fixed decorative caps/corners, stretch only safe centers, and emit exact versioned outputs. A01 consumes the new outputs only after manifest and pixel tests pass; H5 comparison uses the approved board plus real runtime screenshots.

Tech Stack: uni-app/Vue, SCSS, Node.js 24, native node:test, Python 3.14, Pillow 12.3.0, PowerShell contracts, Chrome CDP 9222, built-in ImageGen.

Global Constraints

• Scope is A01 only; do not edit other page implementations.
• Preserve STKaiti, KaiTi, live button copy, WeChat icon, verification copy, interactions, and current logical slots.
• Keep all old assets; write only versioned v3 outputs.
• Do not use scaleToFill to hide a ratio mismatch.
• Master and output assets contain no text, icons, logo, white halo, green fringe, or presentation shadow.
• A01 remains [~]; H5 output is internal evidence only until Android/HBuilderX and user review.
• Do not run worktree, subagent, git add, commit, push, reset, checkout, upload, delete, or cleanup commands.

---

Task 1: Preserve Exact Individual Masters

Files:

• Reference: docs/design/assets/a01-vnext/A01-shared-scroll-skins-with-dialog-approved.png
• Create: docs/design/assets/a01-vnext/masters/a01-scroll-primary-master-v3.png
• Create: docs/design/assets/a01-vnext/masters/a01-scroll-secondary-master-v3.png
• Create: docs/design/assets/a01-vnext/masters/a01-scroll-toast-master-v3.png
• Create: docs/design/assets/a01-vnext/masters/a01-scroll-dialog-master-v3.png

Interfaces:

• Consumes: the approved four-component board and the measured slots from the design spec.

• Produces: four committed-quality visual masters with flat chroma presentation backgrounds, no text, and quiet safe centers.

• Step 1: Generate the four masters independently

Use ImageGen once per master. Attach the approved board every time. Require the exact family, one isolated component, a flat #00ff00 background for deterministic extraction, no external shadow, and these target ratios: 622:92, 622:100, 590:82, 620:520.

• Step 2: Inspect every master

Open all four with view_image. Reject any master with text, asymmetric clouds, cropped scroll rods, missing gold lines, landscape above the dialog's lower 22%, or decoration crossing the live-content safe center.

• Step 3: Save only the approved individual masters

Copy each generated result to the exact master path without overwriting an existing file. Keep ImageGen originals untouched.

Task 2: Declare the V3 Machine Contract

Files:

• Create: design-pipeline/manifests/a01-scroll-skins-v3.json
• Modify: design-pipeline/tests/manifest-v2.test.mjs
• Modify: design-pipeline/package.json

Interfaces:

• Consumes: four master paths from Task 1.

• Produces: manifest assets a01-scroll-primary-v3, a01-scroll-secondary-v3, a01-scroll-toast-v3, and a01-scroll-dialog-v3.

• Step 1: Write failing manifest tests

Add assertions that the manifest declares exactly four unique outputs, exact logical/output dimensions, uniform-only for fixed button/dialog outputs, nine-slice for Toast, and A01 consumer selectors.

• Step 2: Run RED

Run npm.cmd --prefix design-pipeline run test:v2. Expected: failure because a01-scroll-skins-v3.json does not exist.

• Step 3: Add the manifest and scripts

Declare outputs:

static/assets/foundation/transparent/a01-scroll-primary-v3.png   1866×276
static/assets/foundation/transparent/a01-scroll-secondary-v3.png 1866×300
static/assets/foundation/transparent/a01-scroll-toast-v3.png      1770×246
static/assets/modules/auth/transparent/a01-scroll-dialog-v3.png   1860×1560

Add build:a01-scroll-skins and verify:a01-scroll-skins package scripts. All paths must remain inside the workspace.

• Step 4: Run GREEN

Run the Node tests and manifest validator. Expected: all tests pass and MANIFEST-V2 PASS names the v3 manifest.

Task 3: Build Exact Clean Outputs

Files:

• Create: design-pipeline/tests/test_build_scroll_skins.py
• Create: design-pipeline/scripts/build_scroll_skins.py
• Create: design-pipeline/scripts/build-a01-scroll-skins.mjs
• Modify: design-pipeline/scripts/asset_quality.py

Interfaces:

• Produces: remove_chroma_background(image, key, tolerance), stretch_safe_center(image, output_size, insets), and build_manifest(manifest, workspace).

• Step 1: Write failing synthetic tests

Tests must prove that chroma pixels become transparent black, decorative caps/corners remain pixel-identical after resizing, only the declared center stretches, exact output dimensions are returned, and a dialog with alpha.required=false remains opaque.

• Step 2: Run RED

Run the Python unittest discovery command. Expected: import failure for build_scroll_skins.

• Step 3: Implement minimal Pillow processing

Use RGBA conversion, chroma-distance Alpha removal, bounding-box trim, manifest insets, Pillow LANCZOS only for target-height normalization, center-only stretching, transparent-black cleanup, sRGB chunk writing, and optimized PNG output.

• Step 4: Run GREEN and build actual assets

Run Python tests, npm.cmd --prefix design-pipeline run build:a01-scroll-skins, and the quality verifier. Expected for every asset: exact dimensions, zero visible chroma residue, zero light fringe, zero transparent RGB, and no manifest errors.

• Step 5: Inspect all four outputs

Use view_image; reject seams, cropped rods, distorted clouds, weak gold contrast, center-knot drift, or dialog landscape entering the content region.

Task 4: Integrate A01 Test-First

Files:

• Modify: tests/a01-a02-ui-contract.ps1
• Modify: tests/a01-asset-alpha-audit.ps1
• Modify: tests/a01-responsive-runtime-smoke.js
• Modify: pages/auth/a01-entry.vue

Interfaces:

• Consumes: four verified v3 outputs.

• Produces: A01 using v3 visuals without changing behavior or live content.

• Step 1: Extend contracts before page changes

Require the four v3 paths, exact sizes, no old A01 button/Toast/dialog references in A01, no scaleToFill on these skins, and the approved runtime selectors.

• Step 2: Run RED

Run both PowerShell contracts. Expected: failure because A01 still uses v2 buttons and the old dialog/code-native Toast.

• Step 3: Make the minimal A01 change

Replace only the decorative skin layers. Preserve copy, icon, state, click handlers, normal-flow layout, overlay positioning, and slot dimensions. Use aspectFit for exact button/dialog assets; use the Toast v3 asset through its declared adaptive rendering strategy.

• Step 4: Run GREEN

Run the PowerShell contracts and Python quality audit. Expected: pass.

Task 5: Real Runtime and Visual Comparison

Files:

• Modify: scripts/capture-chrome-page.js
• Create ignored evidence under: tmp/a01-scroll-skins-v3-*.png
• Modify: design-qa.md

Interfaces:

• Produces: password, Toast, and verification-dialog runtime evidence at 412×915, plus four-viewport structural verification.

• Step 1: Add deterministic capture states

The capture tool must support password-tab, invalid-login, and verification-dialog without arbitrary click timing. Runtime smoke must assert all four v3 assets load at expected natural dimensions.

• Step 2: Run four viewports

Run node tests/a01-responsive-runtime-smoke.js. Expected: pass at 320×568, 360×640, 360×800, and 412×915, with natural scrolling at 320×568 and no horizontal overflow.

• Step 3: Capture and compare

Capture the three meaningful A01 states. Compare the approved visual board and runtime evidence together. Fix P0/P1/P2 mismatches; do not loop on P3 polish.

• Step 4: Update QA truthfully

Record the exact source and runtime images in design-qa.md. The result may say H5 passed only; Android and user acceptance remain pending.

Task 6: Documentation and Final Verification

Files:

• Modify: docs/design/设计资产生产流水线规范.md

• Modify: docs/design/P00_页面结构与资产清单.md

• Modify: docs/交接记录.md

• Step 1: Record implemented facts

Document the selected visual source, four v3 outputs, build/verify commands, A01-only scope, preserved old assets, and remaining Android/user gates.

• Step 2: Run the focused verification set

npm.cmd --prefix design-pipeline run test:v2
npm.cmd --prefix design-pipeline run build:a01-scroll-skins
npm.cmd --prefix design-pipeline run verify:a01-scroll-skins
design-pipeline/.venv/Scripts/python.exe -m unittest discover -s design-pipeline/tests -p "test_*.py" -v
powershell -NoProfile -ExecutionPolicy Bypass -File tests/a01-a02-ui-contract.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File tests/a01-asset-alpha-audit.ps1
node tests/a01-responsive-runtime-smoke.js
git diff --check

Expected: all focused checks pass; git diff --check has no whitespace error. CRLF notices alone are not failures.

• Step 3: Report remaining gates

State explicitly: H5 internal evidence completed or blocked, Android/HBuilderX pending, user page acceptance pending, A01 remains [~], no Git mutation commands executed.