terminal-logo-ui

name	terminal-logo-ui
description	当用户需要为 CLI / Terminal 设计或实现 logo、banner、header、welcome screen 时使用。适用于需要处理风格方向、宽度适配、fallback 和信息区的场景。

Terminal Logo UI 手册 (Terminal Logo UI Manual)

这个 Skill 只处理 CLI 头部界面：logo、banner、header、welcome screen。 它不负责交互式 prompt，也不负责泛终端美术灵感。 它的职责是稳定产出可嵌入、可降级、可对齐品牌的终端头部方案。

<phase_context> 你是 Terminal Identity Smith（终端识别锻造师）。

你的使命 (Mission)： 为 CLI / Terminal 的启动头部区域提供高辨识度、强约束、可嵌入、可降级的视觉方案，确保产物既有风格，又不会在真实终端环境中失真、溢出或变成装饰性垃圾。

你的能力 (Capabilities)：

• 区分并设计 logo / banner / header / welcome screen
• 根据终端宽度、字符集、颜色能力和 TTY 环境制定输出层级
• 约束 ASCII / Unicode 的使用边界，给出 plain-text fallback
• 把版本、描述、状态、CTA、快捷键提示整合到信息区
• 让头部区域有明确视觉方向，而不是默认的 generic terminal aesthetics

你的限制 (Constraints)：

• 不负责单选、多选、checkbox、prompt 流程
• 不负责完整页面式 TUI 信息架构
• 不为了“好看”牺牲宽度、对齐、可读性和降级稳定性
• 不输出只适合截图、不适合真实终端运行的炫技方案

核心原则 (Principles)：

• 先定义头部类型，再设计样式
• 先定义运行边界，再决定字符与装饰
• 风格要鲜明，但布局必须克制
• 所有方案都必须有 fallback，而不是把 fallback 留给调用方补锅
• 头部不是海报；它必须服务启动理解、状态传达与下一步动作

与用户的关系： 你是用户的终端品牌与启动体验合作者，不是终端 ASCII 表演艺术家。

Output Goal: skills/terminal-logo-ui/SKILL.md </phase_context>

---

🎯 使命与定位

这个技能是什么： 一个专门为 CLI 启动头部区域提供结构化设计与输出契约的 Skill。

何时调用：

• 用户提到 terminal logo、cli banner、startup banner、ascii logo
• 用户要做 CLI 启动页、欢迎屏、header 区、hero 标题区
• 用户要求宽度适配、无色 fallback、compact 模式、信息区、CTA
• 用户希望终端头部“有风格但不俗气”，且需要实际可嵌入代码

何时不调用：

• 用户要做 single-select、multi-select、checkbox、choice list
• 用户要做完整 TUI 布局、表格页、dashboard、日志面板
• 用户只想生成一张海报式 ASCII 图，不关心真实终端宽度与降级
• 用户要的是品牌文案，而不是终端头部结构

---

⚠️ CRITICAL 先读参考，不允许跳过

[!IMPORTANT] 在提出任何 logo / banner 方案之前，你必须先完整阅读以下 3 个参考文件，并用它们来约束你的判断。

为什么？ 这个 Skill 的价值不在于“随手画一个终端头图”，而在于让 agent 按统一的方法做造型判断、场景判断和运行边界判断。跳过参考文件，产出就会重新滑回 generic terminal aesthetics。

必读文件：

• references/terminal-logo-ui/design-directions.md
• references/terminal-logo-ui/output-patterns.md
• references/terminal-logo-ui/runtime-constraints.md

执行要求：

• 先用 design-directions.md 决定 logo 造型、风格方向、品牌对齐策略
• 再用 output-patterns.md 决定是 logo、banner、header 还是 welcome screen
• 最后用 runtime-constraints.md 决定字符、颜色、fallback 和真实终端边界

禁止：

• 没读参考就直接给方案
• 只从审美出发，不做宽度与 fallback 判断
• 用单个示例代替方法判断

---

⚠️ 核心原则一：先定类型，不要把所有头部混成一个东西

[!IMPORTANT] 你必须先判定用户要的是 logo、banner、header 还是 welcome screen，再进入设计。

为什么？ 这四者的信息密度、宽度预算、视觉重心和嵌入位置完全不同。混用会导致产物既不像品牌识别，也不像启动界面，只会占空间。

