1. 项目概述“Claude-Red”这个名字第一眼看上去像是某个模型代号其实这是我最近用 AI 辅助开发的一个前端主题设计系统的项目代号。简单来说它是一套以红色作为主视觉基调的组件样式体系配合 Claude 生成代码、设计令牌以及主题切换能力最终形成一套可以直接投入生产使用的 React 组件库。这个项目解决的痛点很直接前端项目里颜色管理最容易失控。开发时随手写死一个#f00设计稿和实际页面差了三个色号加暗色模式时又得全量排查久而久之主题系统变成了一坨没人敢动的“屎山”。Claude-Red 的目标就是把颜色的定义、计算、切换和组件消费整个链路梳理清楚同时借助 Claude 的代码生成能力把重复性工作压缩到最低。适合正在做前端工程化、组件库建设或者被多主题适配折腾到头秃的同学参考。如果你对“用 AI 写代码”的理解还停留在“让它生成一个按钮”的阶段那这篇文章会给你展示一条更务实的路线AI 负责产出一版能跑通的基础实现人负责设计约束、边界审查和细节修正。这套流程跑下来我对 Claude 在真实工程中的定位有了新的判断——它不是替代工程师而是把工程师从低级重复里解放出来。2. 核心设计思路与方案拆解2.1 为什么选红色作为主题色做主题系统第一个问题永远是用什么色相做主视觉我把候选色卡铺开对比之后最终锁定了红色系。原因不只是视觉冲击力更在于红色这个色相跨度极大——从深褐红到亮珊瑚红色阶可以做得非常宽。这种特性让红色主题天然具备层次感主按钮可以高饱和背景可以低饱和危险提示可以深红点缀可以亮红。一个色相就能撑起整个语义体系不需要多个色相来回切。但红色也是最难驾驭的颜色之一。用不好就会让整个界面显得廉价、刺眼、压抑。所以 Claude-Red 的核心工作就是在色阶的“度”上做文章明亮度低了看不清高了刺眼饱和度低了发灰高了廉价。这些细微的权衡恰好是 Claude 最擅长从大量现有设计系统里归纳规律的地方。2.2 技术选型为什么是 React CSS 变量技术栈上我选了 React TypeScript Vite样式部分用原生 CSS 变量没有引入 Tailwind 或者 styled-components。选择背后的逻辑很简单主题系统的第一诉求是运行时切换轻量CSS 变量天然支持运行时覆盖浏览器原生能力就能搞定。引入 Tailwind 的话主题色必须做成配置项二次封装反而繁琐。styled-components 当然也能做主题但 TypeScript 泛型推导和 SSR 场景下要处理的问题更多对一个小型组件库来说引入成本偏高。CSS 变量的另一个好处是兼容性极佳现代浏览器全部支持和 Web Components、微前端这类架构也能和平共存。Claude-Red 的组件消费样式时只读取变量名不关心变量值是怎么换的。这意味着未来要把这套主题接入设计稿工具、甚至导出给小程序端都预留了空间。Claude 在这阶段的参与方式是我把我倾向的技术选型、项目约束和设计规范它让它生成初始化代码和一版设计令牌。之后我再逐项调整把 Claude 输出的结果从“能用”打磨到“好用”。这一点后面实操章节会详细展开。2.3 整体架构令牌、组件、消费者三层模型Claude-Red 的架构分层参考的是我在多个设计系统项目里沉淀下来的三层模型最底层是设计令牌Design Tokens定义颜色、间距、圆角、阴影、字体等基础变量用 CSS 自定义属性的形式挂在:root上。中间层是主题适配层负责不同主题下变量值的切换包括亮色主题、暗色主题以及未来的品牌定制主题核心是>:root { --color-primary: var(--clr-red-600); --color-primary-hover: var(--clr-red-700); --color-primary-subtle: var(--clr-red-100); --color-text-on-primary: var(--clr-base-white); }这样做的可维护性收益是质变级的。哪天要换品牌色只需要改语义令牌的映射关系组件层的 CSS 代码一行都不用动。暗色模式也是这样只是把映射表整体换一套值。Claude 在我的提示词里被要求严格遵守这层语义化规范生成按钮组件时只准用--color-primary如果它输出var(--clr-red-600)我会直接把这个 PR 打回去。现在回看这个约束是 Claude-Red 整体设计能保持干净的头号功臣。4. 实操过程Claude 辅助从零构建主题系统4.1 项目初始化与基础文件结构环境搭建部分不需要重复造轮子。我用 Vite 的 React-TS 模板初始化项目然后把目录结构按三层模型组织好claude-red/ ├── src/ │ ├── tokens/ # 设计令牌定义 │ │ ├── primitive.css │ │ └── semantic.css │ ├── themes/ # 主题适配层 │ │ ├── light.css │ │ └── dark.css │ ├── components/ # 组件层 │ │ ├── Button/ │ │ ├── Badge/ │ │ └── Alert/ │ └── styles/ │ └── global.css # 全局样式这个结构看起来很简洁但每一层的职责边界必须定义清楚不然 Claude 在生成代码时容易把样式到处乱塞。我在提示词里明确了规则tokens目录只允许出现变量定义themes目录只允许出现主题级的变量覆盖components目录里每个组件自带一个 css 文件只引用语义令牌。其中一个值得展开的小细节是Claude 在生成primitive.css时会自动给色阶加上 CSS 变量名效果不错但它会顺手把注释写得过于详尽比如“这是主色用于主要操作按钮和强调文本”这种。这类注释在语义令牌里是合理的但在原始色阶层写操作语义就错了因为原始色阶本身不和业务语义挂钩。我会把这类注释清理掉避免后面维护的人被误导以为clr-red-500就是品牌红色。4.2 用 Claude 生成基础组件Button 为例项目骨架搭好之后我挑 Button 组件作为第一个生成的试验品。给 Claude 的提示词大致是这个思路你是资深前端工程师。请帮我生成一个 React TypeScript 的 Button 组件要求 1. 样式使用 CSS Modules颜色只允许引用语义令牌变量 2. 支持 variantprimary / secondary / ghost / danger 3. 支持 sizesm / md / lg 4. 需要处理 loading、disabled 状态 5. 提供 focus-visible 的可见焦点样式 6. 不许在 css 中出现十六进制色值Claude 的初稿完成度相当高组件 Props 的类型定义、基本样式逻辑都写对了。需要我手改的问题主要有这几个第一Claude 生成的 loading 状态没有处理“加载时禁止重复点击”的问题我把按钮内联了一个>.button:focus-visible { outline: 2px solid var(--color-focus-ring); outline-offset: 2px; }--color-focus-ring我专门定了一个带透明度的红色变量这样跳过键盘焦点的人不会看到样式键盘用户也能获得清晰的焦点指示。这几个修正单拎出来都很小但组合起来就体现了人和 AI 协作的正确姿势AI 负责把七十分的骨架快速搭出来人负责从可访问性、边界条件和设计意图的角度做打磨把七十分推到九十分以上。4.3 暗色主题适配解析Claude-Red 的主题系统支持亮色和暗色两套模式。实现方式不复杂给html根元素加>:root[data-themedark] { --color-bg-body: #1A1414; --color-bg-surface: #241C1C; --color-text-default: #F5E6E6; --color-text-secondary: #C9A8A8; --color-primary: var(--clr-red-500); --color-primary-hover: var(--clr-red-400); --color-primary-subtle: var(--clr-red-900); }暗色主题下我把主色从 600 档提升到了 500 档因为深色背景上同样色相的颜色会显得更暗需要整体提亮一档才能保持视觉上的重量感。这个细节如果不用心调很容易出现“暗色模式下按钮像被糊了一层灰”的效果。暗色模式下另一个常见的坑是阴影。亮色模式下阴影用rgba(0, 0, 0, 0.1)很自然暗色模式下黑色阴影几乎是不可见的。我在全局样式中定义了一组基于背景色明度的阴影变量暗色模式用色相偏红的深色阴影加一层内边框来模拟层次感。Claude 初稿没有这个意识这些细节还是靠人工经验去补。4.4 主题切换的闪烁问题与解决方案暗色模式做好了但主题切换时还有一个很容易被忽略的问题页面刷新瞬间的白屏闪烁FOUC。如果主题值存在 localStorage 里页面加载时 JavaScript 还没执行完CSS 就会先用默认的亮色主题渲染一帧然后 JavaScript 再去切换视觉上画面闪了一下体验相当割裂在暗色模式用户那里尤其明显。这个问题的标准解法是把主题初始化的脚本放到index.html的head里内联执行在浏览器渲染任何内容之前就把>script (function() { var theme localStorage.getItem(claude-red-theme) || light; document.documentElement.setAttribute(data-theme, theme); })(); /script这样页面第一帧就是用正确主题渲染的闪烁问题直接消失。这段脚本是 Claude 主动给的方案我当时还有点意外因为这种脱胎于实际经验的优化点不是单纯的“代码生成”能覆盖的。这让我对“AI 辅助工程化”这件事有了新的认知只要给够上下文Claude 能把真实工程中踩过的坑变成解决方案但前提是提问的人知道这个问题的存在。如果完全不了解 FOUC连向 AI 提问的入口都没有。5. 完整实操流程实录5.1 需求拆解与提示词闭环把这套流程整理成可以复用的方法论对我个人来说比组件本身价值更大。Claude-Red 的每个模块我都是用同一个四步循环走完的拆解需求边界、写清楚约束提示词、让 Claude 产出初稿、人工审查修正。以模态框组件为例。我的需求拆解结果是模态框至少要处理打开关闭的过渡动画、点击遮罩关闭、Esc 键关闭、内容滚动锁定、可访问性属性roledialog、aria-modaltrue、以及服务端渲染时不能直接访问 document。这些约束在提示词里要一次性说清否则 Claude 生成的初稿会在 SSR 环境下直接跑崩。写提示词还有一个技巧给 Claude 看一段正面的参考代码比纯粹的文字描述效果好得多。我会先自己写一个最简单的 Badge 组件作为范本让 Claude 模仿它的风格去实现其他组件。这比让它凭空发挥稳定得多生成的代码风格一致性也更好后续维护起来不用在一堆风格迥异的文件里反复横跳。5.2 关键参数的计算校验过程在主题令牌构建的过程中我维护了一组核心参数。下面这张表记录了 Claude-Red 最关键的几个色值与它的核心用途每个值都跑过对比度校验令牌名色值核心用途与正文白的对比度--clr-red-500#E53935暗色主按钮背景3.9:1--clr-red-600#C62828亮色主按钮背景4.6:1--clr-red-700#B71C1C主色 hover5.7:1--clr-red-900#7F1010暗色 subtle 背景12.1:1--color-text-on-primary#FFFFFF主按钮文字见上行--color-text-danger#B71C1C错误提示文字7.2:1从表里可以看出一条规律亮色主题下的主按钮用 600 档暗色主题用 500 档两档在同色相下形成互补。这个选择不是拍脑门而是经过对比度计算和实际视觉验证之后的结果。如果你在做自己的主题系统时想让 AI 辅助计算可以在 Claude 提示词里直接要求它输出对比度表再人工复核一遍效率会高很多。5.3 最终组件清单Claude-Red 目前已经完成了九个基础组件的接入Button、Badge、Alert、Card、Input、Modal、Tooltip、Tabs、Tag。数量不多但覆盖了一个组件库最核心的展示型交互组件。从实际效果来看这些组件既能支撑普通的业务页面又能作为后续扩展更复杂组件的地基。每个组件接入时我都用 Storybook 做视觉回归测试就是为了方便同一组件在亮暗两种主题下的表现对照。样式改动后Storybook 的截图对比能快速发现问题。这套流程我在多个项目里已经验证过实用性Claude-Red 算是把这套验证机制落地得最彻底的一次。至少我改一个令牌值时不用再手动打开七八个页面来回检查了。6. 常见问题与排查技巧实录6.1 问题速查表把整个过程中踩过的坑整理成表下面这些问题在前端主题系统开发中极具普遍性值得收藏备用现象根本原因解决方案按钮文字看不清、对比度堪忧令牌色值选择不当计算 WCAG 对比度调整色阶档位暗色模式下阴影消失阴影使用纯黑透明度深色背景失效使用基于色的阴影变量页面刷新主题闪烁主题初始化脚本执行过晚内联脚本注入head样式被意外覆盖CSS 类名权重冲突用:where()降低权重或使用 CSS Modules字体在暗色主题下显得刺眼纯白文字对比度过高使用 90% 白加红色调色红色背景上的红色文字看不清色相一致导致层次缺失文字改用基色白或加深红色6.2 红色系特有的三个坑红色系主题比普通主题多出几个需要特别注意的地方第一个是色盲可访问性。红绿色盲是常见色觉障碍如果只靠颜色深浅来区分状态部分用户会完全无法分辨。在 Claude-Red 里危险状态不仅从背景色上体现还补充了图标和文字标识这样只靠颜色也能传达信息。这不是强制要求但在设计阶段能做到就是做到了等出问题再返工成本就高了。第二个坑是红色的视觉膨胀效应。同样尺寸的元素红色会比蓝色、灰色显得更大更重。组件设计时我用红色做强调色但会主动缩小红色元素的面积避免视觉失衡。第三个是“红得刺眼”的问题。尤其是大面积红色背景饱和度稍微高一点就会让整个页面显得浮躁。做法是背景层的红色从混合色阶里取低饱和低亮度的档位只有主操作元素才用高饱和度。这个分寸感很难用规则表达但掌握了就能明显感觉到页面质感不一样。6.3 与 Claude 协作的避坑心得和 Claude 配合了这么多个组件之后我被坑过的点也积累了不少。最有价值的一条心得是不要让 Claude 同时做太多事。一次只让它生成一个组件、一个页面或一份令牌输出质量会稳定得多。让它一口气生成五个组件的初稿大概率每个组件都有细节缺失反而不如一次一个来得快。还有一条是Claude 非常容易被暗示诱导。如果提示词里写了“使用红色系”这种模糊表述它容易自由发挥导致颜色风格不可控。但如果提示词里明确写了“只准引用语义令牌、禁止硬编码色值、禁止设置字体族沿用全局”输出的代码就能满足工程化约束。最后所有 AI 生成的代码都要经过人工审查这条不能省。审查的重点包括可访问性焦点样式、aria 属性、边界条件空状态、加载状态、以及设计约束的一致性。AI 生成的代码质量确实在提升但它不会主动理解你的设计意图。最终的产品质感还是由人来定义的。7. 后续扩展与应用场景Claude-Red 目前的状态算是一个“可用的基础版”。后续可以扩展的方向我根据自己的使用场景梳理了几个第一个是接入更多品牌主题。当前框架下主题的本质是一组令牌映射理论上加一个新的>