ckmirafss/easy-on-the-eyes

轻松养眼（Easy on the Eyes）

屏幕前的眼部疲劳大多来自网站无法触及的因素：眨眼频率、对焦距离、未矫正的视力、环境光线等。网站能控制的是它要求用户付出多少额外的视觉工作。本技能消除这些额外工作，并明确每条规则背后的证据强度。

同时，它也能让舒适的页面看起来不像是模板。在设计之前，它会研究真实的上线网站，并携带一套工艺规则，用于区分手工打造和 AI 生成的作品。

你可以做出的声明

可以声称设计“不增加可避免的视觉负担”。绝对不能声称设计能预防、减少或治愈眼疲劳，保护眼睛，或具有“防蓝光”功效。不要将深色模式、暖色滤镜或特殊字体描述为健康功能。如果用户要求这类文案，请解释原因并提供诚实的措辞。

模式

根据调用技能时的参数来决定操作模式。

• 无参数，或构建任务。 对于新页面或新章节，首先研究参考站点（参见“设计前先研究”）。然后在编写或编辑 UI 时应用规则。如果项目还没有颜色或字体 token，从 assets/tokens.css 开始。UI 编写完成后，对源码运行 audit.mjs，对渲染后的页面运行 inspect.mjs，并在宣布完成之前检查“脚本无法发现的内容”。
• audit（可选后跟路径）。运行脚本，然后检查脚本无法发现的内容。使用下方模板报告。不修改任何内容。
• study 后跟一个或多个 URL。检查每个页面并报告其设计简报：它做了什么、哪些值得借鉴以及它违反了哪些舒适性规则。不修改任何内容。
• fix（可选后跟路径）。运行审核。修复错误，然后修复警告。除非修复某个错误或警告依赖于某条注释，或者你自己的审查显示它确实是个问题，否则不要改动注释。重新运行脚本并报告。

运行脚本

从项目根目录运行，并提供要检查的路径。脚本位于本技能的 scripts/ 文件夹中，因此请使用加载本技能的路径：

node <skill-dir>/scripts/audit.mjs src                 # 文本报告，有任何错误则退出码为1
node <skill-dir>/scripts/audit.mjs src --json          # 机器可读
node <skill-dir>/scripts/audit.mjs src --strict        # 警告也导致退出码为1
node <skill-dir>/scripts/audit.mjs contrast "#1f2328" "#ffffff"          # 检查一对颜色
node <skill-dir>/scripts/audit.mjs contrast "#8a8f98" "#ffffff" --min 3  # 针对边框或图标

node <skill-dir>/scripts/inspect.mjs https://example.com              # 设计简报和渲染后的舒适性检查
node <skill-dir>/scripts/inspect.mjs http://localhost:3000 --out shots # 同时保存明暗截图
node <skill-dir>/scripts/inspect.mjs dist/index.html --json

• audit.mjs 读取源文件。inspect.mjs 在真实浏览器中打开页面，因此它测量的是读者实际看到的内容：真实文本在其真实背景上的对比度、每行真实字符数、是否存在深色方案，以及当请求减少动效时动画是否停止。
• inspect.mjs 适用于任何 URL 或本地 HTML 文件。它需要项目中安装 Playwright（npm i -D playwright && npx playwright install chromium）。如果缺失且无法安装，请说明渲染后的检查未运行。
• 路径是必需的。如果用户未提供路径，则使用包含 UI 源码的文件夹。
• 颜色可以是十六进制、rgb()、hsl()、oklch()、white 或 black。
• 要静音某个被认为是故意的发现，在该行上添加包含 easy-on-the-eyes-ignore 的注释，或在前一行上添加 easy-on-the-eyes-ignore-next-line。
• 脚本需要 Node 18 或更高版本，且无其他依赖。如果 Node 缺失，则手动应用规则并说明脚本未运行。

两个脚本都使用下表中的规则 ID 进行报告。在你的报告中也应使用相同的 ID。

设计前先研究

