Consumer Scaffold + Marp 主题 · 2026-05-21

Consumer Scaffold 升级 + Marp tvu-dark 主题

一次基础设施型 AI 协作复盘

Nancy Zeng · UX Designer
Claude Opus 4.7 · AI 协作伙伴

2026-05-21

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

TL;DR

  • ~25 轮 user feedback · 6 条 memory 落地 · 1 套 scaffolding 入 TVU 真源
  • 跟典型 UX mockup session 不同：本次不画 Figma，做 infra（templates / skills / CSS / docs）

核心 insight：
AI 在做"无 token / 无视觉真源参考"的视觉任务时最容易凭印象犯致命错。
每个"看起来通用的"决定都该先 grep 真源。

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

Session 演化路径

gitea push 检查 → 看似简单的 git status

       ↓ docs/ 14 文件平铺难找
5 子目录重组

       ↓ MD 不适合分享给领导
引入 Marp + tvu-dark 主题

       ↓ 品牌色蓝/绿致命错位
6 文件批量替换 + memory 防再犯

       ↓ 单 consumer 维护成本高
upstream 到 TVU 真源 templates/

       ↓ @import default 高优先级压住样式
独立自包含主题

       ↓ PDF 失真 + dist 默认导出过头
on-demand 导出 + 不出 PDF
Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

最终交付（TVU 真源）

templates/consumer-product/
├── README.md                   ← 模板套件说明
├── PROJECT_STRUCTURE.md        ← 消费产品根目录规则
├── .marprc.yml.template        ← Marp 配置模板
├── gitignore.fragment          ← 标准 .gitignore 片段
├── marp-themes/
│   ├── tvu-dark.css            ← 主题（深 + TVU 品牌绿 #2fb54e）
│   └── README.md               ← 架构 rationale + 陷阱文档
└── docs/                       ← 5 子目录骨架 (retrospects/handoffs/audits/specs/decisions)

setup-tvu-consumer SKILL.md 扩展：Step 5 docs scaffold + .marprc.yml 自动复制 + {{AUTHOR}} 替换

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

时间线（关键 turning points）

# 用户 feedback 性质
3 "文件目录不清晰" 重组 docs/
4 "MD 不适合分享" 引入 Marp
7 "这是单产品还是所有产品" upstream 真源
9 "TVU 品牌是绿色的，不是蓝色的" 致命错误纠正
11 "表格白底浅灰字看不清" @import default 陷阱定位
12 "署名为什么不是 Nancy Zeng" {{AUTHOR}} 占位符
14 "PDF 排版不一致 + dist 默认不生成" on-demand 导出
Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

Top 5 Process Gap

按返工成本排序

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

Gap 1 · 没查 token 就 hardcode 品牌色

致命错误

  • 凭印象写 #1f4e8c（深蓝）→ 污染 6 文件
  • 真值 #2fb54e 在 variables.css 早就有，一行 grep 就能拿
  • User 原话："这个是最致命的错误，你都没发现"

根因：AI 默认"我记得是 X"——记忆不可靠

回流：feedback_brand_color_verify_first + reference_tvu_brand_color memory + marp-themes/README.md 强制"改色板先 grep token"

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

Gap 2 · Marp 主题选错（gaia 文档风）

  • 第一版 PPTX 跟 Word 文档没区别（白底深字）
  • AI 起手用 Marp 内置 gaia 主题——没考虑"消费产品是深色 UI"

根因：AI 默认"用内置主题省事"——没主动问 user 视觉方向

返工：重写 tvu-dark.css（240 行独立主题）

回流：以后做"视觉相关任务"起手必先确认风格方向，不假设

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

Gap 3 · @import default 高优先级陷阱

  • tvu-dark.css 顶部 @import 'default' 想"扩展"
  • GitHub Markdown CSS 用超高特异性选择器压住自定义规则
  • 表格依然白底浅灰字

根因：凭直觉用 @import 复用代码——没读 Marp 内置 CSS 看特异性

