如何让 Codex 统一一个网站的 UI 风格

一个网站看起来不成熟，通常不是因为某个页面特别差，而是因为整站风格没有统一。首页像一套风格，文章页像另一套风格，按钮、卡片、标题、间距、圆角、阴影、图标和表单状态各写各的。用户不会说“你的 design token 不统一”，但会直接感觉这个网站不专业、不可信。

这种问题很适合让 Codex 参与处理。Codex 不只是写代码工具，它可以读取项目结构、扫描重复样式、分析组件用法、修改前端代码、运行检查命令，并把长期规则沉淀到 AGENTS.md。关键是你不能只说“帮我统一 UI”，而要把任务拆成可执行、可验证、可回滚的流程。

本文会给你一套完整流程：如何让 Codex 先做 UI 风格体检，再建立统一视觉规则，然后分批迁移页面，最后把规则写进项目文档。

先明确：统一 UI 风格不是重新设计网站

很多人让 Codex 统一 UI 时，会把任务说成“帮我美化一下网站”。这很危险。美化是主观任务，统一是工程任务。你要让 Codex 做的是减少混乱、复用规范、修正不一致，而不是让它自由发挥重做视觉。

统一一个网站的 UI 风格，通常包含下面这些范围：

• 统一颜色：主色、辅助色、背景色、边框色、文本色、状态色。

• 统一字体：字号层级、字重、行高、标题和正文比例。

• 统一间距：页面容器、模块间距、卡片内边距、表单间距。

• 统一圆角和阴影：按钮、卡片、输入框、弹窗、图片容器。

• 统一组件状态：hover、active、disabled、focus、loading、empty、error。

• 统一页面模板：列表页、详情页、文章页、登录页、设置页、空状态。

• 统一代码入口：通过组件、tokens、Tailwind 配置或 CSS 变量管理样式。

所以，这不是让 Codex 当视觉设计师，而是让它当“UI 规范审查 + 前端规范化重构助手”。

什么时候适合让 Codex 做整站 UI 风格统一？

如果你的网站已经有基本页面和功能，但看起来不像一个完整产品，就可以做这件事。尤其是下面几种情况：

• 项目由不同人或不同时间段开发，页面风格明显不一致。

• Tailwind className 到处散落，颜色、间距、圆角都是随手写。

• 有组件目录，但页面里仍然大量绕过组件直接写样式。

• 官网、文章页、后台页、登录页之间像不同项目拼起来的。

• 移动端和桌面端风格断裂，响应式状态不稳定。

• 你想提升产品感，但不想推翻重做整套 UI。

不适合的情况也要说清楚：如果你还没有确定品牌风格、页面信息架构还在变、核心功能还没跑通，不要急着让 Codex 大面积统一 UI。先做页面结构，再做风格归一。

错误指令：为什么一句“帮我统一 UI”不够用？

下面这种指令很常见，但效果通常不可控：

帮我把这个网站的 UI 风格统一一下，看起来高级一点。

这条指令的问题是：没有基准页面、没有修改范围、没有禁止事项、没有组件规则、没有验收标准。Codex 可能会改颜色、改布局、改组件结构，甚至顺手动到业务逻辑。最后你看到的是一个很大的 diff，很难判断哪些改动是必要的。

正确方法是：先让 Codex 只扫描，不修改；再让它提出统一规则；确认规则后再分批改代码。

第一步：让 Codex 先做整站 UI 风格体检

不要一上来就让 Codex 改代码。第一步应该让它扫描项目，找出 UI 不统一的证据。

请你先不要修改代码，只做整站 UI 风格体检。 目标：找出当前网站 UI 风格不统一的问题，并给出可执行的统一建议。 请重点检查： 1. 全局样式：globals.css、tailwind.config、theme、CSS variables、design tokens。 2. 组件目录：Button、Card、Input、Modal、Header、Footer、Nav、Badge、Tabs 等。 3. 页面层级：首页、列表页、详情页、文章页、登录注册页、后台页、错误页、空状态。 4. 颜色：主色、文本色、背景色、边框色、状态色是否散乱。 5. 字体：标题、正文、辅助文本、按钮文字的字号和字重是否统一。 6. 间距：section、container、card、form、list、grid 的间距是否一致。 7. 圆角、阴影、边框、hover、focus、disabled、loading 状态是否统一。 8. 是否存在重复 3 次以上的大段 className 或样式组合。 输出要求： - 按文件路径列出主要问题。 - 总结当前网站已有的主风格。 - 区分“必须统一”“建议统一”“暂时不要动”。 - 提出下一步统一方案。 - 不要修改任何文件。

