applying-themes

应用主题

概述

主题是一套完整的语义令牌，而不是一组好看的颜色。四个没有定义用途的十六进制值会产生不一致的结果，因为每个组件都得自行判断哪个是文本颜色、哪个是背景颜色。

**核心原则：**每个主题都解析为相同的八个令牌。组件引用令牌名称，而不是十六进制值。切换主题时，只需替换一个代码块。

base  surface  line  ink  ink-2  ink-3  accent  accent-ink

铁律

NO THEME APPLIED WITHOUT ITS CONTRAST VERIFIED

配色方案看起来不错，却达不到 4.5:1 对比度，就无法使用；而且对比度不能靠肉眼判断——中间调的强调色搭配中间调的表面色时，常常会在看起来没问题的情况下未达标。每个内置主题都附带可通过机器检查的 contrast 代码块。自定义主题在使用前也要经过同样的检查。

检查清单

1. 展示主题——使用下表，并说明每个主题的用途
2. 明确征求选择——不要擅自决定
3. 读取主题文件——themes/<name>.md 是唯一准确信息来源
4. 验证对比度——运行检查器；自定义主题必须执行此步骤
5. 输出令牌代码块——在制品顶部输出一次
6. 按令牌名称应用——组件中不得出现原始十六进制值
7. 检查渲染结果——查看输出，尤其是次要文本

主题

主题	风格特点	基础色调	最适合
ocean-depths	深邃沉静的海洋风格	深色	金融、咨询、基础设施
sunset-boulevard	金色时刻的温暖感	浅色	创意、发布活动、酒店与餐饮
forest-canopy	沉稳的土色调	浅色	可持续发展、手工艺、长篇内容
modern-minimalist	严谨的灰度风格	浅色	文档、作品集、系统
golden-hour	丰富的琥珀色调	浅色	评论、美食、回顾
arctic-frost	冷冽、清晰的临床风格	浅色	医疗、分析、合规
desert-rose	雅致的灰粉风格	浅色	精品店、邀请函、健康养生
tech-innovation	高对比度终端风格	深色	开发工具、AI、更新日志、状态页面
botanical-garden	精心培育、生机盎然	浅色	美食、农业、社区
midnight-galaxy	深空般的戏剧感	深色	发布活动、娱乐、主题演讲

每个 themes/<name>.md 都包含完整配色及其用途、对比度要求、网页字体搭配与度量安全的 PDF 后备字体、比例尺比率，以及主题误用时会出现的问题说明。

theme-showcase.pdf 是此技能早期版本遗留的视觉示例，其中的颜色和字体已不再与主题文件相符。Markdown 文件才是权威来源。不要将该 PDF 作为准确预览展示。

展示与选择

展示表格，询问一次，然后等待。未经明确选择，不要应用主题——用错误的配色重新设计整套演示文稿，浪费的时间远多于提问所需的时间。

如果用户描述需求而没有指定主题（例如“适合董事会演示文稿的严肃风格”），就推荐两个主题，各用一句话说明理由，然后让用户选择。

验证对比度

source ~/.local/opencode-venv/bin/activate

python3 scripts/check_contrast.py themes/ocean-depths.md   # one theme
python3 scripts/check_contrast.py themes/*.md              # all of them
python3 scripts/check_contrast.py --pair "#8a7357" "#fbf5ea"   # ad-hoc pair

只要有一项检查失败，退出码就会非零，因此可以将其用作门槛。所有十个内置主题均通过了全部六项检查。

应用

HTML / CSS

在 :root 中输出一次令牌代码块，之后只引用令牌。

:root {
  --base: #0f1c26; --surface: #16283a; --line: #2d4859;
  --ink: #eef6f8; --ink-2: #accad4; --ink-3: #8aa7b3;
  --accent: #4fd1c5; --accent-ink: #04222a;
  --font-display: "Young Serif", Georgia, serif;
  --font-text: "IBM Plex Sans", system-ui, sans-serif;
}
body   { background: var(--base); color: var(--ink); font-family: var(--font-text); }
h1, h2 { font-family: var(--font-display); }
.card  { background: var(--surface); border: 1px solid var(--line); }
.meta  { color: var(--ink-3); }
.btn   { background: var(--accent); color: var(--accent-ink); }

**:root 之外不得出现原始十六进制值。**完成前，在组件样式中搜索 #——任何遗漏的十六进制值都会导致主题无法切换。

两种配色方案

如果制品必须同时适用于浅色和深色模式，请选择一个浅色主题和一个深色主题，并将它们映射到相同的令牌名称：

:root { /* forest-canopy tokens */ }
@media (prefers-color-scheme: dark) { :root { /* ocean-depths tokens */ } }
:root[data-theme="dark"]  { /* ocean-depths tokens */ }
:root[data-theme="light"] { /* forest-canopy tokens */ }

