如何让 Codex 统一项目里的按钮和卡片样式

一个项目看起来不像成熟产品，很多时候不是因为页面结构不完整，而是因为基础组件不统一。最明显的就是按钮和卡片：有的按钮圆角 8px，有的 12px；有的 hover 有阴影，有的没有；卡片有的用 border，有的用 shadow，有的 padding 随手写。单个页面看问题不大，但整个项目放在一起，就会显得便宜、混乱、不像一个完整产品。

这类问题很适合交给 Codex 处理。Codex 不只是帮你写一个 Button 组件，而是可以先读代码库、找出散落样式、归纳当前规则、生成统一组件，再逐步替换页面里的重复写法。前提是你的任务指令不能只写“帮我统一样式”，而要告诉它统一什么、怎么统一、不能破坏什么、做到什么程度才算完成。

本文会讲清楚如何用 Codex 统一项目里的按钮和卡片样式，并给你一套可以直接复制到 Codex 里的执行指令。

为什么先统一按钮和卡片，而不是直接做完整设计系统？

很多团队一上来就想做完整设计系统，结果越做越大，最后没有落地。更现实的方式是先统一最高频、最影响质感的组件。按钮和卡片就是最适合切入的两个组件。

• 按钮几乎出现在所有页面，包括导航、表单、弹窗、列表操作、空状态和详情页。

• 卡片决定了内容区的秩序感，包括列表、数据面板、文章卡、功能入口和价格模块。

• 这两个组件一旦统一，整个产品的视觉稳定性会明显提升。

• 按钮和卡片的改动范围可控，适合让 Codex 分阶段执行和验证。

所以，不建议一开始就让 Codex “重构所有 UI 组件”。更稳的做法是先让它围绕 Button 和 Card 建立规范，再把这套方式复用到 Input、Modal、Tabs、Badge 等组件上。

适合让 Codex 处理的按钮和卡片问题

你可以先判断项目里是否出现了下面这些问题。如果有，就可以让 Codex 介入统一。

• 页面里到处写 className="px-4 py-2 rounded..."，没有统一 Button 组件。

• 已经有 Button 组件，但还有大量页面绕过组件直接写原生 button。

• primary、secondary、ghost、danger 等状态没有统一命名。

• loading、disabled、icon button、full width 等状态处理方式不一致。

• Card 的 padding、border、shadow、radius、background 写法分散。

• 同一类卡片在首页、列表页、详情页样式不一致。

• Tailwind 项目里存在大量重复 utility class，后续维护成本很高。

不要直接让 Codex “统一样式”

很多人使用 Codex 出问题，是因为任务指令太短。比如：

帮我把项目里的按钮和卡片样式统一一下。

这条指令的问题是：没有说明项目范围、没有定义组件标准、没有要求先盘点、不知道是否允许改布局、不知道是否允许新增依赖，也没有验收标准。Codex 可能会做出一个看似合理但很难 review 的大改动。

更好的方式是分成四步：先盘点，再定规范，再实现组件，最后迁移页面。每一步都要让 Codex 输出可检查的结果。

第一步：让 Codex 先扫描现有按钮和卡片写法

统一之前，不要先写组件。应该先让 Codex 找出项目里所有按钮和卡片的用法，包括原生 button、a 链接伪装按钮、已有 Button 组件、Card 容器、重复 className、不同 variant。

请你先不要修改代码，只做项目扫描和分析。 目标：找出当前项目里所有按钮和卡片相关的样式写法，并判断哪些需要统一。 请重点检查： 1. 原生 button、a 标签伪装按钮、已有 Button 组件的使用位置。 2. 按钮常见样式：尺寸、圆角、颜色、hover、disabled、loading、icon、full width。 3. 卡片常见样式：background、border、shadow、radius、padding、hover、interactive 状态。 4. 重复出现 3 次以上的 className 或样式组合。 5. 哪些页面适合替换成统一组件，哪些地方暂时不要动。 输出要求： - 按文件路径列出问题。 - 总结当前按钮和卡片的主要样式模式。 - 给出建议的 Button / Card 组件 API。 - 不要修改任何文件。

这一步的核心价值是降低误改风险。你先拿到一份组件样式体检报告，再决定是否让 Codex 进入实现阶段。

第二步：让 Codex 设计统一组件 API

按钮和卡片统一不是简单换颜色，而是要先定义组件 API。对于大多数 React / Next.js / Tailwind 项目，可以先用下面这套最小规范。