模型会产生它所见过内容的平均值，而平均值正是人们能识别出是 AI 生成的东西。先看看具体的、已上线的作品，你就能对真实的决策做出反应。

1. 挑选三到五个与你要构建的内容同类别的线上站点。使用用户指定的站点。否则通过网页搜索，或通过接入会话的任何设计参考或截图工具来查找。
2. 对每个站点运行 inspect.mjs，加上 --out 参数，以便你打开截图查看。
3. 对每个站点，记录其字体和字号缩放、使用的颜色数量及强调色的位置、行宽、章节结构，以及使其具有辨识度的一个特点。
4. 阅读每个参考站点的舒适性检查结果。受人尊敬的站点常常会有很小的字号、较弱的对比度和过度的动效。借鉴其结构，但忽略这些问题。references/craft.md 中有对照表。
5. 告诉用户你研究了哪些站点以及从每个站点借鉴了什么。借鉴结构和决策。绝不复制品牌的名称、标志、文案、图片或精确布局。

如果无法打开任何参考站点，请说明情况，然后根据规则和 references/craft.md 进行设计。

证据等级

每条规则都带有一个等级。在解释某个发现时重复该等级，这样就不会有人将习惯误认为事实。

等级	含义
research	有受控研究或系统综述支持
standard	由 WCAG 2.2 成功标准设定。参考文件给出了该标准及其级别
convention	合理且被广泛采用，但背后没有试验支持
inference	从相关刺激物的研究中推导而来，尚未在网页上进行测试

规则

严重性决定处理顺序：先是错误，然后是警告，最后是备注。在相同严重性内，按表格从上到下处理。表格中显示的是通常的严重性。当脚本无法确定某行是否为问题时（例如小字号可能是标签），它会降低严重性；而当你审查后发现确实存在问题时，可以提高严重性。

