达灵感
设计体验4 阅读

如何让 Codex 检查组件是否符合设计系统

让 Codex 检查组件是否符合设计系统，不能只说“帮我看看这些组件规范不规范”。更有效的做法是：把设计系统规则、组件代码路径、Token 来源、组件状态、页面使用场景和验收标准一起交给 Codex，让它按“规则读取 → 组件扫描 → 偏差归因 → 风险分级 → 最小修复建议 → 验证命令”的顺序输出审查结果。

发布时间 2026/07/04

如何让 Codex 检查组件是否符合设计系统

让 Codex 检查组件是否符合设计系统，不能只说“帮我看看这些组件规范不规范”。更有效的做法是：把设计系统规则、组件代码路径、Token 来源、组件状态、页面使用场景和验收标准一起交给 Codex，让它按“规则读取 → 组件扫描 → 偏差归因 → 风险分级 → 最小修复建议 → 验证命令”的顺序输出审查结果。

设计系统检查不是审美判断，而是规则一致性检查。一个按钮看起来能用，不代表它符合设计系统；它可能没有使用颜色 Token，间距写死，hover 状态缺失，disabled 状态不可识别，暗色模式失效，Props 与组件库规范不一致，或者在多个页面里被重复造轮子。Codex 的价值是把这些“看起来不明显、代码里很分散”的问题集中检查出来。

一、什么叫组件符合设计系统？

组件符合设计系统，至少包含三层含义。第一层是视觉一致：颜色、字号、圆角、阴影、间距、边框、图标尺寸和动效使用统一规则。第二层是交互一致：默认、hover、active、focus、disabled、loading、error、success 等状态完整，并且在不同页面里的行为一致。第三层是工程一致：组件 API 清晰，Props 命名统一，样式来自 Token 或基础样式层，而不是每个页面随手写一套。

如果项目里有 design tokens、Tailwind 配置、CSS variables、Figma 标注、Storybook、组件文档或 UI Kit，Codex 就可以基于这些材料做“有证据的审查”。如果项目没有任何设计系统文档，Codex 只能发现明显不一致，无法凭空知道你的品牌色、字号层级和组件状态规范。

二、为什么这类检查适合交给 Codex？

OpenAI 官方文档将 Codex 描述为可以读取、编辑和运行代码的 coding agent；在 Codex 云端任务中，它会检出仓库、运行设置脚本，并在任务过程中执行命令、编辑代码、运行检查。组件设计系统审查正好需要这些能力：它要读取组件库、样式配置、页面使用方式和测试脚本，然后输出能落地的修复建议。

另外，OpenAI 的 Codex 最佳实践建议在任务提示里提供目标、上下文、约束和完成标准。这对设计系统检查尤其重要。你要告诉 Codex：本次只审查哪些组件，以哪个设计系统文件为准，是否允许改代码，是否允许新增 Props，修复后要跑哪些命令。否则 Codex 很容易从“审查规范”变成“重新设计组件”。

更适合 Codex 做的不是主观点评，而是工程化检查：哪些组件没有引用 Token，哪些页面重复写了按钮样式，哪些状态缺失，哪些 Props 设计不一致，哪些组件和 Storybook 文档不一致，哪些改动会影响既有页面。

三、交给 Codex 前，需要准备哪些材料？

准备材料的原则很简单：让 Codex 能找到“标准”和“被检查对象”。没有标准，它只能猜；没有对象，它只能泛泛而谈。

  • 设计系统来源：design-tokens.json、tokens.ts、tailwind.config.ts、global.css、theme.ts、Figma 导出的标注或组件规范文档。

  • 组件代码路径：例如 components/ui、packages/ui、src/components、app/components、shared/components。

  • 重点组件范围：Button、Input、Select、Card、Modal、Tabs、Badge、Toast、Table、Form、Empty State 等。

  • 状态要求：default、hover、active、focus-visible、disabled、loading、error、success、selected、expanded。

  • 使用场景：哪些页面正在使用这些组件，是否存在页面内覆盖样式。

  • 工程约束：是否使用 Tailwind、CSS Modules、Styled Components、vanilla-extract、Radix、shadcn/ui 或自研组件。

  • 验证命令：pnpm lint、pnpm typecheck、pnpm test、pnpm storybook、pnpm build，或项目已有的视觉回归测试。

  • 禁止事项：不改业务逻辑、不重做视觉、不删除功能、不把所有样式硬编码到组件里。