不要把组件 API 设计得太复杂。一个项目还没有稳定规范时，组件属性越多，后续越容易失控。先覆盖 80% 高频场景，特殊场景通过 className 少量扩展即可。

第三步：让 Codex 创建或重构 Button / Card 组件

扫描完成后，再让 Codex 进入实现阶段。此时要明确告诉它：优先复用现有设计 token、Tailwind 配置、cn 工具函数和已有组件目录，不要随便引入新的 UI 库。

请根据刚才的扫描结果，开始实现统一的 Button 和 Card 组件。 执行要求： 1. 优先复用项目现有目录结构，例如 src/components/ui、components/ui 或 app/components。 2. 如果项目已有 Button / Card，请在保留兼容性的前提下重构，不要贸然删除旧 API。 3. 如果项目没有统一组件，请新增 Button.tsx 和 Card.tsx。 4. 优先使用项目已有的 Tailwind 配置、design tokens、cn/classNames 工具函数。 5. 不要引入新的 UI 组件库，除非项目已经在使用。 6. 不要改变页面布局、业务逻辑、路由和数据请求。 7. 为 Button 覆盖 variant、size、disabled、loading、icon、fullWidth。 8. 为 Card 覆盖 variant、padding、interactive、className 扩展。 9. 添加必要的 TypeScript 类型。 10. 修改后运行 lint、typecheck 或项目中已有的检查命令。 完成后请输出： - 新增或修改的文件列表。 - Button 和 Card 的使用示例。 - 还有哪些页面建议下一步迁移。

第四步：分批替换项目里的散落样式

不要让 Codex 一次性替换全项目。按钮和卡片通常分布在很多页面，一次性大改会增加 review 成本。更好的做法是按页面类型分批迁移。

• 第一批：公共页面，例如首页、文章列表页、关于我们、登录注册页。

• 第二批：后台或业务页面，例如控制台、设置页、详情页、数据列表。

• 第三批：边缘页面，例如空状态、错误页、弹窗、移动端底部操作区。

每批迁移都要让 Codex 保持视觉结构不变，只替换组件入口和重复样式。

请开始第一批迁移，只处理公共页面里的按钮和卡片样式。 范围： - 首页 - 列表页 - 详情页 - 关于页 - 登录/注册页（如果存在） 迁移规则： 1. 把重复的原生 button / a 按钮替换为统一 Button 组件。 2. 把重复的卡片容器替换为统一 Card 组件。 3. 保持现有布局、间距层级和响应式结构不变。 4. 不要改文案、路由、数据逻辑和交互逻辑。 5. 如果某处样式无法安全替换，请保留并在最后说明原因。 6. 每完成一类页面，运行项目已有检查命令。 输出： - 本次迁移的文件列表。 - 替换前后的组件用法示例。 - 无法迁移的位置和原因。 - 需要我人工确认的视觉风险。

第五步：把规则写进 AGENTS.md，避免以后又变乱

统一一次不难，难的是以后不反弹。最容易出问题的是新页面继续随手写 className，几周后又回到原来的状态。所以要把组件规则写进 AGENTS.md，让 Codex 后续每次执行任务都知道项目约定。

UI component rules - 所有主要操作按钮必须优先使用 Button 组件。 - 禁止在页面中重复手写大段按钮样式，例如 px- py- rounded- bg- hover:。 - 按钮视觉层级统一使用 variant: primary、secondary、ghost、danger、link。 - 按钮尺寸统一使用 size: sm、md、lg、icon。 - 卡片容器必须优先使用 Card 组件。 - 禁止在页面中重复手写卡片的 border、shadow、radius、padding 组合。 - 如果确实需要特殊样式，必须通过 className 扩展，并保持基础结构来自统一组件。 - 修改 UI 时不得破坏现有响应式布局和业务逻辑。 - 完成后必须运行 lint、typecheck、build 中项目支持的检查命令。

这一步对长期维护很重要。Codex 适合处理重复性开发任务，但前提是你把稳定的规则沉淀下来，而不是每次都重新口述。

可直接复制的 Codex 一键执行指令

下面这条适合直接放进 Codex，适用于大多数 React、Next.js、Vite、Tailwind 项目。