这一步的输出越清楚，后面的修改越安全。你要先知道风格问题在哪里，而不是让 Codex 靠感觉改。

第二步：给 Codex 一个“基准风格”

UI 统一一定要有基准。基准可以来自现有页面，也可以来自你指定的设计方向。最稳的方式是从项目里挑一个完成度最高的页面，让 Codex 以它为风格参考。

基准风格可以这样定义：

• 以首页为视觉基准，其他页面向首页的颜色、圆角、阴影和间距靠拢。

• 以新版落地页为视觉基准，旧页面只做风格统一，不改布局结构。

• 以 components/ui 里的现有组件为基准，页面里散落样式都向组件收敛。

• 以 Tailwind theme 和 globals.css 为基准，不允许随意新增一次性颜色值。

请以当前首页作为整站 UI 风格基准，继续制定统一方案。 限制： 1. 不要重新设计网站。 2. 不要大幅改变页面布局。 3. 不要改文案、路由、接口和业务逻辑。 4. 其他页面只向首页的视觉规则靠拢。 请基于首页总结以下规则： - 主色和辅助色 - 背景色和边框色 - 标题、正文、辅助文本字号层级 - section 间距和 container 宽度 - 卡片圆角、阴影、边框、padding - 按钮 variant、size、hover、disabled - 表单和空状态的视觉规则 输出一份可执行的 UI 风格统一规则，然后等待我确认。

如果没有基准，Codex 可能会把所有页面改成它认为“更现代”的样子。对真实项目来说，这不是统一，是不可控重设计。

第三步：把风格规则落到 tokens 和基础组件

统一 UI 最忌讳只在页面层改 className。正确做法是先统一底层入口，再迁移页面。常见入口包括 Tailwind theme、CSS variables、globals.css、components/ui 和基础 layout。

请根据已确认的 UI 风格规则，开始把规则落到项目的基础样式层。 执行要求： 1. 优先复用现有 Tailwind 配置、CSS variables、globals.css 和组件目录。 2. 如果已有 design tokens，请在现有体系内整理，不要另起一套。 3. 如果没有 tokens，请以最小改动补充颜色、字号、间距、圆角、阴影等基础变量。 4. 优先整理 Button、Card、Input、Badge、Header、Footer 等高频组件。 5. 不要引入新的 UI 框架。 6. 不要改业务逻辑、路由、接口请求和文案。 7. 保持现有页面结构不变，只做风格入口统一。 完成后请输出： - 修改了哪些基础样式文件。 - 新增或调整了哪些 tokens。 - 哪些组件已经接入统一规则。 - 下一批建议迁移哪些页面。

第四步：分批迁移页面，不要一次性全站大改

整站 UI 统一最容易失控的地方，就是一次性改太多页面。建议按页面重要性和复用程度分批迁移。

• 第一批：全局组件和高频页面，包括 Header、Footer、首页、登录页、文章列表页。

• 第二批：内容页面，包括文章详情页、分类页、搜索页、空状态、错误页。

• 第三批：业务页面，包括后台、设置页、表格页、详情页、弹窗和表单。

• 第四批：边缘状态，包括 loading、error、empty、disabled、hover、focus、dark mode。

每批迁移后都应该让 Codex 输出修改文件、运行检查，并说明视觉风险。

