# Style presets — 七种可选的 README 风格

`repo_readme` 不替用户决定"哪种 README 好看"，而是把七种成熟的 README 传统拆成 **layout + tone 预设**，让用户按项目类型选。每个预设只决定结构、首屏形态、徽章数量、语气和章节顺序；**内容仍然来自仓库事实**。

预设本身是**结构化 JSON 数据**（`styles/*.json`），不是代码；加载、合并、校验由 `logic/styles.mjs` 负责。用户可以在仓库或本机加自己的风格，详见下文「结构化存储与自定义风格」。

## 先看共性：优秀仓库的 12 个特征

从一批成熟仓库的 README 里归纳出的共同点（只提炼做法，不引用具体仓库）：

1. **首屏只说一件事**：一句定位 + 一个视觉锚点 + 一条安装命令。
2. **视觉锚点只有一种**：banner、logo、GIF 或纯排版，四选一，不叠加。
3. **徽章只放动态信息**：版本、CI、测试数、License；静态口号不放。
4. **demo 必须是真的**：GIF 来自真实运行，截图带日期/版本，不摆拍。
5. **安装命令可复制**：一条能直接粘进终端的命令，不写"详见文档"。
6. **结构先于措辞**：先定 section 顺序，再写句子；长文进 docs/。
7. **数字有口径**：每个 before/after 都指到 BENCHMARK 或测试。
8. **主动写限制**：Known limitations / 非目标 / 安全边界，反而增加可信度。
9. **反馈入口明确**：Issues、Discussions、安全报告渠道分开写。
10. **双语是结构对等**，不是机翻：两页同样章节、同样数字、互相链接。
11. **重复信息只出现一次**：README 给入口，docs/ 给细节。
12. **发布物和仓库一致**：tag、CHANGELOG、包清单、市场收录互相对得上。

## 预设矩阵

| id | 风格 | 语言 | hero | demo | 适合 |
|---|---|---|---|---|---|
| `evidence` | 证据优先 | 双语 | banner | GIF | 有基准/测试、需要把数字放前面的工程仓库 |
| `terminal` | 终端工具 | 双语 | 居中 logo | GIF | 有品牌 logo、愿意维护双语页面的命令行工具 |
| `mobile` | 移动端 · 社群 | 中文优先 | banner | 截图 | App / 移动端 / 有社群入口的产品 |
| `playful` | GIF 开场 · 教程 | 英文优先 | logo | GIF | 开发者工具 / TUI，用 GIF 证明手感 |
| `product` | 品牌产品页 | 英文优先 | 品牌 banner | 截图 | 面向普通用户、首屏就要下载入口 |
| `platform` | 面板平台 | 双语 | 居中 logo | GIF | 面板 / 平台，截图多于文字 |
| `minimal` | 极简排版 | 英文优先 | 无图 | 无 | 成熟工具 / 框架，靠排版和链接密度 |

## 结构化存储与自定义风格

风格文件是纯 JSON，按下面的顺序加载（同 id 后者覆盖前者）：

| 位置 | 作用 |
|---|---|
| `styles/*.json`（随包发布） | 7 个内置风格 |
| `~/.tailor/styles/*.json`（或 `TAILOR_STYLES_DIR`） | 本机自定义 |
| `<repo>/.tailor/styles/*.json` | 单仓库自定义，可提交进仓库 |

自定义风格可以只写差异：

```json
{
  "extends": "evidence",
  "id": "acme",
  "label": { "zh": "Acme 证据风", "en": "Acme evidence" },
  "palette": { "brand": "#E4572E" },
  "labels": { "install": { "zh": "开始使用", "en": "Get started" } }
}
```

```sh
node bin/tailor.mjs style:init . --id=acme --extends=evidence
node bin/tailor.mjs styles .                 # 看到 acme（repo 来源）
node bin/tailor.mjs readme . --style=acme --lang=both
```

- `extends` 逐键合并：`label` / `essence` / `tone` / `notes` / `palette` 合并，`labels` 合并，`sections` / `badgeSet` / `requiredFacts` 数组替换。
- 不写 `extends` 时必须提供完整必填字段（schema 见 `styles/schema.json`）。
- 内置风格加载时强制校验，失败直接报错；自定义风格校验失败会**跳过该文件**，`repo_styles` 输出文件路径与原因，其他风格不受影响。
- 所有工具接受自定义 `style` id；`repo_styles` 的 `origin` 列显示 builtin / global / repo。

字段清单、错误语义和完整示例见 [`styles/README.md`](../styles/README.md)。

## 各预设细节

### `evidence` — 证据优先 · 双语

- **首屏**：banner → 语言切换 → 6 徽章 → H1 → 一句定位 → demo GIF
- **章节**：目录 → 为什么需要它 → 怎么工作 → 快速开始 → 功能 → 效果与证据 → 结构 → 测试与 CI → 已知限制 → 反馈与安全 → License
- **语气**：工程口吻，短句、具体、写限制
- **选取条件**：你有基准/测试/明确取舍，且希望数字出现在第一屏

### `terminal` — 终端工具 · 双语

- **首屏**：语言切换 → 居中 logo（240px）→ 5 flat-square 徽章 → H1 → demo GIF
- **章节**：目录 → 为什么是它 → 亮点 → 安装 → 截图 → 证据 → 兼容性 → 社区 → License
- **语气**：产品说明会，先说"像什么、怎么用"
- **选取条件**：有真正的 logo，愿意维护中英两页

### `mobile` — 移动端 · 社群驱动