ID	规则	严重性	等级	参考文件
type-rem-zoom	文本必须能随缩放生存。使用 rem 单位，不能使用仅视口相关的字体大小，从不禁止缩放。	错误	standard	typography
contrast-floor	每个文本对比度至少 4.5:1。大文本和 UI 元素至少 3:1。	错误	standard	contrast-and-color
contrast-color-alone	绝不能仅用颜色来表示状态。	错误	standard	contrast-and-color
motion-flash	任何闪烁频率不超过每秒三次。	错误	standard	motion
motion-autoplay	无自动播放的视频（除非有控件）。任何持续运动超过 5 秒（文本除外）必须可暂停。文本附近不能有无尽循环。	错误	standard	motion
motion-reduced	动画仅存在于 prefers-reduced-motion: no-preference 条件下。	错误	standard	motion
theme-focus	切勿移除焦点轮廓，除非有可见的、对比度至少 3:1 的替换方案。	错误	standard	theming
type-body-size	正文文本最小 1rem，长阅读时使用 1.125rem 到 1.25rem。任何可读内容不得小于 0.875rem。	警告	research	typography
motion-triggers	无视差、劫持滚动或大面积缩放。淡出和颜色变化是允许的。	警告	research	motion
contrast-dark-secondary	深色背景上的次级文本对比度至少 8.5:1。仅 AA 标准在那里显得不足。	警告	inference	contrast-and-color
contrast-saturated-on-dark	深色主题中避免使用饱和的红色或蓝色作为小字。在深色主题中使用更亮、更柔和的强调色。	警告	research	contrast-and-color
lum-section-steps	避免交替使用全出血的深色和白色区域。深色主题中避免白色嵌入内容或模态框。	警告	inference	layout-and-patterns
lum-white-flash	需要设置主题化的 html 背景以及 color-scheme 声明和 meta 标签。	警告	convention	theming
layout-shift	预留媒体尺寸，匹配后备字体的度量值，保持 CLS 小于等于 0.1。	警告	research	layout-and-patterns
contrast-pure-extremes	使用接近黑色搭配接近白色，或米白色搭配深灰色。避免使用纯黑和纯白作为页面文本和背景。	警告	convention	contrast-and-color
type-leading	正文 line-height 1.5（1.4 到 1.6）。标题 1.1 到 1.3。	警告	convention	typography
type-weight	正文字重 400 或以上。正文大小下避免使用 100 到 300 字重。	警告	convention	typography
type-align	使用 text-align: start。不要使用两端对齐的正文。大写字母仅用于短标签。	警告	standard	typography
layout-targets	指针触控目标最小 24x24 CSS 像素，主操作目标 44x44。句子中的链接除外。	警告	standard	layout-and-patterns
theme-both-schemes	提供明暗两种主题，并遵循 prefers-color-scheme。手动切换可选，默认为系统偏好。	备注	research	theming
pattern-stripes	避免在大面积区域上使用周期为 7 到 27 像素的高对比度条纹或网格。	备注	inference	layout-and-patterns
type-measure	阅读文本限制在 50ch 到 60ch 之间，即大约 65 到 78 个字符。	备注	convention	typography
motion-duration	动画时长 100 到 300 毫秒，最高 500 毫秒，入场使用 ease-out。	备注	convention	motion
theme-preferences	尊重 prefers-contrast、forced-colors 和 prefers-reduced-transparency。	备注	convention	theming
pattern-clutter	每个视图只有一个主要强调点。使用较少的强调色、字号和边框样式。	备注	research	layout-and-patterns
craft-copy	使用具体的文案。绝不编造统计数据、客户评价、评分或客户标志。	警告	convention	craft
craft-reference	在设计前研究三到五个相同类别的真实站点。借鉴决策，绝不复制。	备注	convention	craft
craft-one-idea	每个视图只有一个独特的创意。其他所有内容保持低调。	备注	convention	craft
craft-palette	使用带色调的中性色和一个强调色。避免使用靛蓝或紫色渐变，避免渐变色文字。	备注	convention	craft
craft-show-product	展示真实的界面、数据或代码。避免使用一排三个相同的图标卡片或 emoji 图标。	备注	convention	craft
craft-layout	不要将所有内容居中。使用不均匀的网格分割和多样的章节结构。	备注	convention	craft
craft-restraint	使用平面和发丝线。少用阴影，使用一套圆角半径，避免堆叠模糊和发光效果。	备注	convention	craft

参考文件保存了推理过程、来源和修改前后的代码。对于你正在应用或报告的规则，请阅读相应的参考文件。一次对整个页面的修复通常需要三到四个参考文件。

• references/contrast-and-color.md：选择颜色、构建调色板或深色主题、解释对比度发现。
• references/typography.md：字号、行宽、间距、字体、流式排版。
• references/motion.md：动画、过渡、视频、滚动效果、加载器。
• references/layout-and-patterns.md：表格、网格、条纹、密度、章节背景、图片、布局偏移。
• references/theming.md：明暗主题、主题切换、焦点样式、用户偏好媒体查询、Tailwind 和 shadcn/ui。
• references/craft.md：设计新页面或新章节、结果看起来模板化或 AI 生成、从参考站点借鉴什么及忽略什么。
• references/evidence.md：当用户问为什么、质疑某条规则、或问到关于蓝光、深色模式、阅读障碍字体或 APCA 时。

默认样式（无需询问即可写入）

:root {
  color-scheme: light dark;
  --bg:     light-dark(oklch(0.985 0.002 90), oklch(0.18 0.01 255));
  --text:   light-dark(oklch(0.24 0.01 255),  oklch(0.93 0.005 255));
  --muted:  light-dark(oklch(0.48 0.01 255),  oklch(0.78 0.01 255));
  --accent: light-dark(oklch(0.5 0.19 255),   oklch(0.74 0.13 255));
}
html { background-color: var(--bg); color: var(--text); }
body { font-size: clamp(1rem, 0.95rem + 0.25vw, 1.125rem); line-height: 1.6; }
p, li { max-inline-size: 55ch; }
:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
@media (prefers-reduced-motion: no-preference) {
  .card { transition: transform 200ms ease-out; }
}

