--- marp: true theme: tvu-dark paginate: true size: 16:9 header: 'Consumer Scaffold + Marp 主题 · 2026-05-21' footer: 'Nancy Zeng × Claude Opus 4.7 · 内部分享' --- # Consumer Scaffold 升级 + Marp tvu-dark 主题 ## 一次基础设施型 AI 协作复盘 **Nancy Zeng** · UX Designer **Claude Opus 4.7** · AI 协作伙伴 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 真源。** --- ## 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 ``` --- ## 最终交付（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}} 替换 --- ## 时间线（关键 turning points） | # | 用户 feedback | 性质 | |---|---|---| | 3 | "文件目录不清晰" | 重组 docs/ | | 4 | "MD 不适合分享" | 引入 Marp | | 7 | "这是单产品还是所有产品" | upstream 真源 | | **9** | **"TVU 品牌是绿色的，不是蓝色的"** | **致命错误纠正** | | 11 | "表格白底浅灰字看不清" | @import default 陷阱定位 | | 12 | "署名为什么不是 Nancy Zeng" | {{AUTHOR}} 占位符 | | 14 | "PDF 排版不一致 + dist 默认不生成" | on-demand 导出 | --- # Top 5 Process Gap ## 按返工成本排序 --- ## 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" --- ## Gap 2 · Marp 主题选错（gaia 文档风） - 第一版 PPTX 跟 Word 文档没区别（白底深字） - AI 起手用 Marp 内置 `gaia` 主题——**没考虑"消费产品是深色 UI"** **根因**：AI 默认"用内置主题省事"——**没主动问 user 视觉方向** **返工**：重写 `tvu-dark.css`（240 行独立主题） > **回流**：以后做"视觉相关任务"起手必先确认风格方向，不假设 --- ## Gap 3 · `@import default` 高优先级陷阱 - tvu-dark.css 顶部 `@import 'default'` 想"扩展" - GitHub Markdown CSS 用超高特异性选择器**压住自定义规则** - 表格依然白底浅灰字 **根因**：凭直觉用 `@import` 复用代码——**没读 Marp 内置 CSS 看特异性** **修复**：移除 import，独立自包含整个主题 > **回流**：`marp-themes/README.md` 显式记录陷阱 --- ## 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 --- ## 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 --- ## 高效对话建议 · 给 UX/PM **(1) 涉及品牌视觉的任何任务，起手 1 句给真源路径** > "TVU 品牌色 token 在 `variables.css`，按 `--brand` 拿真值" **(2) "通用 / 全产品复用"诉求要早说** > 起手就说"做成 TVU 通用 scaffold"——AI 一次走对架构 **(3) 视觉任务起手要说"什么风格"** > "出 PPT，跟 TVU 产品 dark UI 风格一致（深色 + 品牌绿）" --- ## 高效对话建议 · 给 AI **(4) 写涉及 token / 真源数据的任何 hex / 字符串前，强制先 grep** > 不写"我记得是 X"——所有 hex / 路径必查后写 **(5) Demo 跑产物（PPTX / 截图）默认要 on-demand** > 跑了告诉用户"这是预览，按需保留" **(6) 写模板默认值时主动用 user 真实数据** > `git config user.name`、cwd basename 等取真值，不用 generic placeholder --- ## 高效对话建议 · 给 Review 方 **(7) Review 视觉物料时用对比 baseline** > 前后版本截图能秒指出"表格背景倒了" **(8) 文档差异点要明确说** > 反例："PDF 跟 HTML 不一样"——笼统 > 正例："PDF 渐变变成块状，box-shadow 丢了"——AI 能精确定位 --- ## 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 | --- ## 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 条） --- ## Model 选型实证 | 模型 | 适合场景 | 本 session 时刻 | |---|---|---| | **Opus 4.7** | 架构推理 / 自审 / 跨文件回流 / 错误根因 | `.marprc.yml` 共享架构提案 · `@import default` 根因定位 · 复盘根因分析 | | **Sonnet 4.6** | 批量替换 / scaffold 执行 / 简单 sed | 6 文件品牌色批量替换 / docs git mv | **Hybrid 最佳**：Opus 决策 + Sonnet 执行 --- ## 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 主动提示，避免依赖用户记得说"收尾" --- # Post-Wrap-Up 第二波学习 ## AI 元规则 · Memory vs TVU 真源 --- ## 触发：用户两次连续追问 | # | 用户原话 | 暴露的问题 | |---|---|---| | A | "这个为什么是项目级别？不应该是 TVU 设计系统里面的消费产品规则吗？" | 6 条 feedback memory 都是通用规则，被误塞项目级 | | B | "[2 条 retrospect memory] 这两个放在 Memory 里面合适吗？" | 复盘格式 / 触发规则同样误塞 memory | > **关键观察**：同一 anti-pattern 重复 2 次 = **AI 系统性偏置**，不是单次失误 --- ## 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 通用规则** --- ## 真源新增 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 --- ## 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` --- ## 补 Action Items（基于元学习） **4. 把 Meta-Rule 加进 `superpowers:auto-memory` skill 起手协议** > 当前 auto-memory 默认行为缺"先判断通用性"的过滤。跨项目使用真源 + memory 双轨架构成熟后可考虑加这个判断 **5. setup-tvu-consumer 加 `consumer-product-conventions` skill 加载报告** ✅ 已落 > 新接入 consumer 自动看到通用规则集 + Meta-Rule --- ## 最终回流地图 ``` 本 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` 就拿到全套 --- # 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)