设计系统转 Apple Terminal 主题是做什么的？

此技能可从设计系统生成 Terminal.app 配置文件（.terminal 文件）。代码完成实际工作：scripts/ds2terminal.py（Python 3.9 或更高版本，仅使用标准库）。代码还会检查可读性。只有当每个硬性门控都通过时，主题才算完整。

规则

不要根据个人喜好选择颜色。运行脚本。脚本会映射并检查颜色。
不要手动编辑 .terminal 文件。请使用 --set 或 --prefer-token，然后重新运行脚本。
使用 -I 参数运行 Python。下载的文件是数据，不是代码。
除非用户要求，否则不要打开（导入）.terminal 文件。打开文件会向 Terminal 添加配置文件并打开一个窗口。
不要退出或终止 Terminal。不要运行 defaults write com.apple.Terminal。
不要发布用户的私有令牌。

步骤 1：获取设计系统文件

确定链接的类型。然后执行下表中的步骤。

链接类型	操作
本地文件或文件夹	将路径提供给脚本。
公共 GitHub 仓库、树或文件；npm 包；unpkg 或 jsDelivr URL；原始文件	将 URL 提供给脚本。脚本会查找并下载令牌文件。
公共文档或营销页面	将 URL 提供给脚本。它会读取链接的 CSS。结果可能不理想；告知用户。
claude.ai 设计系统工件（`claude.ai/artifact/...`）	使用 Artifact 工具：`action: "list"`, `scope: "files"`。然后对每个存在的令牌文件使用 `action: "read"` 和 `path`：`project/tokens.json`、`project/tokens.css`、`project/tokens/tokens.json`、`project/tokens/colors.css`。将文件保存在一个文件夹中。将该文件夹提供给脚本。
Pidgin 设计系统	使用 `pidgin_get_design_system`。将其 `tokens` 对象保存为 `.json` 文件。将该文件提供给脚本。
Claude Design 项目	使用 `mcp__claude-design__list_files` 和 `read_file` 获取令牌文件。保存它们。将文件夹提供给脚本。
Figma 文件	当 Figma 工具（变量）已连接时使用。如果未连接，请向用户请求变量导出（JSON）。

如果脚本以退出码 2 终止，且消息中提到了某个工具，则执行该链接类型的步骤。关于脚本可读取的格式，请参见 references/sources.md。

步骤 2：运行脚本

python3 -I scripts/ds2terminal.py SOURCE [SOURCE ...] --name "名称" --out 输出目录

脚本会写入：

输出目录/<名称> Light.terminal 和 输出目录/<名称> Dark.terminal
输出目录/report.md 和 输出目录/report.json：每个颜色、其源令牌、APCA Lc、WCAG 比率、每个门控结果以及每次修复
输出目录/preview.html：每个主题绘制为一个包含典型程序输出的终端窗口

退出码：

码	含义	操作
0	每个主题的所有硬性门控均通过。	转到步骤 3。
1	修复后仍有门控失败。	读取 `report.md`。告知用户哪个门控失败。尝试对该颜色使用 `--set`。不要将该主题视为完成。
2	输入错误，或链接需要已登录的工具。	读取消息。对该链接执行步骤 1，或修正选项。

选项

选项	用途
`--name 名称`	配置文件名称。生成的文件为 `<名称> Light.terminal` 和 `<名称> Dark.terminal`。请始终提供。
`--modes auto\|light\|dark\|both`	`auto`（默认）和 `both` 会生成两个主题。设计系统未定义的模式将从另一种模式派生。报告会将其标记为 "derived"。
`--font 字体名称`, `--font-size 13`	字体（PostScript 或字体系列名称）。默认值：设计系统已安装的等宽字体，否则为 SF Mono Terminal（Terminal.app 内置）。默认字号：13 pt。
`--cursor block\|underline\|bar`, `--cursor-blink`	光标形状。
`--set 角色=十六进制颜色`	强制指定一个颜色。角色为 `bg`、`fg`、`bold`、`cursor`、`selection`、`black` ... `brightWhite` 或 `0` ... `15`。为了通过门控，修复程序仍可更改它；报告会说明。
`--prefer-token 角色=令牌`	对 `bg`、`fg`、`brand`、`red`、`green`、`yellow`、`blue`、`magenta` 或 `cyan` 使用此令牌。
`--all-tokens`	保留语义令牌未使用的原始令牌（请参见“无关令牌”）。
`--source-mode ID`	仅使用设计系统的此模式。
`--no-chroma-floor`	在深色模式下保持淡红色和淡绿色的柔和色调。
`--translucent 透明度值`	透明度低于 1 的背景 Alpha（例如 0.95）。浅色主题需要约 0.93 或更高；浅灰色页面背景需要 0.95-0.98，否则脚本会将其替换为白色。默认值：不透明（Alpha 1，无模糊）。仅在用户要求时使用。每个门控随后必须在黑色和白色桌面上均通过。如果 ALPHA 过低，脚本将以退出码 1 终止。报告会给出在测试构建中通过的最低 Alpha。
`--columns 列数`, `--rows 行数`	窗口大小。
`--report json\|md\|both`, `--no-preview`	输出文件。