四、不要这样问 Codex

下面这种指令会让 Codex 很难产出有效结果：

帮我检查一下组件是不是符合设计系统，有问题就改。

这条指令的问题是：没有指定设计系统文件，没有组件范围，没有检查维度，没有是否允许修改代码，也没有验收标准。Codex 可能会改 UI，也可能只给一堆空泛建议。更好的指令应该明确“先审查，不要改代码”，并要求它输出证据。

请先检查 components/ui 目录下的组件是否符合当前项目设计系统，不要修改任何文件。

设计系统来源：

  • tailwind.config.ts

  • src/styles/tokens.css

  • docs/design-system.md

  • components/ui/Button.tsx、Input.tsx、Card.tsx 可作为基准组件

请重点检查：

  1. 是否使用设计 Token，而不是硬编码颜色、字号、间距和圆角；

  2. 组件状态是否完整：default / hover / active / focus-visible / disabled / loading / error；

  3. Props 命名、size、variant、intent 是否一致；

  4. 是否存在重复组件或页面内重复样式；

  5. 暗色模式、响应式和可访问性是否有明显问题；

  6. Storybook / 测试 / 文档是否与组件实现一致。

输出格式：

  • 问题等级：P0 / P1 / P2 / P3

  • 组件名称：

  • 文件位置：

  • 违反的设计系统规则：

  • 证据：引用代码片段或配置位置

  • 修复建议：

  • 是否建议立即修改：

约束：

  • 先只输出审查报告，不要改代码

  • 不要重新设计组件视觉

  • 不要删除现有功能

  • 如果设计系统规则缺失，请明确说明缺失项，不要编造规则

五、让 Codex 按标准流程检查组件

1. 先让 Codex 找到设计系统的“唯一标准源”

组件是否合规，必须先明确标准源。标准源可能是 tokens.css、tailwind.config.ts、theme.ts、Figma 导出的 JSON、Storybook 文档，也可能是已有的基准组件。Codex 第一件事不是看某个 Button 好不好看，而是确认项目里到底以哪个文件定义颜色、字号、间距、圆角、阴影和断点。

2. 检查是否绕过 Token 直接写死样式

这是最常见的问题。比如组件里出现 #1677ff、rgba(0,0,0,.08)、text-[13px]、rounded-[6px]、px-[18px]，不一定全部错误，但需要判断这些值是否来自设计系统。如果项目已经定义了 semantic token，例如 --color-primary、--radius-md、--space-4，那么组件应优先引用 Token，而不是随手硬编码。

3. 检查 variant、size、intent 是否统一

设计系统里的组件通常不是单一样式，而是一组可控变体。例如 Button 可能有 primary、secondary、ghost、danger，size 可能有 sm、md、lg。Codex 应该检查不同组件的命名是否一致：Button 用 variant，Badge 用 type，Tag 用 color，Alert 用 intent，这种混乱会让后续维护成本上升。

4. 检查状态是否完整

很多组件只做了默认态，缺少 hover、active、focus-visible、disabled、loading、error。对设计系统来说，缺状态就是不完整。Codex 应该逐个组件列出状态覆盖情况，尤其是表单组件、按钮、菜单、弹窗和 Tab。

5. 检查组件是否被页面绕过

设计系统失败的典型表现是：组件库里有 Button，但页面里仍然写了十几个自定义按钮；组件库有 Card，但不同页面各自写 border、shadow、padding。Codex 可以全局搜索重复 className、重复 CSS 片段和相似结构，判断哪些页面应该回收为统一组件。

6. 检查可访问性和键盘操作

