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:

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

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