步骤 3：检查并告知用户

读取 report.md。确保其写明“每个主题的所有硬性门控均通过”。
告知用户：
- .terminal 文件的路径；
- 哪个模式是派生的；
- 用于背景、文本、光标和六种色调的令牌；
- 修复（每个更改的颜色以及导致更改的门控）；
- 被省略的令牌；
- 未达成的“特性”目标（report.md 中的“未命中目标”行）；
- report.md 中的“推荐的 Claude Code 主题”行。
如果用户可以打开文件，则展示 preview.html。
要安装主题，用户需打开 .terminal 文件（Finder 或 open "<file>"）。仅在用户要求时执行此操作。然后用户可以在终端 > 设置 > 配置文件中将其设置为默认。
python3 scripts/demo.py 以 16 种颜色以及淡色（SGR 2）文本打印示例输出。在使用了该主题的窗口中运行它。
告知用户应设置哪个 Claude Code 主题（请参见“与 Claude Code 配合使用”）。

与 Claude Code 配合使用

Claude Code 有两种主题。每种主题以不同方式使用终端主题。

ANSI 主题（dark-ansi、light-ansi；在 /theme 列表中显示为“深色模式（仅 ANSI 颜色）”和“浅色模式（仅 ANSI 颜色）”）。Claude Code 使用 16 种 ANSI 颜色。它使用 ANSI 绿色和红色单元格背景绘制差异行，并在这些单元格上绘制文本颜色。在普通颜色可作为文本阅读的主题上，这些单元格在深色模式下很亮，因此添加行上的文本对比度低。
标准主题（dark、light）。Claude Code 在主题背景上使用自己的 24 位颜色。这些颜色保持可读。通过名称设置主题。设置 auto 会读取终端背景。Terminal 2.15 可响应此查询（OSC 11）并返回主题背景（浅色和深色模式下），因此 auto 可选择正确的模式。此功能未在运行的 Claude Code 会话中检查。在终端主题中，Claude Code 检查并使用背景、光标、选择和淡色文本。16 种颜色用于其他程序。

报告为每个主题提供一个“Claude Code”部分。它给出 ANSI 主题和标准主题的 16 对对比度，以及一行“推荐的 Claude Code 主题”。规则：当最弱文本对的 Lc 大于等于 45 时使用 ANSI 主题；否则在标准主题表现更好时使用标准主题。preview.html 会绘制两个示例。这些表格来自 Claude Code 2.1.323 程序文件。未对照正在运行的会话进行检查。

告知用户执行以下操作：

在 report.md 中读取所使用主题的“推荐的 Claude Code 主题”行。
在 Claude Code 中，输入 /theme 并选择该主题。或者在 Claude Code settings.json 中设置 theme 选项，例如 "theme": "dark-ansi"。

如果 Claude Code 主题模式与终端主题模式不同（例如浅色 Claude Code 主题搭配深色终端主题），文本可能变得不可读。半透明终端背景也会使文本不可读。请就这两点警告用户。

映射工作原理

