2026-04-04-yomiya-page-template-design-plan

Yomiya Page Template Design Doc 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: Publish the approved Yomiya page-template Design.md as a canonical repo document, wire it into the active Yomiya docs, persist the approved design context, and verify the docs site renders it correctly.

Architecture: Keep product/YomiyaContentSystem/01-07 as the active operational doc set, and add one long-form canonical design document under docs/yomiya/ so site/scripts/sync-content.mjs:19-26,77-83 picks it up automatically without changing the sync pipeline. Then add light cross-links from product/YomiyaContentSystem/README.md and product/YomiyaContentSystem/07-视觉与页面表达.md, and mirror the approved design context into a new root CLAUDE.md so future Claude sessions inherit the same design guardrails.

Tech Stack: Markdown docs, Node.js sync script, Astro + Starlight docs site, Claude Code local file workflow

File structure

Create

docs/yomiya/yomiya-page-template-design.md — canonical long-form page-template Design.md derived from the approved spec
CLAUDE.md — project-level Claude instructions containing the approved ## Design Context

Modify

product/YomiyaContentSystem/README.md:8-23 — add a pointer from the active 01-07 reading flow to the canonical design doc
product/YomiyaContentSystem/README.md:41-57 — clarify that the canonical Design.md exists outside the 01-07 active set
product/YomiyaContentSystem/07-视觉与页面表达.md:4-8 — add a boundary note pointing to the canonical Design.md
product/YomiyaContentSystem/07-视觉与页面表达.md:27-39 — add one line in the division-of-responsibilities section referencing the canonical Design.md

Validate, do not modify unless broken

site/scripts/sync-content.mjs:19-26,77-83 — confirms docs/ and product/ are already synced into the site
site/package.json:5-12 — commands for sync, dev, and build
docs/superpowers/specs/2026-04-04-yomiya-page-template-design.md — approved source spec to copy from verbatim
.impeccable.md — approved Design Context source to mirror into CLAUDE.md

Task 1: Publish the canonical page-template Design.md

Files:

Create: docs/yomiya/yomiya-page-template-design.md
Source: docs/superpowers/specs/2026-04-04-yomiya-page-template-design.md
Validate: site/scripts/sync-content.mjs:19-26,77-83
Step 1: Verify the canonical doc does not exist yet

Run:

test -f "/Users/cc/Documents/root-remote/docs/yomiya/yomiya-page-template-design.md"

Expected: FAIL with exit code 1 because the canonical doc has not been created yet.

Step 2: Create the canonical doc by copying the approved spec verbatim

Run:

mkdir -p "/Users/cc/Documents/root-remote/docs/yomiya" && cp \
  "/Users/cc/Documents/root-remote/docs/superpowers/specs/2026-04-04-yomiya-page-template-design.md" \
  "/Users/cc/Documents/root-remote/docs/yomiya/yomiya-page-template-design.md"

The resulting file must begin with this exact header and keep all 9 sections from the approved spec:

# Yomiya 页面模板 Design.md

**项目**：Yomiya Content System
**文档性质**：完整页面模板设计文档（Design.md）
**用途**：把当前 active 文档中的页面职责、视觉规则和分发逻辑组织成一份可复用的页面模板说明书，供产品 / iOS / 前端 / 设计协作使用

Step 3: Verify the copied doc contains the required section headings

Run:

grep -n "^## " "/Users/cc/Documents/root-remote/docs/yomiya/yomiya-page-template-design.md"

Expected output contains these headings in order:

## 1. 文档目标、边界、与 active 文档的分工
## 2. 文档结构
## 3. 总体设计目标
## 4. 全局页面表达原则
## 5. 共用模板构件
## 6. 五类页面模板
## 7. 页面间跳转与承接关系
## 8. 设计侧行为规则总表
## 9. 附录
Step 4: Run sync to verify the docs pipeline picks up docs/ automatically

Run:

npm --prefix "/Users/cc/Documents/root-remote/site" run sync

Expected output includes:

[sync-content] Synced markdown from 5 directories
[sync-content] Found
[sync-content] Done

Step 5: Verify the synced site copy exists

Run:

test -f "/Users/cc/Documents/root-remote/site/src/content/docs/docs/yomiya/yomiya-page-template-design.md"

Expected: PASS.

Step 6: Commit

git add docs/yomiya/yomiya-page-template-design.md
git commit -m "$(cat <<'EOF'
docs: publish yomiya page template design doc
EOF
)"

Task 2: Wire the canonical doc into the active Yomiya docs

Files:

Modify: product/YomiyaContentSystem/README.md:20-22
Modify: product/YomiyaContentSystem/README.md:41-57
Modify: product/YomiyaContentSystem/07-视觉与页面表达.md:4-8
Modify: product/YomiyaContentSystem/07-视觉与页面表达.md:27-39
Test: grep checks against both markdown files
Step 1: Verify the active docs do not point to the canonical Design.md yet