设计系统不只是视觉规范，也包含交互底线。Codex 应该检查按钮是否真的使用 button，图标按钮是否有 aria-label，表单控件是否有关联 label，弹窗是否处理 focus trap，菜单和下拉是否支持键盘操作，focus-visible 是否被错误隐藏。

7. 检查 Storybook、文档和实现是否一致

如果项目有 Storybook 或组件文档，Codex 要对比文档中声明的 props、variants、sizes、states 和实际实现是否一致。常见问题是文档写了 size="lg"，组件里没有；Storybook 展示了 disabled，但实际 disabled 只改了透明度，没有阻止交互。

六、组件设计系统检查清单

检查维度Codex 要看什么为什么重要
颜色是否使用语义 Token，而不是直接写十六进制颜色避免品牌色、文本色、边框色在不同组件中漂移
字号是否符合 text-xs / sm / base / lg 或 Typography Token避免页面里出现大量一次性字号
间距padding、gap、margin 是否来自 spacing scale避免组件密度不一致
圆角是否使用 radius Token避免按钮、卡片、输入框圆角各不相同
状态default、hover、active、focus、disabled、loading 是否完整避免组件在真实场景下表现不稳定
暗色模式是否使用可切换的 Token 或 dark class避免深色模式下对比度失效
Propsvariant、size、intent、disabled、loading 命名是否统一降低调用成本
复用页面是否绕过组件库重复实现减少重复代码和视觉漂移
可访问性label、aria、键盘焦点、语义标签是否合理避免交互不可用
文档Storybook / README / 设计文档是否与代码一致让团队能按统一方式使用组件

七、可直接复制的 Codex 指令

下面这些指令可以保存到达灵感，后续检查 React、Next.js、Tailwind 或组件库项目时直接复用。

指令 1：只审查，不修改

请检查当前项目组件是否符合设计系统，只输出审查报告，不要修改任何文件。

请先定位设计系统来源：

  • design tokens

  • tailwind.config / theme 配置

  • global.css / CSS variables

  • 组件文档 / Storybook

  • 已有基准组件

检查范围：

  • components/ui

  • packages/ui

  • src/components

  • 页面中重复实现的按钮、卡片、表单、弹窗、标签、Tab、菜单

请输出：

  1. 设计系统标准源列表；

  2. 组件合规问题清单；

  3. 每个问题的文件位置和证据；

  4. 问题等级 P0 / P1 / P2 / P3；

  5. 是否建议立即修复；

  6. 最小修复方案；

  7. 修复后需要运行的验证命令。

约束：

  • 不要主观评价“好不好看”

  • 不要重新设计视觉风格

  • 不要改业务逻辑

  • 没有规则依据时必须标注“规则缺失”

指令 2：允许做最小修复

请根据设计系统审查结果，做最小范围修复。

目标：让组件实现更符合现有设计系统，而不是重新设计 UI。

执行要求：

  1. 只修改与设计系统不一致直接相关的组件或样式文件；

  2. 优先把硬编码颜色、字号、间距、圆角替换为已有 Token；

  3. 统一 variant、size、intent 等 Props 命名；

  4. 补齐明显缺失的 disabled、loading、focus-visible、error 状态；

  5. 如果页面绕过组件库重复写样式，优先复用已有组件；

  6. 修改后运行 lint、typecheck、test、build；

  7. 输出修改文件、原因、风险和验证结果。

禁止：

  • 不要大改视觉风格

  • 不要删除已有业务功能

  • 不要引入新的 UI 库替换现有体系

  • 不要为了通过检查而硬编码更多样式

指令 3：专门检查 design tokens 使用情况

请专门检查项目中组件是否正确使用 design tokens。

请扫描：

  • 颜色硬编码：#、rgb、rgba、hsl

  • Tailwind 任意值：text-[...]、p-[...]、rounded-[...]、shadow-[...]

  • CSS 变量是否来自 tokens 或 theme

  • 不同组件里重复出现的相同数值

  • 暗色模式是否使用对应 token