模式。 背景亮度确定模式（OKLab L < 0.5 为深色）。脚本不使用模式名称。设计系统可能将屏幕尺寸称为“主题”（例如 root-tablet）。相同种类的多个模式合并为一个主题；报告列出其他模式。
无关令牌。 当一个设计系统有 4 个或更多语义别名（例如 color-brand -> hb-pink）时，任何别名未使用且不与系统名称前缀共享的原始令牌将被省略。这些通常是客户端或旧品牌的颜色。
角色。 语义别名优先。页面背景是背景。在浅色模式下，当设计系统也有较浅的卡片表面时，该表面被用作背景：文本位于卡片上，而页面颜色位于卡片之后。--prefer-token bg=令牌 可选择不同的令牌。正文文本令牌是文本颜色。品牌令牌是光标并淡化选择。当品牌颜色在背景上作为光标太弱时，使用品牌色谱上通过 WCAG 4.5 的一步作为光标（例如可访问的橙色）。
色调。 最小成本分配将令牌放入六个色调槽位。它使用 OKLCH 色调、令牌名称（danger -> red、success -> green、warning -> yellow、info -> blue）和亮度变化。仅当色调在该槽位的 45 度范围内时，名称才计入。
亮度。 每种颜色（保持色调和色度）移动到其模式的 APCA 波段内。已在波段内的令牌保持精确。
缺失颜色。 空的槽位获得色盲友好的色调，色度与品牌色相同。
派生的深色模式。 浅色文本或墨色令牌成为深色背景。浅色纸张成为深色文本。
特性。 主题必须在其设计系统的门控内看起来像它。
- 品牌槽位：当没有色调颜色显示品牌颜色时，品牌颜色成为最近色调（26 度内）的亮色步进。其亮度移动到亮色目标。
- 粗体：当标题文本令牌比文本更强时，它成为粗体颜色。在深色模式下没有这样的令牌时，粗体是文本颜色，最多亮 Lc 4，低于晕环门控。
- 每种色调的深色模式低边（Lc）：红色 50，绿色 72，黄色 62，蓝色 55，洋红 55，青色 60。
- 亮度适配后低于 WCAG 3 的色调令牌颜色将移动到 WCAG 3。
- 报告中的“特性”部分列出了目标，而非门控：来自令牌的颜色、品牌颜色、保持的色度（目标 70% 或更高）、最大色调变化（12 度或更小）、最小普通到亮色步进（dE 0.030 或更大），以及一行“未命中目标”。
修复。 如果硬性门控失败，脚本会以最小步进更改优先级最低的颜色：先亮度，然后色调和色度，最后综合颜色。优先级：--set > 品牌 > 命名令牌 > 令牌 > 派生 > 综合。如果背景无法承载可读文本，脚本会在标准背景上重新映射所有颜色。报告会说明。

可读性门控（硬性）

references/gates.md 给出每个门控、其限制和原因。概要：

门控	失败条件
文本在背景上	APCA Lc < 75 或 WCAG < 7
晕环（深色）	文本、粗体、白或亮白 Lc > 104
ANSI 1-6 和 9-14	Lc < 45 或 WCAG < 3
亮黑（颜色 8）	Lc < 30，或低于文本 15 以上
灰色	深色：白和亮白 Lc < 60；浅色：黑 Lc < 75，白和亮白 Lc < 30
区分度	两个色调颜色接近度小于 dE(OKLab) 0.06
色盲	红/绿 < 0.06，红/黄和红/洋红 < 0.05（红色盲、绿色盲）
选择	其上的文本 WCAG < 4.5 或 Lc < 60；其上的色调颜色 Lc < 30；与背景的 dE < 0.05 或 WCAG < 1.10
光标	WCAG < 3
粗体	粗体比文本更暗
文本在颜色上	绿色、黄色或青色上的黑色文本 Lc < 30
色调 vs 文本	色调颜色与文本颜色接近度小于 dE 0.06
淡色文本（SGR 2）	淡色文本 Lc < 30；淡色色调颜色（1-6，9-14）Lc < 15
半透明	仅当使用 `--translucent`：上述门控在黑色或白色桌面上失败

淡色文本是颜色向单元格背景混合的结果（colorlab.faint，DIM_BLEND 0.60，DIM_POWER 1.26）。这是在 Terminal 2.15 中测量的（docs/faint-measurement.md）。真实的淡色文本很弱，因此限制较低。深色色调颜色保持其色度。用户可以提高 GATES["faint_text"]["gate"]["ansi_min_lc"] 以获得更强的淡色，代价是降低色度。

已知限制

使用 24 位颜色（终端设置 COLORTERM=truecolor）的程序不使用该主题。对于 Claude Code，请设置报告推荐的主题（请参见“与 Claude Code 配合使用”）。
尚未测量：粗体颜色，以及终端在半透明窗口上绘制单元格背景的方式。尚未检查生成的主题在终端中的渲染（粗体颜色、选择）。
脚本写入不透明背景。半透明背景会让桌面透出，降低文本可读性。
Terminal 没有用于选中文本或光标下文本的颜色。门控改为检查选择背景上的文本和光标上的文本。
.terminal 颜色格式见 references/terminal-format.md。在 Mac 上，文件嵌入 sRGB ICC 配置文件。在其他系统上，它们仅包含 sRGB 颜色空间 ID（解码方式相同）。
scripts/verify_terminal.swift（仅限 Mac）使用 AppKit 解码每种颜色： swiftc -O scripts/verify_terminal.swift -o scripts/verify_terminal，然后 scripts/verify_terminal --register-terminal-fonts "<file>.terminal"。

设计系统转 Apple Terminal 主题