Pierre 主题变体（Theme Variants）完整指南：Standard、Soft、Vibrant 与色觉障碍（CVD）变体的选型与使用

Pierre 主题包（@pierre/theme）为 Shiki、VS Code、Cursor 与 Zed 提供了十个不可变的主题对象，它们按“五种处理方式（treatment）× 明暗双色（light/dark）”组织成五对变体。本文以 skills/theme/references/variants.md 为核心骨架，深入讲解每一种变体的适用场景、底层实现原理（色板、角色映射、Display-P3 与 CVD 模拟），并给出在 Shiki 与编辑器中落地使用的完整方法，帮助你为自己的产品选出正确且成对使用的 Pierre 主题。

一、变体总览：五种处理方式与十款主题

Pierre 主题包一共交付10 个主题对象，它们并非十个彼此独立的设计，而是5 种“处理方式”（treatment）各自成对：

选择与配对的核心规则：

1. 选择一个处理方式，并将其浅色与深色条目作为一对使用——不要混搭，例如不要同时使用pierre-light与pierre-dark-soft。
2. 除非产品明确指定其他处理方式，否则使用标准（Standard）对。
3. 明暗两套配色必须使用同一种处理方式，以保证界面在切换深浅色时风格一致。

包内所有主题的完整清单、默认导出与字段结构见 skills/theme/references/api.md；主题对象可通过themeNames（主入口导出）按包内顺序列出全部 10 个名称。

二、Standard 与 Soft：默认外观与低对比度外观

2.1 Standard（标准）

pierre-light/pierre-dark是 Pierre 的默认外观，也是主题包内绝大多数角色映射的“基准设计”。从源码结构看，两套标准主题分别由 src/roles/light.ts 与 src/roles/dark.ts 中定义的Roles对象驱动，并通过统一的 src/createTheme.ts 组装为完整 VS Code 主题对象。

Roles类型（见 src/roles/Roles.ts）把一套主题拆解为六类角色：

• bg：编辑器背景（editor）、窗口背景（window）、内嵌控件背景（inset）、浮层背景（elevated）；
• fg：基础前景与fg1–fg4五级前景灰度；
• border：窗口、编辑器、缩进引导线、内嵌控件、浮层的边框；
• accent：强调色primary、链接色link、弱化强调subtle、强调色上的对比前景contrastOnAccent；
• states：合并、成功、危险、警告、信息五种状态色；
• syntax：注释、字符串、数字、关键字、正则、函数、类型、变量等 18 类语法 token 色；
• ansi：终端 16 色（8 标准色 + 8 亮色）。

2.2 Soft（柔和 / 低对比度）

pierre-light-soft/pierre-dark-soft在同一套色板体系内降低整体对比度，适合希望减弱视觉冲击、长时间阅读的场景。以 src/roles/lightSoft.ts 为例，Soft 浅色版的关键特征是：

• 背景全部落在中性色neutral刻度的高亮端（编辑器纯白#ffffff，窗口neutral['040']，内嵌neutral['060']，浮层neutral['020']）；
• 前景与边框整体下移一档（基础前景为neutral['800']，边框为neutral['080']–neutral['200']），从而比 Standard 更柔和；
• 语义色与语法色仍复用同一套 21 色色板（见下文），保证“家族一致性”。

Standard 与 Soft 共用neutral中性刻度；src/palettes.ts 中保留了一份gray刻度仅作为参考色板，源码注释明确说明它不用于任何内置角色，四个变体（Standard、Soft 及两个 CVD 变体）全部使用neutral。

三、Vibrant：面向 Shiki 与网页的 Display-P3 输出

pierre-light-vibrant/pierre-dark-vibrant是专为Shiki 语法高亮或网页输出设计的变体，其颜色使用 CSScolor(display-p3 r g b)语法书写，以充分利用 Display-P3 广色域。编辑器扩展中不包含这两款——src/color/p3.ts 的注释明确说明：VS Code 仅支持 hex/RGB 颜色格式，因此 Vibrant 主题在 VS Code 中无法使用（详见 DISPLAY-P3.md）。

3.1 色域转换与增强算法

从源码看，srgbHexToP3Color()（src/color/p3.ts）的转换流程为：

1. 解析 sRGB hex → RGB（0–1 范围）；
2. 通过srgbToLinear线性化（去 gamma）；
3. 用线性 sRGB → 线性 P3 矩阵变换（Display-P3 与 sRGB 使用相同的传输函数）：