媒体查询和显式属性两者都要设置——如果切换开关无法在两个方向上覆盖操作系统偏好设置，那它就是有问题的。

PDF 和幻灯片

使用主题排版表中的 PDF / 幻灯片 列。PDF 渲染器通常无法使用 Web 字体，而缺失的字体会被静默替换为字形度量不同的字体，从而破坏所有基于原字体设计的布局。

from reportlab.lib.colors import HexColor
from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.ttfonts import TTFont

BASE, SURFACE, LINE = HexColor("#f7f6f0"), HexColor("#fffffb"), HexColor("#dcded1")
INK, INK2, INK3     = HexColor("#1a271a"), HexColor("#4a5a46"), HexColor("#79876f")
ACCENT, ACCENT_INK  = HexColor("#2f6b3c"), HexColor("#f4fbf5")

# Bundled open-licensed faces from the designing-canvas-art skill
pdfmetrics.registerFont(TTFont("Display", "../designing-canvas-art/canvas-fonts/YoungSerif-Regular.ttf"))
pdfmetrics.registerFont(TTFont("Text",    "../designing-canvas-art/canvas-fonts/WorkSans-Regular.ttf"))

ink-3 是最容易在打印中出问题的令牌——许多打印机和投影仪都会压缩浅色部分。在明亮环境中投影幻灯片时，凡是观众必须读到的内容都应使用 ink-2。

React

export const theme = {
  base: "#0f1c26", surface: "#16283a", line: "#2d4859",
  ink: "#eef6f8", ink2: "#accad4", ink3: "#8aa7b3",
  accent: "#4fd1c5", accentInk: "#04222a",
};

对于 Tailwind，请将令牌映射到 theme.extend.colors，让实用类体现其语义：bg-base、text-ink-2、border-line。

构建自定义主题

如果没有合适的内置主题，请构建一个，而不是随意挑选颜色。

1. 用两个词确定方向，并指定一个现实世界的参考对象。“海岸测绘——1970 年代的航海图”能引出一套配色；“现代且简洁”只会得到默认配色。
2. 选择色相策略——单色、类似色、互补色，或中性色加点缀色。选定一种并坚持使用。
3. 通过添加色调构建中性色，切勿使用纯灰色。在每种中性色中混入 4-8% 的强调色，让整个调色板浑然一体。
4. 从强调色的色相推导 ink，使用极低的色度和极低的亮度——这正是让调色板显得经过设计，而非拼凑而成的关键。
5. 必要时设置两种强调色值：一种明亮值用于填充，一种较暗值用于文本。一个值很少能同时胜任两者。
6. 在 themes/ 中编写文件，以现有文件为模板，并包含 contrast 块。
7. 运行检查器。 调整亮度，直至通过。不要发布检查未通过的自定义主题。
8. 向用户展示调色板和一个渲染示例，再将其应用到整个作品中。

关于底层色彩理论——OKLCH 构建、色阶生成、深色模式规则——请参阅 designing-frontend-interfaces/references/color-and-theme.md。

常见错误

未经询问就应用主题。 将用户没有选择的调色板应用到已完成的演示文稿中重新设置样式，比不应用主题更糟糕。

在组件中直接使用十六进制颜色。 :root 块明明已经存在，Card.css 中却仍写着 #16283a。主题因此无法切换。

将 ink-3 用于正文。 它满足的是 3:1，而不是 4.5:1。它仅适用于大字号的说明文字和元数据。

将强调色同时用于大面积填充和小字号文本。 适合填充的亮度几乎从来不够深，无法用于文本。请使用两个色阶。

在 PDF 流程中使用 Web 字体。 字体会被静默替换，破坏所有布局。请使用度量安全列。

为了“丰富变化”添加第二种强调色。 来自不同色相族的两种高饱和度强调色会让作品显得像是拼凑出来的。如果确实需要第二种颜色，请从 ink 色阶中选取。

深色主题中阴影保持不变。 阴影在深色背景上不可见。深色模式下的层次感来自更亮的表面，而不是更暗的阴影。

只检查一种模式下的对比度。 浅色模式通过了，并不能说明深色模式也没问题。