在页面 <head> 中添加 <meta name="color-scheme" content="light dark">。

正文文本在浅色模式下对比度为 15.75:1，深色模式下为 15.30:1。弱色文本对比度分别为 6.25:1 和 9.39:1。强调色对比度分别为 5.78:1 和 8.14:1，因此用于焦点环：系统 Highlight 颜色在深色背景上可能低于 3:1。assets/tokens.css 包含完整的集合，包括表面色、控件边框色、长阅读字号和可选的暗化主题。

只有在页面真正为两种配色方案都设置了颜色后，才添加 color-scheme: light dark。在硬编码为浅色颜色的页面上，它会导致深色滚动条和表单控件出现在白色页面上。修复 theme-both-schemes 应在同一个更改中完成。

Tailwind 和 shadcn/ui 使用纯白色搭配近黑色（约 19.8:1），并且 bg-white / text-black 是纯值。请覆盖 --background 和 --foreground，并使用诸如 bg-background 和 text-foreground 之类的语义化工具类。

脚本无法发现的内容

当你能够在渲染后的页面上运行 inspect.mjs 时，它会覆盖下面列表中的第一、三和五项。通过阅读代码或页面来检查其余项目，以及当它无法运行时检查所有项目。如果你无法检查某个项目，请在“未验证”下列出并说明原因。

• 每个真实文本和背景对的对比度，包括图片和渐变上的文本。使用 contrast 命令测量对比对
• 小号文本是正文还是短标签
• 渲染布局中的行宽。在几个完整行中统计字符数
• 动画和视频的闪烁频率
• 各部分之间的亮度跳跃以及深色主题中的白色嵌入内容
• 加载过程中的布局偏移，包括没有设置 width 和 height 的图片和视频
• 状态是否仅通过颜色表示
• JavaScript 驱动的动画是否忽略了减少动效的偏好
• 以 em、百分比或 font 简写设置的大小，以及由 background-size 构建的条纹

报告模板

Easy on the Eyes — 审核报告
──────────────────────────────

检查路径：<路径>
模式：<模式>

错误
────
[15:21] ID: type-rem-zoom  所在行：<文件>:<行>
  <描述>
  ✓ 已修复

警告
────
[15:22] ID: contrast-floor  所在行：<文件>:<行>
  <描述>
  ✓ 已修复

备注
────
[15:23] ID: theme-both-schemes  所在行：<文件>:<行>
  <描述>
  保留（有意为之｜由修复 <ID> 引起）

未验证
───────
- <检查项>：<原因>

总结
────
<发现次数> 个错误，<发现次数> 个警告，<发现次数> 条备注

工艺规则参考

references/craft.md 中的工艺规则帮助确保你的设计看起来经过深思熟虑而非 AI 生成。它们处理在规则表末尾的 craft-* 条目中概括的具体选择。关键原则：

• 文案: 使用具体、准确的文案。不要编造统计数据、客户评价或有影响力的数字。
• 参考: 在设计前研究三到五个真实站点。借鉴其结构、调色板或布局理念，但绝不直接复制品牌元素。
• 一个创意: 每个视图应围绕一个独特、与众不同的理念展开。其他所有内容保持背景和辅助角色。
• 调色板: 使用带色调的中性色（例如暖灰或冷灰）和一个明确的强调色。避免常见的 AI 视觉模式，例如靛蓝到紫色渐变或渐变色文字。
• 展示产品: 突出显示真实的内容、界面截图或代码。避免使用图标卡片、emoji 图标或通用的占位符图形。
• 布局: 采用不对称或多样化的布局结构。避免将所有内容居中于单一的窄列中。使用不均匀的网格划分和变化的章节宽度。
• 克制: 使用扁平表面和发丝状边框。限制阴影数量、使用统一的圆角比例，并避免视觉上过于复杂的模糊和发光效果。

这些规则没有像对比度规则那样严格的证据基础，但它们封装了当前关于生成式 AI 设计模式何时显得不自然的共识。