R_p3 = 0.82246197 * R_srgb + 0.17753803 * G_srgb G_p3 = 0.03319420 * R_srgb + 0.96680580 * G_srgb B_p3 = 0.01708263 * R_srgb + 0.07239744 * G_srgb + 0.91051993 * B_srgb

4. 施加 P3 gamma 后，再执行色域增强（enhanceForP3Gamut）：饱和度提升15%–30%（0.15 + s * 0.15，随原始饱和度变化）；对高饱和中调颜色（s > 0.5且l < 0.7）亮度再提升约5%；灰色与接近黑/白的颜色（s < 0.1或l < 0.1或l > 0.9）保持不动。

这种“先转换、再有选择地增强”的做法，与单纯的数学空间变换不同：它把颜色真正推入 sRGB 无法表达的 P3 区域，同时保证灰阶、黑、白保持准确，在非 P3 浏览器上也能优雅降级。

3.2 在 Shiki 中使用 Vibrant

在网页项目中使用 Vibrant 变体的完整方式见 skills/theme/references/recipe-shiki.md：

pnpm add @pierre/theme shiki

import pierreDarkVibrant from '@pierre/theme/pierre-dark-vibrant'; import { codeToHtml } from 'shiki'; const html = await codeToHtml(source, { lang: 'typescript', theme: pierreDarkVibrant, });

若应用同时支持明暗两种配色，应同时导入匹配的明暗一对；若允许用户在运行时切换主题，则应使用themingskill 的运行时主题方案。

四、CVD 变体：为色觉障碍人群工程化设计的主题

四种 CVD 主题（红绿色觉障碍 × 明暗、蓝黄色觉障碍 × 明暗）是 Pierre 主题包中最有技术含量的一组。它们并非简单的“换色”，而是基于色觉缺陷生理模型重新映射了全部语义与语法颜色，详见 ACCESSIBILITY.md。

4.1 背景：三种二色性色觉缺陷

视网膜通过 L（长波/红）、M（中波/绿）、S（短波/蓝）三种视锥感知颜色。当某一种视锥缺失或偏移时，主要沿该视锥轴区分的颜色会坍缩为同一种感知色：

注意：Tritanopia 常被粗略称为“蓝黄色盲”，但蓝与黄在亮度上差异很大（亮度通道是保留的），真正坍缩的配对是蓝 ↔ 绿。

对代码编辑器而言最致命的是：普通主题把最重要的信号——新增 vs 删除、通过 vs 失败、错误 vs 警告——编码为红 vs 绿，而红绿色盲（最常见的 CVD）看红绿几乎相同。

4.2 工程化设计的四条原则

1. 相同的“壳”＝家族一致性：每个 CVD 主题原样复用基础light/dark的bg、fg、border角色，窗口、文本与边框与 Pierre Light/Dark 逐像素一致，只改accent、states、syntax、ansi等彩色角色。
2. 信号搭载在保留的轴上：
   • Protan/Deutan：正向/新增 →蓝，负向/删除 →橙；
   • Tritan：正向/新增 →teal/青，负向/删除 →红/朱红（vermillion）。
3. 亮度作为备份通道：二色性色觉下只有约 2 个可用色相极 + 亮度，却有约 20 个彩色角色；当两个角色必须共用同一色相极时（如多个“冷色”语法 token），用**不同色板刻度（亮度）**分离。
4. 复用既有色板：所有颜色都来自 src/palettes.ts 中已有的刻度（blue、orange、teal、vermillion、magenta等），不发明偏离品牌的新色相。

4.3 角色映射示例（源码可验证）

以 src/roles/protanDeutanLight.ts 与 src/roles/tritanopiaLight.ts 为代表的角色映射（ACCESSIBILITY.md 中的表格）：

Protan/Deutan —— 轴：蓝 ↔ 橙

Tritanopia —— 轴：红 ↔ 青/teal

4.4 客观测试门禁：不靠猜，靠模拟

CVD 主题的可靠性由模拟 + 量化指标保证，而非主观判断：

