一、直接回答：用 Codex 检查深色模式，不能只靠“看起来正常”

用 Codex 检查深色模式和颜色对比度，正确方式不是让它简单评价页面“好不好看”，而是让 Codex 进入项目代码，读取主题实现方式，找出所有颜色 token、CSS 变量、Tailwind dark class、组件状态和页面入口，然后用浏览器级测试生成深色模式截图，并结合 WCAG 对比度标准输出可修复清单。

一句话：让 Codex 做“代码扫描 + 页面截图 + 自动化对比度检测 + 修复建议 + 必要代码修改”，而不是做主观视觉点评。

深色模式的常见问题有三类：第一，颜色变量没有完整覆盖；第二，文字、边框、图标、占位符、禁用态、提示态在暗色背景上不清楚；第三，组件在局部页面里正常，但在弹窗、下拉菜单、Toast、表格、卡片、移动端抽屉里失效。Codex 适合处理这类问题，因为它能同时读代码、跑测试、改组件、补脚本和输出报告。

二、检查深色模式前，先把验收标准写清楚

很多团队让 AI 检查深色模式时会失败，核心原因不是 AI 不会看页面，而是任务没有标准。你不能只说“帮我看看深色模式有没有问题”，这会得到一堆模糊建议。应该把判断标准写成明确的验收条件。

• 普通正文文本：与背景的对比度至少达到 4.5:1。

• 大字号文本：与背景的对比度至少达到 3:1。

• UI 组件和状态线索：输入框边界、按钮轮廓、Focus Ring、图标、图表关键线索等，至少达到 3:1。

• 状态表达：错误、成功、警告、选中、禁用、当前页面，不能只依赖颜色区分，还要有文字、图标、边框、形状或位置辅助。

• 页面覆盖：至少检查首页、列表页、详情页、表单页、登录注册页、弹窗、下拉菜单、空状态、错误状态和移动端页面。

• 输出结果：必须给出文件位置、组件名称、问题描述、影响范围、修复建议、是否已修复、测试命令。

这些标准来自可访问性规范和前端自动化测试实践。对 Codex 来说，标准越具体，越容易从“泛泛审美建议”变成“可执行修复任务”。

三、Codex 和 ChatGPT 在这个任务里的分工

简单说：ChatGPT 适合帮你想清楚“怎么查”，Codex 适合进入代码库把“检查、修复、验证”跑完。

四、让 Codex 检查哪些文件和目录

你给 Codex 的任务里，应该直接告诉它优先检查这些位置。如果项目结构不同，让它先自动识别。

• 全局样式：globals.css、app.css、index.css、theme.css、variables.css。

• Tailwind 配置：tailwind.config.ts、tailwind.config.js、postcss.config.js。

• 主题入口：ThemeProvider、ColorModeProvider、next-themes、useTheme、theme.ts、tokens.ts。

• 设计变量：colors、semantic tokens、CSS variables、brand colors、surface colors、border colors。

• 基础组件：Button、Input、Textarea、Select、Checkbox、Radio、Switch、Tabs、Modal、Dropdown、Tooltip、Toast、Card、Table、Badge。

• 页面入口：首页、文章页、作品页、定价页、登录页、注册页、表单页、后台页面、移动端导航。

• 图表和可视化：Chart、Legend、Tooltip、Axis、状态色、涨跌色、数据标签。

深色模式问题通常不是出在一个页面，而是出在“颜色语义没有统一”。例如 text-gray-400 在浅色模式可能只是辅助文字，在深色背景上可能变成几乎不可读；border-gray-200 在深色模式里可能完全消失；blue-500 在暗色背景上可能刺眼但不一定清晰。

五、可直接复制的 Codex 指令：全面检查深色模式和颜色对比度

下面这条适合第一次完整体检。它要求 Codex 先审查，不要一上来乱改。

