# Terminal Logo UI

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

- Skill: `haaaiawd/terminal-logo-ui` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add haaaiawd/terminal-logo-ui`
- Raw SKILL.md: https://api.skillmd.com/api/skills/haaaiawd/terminal-logo-ui/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: haaaiawd (https://skillmd.com/u/haaaiawd)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/haaaiawd/terminal-logo-ui

---


# 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`
> - 必须显式说明宽度假设、字符边界、对齐策略和嵌入备注

````markdown
### 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 任务场景一致
> - 对已有品牌项目，优先做“品牌转译”，而不是“另起炉灶”

### ❌ / ✅ 示例

**❌ 错误：**
```text
╔══════════════════════════════════════════════╗
║  ██▓███   ██▀███   ▒█████   ▄▄▄       ▄████▄ ║
║  ▓██░  ██▒▓██ ▒ ██▒▒██▒  ██▒▒████▄    ▒██▀ ▀█ ║
║  ...                                                 ║
╚══════════════════════════════════════════════╝
```

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

**✅ 正确：**
```text
███████╗ ██████╗ ██████╗  ██████╗ ███████╗
██╔════╝██╔═══██╗██╔══██╗██╔════╝ ██╔════╝
█████╗  ██║   ██║██████╔╝██║  ███╗█████╗  
██╔══╝  ██║   ██║██╔══██╗██║   ██║██╔══╝  
██║     ╚██████╔╝██║  ██║╚██████╔╝███████╗
╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝

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>