# TVU Marp Themes · 真源

> 路径：`tvu-design-system/templates/consumer-product/marp-themes/`
> 目的：所有 TVU 消费产品的复盘幻灯片 / 内部分享物料的统一主题

## 当前主题

| 文件 | 用途 | 颜色 |
|---|---|---|
| `tvu-dark.css` | 复盘 / 内部分享 / 投屏（默认） | 深 tech 黑 + TVU 品牌绿 `#2fb54e` |

## 架构：一处改全 consumer 跟随

```
tvu-design-system/                                     ← 真源（CSS 只此一份）
└── templates/consumer-product/
    ├── marp-themes/tvu-dark.css                       ← 主题
    └── .marprc.yml.template                           ← 配置模板，指向上面绝对路径

<consumer-A>/  <consumer-B>/  <consumer-C>/...         ← 所有 consumer
├── .marprc.yml                                        ← 从 template 复制（指 TVU 绝对路径）
└── docs/retrospects/*.slides.md                       ← frontmatter: theme: tvu-dark
```

### 这个架构怎么工作

1. `.marprc.yml` 用绝对路径 `themeSet:` 注册 TVU 真源 CSS
2. consumer 的 `.slides.md` frontmatter 只需 `theme: tvu-dark`
3. 跑 `marp file.slides.md --pptx -o out.pptx` → Marp 自动用 themeSet 注册的 CSS
4. 改 `tvu-dark.css` 一次 → 所有 consumer 下次导出自动套新主题

### 为什么不用 `@import` / inline style

历史曾尝试两条路径，都不可用：

#### ❌ `@import 'default'` + 自定义 override
```css
@import 'default';
section { background: #0a0e14; }  /* 不生效 */
```
Marp 的 `default` 主题用 GitHub Markdown CSS，选择器形如 `div#\:\$p > svg > foreignObject > section`，**特异性极高**，会压住任何自定义 `section { ... }` 规则。结果：表格仍是白底浅灰字。

**教训**：tvu-dark 必须**独立自包含**，不 `@import` 任何内置主题。

#### ❌ frontmatter `style:` inline CSS
```yaml
style: |
  section { background: #0a0e14; }
```
每个复盘的 `.slides.md` 都内嵌 CSS 副本——TVU 改色板时要逐文件改，立刻漂移。

**教训**：CSS 必须**只有一份**在 TVU 真源，consumer 端零内嵌。

## 改主题的标准流程

修改 `tvu-dark.css` 后：

1. **跑视觉检查**（推荐拿 MicroApps video-sync 复盘做 baseline）：
   ```bash
   cd /Users/nancy/Documents/AICoding/VS_Code/MicroApps
   marp docs/retrospects/<file>.slides.md --html -o /tmp/tvu-dark-preview.html
   open /tmp/tvu-dark-preview.html
   ```
2. 检查关键页：
   - 封面页（lead 类，gradient + 标题）
   - 内容页（左侧 accent bar + h1/h2）
   - 表格页（深底 + 品牌色 thead）
   - blockquote 页（key insight 强调块）
   - code 块（等宽 + 边框）
3. **测 PPTX 导出**（不止 HTML，PPTX 是主要分享格式）：
   ```bash
   marp docs/retrospects/<file>.slides.md --pptx -o /tmp/tvu-dark-preview.pptx
   open /tmp/tvu-dark-preview.pptx  # Keynote 打开
   ```
4. 改色板时**先 grep TVU 真源 token**：
   ```bash
   grep "brand" tvu-design-system/src/tokens/variables.css
   ```
   主题 CSS 顶部 `:root` 变量应该跟 dark mode token 对齐（不漂移）

## 导出格式建议

| 格式 | 推荐 | 场景 |
|---|---|---|
| `--html` | ✅ | 本地预览 / 内网分享链接 |
| `--pptx` | ✅ | 投屏会议 / 周报嵌入 / 领导要改 |
| `--pdf` | ❌ **不推荐** | 见下方 |

### 为什么不出 PDF

Marp PDF 走 Chromium 的**打印 CSS 管线**（`@page` 规则 + 字体 hinting + 打印 media query），跟 HTML 直接渲染 / PPTX 嵌入位图的产物排版**不一致**：

- 多层 `radial-gradient` 在 PDF 引擎里会被简化（颜色阶数减少 → 看起来"块状"）
- `box-shadow` 经常丢失
- 字体行间距偏差几个 px → 长 list 在 PDF 里会溢出 slide
- 表格圆角 / 渐变 header 失真

**替代方案**：领导要 PDF 附件 → 跑 PPTX → 用 Keynote / PowerPoint 自带的"另存为 PDF"，渲染走 PowerPoint 而非 Chromium，保真度更高。

## 默认 = 不主动导出 dist/

复盘写完只产 `.md` + `.slides.md` 源文件，**不自动跑 marp**。`dist/*.{html,pptx}` 由用户显式说"导出 / 分享 / 出 PPT"才生成。

理由：
- `.md` + gitea 浏览器渲染已覆盖"日常看复盘"
- PPTX 每份 ~6MB + Chromium 启动 10s，频繁生成浪费资源
- 多产物维护混乱（源改了但 dist 不同步）

## 给未来的 maintainer

如果你要：
- **加新主题**（如 `tvu-light` 给浅色场景）：复制 `tvu-dark.css` 为蓝本，改顶部 `:root` 变量；在 `.marprc.yml.template` 加进 `themeSet:` 数组
- **改色板/字号**：改 `tvu-dark.css` 顶部 `:root` 变量；勿在底部规则里再 hardcode hex
- **改架构**（如改用 npm 包分发主题）：先看本文件"为什么不用 @import / inline style"段，确认不重蹈旧路；同步更新 `setup-tvu-consumer` SKILL.md Step 5(c2)
- **更新 Marp 版本**（marp-cli major bump）：先在 MicroApps video-sync 复盘上跑一遍 baseline 检查渲染是否一致

文件改动后**必须**同步更新：
1. `templates/consumer-product/.marprc.yml.template`（如新增主题）
2. `setup-tvu-consumer/SKILL.md`（如改 scaffold 流程）
3. 本 README（如改架构 / 加新约定）