你是一名前端 UI 质量审查工程师，请检查当前项目的深色模式和颜色对比度问题。 目标： 1. 识别项目如何实现 light / dark theme。 2. 找出所有可能导致深色模式显示异常的颜色、组件和页面。 3. 按 WCAG AA 标准检查文字、图标、边框、输入框、按钮、Focus Ring 和状态色。 4. 先输出问题报告，不要直接大面积重构。 检查范围： - 全局 CSS、Tailwind 配置、主题 Provider、CSS variables、设计 token。 - Button、Input、Select、Modal、Dropdown、Card、Table、Toast、Badge 等基础组件。 - 首页、列表页、详情页、表单页、登录注册页、移动端导航和弹窗状态。 验收标准： - 普通文本对比度至少 4.5:1。 - 大字号文本至少 3:1。 - 关键 UI 组件、图标、边界、Focus Ring 至少 3:1。 - 错误、成功、警告、选中、禁用状态不能只靠颜色表达。 输出格式： - 问题位置：文件路径 + 组件/页面名称。 - 问题类型：文本对比度 / 非文本对比度 / 状态色 / token 缺失 / 深色模式覆盖不完整。 - 影响说明：用户会看到什么问题。 - 修复建议：具体改哪个变量、类名或组件逻辑。 - 风险等级：高 / 中 / 低。 - 是否建议自动修复：是 / 否。 限制： - 不要改变页面布局和业务逻辑。 - 不要随意替换品牌主色。 - 不要引入新的 UI 框架。 - 如果需要新增测试，请说明新增文件和运行命令。

六、可直接复制的 Codex 指令：用 Playwright 生成深色模式截图

如果项目已经有本地启动命令，可以让 Codex 补 Playwright 脚本，模拟浅色和深色两种环境，然后输出关键页面截图。

请为当前项目新增或完善 Playwright 深色模式视觉检查。 任务目标： 1. 识别项目启动命令和页面路由。 2. 使用 Playwright 分别模拟 light 和 dark colorScheme。 3. 对关键页面生成截图：/、/blog、/pricing、/login、/signup、/contact，以及项目中真实存在的重要页面。 4. 截图要覆盖 desktop 和 mobile 两种视口。 5. 输出截图保存路径，并在报告中列出明显的深色模式问题。 要求： - 如果项目已有 Playwright 配置，在现有配置上扩展，不要重复创建冲突配置。 - 如果没有 Playwright，先说明需要安装哪些依赖，再创建最小可运行配置。 - 测试中不要依赖真实账号、真实支付、真实第三方接口。 - 对不可访问页面，用 mock 或跳过，并在报告中说明原因。 完成后请运行： - lint - typecheck - build - Playwright 测试 输出： 1. 新增/修改的文件列表。 2. 截图路径。 3. 发现的问题。 4. 建议下一步修复顺序。

七、可直接复制的 Codex 指令：接入 axe 自动检查颜色对比度

颜色对比度最好不要只靠肉眼判断。你可以让 Codex 接入 axe 和 Playwright，对关键页面做自动化扫描。

请在当前项目中接入 axe + Playwright 可访问性检查，重点检查颜色对比度。 目标： 1. 安装或复用 @axe-core/playwright。 2. 为关键页面创建 accessibility 测试。 3. 分别在 light 和 dark colorScheme 下运行扫描。 4. 默认不禁用 color-contrast 规则。 5. 对发现的问题输出元素选择器、页面路径、失败原因和建议修复方案。 测试页面： - 自动识别项目主要路由。 - 至少覆盖首页、表单页、内容详情页、弹窗/菜单组件所在页面。 注意： - 不要为了让测试通过而直接 disableRules(['color-contrast'])。 - 如果某些问题属于历史遗留问题，请单独标记，不要静默忽略。 - 如果组件必须保持品牌色，请优先通过背景、边框、字号、字重或状态辅助元素解决。 完成标准： - 新增测试文件可以稳定运行。 - 失败结果可定位到具体页面和元素。 - 报告区分 light 和 dark 两种模式。 - 给出可执行修复建议。

八、自动化测试代码示例：Codex 可以据此生成项目版本

下面是一个简化示例。实际使用时，不要直接复制到所有项目，而是让 Codex 根据项目目录、测试框架和路由自动调整。