修复：移除 import，独立自包含整个主题

回流：marp-themes/README.md 显式记录陷阱

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

Gap 4 · dist 默认导出 vs on-demand 没问 user

  • 每次 demo / 验证主题，AI 顺手 marp ... --pptx --pdf --html
  • 累积后用户："能不能我说要分享时再生成，默认不生成"
  • 加上 PDF 失真"用不上"

根因：AI "demo 顺手"模式没有刹车

回流：feedback_export_on_demand_only + feedback_no_pdf_export memory

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

Gap 5 · 署名默认 generic team name

  • 模板写 TVU UX × Claude + TVU UX team
  • User："署名为什么不是 Nancy Zeng？不应该是对话的署名是谁吗"
  • Generic team name = 没署名，同事看不到是谁的贡献

根因：AI "安全做法"用 team name——忘了"安全" ≠ "有用"

修复：{{AUTHOR}} 占位符 + setup-tvu-consumer 用 git config user.name 替换

回流：feedback_signature_real_author memory

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

高效对话建议 · 给 UX/PM

(1) 涉及品牌视觉的任何任务，起手 1 句给真源路径

"TVU 品牌色 token 在 variables.css，按 --brand 拿真值"

(2) "通用 / 全产品复用"诉求要早说

起手就说"做成 TVU 通用 scaffold"——AI 一次走对架构

(3) 视觉任务起手要说"什么风格"

"出 PPT，跟 TVU 产品 dark UI 风格一致（深色 + 品牌绿）"

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

高效对话建议 · 给 AI

(4) 写涉及 token / 真源数据的任何 hex / 字符串前，强制先 grep

不写"我记得是 X"——所有 hex / 路径必查后写

(5) Demo 跑产物（PPTX / 截图）默认要 on-demand

跑了告诉用户"这是预览，按需保留"

(6) 写模板默认值时主动用 user 真实数据

git config user.name、cwd basename 等取真值，不用 generic placeholder

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

高效对话建议 · 给 Review 方

(7) Review 视觉物料时用对比 baseline

前后版本截图能秒指出"表格背景倒了"

(8) 文档差异点要明确说

反例："PDF 跟 HTML 不一样"——笼统
正例："PDF 渐变变成块状，box-shadow 丢了"——AI 能精确定位

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

6 条 Memory 已回流

规则 文件 类型
收尾默认 push gitea feedback_wrap_up_git_push feedback
TVU 品牌色绿不是蓝 reference_tvu_brand_color reference
品牌色写前必查 token feedback_brand_color_verify_first feedback
署名默认 git user.name feedback_signature_real_author feedback
dist 导出按需触发 feedback_export_on_demand_only feedback
Marp 不出 PDF feedback_no_pdf_export feedback
Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

TVU 真源已落 artifact

  • templates/consumer-product/ 完整 scaffolding（8 文件）
  • marp-themes/tvu-dark.css 独立主题
  • marp-themes/README.md 架构 rationale + 陷阱文档
  • .marprc.yml.template Marp 配置模板
  • PROJECT_STRUCTURE.md 消费产品根目录规则
  • gitignore.fragment 标准片段
  • setup-tvu-consumer/SKILL.md 扩展（Step 5 + 反模式 3 条）
Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

Model 选型实证

模型 适合场景 本 session 时刻
Opus 4.7 架构推理 / 自审 / 跨文件回流 / 错误根因 .marprc.yml 共享架构提案 · @import default 根因定位 · 复盘根因分析
Sonnet 4.6 批量替换 / scaffold 执行 / 简单 sed 6 文件品牌色批量替换 / docs git mv

Hybrid 最佳：Opus 决策 + Sonnet 执行

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

3 个 Action Items

1. 给 TVU 真源加 BRANDING.md 速查文档 ✅ 已落

品牌色 token 表 + logo 用法 + 字体规范（post-wrap-up 完成）

2. setup-tvu-consumer 加自检"BRANDING.md 已读"

AI 跑 setup 时输出"建议查 $TVU/BRANDING.md"，降低未来视觉漂移

