2026年8月5日

frontend-ui 技能——HTTP 200 无法替代的检查清单

Datarim 如何通过结构化的九节检查清单,捕获那些能通过语法检查的反复出现的 UI 缺陷——暗色模式特异性陷阱、移动端视口破损、i18n 键漂移、无障碍缺口以及过时的组件计数。

一个返回 HTTP 200 且 HTML 有效的页面,仍可能在渲染时出现暗色模式破损、在 375px 屏幕上文本溢出、缺少 Open Graph 标签,或硬编码字符串以错误语言显示。frontend-ui 技能是一份结构化检查清单,适用于任何涉及 HTML、CSS、模板或视觉组件的任务。它能捕获单元测试和 HTTP 检查遗漏的那类反复出现的 UI 缺陷。

该技能会在任何修改 .html、.php 模板、.css、.vue 或涉及 UI 的 .tsx 文件的 /dr-do 中加载,也适用于任何类型为 "Website Development" 或 "Frontend" 的任务。它也是使用 /dr-compliance 关闭 UI 任务之前的合规参考。

暗色模式特异性——无声的破坏

暗色/亮色主题中最常见的 CSS 失败是 :not(.dark) 选择器。它会匹配任何不带有 dark 类的祖先元素——包括 <body>、<section> 以及所有其他容器。由于这些祖先元素同时也是目标组件的祖先,该选择器无论主题状态如何都会始终匹配,亮色颜色会基于层叠顺序泄漏到暗色模式中。

正确的模式是将亮色样式写为默认样式,不带类前缀,并将暗色覆盖写为 .dark .component。检查清单会验证 Tailwind 是否配置了 darkMode: 'class',任何 CSS 文件中是否出现 :not(.dark) 选择器,以及 <html> 上的初始 dark 类是否来自 localStorage。

视觉与视口验证

检查清单要求提供暗色和亮色两种模式的截图,并在 320px 和 375px(无水平滚动、文本可读)、768px(布局自适应)以及 1280px 及以上(max-width 容器正常工作)进行视口检查。对于多语言站点,i18n 部分会检查所有语言文件是否具有相同的键、语言切换器是否在每个页面都能工作、所有内部链接是否遵守 /en/ 和 /ru/ URL 前缀,以及文本布局是否能处理俄语文本相比英语多出的约 20–30% 长度。

在 /dr-qa 中,当涉及任何视觉部分时,会自动运行 Playwright 检查本地开发环境。该检查会捕获截图并将发现记录在 datarim/qa/playwright-{ID}/ 下。截图是否符合意图的视觉审查仍由操作员完成——自动检查捕获证据,但不裁定美学。

组件计数作为事实来源

该技能包含一条关于为内容或文档生成框架组件计数(代理、技能、命令)的规则。这些计数必须在写入时来自实时文件系统查询,绝不能来自会话记忆。此前的一次事故产生了一个页面,显示 "15 agents / 18 skills",而实际计数分别为 16 和 22,并且显示 6 个用例而不是 13 个。这三个错误都来自缓存数据,而不是 ls ... | wc -l 调用。

性能、无障碍与 SEO

其余部分涵盖无障碍(WCAG AA 颜色对比度、可访问的按钮标签、可见的焦点状态、减少动态效果支持)、性能卫生(无无界 CSS 动画、懒加载图片、font-display swap、延迟脚本)以及 SEO 和社交预览(唯一页面标题、元描述、Open Graph 和 Twitter Card 标签、规范 URL、多语言站点站点地图中的 hreflang)。每个部分都是简短、可操作的检查清单,而不是风格指南。

在 什么是 Datarim 中了解更多关于 Datarim 流水线的信息,或查看 health-controller-stub-detector 技能如何在实现阶段捕获另一类静默通过的缺陷。