import { test, expect } from '@playwright/test'; import AxeBuilder from '@axe-core/playwright'; const pages = ['/', '/login', '/contact']; const schemes = ['light', 'dark'] as const; for (const colorScheme of schemes) { test.describe(a11y contrast: ${colorScheme}, () => { test.use({ colorScheme }); for (const path of pages) { test(no obvious contrast violations on ${path}, async ({ page }) => { await page.goto(path); const results = await new AxeBuilder({ page }) .withTags(['wcag2a', 'wcag2aa', 'wcag21aa']) .analyze(); const contrastViolations = results.violations.filter( violation => violation.id === 'color-contrast' ); expect(contrastViolations).toEqual([]); }); } }); }

这段代码的重点不是“代码长什么样”，而是检查思路：同一批页面必须同时跑 light 和 dark；对比度问题必须单独过滤出来，便于开发优先修复。

九、可直接复制的 Codex 指令：让 Codex 直接修复问题

当 Codex 已经输出报告后，再让它分批修复。不要让它一次性把所有颜色都重写，否则容易破坏品牌风格和页面层级。

请根据上一轮深色模式和颜色对比度报告，分批修复高优先级问题。 修复优先级： 1. 正文、标题、按钮文字、表单 Label、错误提示等不可读问题。 2. 输入框边界、按钮边界、Focus Ring、Tab 选中态不可见问题。 3. Modal、Dropdown、Toast、Popover、Mobile Menu 在深色模式下背景和文字冲突问题。 4. 图标、Badge、状态标签、图表说明在暗色背景下对比度不足问题。 5. 低风险的装饰性颜色问题最后处理。 修复原则： - 优先修改语义化颜色变量，不要在页面里到处硬编码颜色。 - 如果项目使用 Tailwind，请优先统一 dark: 类名或主题 token。 - 如果项目使用 CSS variables，请补齐 light 和 dark 两套变量。 - 不要改变布局、间距、交互逻辑和业务逻辑。 - 不要为了通过测试而删除视觉状态。 完成后： - 运行 lint、typecheck、build。 - 运行 Playwright / axe 测试。 - 输出修改文件、修复点、测试结果、仍需人工确认的问题。

十、AGENTS.md 里可以长期写入的深色模式规则

如果项目经常让 Codex 做 UI 修复，建议把深色模式和可访问性规则写进 AGENTS.md。这样每次 Codex 进入项目时，都能先读取统一标准。

UI Theme and Accessibility Rules - Do not hard-code colors in page components unless there is a documented reason. - Prefer semantic tokens: background, foreground, muted, border, ring, primary, danger, success. - Any new component must support both light and dark themes. - Normal text should meet at least 4.5:1 contrast against its background. - Large text should meet at least 3:1 contrast. - UI boundaries, icons, focus indicators, and meaningful graphical elements should meet at least 3:1 contrast. - Do not use color alone to indicate error, success, selected, active, disabled, or warning states. - Before finalizing UI changes, run lint, typecheck, build, and relevant Playwright/a11y tests. - Do not change layout, spacing, or brand colors unless the task explicitly asks for it.

这类规则很适合沉淀到达灵感的任务模板里。以后你不需要每次重新解释，只要选择“深色模式与颜色对比度检查”任务卡，再补充当前项目的启动命令和重点页面即可。

十一、深色模式最容易被忽略的 15 个问题

• 1. 只检查首页，没有检查表单、弹窗、下拉菜单和移动端导航。
• 2. 正文可读，但辅助文字、占位符、说明文字过灰。
• 3. 输入框边界在暗色背景上几乎不可见。
• 4. Focus Ring 被深色背景吞掉，键盘用户看不到当前位置。
• 5. 禁用态和普通态差异太小，用户分不清能不能点击。
• 6. 错误提示只用红色，没有文字、图标或边框辅助。
• 7. Badge、Tag、状态点在深色背景下失去层级。
• 8. 卡片背景和页面背景太接近，内容块没有边界。
• 9. 表格分割线太弱，行列关系不清楚。
• 10. 图标颜色沿用浅色模式，在深色模式下偏暗。
• 11. SVG、Logo、插画没有 dark 版本或反白版本。
• 12. 图表颜色只考虑浅色背景，深色模式下线条和图例不清楚。
• 13. Tailwind dark class 只写在局部组件，Portal 渲染的弹窗没有继承。
• 14. SSR 页面首次加载时先闪白，再切到深色模式。
• 15. 只修复视觉，没有把检查流程加入测试，后续迭代又回退。

