# UI 品牌规范

面向用户的 GSD 输出的视觉模式。编排器通过 @ 引用此文件。

## 分隔符与横幅

**绝不要输出固定宽度的制表符（box-drawing）长串。** 由 `━`、`─`、`═` 组成的长串，对渲染
输出的宿主而言只是普通文本。当窗格比该长串更窄时，它会折行，多余的字符落到第二行，于是边框
与它本应框住的标题就散开了。Markdown 会自适应可用宽度，53 个字符的横线不会。

只有三种形式，没有其他：

| 需求 | 输出 |
|---|---|
| 带标题的区块 —— 阶段、检查点、完成、错误 | `### {标题}`（ATX 标题） |
| 两个区块之间的分隔 | 单独一行的 `---`，**其上方必须有一个空行** |
| 带边框的信息面板 | `### {标题}`，随后各行以普通文本列出 |

**`---` 上方的空行是关键，不是排版讲究。** 紧跟在一行文本下方的 `---` 会被解析为该行的
setext 标题下划线，而不是分隔线 —— 那条横线会把上面那行"吞掉"。空行才使它成为分隔线。
（`---` *下方*的空行是可选的：分隔线是叶子块，后面的内容无论如何都会另起一块。）

**阶段横幅只用标题，不要在其上方加 `---`。** ATX 标题本身就是分隔，而且不会像裸的 `---`
那样被误解析。

### 为什么是统一形式，而非按运行时区分

曾考虑过引入 `rendersMarkdown` 能力键：终端类运行时保留线条图形，Markdown 宿主使用
Markdown。该方案被否决 —— 它需要在每个运行时描述符及解析器中新增一个键，并且会留下两套必须
永远保持同步的输出约定，正是本仓库已记录的"分叉"缺陷类别。在纯终端里，标题与分隔线所承载的
结构与原来的横线对并无二致，却不必锁定宽度，因此第二套约定并无收益。若将来确实出现需要线条
图形的运行时，届时再依据该证据添加此键。

---

## 阶段横幅

用于主要工作流过渡。

```
### GSD ► {阶段名称}
```

**阶段名称（大写）：**
- `QUESTIONING`（提问）
- `RESEARCHING`（研究）
- `DEFINING REQUIREMENTS`（定义需求）
- `CREATING ROADMAP`（创建路线图）
- `PLANNING PHASE {N}`（规划阶段 {N}）
- `EXECUTING WAVE {N}`（执行波次 {N}）
- `VERIFYING`（验证）
- `PHASE {N} COMPLETE ✓`（阶段 {N} 完成）
- `MILESTONE COMPLETE 🎉`（里程碑完成）

---

## 检查点面板

需要用户操作。

```
### CHECKPOINT: {类型}

{内容}

---

**→ {操作提示}**
```

**类型：**
- `CHECKPOINT: 需要验证` → `→ 输入 "approved" 或描述问题`
- `CHECKPOINT: 需要决策` → `→ 选择: option-a / option-b`
- `CHECKPOINT: 需要操作` → `→ 完成后输入 "done"`

---

## 状态符号

```
✓  完成 / 通过 / 已验证
✗  失败 / 缺失 / 阻塞
◆  进行中
○  待处理
⚡ 自动批准
⚠  警告
🎉 里程碑完成（仅在横幅中）
```

---

## 进度显示

**阶段/里程碑级别：**
```
进度: ████████░░ 80%
```

**任务级别：**
```
任务: 2/4 完成
```

**计划级别：**
```
计划: 3/5 完成
```

---

## 生成指示器

```
◆ 正在生成研究员...

◆ 并行生成 4 个研究员...
  → 技术栈研究
  → 功能研究
  → 架构研究
  → 陷阱研究

✓ 研究员完成: STACK.md 已写入
```

---

## 下一步区块

始终在主要完成后。

```
---

## ▶ 下一步

**{标识符}: {名称}** — {单行描述}

`{可复制粘贴的命令}`

<sub>`/clear` 优先 → 全新上下文窗口</sub>

---

**也可选：**
- (根据工作流选填可选命令，例如 `/gsd-progress --next`)

---
```

---

## 错误面板

```
### ERROR

{错误描述}

**修复方法:** {解决步骤}
```

---

## 表格

```
| 阶段 | 状态 | 计划 | 进度 |
|------|------|------|------|
| 1    | ✓    | 3/3  | 100% |
| 2    | ◆    | 1/4  | 25%  |
| 3    | ○    | 0/2  | 0%   |
```

---

## 反模式

- 用 `━`、`─`、`═` 的固定宽度长串作分隔符 —— 在窄窗格中会折行
- 用双线制表符（U+2554、U+2557、U+255A、U+255D、U+2551、U+2560、U+2563）画的边框面板 ——
  边框会独立于内容折行。此处以码位命名而非直接展示，因为守卫检查会拒绝这些字符出现在任何
  随包分发的内容中。
- 紧跟在一行文本下方、中间没有空行的 `---` —— 那是 setext 标题下划线而非分隔线，会把上面
  那行吞掉
- 把标题夹在两条横线之间 —— 标题本身就是分隔
- 混合横幅样式（`===`、`***`）
- 横幅中缺少 `GSD ►` 前缀
- 随机 emoji（`🚀`、`✨`、`💫`）
- 完成后缺少下一步区块

由 `tests/responsive-separators.test.cjs` 强制执行。