• src/color/cvd.ts 实现了 Machado, Oliveira & Fernandes (2009) 的生理学模拟模型，对 protan/deutan/tritan 三种二色性分别嵌入 11 个严重度（0.0 正常视觉 → 1.0 完全二色性）的 3×3 矩阵；主题在严重度 1.0（最坏情况）下被门禁校验，因此对较轻的异常三色视也兼容。模拟在线性 RGB中执行，同时test/cvd.test.ts额外用 culori 的 gamma-sRGB 约定交叉核对 Tier-1/Tier-2 的可区分性。
• 模型自带自检（cvdSelfChecks）：severity-0 恒等、中性灰轴保持（每行矩阵行和 ≈ 1）、以及“被混淆的轴确实坍缩”（protan/deutan 下红绿 ΔE 至少减半；tritan 下蓝绿 ΔE 至少减半）。
• packages/theme/test/cvd.test.ts 是客观门禁：对每种缺陷分别在线性 RGB 与 gamma-sRGB 两种约定下模拟每个彩色角色，若任何“必须可区分”的配对不再可区分（CIEDE2000 ΔE）或不可读（WCAG 对比度），构建即失败。

门禁分为三个层级：Tier-1（ΔE ≥ 11，颜色是唯一线索的 diff 增删背景/文本、合并冲突背景、终端红绿）、Tier-2（ΔE ≥ 8，诊断信息与核心语法，有色觉之外的非颜色线索）、Tier-3（仅报告不阻断，git 树与扩展语法，有字母徽章与粗斜体兜底）。对比度方面，正文文本要求4.5:1，语法 token 与语义信号色要求3:1（模拟前后均检查）；品牌蓝、警告黄等固有高亮度颜色仅报告其可区分性而不要求原始对比度。

五、编辑器扩展：包含哪些变体

编辑器扩展（VS Code / Cursor / Zed）包含 8 个 sRGB 主题：标准、柔和（Soft）、protanopia+deuteranopia、tritanopia 四种处理方式 × 明暗。Vibrant 不在其中——从 packages/theme/package.json 的contributes.themes可以看到，VS Code 扩展声明了 8 个主题条目（如Pierre Light、Pierre Light Soft、Pierre Dark Protanopia & Deuteranopia等），全部指向themes/*.json文件。

安装方式（见 skills/theme/references/recipe-editor.md）：

• VS Code / Cursor：从扩展市场安装Pierre Theme扩展 → 打开颜色主题选择器 → 选择Pierre主题；
• Zed：从 Zed 扩展注册表安装Pierre扩展 → 打开主题选择器 → 选择Pierre主题。

六、源码产物：JSON 主题文件与不可变主题对象

• 原始 JSON：@pierre/theme/themes/*暴露每个生成的 JSON 文件（含.json后缀），仓库中对应 packages/theme/themes/ 下的 10 个文件（如pierre-dark.json、pierre-dark-soft.json、pierre-dark-vibrant.json等）。
• 不可变对象：每个具名入口（如@pierre/theme/pierre-dark）默认导出一个不可变主题对象，字段为name（稳定标识）、displayName（主题选择器标签）、type（light/dark）、colors（VS Code 工作台颜色键映射）、tokenColors（TextMate token 样式）、semanticTokenColors（语义 token 样式）——这些字段正是 src/createTheme.ts 中VSCodeTheme类型定义的形状。
• 包元数据：@pierre/theme声明sideEffects: false，适合摇树优化；其exports为每个主题提供独立的子路径入口（./pierre-light、./pierre-dark-vibrant等），便于按需导入单一主题。

七、实战选型建议

综合 variants.md 的规则与源码实现，给出如下选型决策路径：

1. 默认选择：除非产品有明确要求，一律使用 Standard 对（pierre-light+pierre-dark）。
2. 界面偏柔和：使用 Soft 对，二者共用neutral刻度，与 Standard 保持同一家族风格。
3. Web/Shiki 且追求广色域表现：使用 Vibrant 对，注意它只在支持 CSS Display-P3 的浏览器/显示器上发挥优势，且不能用于编辑器扩展。
4. 无障碍需求：若产品面向色觉障碍用户或需要满足无障碍合规，按目标人群选择 CVD 变体——红绿色觉障碍用 protanopia-deuteranopia 对，蓝黄色觉障碍用 tritanopia 对；这些变体的“壳”与 Standard 逐像素一致，切换成本最低。
5. 无论选哪一种，明暗两套始终成对使用同一种处理方式，避免深浅色切换时风格漂移。

若应用需要在运行时跟随系统色模式切换主题，或在运行时动态切换主题，请进一步参考themingskill 的运行时主题方案（见 skills/theme/SKILL.md）。