跳到主要内容

Chapter 03 Interactive Archive Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Replace the current static Chapter 03 grid with a high-fidelity interactive editorial archive matching the approved desktop and mobile v3 mockups.

Architecture: Keep the homepage shell unchanged and extract Chapter 03 into a focused React component with its own CSS module. A small framework-free model module owns the canonical four material colors and pure interaction helpers so PDP, FILTER, and COLOR SWATCH share one source of truth and can be tested with Node's built-in test runner.

Tech Stack: React 19, TypeScript/JSX, CSS Modules, inline SVG, Node test runner, Docusaurus 3.

Global Constraints​

  • Modify only Chapter 03 behavior and styles; Chapters 01, 02, 04, 05, and 06 remain structurally unchanged.
  • The only material colors are SAND, FOREST, INK, and CLAY, rendered by one shared component with material texture.
  • PDP supports color selection, product-view selection, quantity changes, and a non-transactional add-to-cart easter egg.
  • FILTER groups are expandable and interactive; price handles remain ordered with a minimum gap.
  • METAOBJECT destinations are interactive and use restrained motion with prefers-reduced-motion support.
  • Do not add third-party UI or animation dependencies.
  • If Shopify Theme Check is used, check only modified files; this Docusaurus implementation does not require Theme Check.

Task 1: Canonical material and interaction model​

Files:

  • Create: src/components/PortfolioHomepage/chapterThreeModel.mjs
  • Create: tests/chapter-three-model.test.mjs

Interfaces:

  • Produces: MATERIAL_COLORS, clampQuantity(value, delta), toggleToken(tokens, token), normalizePriceRange(range, handle, value), calculateFilterCount(state).

  • Consumes: no UI or browser APIs.

  • Step 1: Write failing tests for the exact four material IDs, quantity bounds of 1–9, immutable selection toggles, ordered price handles with an 80-yuan gap, and deterministic result counts.

  • Step 2: Run node --test tests/chapter-three-model.test.mjs and confirm failure because chapterThreeModel.mjs does not exist.

  • Step 3: Implement the pure model with frozen color records containing id, label, base, highlight, and shadow.

  • Step 4: Re-run the model test and confirm all assertions pass.

Task 2: Interactive archive component contract​

Files:

  • Create: src/components/PortfolioHomepage/ChapterThree.tsx
  • Create: tests/chapter-three-structure.test.mjs
  • Modify: src/components/PortfolioHomepage/index.tsx

Interfaces:

  • Consumes: the Task 1 model exports.

  • Produces: default ChapterThree component with PdpDossier, FilterDossier, ColorDossier, MetaobjectDossier, MaterialSwatch, and DaypackArtwork internal units.

  • Step 1: Write failing source-contract tests requiring the four units, shared MATERIAL_COLORS.map, accessible quantity/cart controls, expandable filter groups, two range inputs, and interactive metaobject destinations.

  • Step 2: Run node --test tests/chapter-three-structure.test.mjs and confirm failure because ChapterThree.tsx does not exist.

  • Step 3: Implement the minimal interactive component and replace only the old Chapter 03 section in PortfolioHomepage/index.tsx with <ChapterThree />.

  • Step 4: Re-run both Chapter 03 tests and keep them green before styling.

Task 3: Editorial desktop and mobile styling​

Files:

  • Create: src/components/PortfolioHomepage/chapterThree.module.css
  • Modify: src/components/PortfolioHomepage/ChapterThree.tsx

Interfaces:

  • Consumes: semantic class names from Task 2.

  • Produces: desktop 12-column archive and mobile single-column archive without horizontal overflow.

  • Step 1: Add a failing style-contract assertion for a four-material texture class, desktop named grid areas, the 700px single-column breakpoint, 44px mobile controls, and reduced-motion rules.

  • Step 2: Run the structure test and confirm those declarations are missing.

  • Step 3: Implement desktop layout with a chapter rail, editorial heading, PDP/Filter/Color/Metaobject dossiers, folio numbers, thin rules, and terracotta annotations.

  • Step 4: Implement mobile layout with a CHAPTER 03 / 03 / 06 metadata band and stacked Field Notes matching the approved mobile mockup.

  • Step 5: Implement material texture, product transition, cart receipt animation, range track, and metaobject connector animation, disabling non-essential motion under prefers-reduced-motion.

  • Step 6: Re-run Chapter 03 tests and confirm all style contracts pass.

Task 4: Project and browser verification​

Files:

  • Modify if browser evidence requires it: ChapterThree.tsx and chapterThree.module.css only.

Interfaces:

  • Consumes: the running http://localhost:3000/ page.

  • Produces: verified desktop/mobile UI and interaction behavior.

  • Step 1: Run pnpm test:homepage and node --test tests/chapter-three-model.test.mjs tests/chapter-three-structure.test.mjs; expect zero failures.

  • Step 2: Run pnpm typecheck; expect exit code 0.

  • Step 3: Run pnpm build; expect exit code 0.

  • Step 4: Use Browser at desktop width to verify color changes update the backpack, quantity clamps, cart receipt appears, filters expand/select/update count, and metaobject destinations animate/select.

  • Step 5: Use Browser at 390×844 to verify the single-column layout, 44px controls, readable trust copy, four consistent material swatches, and no horizontal overflow.

  • Step 6: Inspect console errors and fresh screenshots, then make only focused Chapter 03 corrections and repeat the relevant checks.