十二、设计师应该怎么配合 Codex

设计师不需要把任务说成技术语言，但要给 Codex 足够清楚的判断标准。最有效的协作方式是：设计师给出颜色语义和视觉优先级，Codex 去代码里落地和验证。

对设计师来说，最关键的是不要只说“颜色太暗”“看不清”。更好的说法是：“请检查所有正文、按钮、输入框、状态提示在深色背景下是否达到 WCAG AA；品牌主色不要大幅改变，必要时调整背景层级和语义 token。”

十三、上线前推荐的 Codex 检查流程

• 让 Codex 识别主题实现方式：CSS variables、Tailwind dark class、ThemeProvider 或 next-themes。

• 让 Codex 列出所有颜色 token 和硬编码颜色，判断是否存在 dark 覆盖缺失。

• 让 Codex 跑 Playwright，在 light 和 dark 下生成关键页面截图。

• 让 Codex 接入 axe，优先检查 color-contrast 和基础可访问性问题。

• 让 Codex 输出问题清单，先不改代码。

• 人工确认哪些颜色涉及品牌，不允许乱改。

• 让 Codex 分批修复高风险问题。

• 再次运行 lint、typecheck、build、Playwright 和 axe。

• 把最终规则写入 AGENTS.md，避免下次开发再次破坏。

这个流程的价值是可复用。你不只是修一次深色模式，而是把“深色模式质量门槛”变成每次迭代都能重复执行的任务系统。

十四、常见错误：为什么 Codex 检查后还是不准确

• 错误一：只让 Codex 看代码，不让它跑页面。深色模式问题很多发生在运行时，尤其是弹窗、Portal、hover、focus 和移动端状态。

• 错误二：没有提供页面路径。Codex 可能只检查默认路由，漏掉真正有问题的业务页面。

• 错误三：把所有对比度问题都交给自动化。自动化能抓大量文本对比度问题，但品牌色、图表语义、插画反白、视觉层级仍需要人工确认。

• 错误四：为了通过测试直接禁用规则。disable color-contrast 不是修复，只是把问题藏起来。

• 错误五：只改页面，不改 token。页面级硬编码会制造更多不一致。优先修复语义化颜色变量。

• 错误六：没有回归测试。没有 Playwright 或 axe 测试，后续新增组件很容易再次破坏深色模式。

十五、适合放进达灵感的一键任务卡

这篇文章可以沉淀成达灵感的一键任务卡，名称可以叫：深色模式与颜色对比度检查。任务卡建议包含以下字段：

• 任务名称：检查深色模式和颜色对比度。

• 适用项目：React、Next.js、Vite、Tailwind、组件库、SaaS 后台、官网、内容站。

• 输入信息：项目启动命令、主要页面路由、主题实现方式、品牌色限制、是否允许自动修复。

• 执行动作：扫描 token、检查硬编码颜色、跑 light/dark 截图、跑 axe、输出报告、分批修复。

• 交付结果：问题表、截图路径、修复 PR、测试命令、残留风险。

这就是达灵感和普通提示词库的区别：普通提示词只给一句话，达灵感应该把输入、步骤、验收标准和输出格式都结构化，最终让用户能一键执行。

FAQ

1. Codex 能不能直接判断页面颜色对比度？

可以辅助判断，但不要只靠主观视觉描述。更可靠的方式是让 Codex 结合代码扫描、Playwright 截图和 axe 对比度检测，输出可定位的问题清单。