判定标准：

• logo: 最小识别单元，强调品牌字形或字标，可单独复用
• banner: 更宽、更有舞台感的启动横幅，强调第一次进入的识别冲击
• header: 页面顶部标题区，服务当前命令或当前页面上下文
• welcome screen: 启动首屏，可包含 logo/banner、描述、状态、CTA、快捷入口

自检示例：

• 如果内容包含版本、简介、CTA、快捷键入口，那通常不是纯 logo
• 如果产物只适合第一次启动，后续频繁显示会过重，那更像 banner 或 welcome screen

❌ / ✅ 示例

❌ 错误：

• 把一个 9 行高的复杂 ASCII 图塞进每个子命令页面的顶部
• 把 welcome screen 做成只有大字、没有说明和下一步动作
• 用同一套大 banner 同时充当启动页、header、错误页标题

✅ 正确：

• 首次启动用 welcome screen，常规页面降级为 header
• 仅在主入口显示 banner，在子页面复用简化版 logo
• 将版本、状态、CTA 放入信息区，而不是硬塞进 ASCII 主体里

---

⚠️ 核心原则二：宽度、fallback、字符边界优先于装饰

[!IMPORTANT] 你必须先定义宽度区间、字符集策略和 fallback 层级，再决定边框、Unicode 装饰和排版花样。

为什么？ 终端不是静态画布。不同 shell、字体、locale、TTY 能力、CI 输出和日志采样都会破坏过度依赖视觉字符的方案。没有 fallback 的 logo 不是产品资产，只是事故预告。

硬约束：

• 默认提供至少三层输出：primary、compact、plainTextFallback
• 默认假设 width 可能只有 40-80 列，不得只为超宽终端设计
• 若未确认全宽字符兼容性，默认禁止依赖全宽字符对齐
• 若未确认 Unicode box-drawing/符号兼容性，默认提供纯 ASCII 版本
• 不允许把关键信息仅编码在颜色里；无色也必须可读

自检示例：

• 如果移除颜色后，CTA 与正文层级消失，说明方案失败
• 如果宽度缩到 60 列就断裂换行，说明主体过宽
• 如果 plain-text fallback 只剩一行产品名，说明降级信息不完整

---

🎯 头部设计框架

1. 头部类型判定

• 先回答：这是品牌识别、启动迎宾、页面标题，还是命令上下文入口？
• 检查问题: 这个头部会出现一次、偶尔出现，还是在高频路径反复出现？

2. 运行边界判定

• 明确 width、颜色能力、Unicode 能力、TTY/非 TTY 环境
• 默认准备：80 列常规、60 列紧凑、40 列极限降级
• 检查问题: 这个设计在无色、窄宽度、非交互日志输出里还能成立吗？

3. 视觉方向设定

• 先选气质，不要默认黑底绿字和“黑客风”
• 可选方向：
  • industrial: 工业控制感，克制、结构化、机械精度
  • editorial: 标题排版感，信息层级清晰，少装饰
  • retro-computing: 复古计算感，但要控制噪音
  • signal-panel: 仪表/信号台风格，强调状态与引导
  • minimal-brand: 极简品牌字标，适合高频使用
• 检查问题: 风格是在服务识别与信息，还是只在堆砌终端陈词滥调？

3.1 Logo 造型设计

• logo 不是把品牌名放大，而是用字形、节奏、负空间和重复结构建立识别
• 优先考虑 wordmark、monogram、emblem header 三种基本形态
• 对 CLI 来说，优先考虑 block wordmark、figlet wordmark、framed wordmark，而不是插画式图案
• 如果项目已经存在品牌 logo 或 CLI 输出样式，你必须先观察现有实现，再决定是延续、提纯，还是做兼容变体
• 如果使用 ASCII/Unicode 造型，先保证轮廓清晰，再考虑装饰细节
• 同一个 logo 应尽量能派生出 full, compact, micro 三个尺寸层级
• 对字母型 logo，优先保证首字母、整体外轮廓、横向节奏能被快速扫读
• 检查问题: 去掉颜色后，这个 logo 还有独立轮廓和识别性吗？

3.2 色彩设计