请你作为前端架构和 UI 规范审查助手，帮我统一项目里的按钮和卡片样式。 目标： 让项目中的按钮和卡片拥有统一的组件入口、统一的视觉层级、统一的状态处理方式，并减少重复 className / 重复样式代码。 请按阶段执行： 第一阶段：只分析，不修改代码 1. 扫描项目中所有 button、a 标签伪装按钮、Button 组件、Card 组件和卡片容器。 2. 找出重复出现的按钮样式、卡片样式和不一致的视觉规则。 3. 按文件路径列出问题，并总结当前样式模式。 4. 提出 Button / Card 组件 API 设计建议。 第二阶段：实现统一组件 1. 优先复用现有组件目录和工具函数。 2. 如果已有 Button / Card，在兼容旧用法的基础上重构。 3. 如果没有统一组件，则新增 Button.tsx 和 Card.tsx。 4. Button 至少支持 variant、size、disabled、loading、icon、fullWidth。 5. Card 至少支持 variant、padding、interactive、className。 6. 不要引入新的 UI 库，不要改变业务逻辑和页面布局。 第三阶段：分批迁移 1. 先迁移公共页面和高频页面。 2. 把重复按钮写法替换为 Button。 3. 把重复卡片容器替换为 Card。 4. 无法安全替换的位置先保留，并说明原因。 第四阶段：验证和总结 1. 运行项目已有的 lint、typecheck、test、build 命令。 2. 检查移动端响应式是否受影响。 3. 输出修改文件列表、替换示例、潜在风险和后续建议。 4. 如果适合，请补充 AGENTS.md 中的 UI 组件使用规则。 限制： - 不要改页面文案。 - 不要改路由。 - 不要改接口请求。 - 不要重做视觉风格，只做组件统一和代码规范化。 - 每一步都要说明你做了什么，方便我 review。

如果项目使用 shadcn/ui，指令要稍微调整

如果项目已经使用 shadcn/ui，不建议再让 Codex 自己造一套 Button 和 Card。更好的做法是让它基于现有 shadcn 组件做项目级封装和迁移。

当前项目已经使用 shadcn/ui。请不要重新发明 Button 和 Card。 请基于现有 components/ui/button 和 components/ui/card 做以下工作： 1. 扫描项目里绕过 shadcn Button / Card 的重复写法。 2. 保留 shadcn 原有组件 API，必要时只做轻量扩展。 3. 将页面中重复的按钮样式迁移到 Button 的 variant / size。 4. 将重复卡片容器迁移到 Card、CardHeader、CardContent、CardFooter。 5. 不要破坏 shadcn 的结构和可维护性。 6. 输出迁移清单和需要人工确认的视觉差异。

常见错误：让 Codex 越改越乱的几种写法

• 只说“统一样式”，没有告诉 Codex 先分析再修改。

• 一次性要求重构所有 UI 组件，导致 diff 太大无法审查。

• 没有限制“不要改布局、不要改业务逻辑”，结果样式统一了，页面行为坏了。

• 没有让 Codex 跑 lint、typecheck、build，导致提交后才发现类型错误。

• 没有把组件规则写进 AGENTS.md，新页面继续产生重复样式。

真正稳定的做法是：让 Codex 小步执行，每一步都有输出、可回滚、可检查。

验收清单：怎样判断统一是否完成？

总结：不要让 Codex 猜你的设计规范

按钮和卡片样式统一，本质上不是一个“美化页面”的任务，而是一个“把重复样式组件化、规范化、可维护化”的任务。你不能只让 Codex 看着改，而要让它先盘点现状、抽象组件 API、分批迁移页面、运行检查，并把最终规则沉淀到 AGENTS.md。

如果你的项目已经出现按钮、卡片、列表、弹窗样式各写各的情况，可以先不要急着重做 UI。先用本文这套指令，让 Codex 做一次基础组件体检和小范围重构。只要 Button 和 Card 统一下来，项目的产品感和维护效率都会立刻改善。

达灵感会持续整理这类可直接执行的 Codex 任务指令。相比收藏一堆提示词，更重要的是把任务拆成 Codex 能读懂、能执行、能验证的工作流。这样 Codex 才不是一个代码补全工具，而是一个可以参与项目维护的 AI 执行系统。

参考资料

• OpenAI Developers：Codex 官方文档，介绍 Codex 可用于读代码、改代码、运行代码以及处理开发任务。

• OpenAI Developers：Codex Best Practices，建议在任务提示中明确 Goal、Context、Constraints 和 Done when。

• OpenAI Developers：Custom instructions with AGENTS.md，说明 Codex 会在执行前读取 AGENTS.md，并可用它沉淀项目级规则。