Run:

grep -n "yomiya-page-template-design" \
  "/Users/cc/Documents/root-remote/product/YomiyaContentSystem/README.md" \
  "/Users/cc/Documents/root-remote/product/YomiyaContentSystem/07-视觉与页面表达.md"

Expected: FAIL with exit code 1 because neither file references the new canonical doc yet.

Step 2: Add one reading-order note to product/YomiyaContentSystem/README.md

Insert this block right after the existing paragraph that says “如果只是做产品 / 研发协作，通常前 4 份已经够用。”

如果需要完整的页面模板设计说明，再看 `../../docs/yomiya/yomiya-page-template-design.md`。
它不是根目录 active 文档的一部分，而是对 `01 / 06 / 07` 的设计总说明。

Step 3: Add one division-of-responsibilities note to product/YomiyaContentSystem/README.md

Append this bullet right after the existing 07-视觉与页面表达.md bullet in the “这 7 份主文档分别只回答一类问题” section:

- `../../docs/yomiya/yomiya-page-template-design.md`
  把 `01 / 06 / 07` 组织成完整页面模板 `Design.md`，用于设计总览与跨端协作

Step 4: Add one boundary note and one responsibility note to 07-视觉与页面表达.md

In the boundary block near the top, add:

- 如果需要完整页面模板说明，看 `../../docs/yomiya/yomiya-page-template-design.md`

In the “与其他 active 文档的分工” section, add:

- `../../docs/yomiya/yomiya-page-template-design.md`
  回答如何把 `01 / 06 / 07` 组织成完整页面模板 `Design.md`

Step 5: Verify both files now reference the canonical doc

Run:

grep -n "yomiya-page-template-design" \
  "/Users/cc/Documents/root-remote/product/YomiyaContentSystem/README.md" \
  "/Users/cc/Documents/root-remote/product/YomiyaContentSystem/07-视觉与页面表达.md"

Expected: PASS and print matching lines from both files.

Step 6: Commit

git add product/YomiyaContentSystem/README.md product/YomiyaContentSystem/07-视觉与页面表达.md
git commit -m "$(cat <<'EOF'
docs: link yomiya active docs to canonical design doc
EOF
)"

Task 3: Sync the approved design context into project instructions and verify the docs site build

Files:

Create: CLAUDE.md
Source: .impeccable.md
Validate: site/package.json:5-12
Step 1: Verify CLAUDE.md does not exist yet

Run:

test -f "/Users/cc/Documents/root-remote/CLAUDE.md"

Expected: FAIL with exit code 1 because the project-level Claude instructions file does not exist yet.

Step 2: Create CLAUDE.md by mirroring the approved Design Context

Run:

cp "/Users/cc/Documents/root-remote/.impeccable.md" "/Users/cc/Documents/root-remote/CLAUDE.md"

The resulting file must contain this exact section:

## Design Context

### Users
Yomiya 当前页面表达优先服务内容探索者。用户打开产品时，核心任务不是管理学习计划，也不是执行明确任务，而是快速判断“这里有什么值得点开”，并以尽量低的选择成本进入一条内容、一个合集或一个方向继续逛下去。

### Brand Personality
品牌气质应当是：轻盈、克制、内容感强。

Step 3: Verify CLAUDE.md contains the approved section title

Run:

grep -n "## Design Context" "/Users/cc/Documents/root-remote/CLAUDE.md"

Expected: PASS and print the heading line.

Step 4: Build the docs site to verify the new canonical doc syncs cleanly

Run:

npm --prefix "/Users/cc/Documents/root-remote/site" run build

Expected: PASS with Astro/Starlight build output and no markdown/content sync errors.

Step 5: Spot-check the built output includes the canonical doc route slug

Run:

find "/Users/cc/Documents/root-remote/site/dist" -path "*yomiya-page-template-design*"

Expected: PASS and print at least one built path containing yomiya-page-template-design.

Step 6: Commit

git add CLAUDE.md
git commit -m "$(cat <<'EOF'
chore: persist yomiya design context for future sessions
EOF
)"

Self-review

Spec coverage

Canonical page-template Design.md publication: covered by Task 1
Keep 01 / 06 / 07 as the active short-form doc set: covered by Task 2
Add the long-form Design.md as a design-total-view document instead of replacing 07: covered by Task 2
Persist approved design context for future work: covered by Task 3
Verify the docs site surfaces the new doc without sync-pipeline changes: covered by Tasks 1 and 3

No spec gaps found.

Placeholder scan

No TODO, TBD, or “implement later” placeholders
Every file path is exact
Every command is exact
Every inserted markdown snippet is explicit

Type / naming consistency

Canonical doc path is consistently docs/yomiya/yomiya-page-template-design.md
Approved spec source path is consistently docs/superpowers/specs/2026-04-04-yomiya-page-template-design.md
Design context source is consistently .impeccable.md
Active doc references consistently use the same canonical slug