用 Claude Code 设计 CSS 变量和主题 token

先定义问题边界

用 Claude Code 设计 CSS 变量和主题 token，重点不是让 Claude Code 生成一段看起来很酷的代码，而是把交互、布局、可访问性、移动端和商业目标放在同一张检查清单里。初学者最容易犯的错，是只看桌面截图，不看键盘操作、长文本、空数据、广告区域和 CTA 是否仍然清楚。

CSS 变量，准确来说叫 CSS 自定义属性。你像 --color-accent 这样自己起名定义一个值，再用 var(--color-accent) 在别的声明里引用它。用通俗的话讲，就是给颜色、间距、圆角、阴影、字号建立一个“带名字的存放位置”。把这个存放位置先定好，Claude Code 生成的 CSS 就不容易散乱，能减少“只有按钮是蓝的、只有卡片阴影略不同、只有深色模式文字偏淡”这类事故。

按下面这个顺序来想，结构就不会崩：调色板 token（如 --blue-600 这种原始颜色或数值）、语义 token（如 --color-accent 这种带含义的值）、组件 token（如 --button-bg 这种部件级别的覆盖）、状态 token（dark、danger、compact 等按情况替换的值）。

建议一起阅读 claude code dark mode implementation, claude code design tokens, claude code design system。官方资料参考 MDN CSS custom properties, MDN var(), MDN prefers-color-scheme。给 Claude Code 的指令要写清楚目标、禁止改动的范围、需要保留的设计规则、以及上线前必须检查的 use case 和 pitfall。

Claude Code 提示词

请用最小安全改动实现这个 UI 改善。
保留现有路由、组件结构、设计 token 和主要 CTA。
请给出可复制运行的代码、use case、pitfall、移动端检查和回滚方法。
最后用 review checklist 列出需要人工确认的点。

如果只甩一句“用 CSS 变量”，Claude Code 往往会选外观上的捷径。最好一开始就指定：把什么 token 化、允许覆盖到哪一层、是否必须加 fallback。这里说的“token”就是给设计上的值起个名字——不要到处直接写 #2563eb，而是当作 --color-accent 来用，这样以后改品牌色，需要改动的地方就很小。

适用场景清单

1. 内容站：让读者更快找到下一步，例如相关文章、搜索、咨询按钮或下载入口。正文、卡片、按钮、警告框都用同一个 --color-accent，每次活动改色只要一行；广告或 Gumroad 导线做 AB 测试时，不动整套 CSS 就能改外观。
2. SaaS 管理画面：让操作路径更短，同时保留键盘、移动端和错误状态。按部门各自做画面，灰度和间距会一点点跑偏；共享 --surface、--border、--space-*，Claude Code 生成新画面时就容易贴近既有 UI。
3. 商品页：视觉改善不能遮挡价格、购买按钮、广告或表单。也适合白标和按客户定制品牌：客户 A 用蓝、客户 B 用绿、内部环境用灰，靠 data-brand="customer-a" 只替换 token，不复制组件代码，维护成本就不容易上升。
4. 团队开发：Claude Code 输出代码后，还要输出 review checklist，方便别人复核。把高对比主题、较大间距、易读字号拆成 token，也更容易把可访问性的审查要点落到 CSS 上。

实现示例

:root {
  --color-page: #ffffff;
  --color-text: #111827;
  --color-muted: #4b5563;
  --color-accent: #2563eb;
  --space-page: clamp(1rem, 3vw, 2rem);
}

[data-theme="dark"] {
  --color-page: #0b1120;
  --color-text: #f8fafc;
  --color-muted: #cbd5e1;
  --color-accent: #93c5fd;
}

body {
  background: var(--color-page, white);
  color: var(--color-text, black);
  padding-inline: var(--space-page, 1rem);
}

a {
  color: var(--color-accent, blue);
}

const root = document.documentElement;
const stored = localStorage.getItem("theme");
const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
root.dataset.theme = stored || (prefersDark ? "dark" : "light");

这段代码的要点在于：var() 的第二个参数是 fallback。比如 var(--color-page, white)，当 --color-page 未定义或拿到不可用的值时，就退回用 white。公开页面里务必养成加 fallback 的习惯——写了 color: var(--text-primary); 却漏了定义，这条声明就不会如预期生效，加上 color: var(--text-primary, #111827); 这种保险更稳妥。prefers-color-scheme 则是参照用户操作系统或浏览器设置的媒体特性；想让手动切换优先，就像上面这样把 data-theme 加在 html 元素上做覆盖。

陷阱清单

• 不要只针对漂亮截图优化。必须检查真实用户路径。
• 不要让长文本、代码块或表格撑出横向滚动。
• 不要只用颜色表达状态，必须保留文字、焦点和辅助说明。
• 不要让 Claude Code 顺手重构无关文件，否则 review 成本会变高。
• 不要忘记移动端 375px、键盘操作、慢网络和错误状态。
• 不要搞错自定义属性名的大小写。--main-color 和 --Main-color 是两个不同的东西。给 Claude Code 明确“命名用小写、单词用连字符分隔”，可以减少写法不一致。
• 不要试图把 CSS 变量用在媒体查询条件或属性名上。@media (min-width: var(--breakpoint-md)) 这种写法不会按预期工作；变量基本上只用在“属性的值”上。
• 不要在 JavaScript 里把用户输入直接 setProperty()。即便是取值范围固定的颜色选择器，也最好用 CSS.supports() 先验证一下。
• 不要忘记深色模式下的阴影和边框。只改背景和文字色，留下浅色边框或黑色阴影，UI 就会显得浑浊；--border 和 --shadow-card 也要按主题分别检查。

验证方法

先运行 build，再在浏览器移动端宽度确认没有横向溢出。检查代码块是否能滚动、CTA 是否仍然可见、表单和广告位是否没有被遮挡。让 Claude Code 再做一次只读 review，列出改动文件、风险、可删除代码和回滚方法。具体可以让它批判性地检查这些点：没有 fallback 的未定义自定义属性、浅色与深色的对比度问题、绕过 token 直接改值的组件变体、:root 之外重复出现的原始颜色、没有验证的 setProperty 调用、固定间距 token 导致的移动端溢出，并按“文件名、选择器、风险、建议修复”输出结论。

商业化视角

这个主题直接影响广告可见率、咨询按钮、商品卡、价格表和 lead form。CSS 变量不是“换个颜色”的小技巧，而是为了长期运维 UI 的设计部件：按调色板、语义、组件、状态四层拆 token，从一开始就放进 var() fallback 和深色模式，Claude Code 生成的 CSS 质量才稳定，CTA 卡片也更不容易在改色时崩掉。想把这种 UI 改善变成团队流程，可以从 Claude Code 培训与咨询 开始，把实现、review、发布检查固定下来。

追加检查

每次发布前，把屏幕截图、键盘操作、移动端宽度、慢网络、错误状态和 CTA 位置放在同一张清单里。这样 Claude Code 的输出不会只停留在代码层面，而会连接到实际业务结果。不要害怕让 Claude Code 删除自己刚写的代码，能删掉的复杂度就是收益。

实测记录

这套做法，我在文章页面和管理画面两边都验证过，一边盯着手机宽度、代码块、CTA 和键盘操作一边确认。把实现和审查分开交给 Claude Code，差分会更小，质量也更稳定。实际试下来，CTA 卡片和正文的改色只靠替换 --color-accent 就搞定了，深色模式下边框漏改的问题也更容易在审查指令里被发现。尤其是只要定下“不把原始颜色直接写进组件”这一条，Claude Code 的修改差分就变得相当好读。