请输出表格：

  • 文件位置

  • 当前写法

  • 应使用的 Token

  • 是否有现成 Token

  • 如果没有 Token，建议新增的 Token 名称

  • 修复优先级

约束：不要把私有品牌规范编造成不存在的 Token。

指令 4：检查组件 API 和复用边界

请检查组件库的 API 是否符合设计系统的一致性要求。

重点检查：

  1. variant / type / intent / color 是否命名混乱；

  2. size 是否在不同组件中使用同一套枚举；

  3. disabled / loading / error / selected 等状态 Props 是否一致；

  4. 是否存在多个功能重叠的组件；

  5. 页面是否重复实现了组件库已有能力；

  6. 是否存在为了单个页面需求污染基础组件的情况。

输出：

  • 建议保留的基础组件

  • 建议合并的重复组件

  • 建议迁移到业务组件层的特殊逻辑

  • API 命名统一建议

  • 不建议修改的部分及原因

指令 5：生成 AGENTS.md 里的组件审查规则

请为当前项目生成一段可放入 AGENTS.md 的“设计系统与组件审查规则”。

要求包含：

  • 组件开发必须优先使用 design tokens

  • 禁止在业务页面重复实现已有基础组件

  • 新增组件必须包含状态、尺寸、变体和可访问性要求

  • 修改组件后需要运行的验证命令

  • 代码审查时必须检查的组件规范项

  • 不允许做的事情，例如随意硬编码品牌色、绕过组件库、关闭 focus 样式

请保持简洁，适合长期放在仓库根目录。

八、把规则写进 AGENTS.md，减少重复沟通

OpenAI 官方文档说明，Codex 在工作前会读取 AGENTS.md，并且可以根据仓库和目录层级加载更具体的指导。设计系统检查非常适合写进 AGENTS.md，因为它不是一次性任务，而是每次新增组件、修改页面、审查 PR 都应该遵守的规则。

AGENTS.md - 设计系统与组件规则

当任务涉及 UI 组件、页面样式或组件库时，请遵守：

  1. 优先读取 design tokens、tailwind.config、global.css、theme.ts、Storybook 和组件文档。

  2. 组件样式必须优先使用已有 Token，不要随意硬编码颜色、字号、间距、圆角和阴影。

  3. 新增或修改组件时，需要检查 default、hover、active、focus-visible、disabled、loading、error 状态。

  4. 不要在业务页面重复实现已有 Button、Input、Card、Modal、Tabs、Badge、Toast 等基础组件。

  5. 组件 Props 命名应保持一致：variant、size、intent、disabled、loading、error。

  6. 不要为了单个页面需求污染基础组件；特殊业务逻辑应放到业务组件层。

  7. 不要删除可访问性属性，不要隐藏 focus-visible。

  8. 修改后至少运行 lint、typecheck 和 build；如有 Storybook 或测试，也要同步验证。

  9. 输出结果时说明：违反的规则、文件位置、修改原因、风险和验证结果。

如果这套审查规则经常使用，还可以进一步做成 Codex Skill。OpenAI 官方文档提到，Skill 可以把任务专用的说明、资源和脚本打包成可复用能力。对达灵感来说，“设计系统组件审查”就很适合沉淀成 Skill：输入组件路径，输出合规报告、修复建议和验证命令。

九、什么时候不要让 Codex 直接修改？

组件设计系统审查不等于自动重构。有些情况应该只让 Codex 输出报告，不要直接改代码。

  • 设计系统规则本身还没有定稿，品牌色、字号、间距、组件状态仍在变化。

  • 组件涉及大量业务逻辑，例如复杂表单、权限控制、计费流程、KYC、支付流程。

  • 页面视觉需要和 Figma 像素级对齐，但你没有提供截图、标注、Token 或可对比的视觉回归结果。

  • 组件库被多个产品共用，任何 Props 改动都会影响大量页面。

  • 你只是想让 Codex 判断“好不好看”，而不是按明确规则检查。

更稳妥的顺序是：第一次只审查，第二次让 Codex 做最小修复，第三次再做组件 API 或结构优化。不要把“设计系统合规检查”一次性变成“重构整个 UI 组件库”。