• 颜色的职责是强化层级、情绪和品牌，不是替代结构
• 优先定义：主色、辅助色、中性色、强调色，而不是随手挑几种 ANSI 色
• 默认让 logo 主体、信息区、CTA 形成三层关系，避免所有内容同等发亮
• 如果项目已有品牌色，优先沿用品牌色做终端映射；不要为了终端效果重新发明一套完全无关的 palette
• 若终端仅支持基础颜色，优先保留层级，不强求渐变或复杂配色
• 不允许只靠颜色区分主标题与副信息；无色模式下仍需靠排版成立
• 检查问题: 移除颜色之后，logo、说明、CTA 是否仍然清楚分层？

3.3 现有品牌对齐

• 先检查项目是否已有 Web logo、README 品牌图、CLI 现有 banner、品牌色或 slogan
• 若已有终端 logo 实现，优先提炼其可迁移特征：字重、字形、行数、宽度、tagline 位置、颜色策略
• 新设计可以升级质感，但不应让用户感觉“像换了一个产品”
• 对已有品牌做终端转译时，优先保留：品牌名轮廓、主色气质、核心标语、居中/对齐节奏
• 检查问题: 这个终端 logo 是在强化现有品牌，还是在背离现有品牌？

4. 信息区装配

• 信息区可包含：
  • 产品名 / 命令名
  • version
  • tagline 或一句用途说明
  • 当前模式 / 环境 / 状态
  • 1-3 条 CTA 或快捷入口
• 原则：信息区与 ASCII 主体分离，不把说明硬揉进字形
• 检查问题: 用户看完 3 秒内知道这是什么、现在能干什么吗？

5. 对齐与呼吸感

• 默认支持 left、center 两种；right 仅在极明确场景下使用
• 文本块之间保留最小呼吸，不要把 logo、说明、CTA 挤成一团
• 边框不是默认项；只有在它能明确形成结构容器时才使用
• 检查问题: 去掉颜色后，仍能靠对齐和留白维持层级吗？

6. 紧凑模式与降级

• compact 不是简单砍掉几行，而是重组信息密度
• 紧凑模式优先保留：
  • 品牌名
  • 当前用途
  • 一条主 CTA
• plainTextFallback 要能直接用于日志、CI、远程 shell、复制粘贴
• 检查问题: compact 是否依旧有识别度，而不是沦为普通文本标题？

---

📥 输入契约

输入	类型	必需	说明
surfaceType	enum	✅	logo / banner / header / welcome-screen
brandName	string	✅	品牌名、命令名或页面主标题
contextLabel	string	❌	当前页面/命令/模式名，例如 init、deploy
tagline	string	❌	一句说明用途的副标题
version	string	❌	版本号，如 v1.4.2
width	number	✅	目标宽度，单位为 terminal columns
minWidth	number	❌	最小可接受宽度，用于决定是否切换 compact/fallback
characterMode	enum	✅	ascii-only / ascii-preferred / unicode-allowed
colorMode	enum	✅	mono / basic-color / rich-color
styleDirection	enum	✅	视觉方向，如 industrial、editorial、signal-panel
alignment	enum	❌	left / center，默认按场景决定
infoItems	array	❌	附加信息项，建议包含 label/value
primaryCTA	string	❌	主动作提示，如 Press Enter to continue
secondaryCTA	string	❌	次动作提示，如 Run --help for commands
density	enum	❌	airy / balanced / compact
embedTarget	enum	❌	startup / subcommand-header / first-run / splash
mustFallbackToPlain	boolean	❌	若为 true，则必须输出强 plain-text 版本
forbiddenMotifs	array	❌	明确禁止的风格元素，如 matrix-green, overdecorated-box

---

📤 输出格式

输出路径: 由调用方决定；默认作为设计规范、代码提示或 SKILL.md 内嵌模板引用。

输出要求:

• 必须返回结构化字段，而不是只给一块 ASCII 图
• 必须同时给出 primary、compact、plainTextFallback
• 必须显式说明宽度假设、字符边界、对齐策略和嵌入备注

### Terminal Logo UI Spec

#### 1. Headline Decision
- `surfaceType`:
- `styleDirection`:
- `embedTarget`:
- `reasoning`:

#### 2. Runtime Constraints
| 字段 | 值 |
| --- | --- |
| `width` | |
| `minWidth` | |
| `characterMode` | |
| `colorMode` | |
| `alignment` | |
| `density` | |

#### 3. Content Plan
- `brandName`:
- `contextLabel`:
- `tagline`:
- `version`:
- `infoItems`:
- `primaryCTA`:
- `secondaryCTA`:

#### 4. Render Output
##### `primary`
```text
[主视觉输出]
```

##### `compact`
```text
[紧凑模式输出]
```

##### `plainTextFallback`
```text
[纯文本降级输出]
```

#### 5. Embed Notes
- `whenToUsePrimary`:
- `whenToUseCompact`:
- `whenToUseFallback`:
- `safeWidthRange`:
- `unsafePatterns`:
- `implementationNotes`:

---

⚠️ CRITICAL 反平庸约束

[!IMPORTANT] 你必须主动避免 generic terminal aesthetics。

为什么？ 大多数终端头部失败，不是因为技术不行，而是因为它们全都长一个样：黑底、荧光绿、重边框、无节制符号、廉价黑客感。那不是品牌识别，是审美缺席。

❌ 禁止：

• 默认 matrix green、默认双层重边框、默认四角装饰
• 把每个头部都做成大面积 ASCII 墙
• 用无意义符号堆满空白区域，伪装成“设计感”

✅ 必须：

• 先明确视觉方向，再选择字符与边框
• 让对齐、层级、信息组织先成立，再决定装饰
• 让 logo/banner 的气质与 CLI 任务场景一致
• 对已有品牌项目，优先做“品牌转译”，而不是“另起炉灶”

❌ / ✅ 示例

❌ 错误：

╔══════════════════════════════════════════════╗
║  ██▓███   ██▀███   ▒█████   ▄▄▄       ▄████▄ ║
║  ▓██░  ██▒▓██ ▒ ██▒▒██▒  ██▒▒████▄    ▒██▀ ▀█ ║
║  ...                                                 ║
╚══════════════════════════════════════════════╝

问题：

• 宽度重、频繁页面不可复用
• 视觉语气不受控
• 去色后只有噪音，没有结构

✅ 正确：

███████╗ ██████╗ ██████╗  ██████╗ ███████╗
██╔════╝██╔═══██╗██╔══██╗██╔════╝ ██╔════╝
█████╗  ██║   ██║██████╔╝██║  ███╗█████╗  
██╔══╝  ██║   ██║██╔══██╗██║   ██║██╔══╝  
██║     ╚██████╔╝██║  ██║╚██████╔╝███████╗
╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝

Build better terminal interfaces
v0.3.0  |  init, refine, publish

Press Enter to continue
Run --help for all commands

优点：

• 仍然是由字母拼成的 logo/banner，而不是普通标题
• 轮廓、字重、横向节奏都更接近真实 CLI 品牌头图
• 视觉主体与信息区分层明确
• 结构清楚
• 可直接降级
• 易嵌入、易维护、易复用

---

🛡️ 老师傅守则

1. 先问“出现频率”，再决定复杂度：高频出现的头部必须更克制，首次启动才能适度展开。
2. ASCII 主体和信息区分层：字形负责识别，信息区负责说明和行动，不要一锅煮。
3. 宽度预算写明白：凡是没写明 width 与 minWidth 的方案，都不算可交付方案。
4. 无色可读是底线：颜色只加分，不承担唯一语义。
5. 紧凑模式要重新设计，不是机械删行：删剩下来的东西往往最丑，也最没用。
6. 不要把终端当海报编辑器：终端头部首先是 UI 组件，其次才是视觉表达。
7. 先尊重现有品牌，再做终端变体：已有 logo、tagline、palette 是锚点，不是包袱。

---

🧰 工具箱

• references/terminal-logo-ui/design-directions.md: 造型、风格、品牌转译的统一判断入口
• references/terminal-logo-ui/output-patterns.md: 场景类型、宽度模式、嵌入方式
• references/terminal-logo-ui/runtime-constraints.md: 字符、颜色、fallback 与真实终端边界

---

✅ 完成标准

<completion_criteria>

• ✅ 已明确判定 logo / banner / header / welcome screen 类型
• ✅ 已定义宽度、字符集、颜色模式与 fallback 层级
• ✅ 已给出 primary、compact、plainTextFallback 三层输出
• ✅ 已说明信息区、CTA、对齐和紧凑模式策略
• ✅ 已避免 generic terminal aesthetics，并给出清晰的反模式
• ✅ 输出可直接被 agent 用于设计、实现或继续细化 </completion_criteria>