请开始第一批页面迁移，只处理全局组件和高频公共页面。 范围： - Header / Navbar - Footer - 首页 - 登录注册页 - 文章列表页或主要列表页 迁移规则： 1. 使用已统一的 tokens 和 components/ui 组件。 2. 替换散落的重复颜色、字号、间距、圆角、阴影 className。 3. 保持原页面布局和内容结构不变。 4. 不要改文案、路由、数据请求和交互逻辑。 5. 如果某处会导致视觉变化过大，请先保留并在总结里说明。 6. 修改后运行项目已有的 lint、typecheck、build 命令。 输出： - 修改文件列表。 - 替换前后的典型示例。 - 未迁移位置及原因。 - 需要人工检查的页面。

第五步：让 Codex 检查响应式、暗色模式和交互状态

UI 风格统一不能只看桌面端静态页面。很多问题会出现在移动端、hover、focus、disabled、loading、dark mode 和 error 状态里。

请在本次 UI 风格统一后，继续做一次视觉状态检查。 请检查： 1. 移动端：320px、375px、430px、768px 宽度下是否溢出、拥挤或换行异常。 2. 桌面端：1024px、1280px、1440px 宽度下 container 和 section 是否统一。 3. 交互状态：hover、active、focus、disabled、loading 是否一致。 4. 表单状态：默认、聚焦、错误、禁用、提示文本是否统一。 5. 空状态和错误页：插图、标题、说明、按钮是否和整站风格一致。 6. 暗色模式：如果项目支持 dark mode，检查颜色对比度和边框层级。 限制： - 只修复明显不一致和可验证的问题。 - 不要重做页面视觉。 - 不要引入新依赖。 输出： - 检查过的页面和断点。 - 修复的问题。 - 仍需人工设计确认的问题。

这一步尤其适合设计师和开发协作。设计师不一定要自己写代码，但需要告诉 Codex 哪些视觉变化是允许的，哪些不允许。

第六步：把 UI 规则写进 AGENTS.md

如果只改代码，不写长期规则，项目过几周还会变乱。应该把 UI 风格规则写进 AGENTS.md，让 Codex 之后做任何页面时都遵守这些约定。

UI style rules - 不要重新设计页面，除非任务明确要求。 - 新增或修改页面时，必须优先复用 components/ui 中的基础组件。 - 不要在页面里散落硬编码颜色值，优先使用 theme tokens 或 CSS variables。 - 按钮、卡片、输入框、Badge、Tabs、Modal 必须使用统一组件或统一 variant。 - section、container、grid、card padding 必须遵守现有 spacing scale。 - 圆角、阴影、边框不要随手新增，优先使用现有 token。 - 修改 UI 时不得破坏响应式布局、暗色模式、无障碍焦点状态和业务逻辑。 - 如果需要特殊样式，必须说明为什么不能复用现有组件。 - 完成 UI 修改后，至少运行项目支持的 lint、typecheck、build 检查。

AGENTS.md 的价值不是让 Codex 变聪明，而是让它少猜。稳定项目需要稳定规则。

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

下面这条指令适合直接复制到 Codex，用于 React、Next.js、Vite、Tailwind 等前端项目。