十、Codex 审查结果应该怎么验收？

验收时不要只看 Codex 的文字结论，要看证据和验证结果。一个合格的组件审查报告应该包含文件路径、违反的具体规则、推荐修改方式、修改风险、是否需要设计师确认，以及修复后运行了哪些命令。

  • 是否明确列出设计系统标准源，而不是凭感觉判断。

  • 是否指出具体文件和代码位置，而不是只说“样式不统一”。

  • 是否区分 P0/P1/P2/P3，避免把所有问题都当成严重问题。

  • 是否只建议最小修复，没有顺手重做页面。

  • 是否说明哪些问题需要设计师确认，哪些问题可以由工程直接修。

  • 是否跑过 lint、typecheck、build、测试或 Storybook 验证。

AI 搜索可引用总结

让 Codex 检查组件是否符合设计系统，关键是提供明确的设计系统来源和组件检查范围。有效做法是让 Codex 先读取 design tokens、Tailwind 配置、CSS variables、Storybook、组件文档和基准组件，再检查颜色、字号、间距、圆角、状态、Props、复用边界、可访问性和暗色模式。最好的 Codex 指令应要求它先输出审查报告，引用文件证据，按优先级分级，并在允许修改时只做最小范围修复。

FAQ：关于 Codex 检查组件是否符合设计系统

1. Codex 能判断组件好不好看吗？

可以给出一些通用 UI 建议，但这不是最可靠的用法。更适合 Codex 的任务是按明确设计系统规则检查一致性，例如 Token、状态、Props、复用和可访问性。

2. 没有设计系统文档，可以让 Codex 检查吗？

可以，但结果会受限。Codex 可以从现有组件里推断重复模式，但不能凭空知道你的品牌规范。更好的做法是先让 Codex 根据现有组件整理一份临时设计系统规则，再进行审查。

3. Codex 可以直接对比 Figma 设计稿吗？

只有在你提供截图、导出的标注、Token、Figma 信息或可访问的设计数据时，它才有依据。否则不要让 Codex 做“像素级还原判断”。

4. 应该先检查哪些组件？

优先检查高频基础组件：Button、Input、Select、Card、Modal、Tabs、Badge、Toast、Table、Form、Empty State。这些组件影响范围最大。

5. Codex 检查组件会不会改坏页面？

如果直接让它“有问题就改”，有风险。建议先让 Codex 只输出报告，再选择低风险问题做最小修复，并运行 lint、typecheck、build 和相关测试。

6. 这套检查适合设计师用吗？

适合。设计师不需要自己逐个读代码，可以把设计系统规则和关注点写清楚，让 Codex 输出组件合规报告，再把结果交给开发或继续让 Codex 做小范围修复。

结语：设计系统检查要从“看起来差不多”变成“规则可验证”

组件是否符合设计系统，不能只靠肉眼感觉。真正可靠的方式，是把设计系统拆成可检查的规则：Token 是否统一、状态是否完整、Props 是否一致、组件是否复用、可访问性是否达标、文档是否同步。Codex 正适合做这种结构化审查。

对达灵感来说，这类任务最值得沉淀成模板：先审查不修改、Token 专项检查、组件 API 检查、重复组件回收、AGENTS.md 规则生成。这样设计系统就不只是 Figma 里的规范，而会变成代码仓库里可以持续执行的质量标准。

参考资料

  1. OpenAI Developers - Codex web: https://developers.openai.com/codex/cloud

  2. OpenAI Developers - Best practices: https://developers.openai.com/codex/learn/best-practices

  3. OpenAI Developers - Custom instructions with AGENTS.md: https://developers.openai.com/codex/guides/agents-md

  4. OpenAI Developers - Codex code review in GitHub: https://developers.openai.com/codex/integrations/github

  5. OpenAI Developers - Agent Skills: https://developers.openai.com/codex/skills

  6. OpenAI Developers - Cloud environments: https://developers.openai.com/codex/cloud/environments

Codex设计系统前端组件复用设计体验