- **首屏**：语言切换 → hero 图 → 4 徽章 → H1 → 截图组
- **章节**：截图 → 为什么做它 → 能做什么 → 安装与下载 → 遥控电脑 → FAQ → 社区 → 致谢 → License
- **语气**：对用户说话，亲切、承认内测与限制
- **选取条件**：App / 移动端 / 有群、论坛等社群入口
- **注意**：这个预设需要真实截图；没有截图时 `repo_audit` 会给出 style gap

### `playful` — GIF 开场 · 教程感

- **首屏**：logo → 3 徽章 → 全宽 GIF → 直接进教程
- **章节**：安装 → 特性 → 教程 → 谁在用 → 反馈 → License
- **语气**：轻松、短句、一点幽默
- **选取条件**：TUI / 开发者工具，手感比功能列表更重要

### `product` — 品牌横幅 · 产品页

- **首屏**：深色 banner + 下载按钮 + 功能表 + 截图
- **章节**：截图 → 功能 → 下载 → 安装方式 → 性能 → 社区 → License
- **语气**：落地页，一句话一个动作
- **选取条件**：面向普通用户，首屏目标就是下载

### `platform` — 居中品牌 · 国际化

- **首屏**：居中 logo + 一句话定位 + 语言切换 + 3 徽章
- **章节**：功能 → 截图 → 开始使用 → 快速开始 → 社区 → License
- **语气**：官网简介，定位清楚
- **选取条件**：面板/平台类产品，截图比文字多

### `minimal` — 极简排版 · 无图

- **首屏**：居中标题 + 一行横向导航 + 2 徽章
- **章节**：安装 → 特性 → 用法 → 文档 → 说明 → License
- **语气**：手册口吻，陈述句、克制
- **选取条件**：成熟工具/框架，已有大量文档，不需要视觉锚点

## 风格如何影响生成

| 维度 | 预设字段 | 对生成的影响 |
|---|---|---|
| 首屏 | `hero` | 放 banner / logo / 无图；缺素材时写 TODO 并给出 `repo_brand` 任务 |
| 演示 | `demo` | 放 GIF / 截图 / 不放；缺素材时进 TODO |
| 徽章 | `badgeSet` | 决定渲染哪些 shields 徽章，只渲染有事实的 |
| 结构 | `sections` | 决定章节及顺序；`toc` 自动生成锚点 |
| 文案 | `labels` + `tone` | 章节标题与语气；正文仍来自 facts |
| 品牌 | `palette` + `mark` | `repo_brand` 的调色板与默认概念；可用 `concept` 覆盖 |
| 语言 | `language` | 双语 / 中文优先 / 英文优先，以及语言切换行 |
| 版式 | `visual` | 版式引擎、徽章样式、导航样式、demo 宽度、功能卡片、页脚 |
| 继承 | `extends` | 自定义风格从父风格继承，只覆盖需要的字段 |

### 版式引擎（v0.5+）

风格不再只是“换章节顺序”，`visual.engine` 决定首屏、导航和 demo 的排法：

| engine | 使用的风格 | 首屏 | 导航 | demo | 视觉特征 |
|---|---|---|---|---|---|
| `editorial` | `evidence` / `minimal` | 左对齐 banner 或纯文字 | inline 链接 | 720–760px | 长文感、信息密度高 |
| `centered` | `terminal` / `platform` | 居中 logo + 居中 H1 | `<kbd>` chips | 760px | 产品主页、锚点明确 |
| `showcase` | `mobile` / `playful` / `product` | 全宽 banner + 居中 H1 | `<kbd>` chips | 860px | 发布页、图先行 |

可配置字段：`engine`、`badgeStyle`（`flat-square` / `for-the-badge`）、`demoWidth`（480–960）、`navStyle`（`chips` / `inline`）、`featureCards`、`footer`。没有 `visual` 字段的旧风格/自定义风格使用默认值（editorial / flat-square / inline / 无卡片 / 无页脚），行为向后兼容。

```json
{ "visual": { "engine": "showcase", "badgeStyle": "for-the-badge", "demoWidth": 860, "navStyle": "chips", "featureCards": true, "footer": true } }
```

每个预设的默认图形概念（都可在 `repo_brand` 里换）：

| 预设 | 默认概念 | 预设 | 默认概念 |
|---|---|---|---|
| `evidence` | `arcs` 上升弧 | `terminal` | `prompt` 提示符 |
| `mobile` | `orbit` 轨道 | `playful` | `bubble` 对话泡 |
| `product` | `radar` 雷达 | `platform` | `hexstack` 面板栈 |
| `minimal` | `monogram` 字母环 | 任意 | 另外还有 `needle`、`stitch`、`quill`、`spark`、`layers` |

12 个概念的对照图见仓库 [`assets/brand-sheet.svg`](../assets/brand-sheet.svg)；`repo_brand` 一次生成 12 个文件：icon、maskable icon、明暗 logo、明暗 wordmark、明暗 banner、social、brand-sheet、`brand-tokens.json` 和索引，并对调色板做 WCAG 对比度检查。

## 常见问题

**能改预设吗？** 能，有两种方式：把 `styles/<id>.json` 复制到 `.tailor/styles/` 后改字段；或者用 `style:init --extends=<id>` 只写差异。新增 section 才需要改 `logic/readme.mjs` 加 renderer。

**能自动选风格吗？** 当前不做自动选。`repo_audit` 会报告"当前事实满足哪些预设 / 缺什么"，选择权留给用户。

**自定义风格写坏了会怎样？** 该文件被跳过，`repo_styles` 列出路径和校验错误；内置风格和其余自定义风格照常可用。

**旧命令里的风格 id 还能用吗？** 能。早期 id 作为别名保留，命令不用改；但显示与文档只使用上表的风格 id。

**生成的内容能直接发吗？** 不能。草稿里的 `TODO(tailor)` 是给你填的；`repo_verify` 会把剩余 TODO 作为 warn 报出来。