请你作为前端架构和 UI 规范审查助手，帮我统一这个网站的 UI 风格。 目标： 在不重新设计网站、不改变业务逻辑的前提下，让整站在颜色、字体、间距、圆角、阴影、组件状态和页面模板上保持一致，并减少重复样式代码。 请按阶段执行： 第一阶段：只分析，不修改代码 1. 扫描 globals.css、tailwind.config、CSS variables、theme、layout 和 components/ui。 2. 扫描首页、列表页、详情页、文章页、登录注册页、后台页、空状态和错误页。 3. 找出颜色、字号、间距、圆角、阴影、边框、hover、focus、disabled、loading 等不一致问题。 4. 找出重复 3 次以上的大段 className 或样式组合。 5. 按文件路径输出问题清单，并判断哪些必须统一、哪些建议统一、哪些暂时不要动。 第二阶段：建立 UI 风格基准 1. 优先从现有完成度最高的页面中提取风格规则。 2. 总结颜色、字体、间距、圆角、阴影、按钮、卡片、表单、导航、页脚和空状态规则。 3. 输出一份可执行的 UI 统一方案。 4. 如果某些规则不确定，请保守处理，不要自由发挥。 第三阶段：整理基础样式和组件 1. 优先复用现有 Tailwind 配置、CSS variables、globals.css 和 components/ui。 2. 如果已有 tokens，就在现有体系内整理。 3. 如果没有 tokens，只补充最小必要的颜色、字号、间距、圆角和阴影变量。 4. 统一 Button、Card、Input、Badge、Tabs、Header、Footer 等高频组件入口。 5. 不要引入新的 UI 框架。 第四阶段：分批迁移页面 1. 先迁移 Header、Footer、首页、登录页、列表页等高频页面。 2. 再迁移文章页、详情页、表单页、空状态、错误页。 3. 使用统一 tokens 和组件替换散落样式。 4. 保持布局、文案、路由、接口、业务逻辑不变。 5. 无法安全迁移的位置先保留，并说明原因。 第五阶段：验证 1. 运行项目已有的 lint、typecheck、test、build 命令。 2. 检查 320px、375px、430px、768px、1024px、1440px 断点。 3. 检查 hover、focus、disabled、loading、empty、error、dark mode 状态。 4. 输出修改文件列表、典型替换示例、潜在风险和人工验收清单。 5. 如果适合，请补充 AGENTS.md 中的 UI 风格规则。 限制： - 不要重新设计整站。 - 不要改业务逻辑。 - 不要改路由和接口请求。 - 不要大幅改变页面布局。 - 不要引入新 UI 库。 - 每一步都要说明你做了什么，方便我 review。

如果你是设计师，可以这样给 Codex 补充要求

设计师使用 Codex 时，不需要把前端术语说得很复杂，但要把视觉边界说清楚。可以补充下面这段。

补充说明： 我是设计师，不希望你重新设计页面，只希望你把现有 UI 做得更统一。 请遵守： 1. 保留现在的信息结构和页面布局。 2. 首页目前是最接近目标风格的页面，其他页面向首页靠拢。 3. 不要增加夸张动效、渐变、阴影和装饰元素。 4. 优先统一颜色、字号、间距、圆角、按钮、卡片、表单和导航。 5. 每次修改后告诉我哪些地方视觉变化最大，我会人工确认。

常见错误：这些做法会让 UI 越统一越乱

• 没有指定基准页面，让 Codex 自己判断什么叫“高级”。

• 把“统一 UI”和“重新设计”混在一起，导致改动范围失控。

• 一次性让 Codex 改完整站，diff 太大无法 review。

• 只改页面 className，没有沉淀到 tokens 和组件。

• 没有检查移动端、暗色模式和交互状态。

• 没有写入 AGENTS.md，后续新页面继续出现散乱样式。

真正可维护的 UI 统一，不是把页面改得更花，而是让系统更少分叉、更少例外、更容易继续开发。

验收清单：怎样判断 UI 风格已经统一？

总结：让 Codex 做 UI 统一，关键是流程不是提示词

统一一个网站的 UI 风格，不是让 Codex 随机“美化页面”，而是让它按流程完成一次前端规范化工作：先扫描，后定规则；先整理 tokens 和组件，再迁移页面；先小范围验证，再扩大范围；最后把规则写进 AGENTS.md。

如果你只是丢一句“帮我统一 UI”，结果一定不稳定。更有效的做法是把任务拆成 Codex 能执行的阶段，并给它明确的限制：不改业务逻辑、不重做布局、不引入新库、不自由发挥。这样 Codex 才能成为项目维护工具，而不是一次性的页面美化工具。

达灵感会持续整理这类可直接复制的 Codex 任务指令。真正有价值的不是收藏提示词，而是把复杂工作拆成 AI 能理解、能执行、能验证的任务系统。

参考资料

• OpenAI Help Center：Codex 是用于编写、审查和交付代码的 AI agent。

• OpenAI Developers：Codex Best Practices 建议为复杂任务先规划，并用 AGENTS.md 沉淀可复用规则。

• OpenAI Developers：Codex Prompting 建议将复杂工作拆成更小、更聚焦、便于测试和 review 的任务。

• OpenAI Developers：Custom instructions with AGENTS.md 说明 AGENTS.md 可为代码库提供持久项目指导。