3. 评估 session-end auto-nudge"要不要写复盘"

长 session 末尾 AI 主动提示，避免依赖用户记得说"收尾"

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

Post-Wrap-Up 第二波学习

AI 元规则 · Memory vs TVU 真源

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

触发：用户两次连续追问

# 用户原话 暴露的问题
A "这个为什么是项目级别？不应该是 TVU 设计系统里面的消费产品规则吗？" 6 条 feedback memory 都是通用规则，被误塞项目级
B "[2 条 retrospect memory] 这两个放在 Memory 里面合适吗？" 复盘格式 / 触发规则同样误塞 memory

关键观察：同一 anti-pattern 重复 2 次 = AI 系统性偏置，不是单次失误

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

Gap 6 · Memory 是 default sink，但通用规则应在 TVU skill

实证：

  • auto-memory skill 默认 trigger = "用户给 feedback → 存 memory"
  • 但 memory 是项目级 → TVU 通用规则进 memory = 每 consumer 各一份副本
  • TVU 改规则要逐 consumer 同步 → 架构债务

根因：AI 盲套 auto-memory skill 的默认指引，缺"先判断通用性"的过滤步

返工成本：8 条 memory 全部迁移（6 feedback + 2 retrospect 相关）

回流 → Meta-Rule：consumer-product-conventions/SKILL.md 顶部
写 memory 前先问：用户个人偏好 vs TVU 通用规则

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

真源新增 artifact（post-wrap-up）

Artifact 真源路径
consumer-product-conventions/SKILL.md .claude/skills/ 真源 skill, 6 通用规则 + Meta-Rule
BRANDING.md 🆕 repo root, 品牌色速查 + token + logo
RETROSPECT_FORMAT.md 🆕 templates/.../retrospects/, 8 段格式 spec
Rule 4 例外段 dist git add -f for 远程访问

4 处真源改动 → setup-tvu-consumer symlink 列表 6→7

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

Memory 最终状态：8 → 2

保留（2）：

  • reference_tvu_consumer_conventions.md — pointer 指向 TVU 真源 skill
  • microapps-layout-convention.md — MicroApps 项目专属（LEFT 1216 / RIGHT 680）

删除（8）：全部迁移到 TVU 真源

  • 6 条 feedback / reference → consumer-product-conventions skill + BRANDING.md
  • 2 条复盘相关 → RETROSPECT_FORMAT.md
Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

补 Action Items（基于元学习）

4. 把 Meta-Rule 加进 superpowers:auto-memory skill 起手协议

当前 auto-memory 默认行为缺"先判断通用性"的过滤。跨项目使用真源 + memory 双轨架构成熟后可考虑加这个判断

5. setup-tvu-consumer 加 consumer-product-conventions skill 加载报告 ✅ 已落

新接入 consumer 自动看到通用规则集 + Meta-Rule

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

最终回流地图

本 session 改动:
TVU 真源 ──→ consumer-product-conventions (skill)
        ├──→ BRANDING.md
        ├──→ RETROSPECT_FORMAT.md
        ├──→ marp-themes/tvu-dark.css + README
        ├──→ templates/consumer-product/ (scaffolding)
        └──→ setup-tvu-consumer (Step 5 + skill 列表 7)

MicroApps memory ──→ 8 条 → 删 → 1 pointer 留
MicroApps docs/ ──→ 5 子目录重组 + 3 复盘 + dist (force-add)

任何未来 consumer 跑 setup-tvu-consumer 就拿到全套

Nancy Zeng × Claude Opus 4.7 · 内部分享
Consumer Scaffold + Marp 主题 · 2026-05-21

Thank You

完整复盘
docs/retrospects/2026-05-21-consumer-scaffold-marp-theme-retrospect.md

TVU 真源新落
tvu-design-system/templates/consumer-product/

反馈 / 讨论
Nancy Zeng (TVU UX team)

Nancy Zeng × Claude Opus 4.7 · 内部分享