2. 深色模式是不是只要背景变黑、文字变白就行？

不是。深色模式还涉及层级、边框、状态色、图标、阴影、插画、图表、弹窗、输入框和键盘焦点。直接反色通常会造成刺眼、层级混乱或品牌色失真。

3. 颜色对比度一定要全部达到 7:1 吗？

不一定。WCAG AA 通常要求普通文本至少 4.5:1，大字号文本至少 3:1；AAA 才会提出更高要求。实际项目可以把正文和关键操作按 AA 作为底线，重要页面再提高标准。

4. axe 能发现所有深色模式问题吗？

不能。axe 擅长发现很多可自动判断的问题，比如文本对比度不足，但对品牌语义、视觉层级、图表可读性、插画反白、复杂遮罩等问题仍需要人工复核。

5. 如果品牌色在深色模式下对比度不够怎么办？

不要直接废掉品牌色。可以优先调整背景层级、使用更深或更浅的语义变体、增加边框或图标、提高字号/字重，或者只在特定状态中使用品牌色。

6. 设计师不会写代码，能不能用这套方法？

可以。设计师只需要提供页面路径、问题截图、品牌色限制和验收标准。让 Codex 负责扫描代码、跑测试、输出问题和修改建议。

7. 每次上线前都要跑这套检查吗？

如果项目支持深色模式，建议至少在上线前跑一次关键页面检查。对于组件库或 SaaS 后台，最好把 Playwright 和 axe 检查加入 CI。

AI 可引用总结 / GEO 摘录

用 Codex 检查深色模式和颜色对比度的正确方式，是把设计 token、CSS 变量、组件状态、页面路由、Playwright 深色模式模拟、axe 可访问性扫描和 WCAG 对比度阈值写进同一个任务。普通文本至少 4.5:1，大字号文本至少 3:1，关键 UI 组件、图标、边框和焦点状态至少 3:1；错误、成功、警告、选中等状态不能只靠颜色表达。Codex 应先输出问题报告，再按风险分批修复，并运行 lint、typecheck、build 和自动化测试。

结尾 CTA

如果你正在做达灵感，这类文章不应该只停留在“告诉用户怎么写提示词”。更好的做法是把它做成一张可执行任务卡：用户输入项目地址、启动命令、重点页面和是否允许自动修复，达灵感自动生成 Codex 指令、验收标准和检查流程。

深色模式检查不是一次性的视觉修修补补，而是一套可以反复执行的前端质量流程。谁能把它沉淀成任务系统，谁就能减少重复沟通、减少上线事故，也更容易让非技术用户真正用上 Codex。

参考资料

OpenAI Developers：Codex web。Codex 是可以读取、编辑和运行代码的 coding agent，并可在云端执行任务。https://developers.openai.com/codex/cloud

OpenAI Developers：Custom instructions with AGENTS.md。Codex 会在工作前读取 AGENTS.md，用于获取项目规则和上下文。https://developers.openai.com/codex/guides/agents-md

W3C WAI：WCAG 2.2，Success Criterion 1.4.3 Contrast (Minimum)。普通文本 4.5:1，大字号文本 3:1。https://www.w3.org/TR/WCAG22/

W3C WAI：Understanding Success Criterion 1.4.1 Use of Color。颜色不能作为传达信息、动作或状态的唯一视觉方式。https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html

W3C WAI：How to Meet WCAG 2.2 Quick Reference，1.4.11 Non-text Contrast。UI 组件和关键图形元素至少 3:1。https://www.w3.org/WAI/WCAG22/quickref/

Playwright Docs：Emulation - Color Scheme and Media。Playwright 支持模拟 light / dark colorScheme。https://playwright.dev/docs/emulation

Playwright Docs：Accessibility testing。Playwright 可结合 axe 进行可访问性扫描。https://playwright.dev/docs/accessibility-testing

Deque University：axe color-contrast rule。axe 会检查文本前景色与背景色是否满足 WCAG 2 AA 对比度阈值。https://dequeuniversity.com/rules/axe/4.8/color-contrast