frontend

前端

这个文件是路由器，不是规则手册。规则位于 references/ 下的四套规则中，阅读这些规则才是正事，而非前言。在处理任何文件之前，先列出请求会路由到哪些参考文档，以及需要每份文档的唯一原因，然后只阅读这些文档。先声明文档集合，才能让选择经得起审查：你从未列出的参考文档，就是你决定跳过的文档；你列出却从未打开的参考文档，则是你仍需补上的缺口。跳过路由指定的文档自行发挥，只会产出这项技能旨在避免的泛泛 AI 垃圾内容。

标准不只是整洁且正确，而是要达到 Linear、Stripe 或 Supabase 的资深设计师会交付的水准。 正确却平淡，就是失败，而非完成。像保护构建成果一样用心维护界面：设计是首要交付物，不是一锤定音后便置之不理的决定。

阶段 0 — 路由（任何 UI 工作之前）

请求涉及……	阅读
任何 UI 实现、样式设计、重新设计、模型图或视觉决策	首先阅读 references/design/README.md。它会强制执行两个必经关卡——设计系统关卡（编写任何组件之前必须存在 DESIGN.md）和 React 开发工具关卡（默认安装 react-grab / react-scan / react-doctor）——然后再引导至下方的品味与品牌参考资料。
空间结构——应用外壳、滚动区域归属、“内容放在哪里”、“此布局在 X 处会出问题”	还要阅读 references/design/layout-skill.md 了解实现机制，然后阅读 references/design/stylegallery.md，获取针对该具体空间问题的命名模式规范。两者都建立在样式技能之上，不提供视觉方向。
分页输出——PDF 报告、打印样式表、无头 Chrome 打印流水线、打印成纸质版的 HTML 演示文稿，或任何“为什么这一页有一半是空的”分页缺陷	还要阅读 references/design/print-paged-media.md，了解页面框、分页属性、原子块集合，以及可能导致内容块孤零零留在近乎空白页面上的保持整体副作用。它不提供视觉方向，并建立在所路由到的样式技能之上。
交互或动效工作——微交互、动画组件、过渡效果、手势、悬停／按压／状态反馈、“让它更生动”	还要阅读 references/design/interaction-skill.md。beui.dev 目录是必读的交互参考：找到最接近的模式，通过文件中的 curl 配方阅读其真实源码，并将实现机制调整为符合 DESIGN.md 中的动效令牌。它建立在所路由到的样式技能之上，绝不取代它。
Hero 区域的氛围或环境效果——动画、着色器、粒子或网格背景；字体呈现效果（拆分、模糊、闪烁、打字机、递增计数、跑马灯）；滚动叙事；聚光灯／倾斜／眩光／发光边框卡片表面；“让 Hero 区域惊艳”“添加动态背景”“为标题添加动画”	还要阅读 references/design/ambience-skill.md。react-bits 目录是必读的氛围效果参考：在其意图映射中找到最接近的模式，通过文件中的 curl 配方阅读其真实源码，提取实现机制，并在发布前完成改造检查清单（减少动效、离屏暂停、仅使用合成器、令牌、预算）。它建立在所路由到的样式技能之上，绝不取代它，也绝不引入 react-bits 代码。
需求的基调或表面形式不符合两个参考方向——AI Agent UI、图表、落地页区块、粗野主义或仅用 Tailwind 构建——或者参考方向中没有接近的模式	还要阅读 references/design/component-catalogs.md：了解适合该基调的目录、探索流程，以及使用其他目录时必须通过的许可和条款关卡。
编写或修改前端代码，或审计性能／SEO／无障碍性／质量	还要阅读 references/perfection/README.md。每个类别的 Lighthouse 得分都要达到 100，并在真实的 Playwright Chromium 上测量（绝不使用 lighthouse CLI）；通过架构实现这一目标，绝不通过删除动画或隐藏内容。
查找具体的样式、调色板、字体搭配、图表类型、落地页结构或 UX 指南，或根据关键词生成设计系统	阅读 references/ui-ux-db/README.md。这是带有 CLI 的可搜索 CSV 数据库：它是查询工具，不是设计立场的依据。design 仍是品味与 DESIGN.md 规范的真实来源。
任何会创建或更新 DESIGN.md 的实现或重新设计，以及明确提出的运作层面需求（角色设定、评审、技术债务、交接、合成用户测试）	阅读 references/designpowers/README.md 和 lane-c-review.md。lane-c 是 Phase Final 的单调问题／评审检查者，并会补全 DESIGN.md 要求的无障碍约束与已接受债务章节。仅在其他泳道所处阶段适用时加载它们。

对于实现工作，design 和 perfection 必须同时加载。 视觉效果出色但包体积为 2 MB，仍然不合格；Lighthouse 得分达到 100 但看起来像 AI 垃圾产物，同样不合格。要么两者都达标，要么都不达标。

草稿规范 — 编写第一行 UI 代码前请阅读

某些问题通常会在重新生成时默认出现，因此应在初稿阶段就避免，而不是留给 QA 发现。

• 圆角表面上不得出现彩色边缘，无论是装饰还是状态标记。 卡片、提示框、统计信息块、推荐语、警报或列表行，任何一侧都不得带有彩色条纹：例如圆角框上的 border-top: 4px solid <accent> 或 border-l-4 border-indigo-500、框内彩色的 ::before／::after 条、嵌入式 box-shadow 条纹，或沿某条边带有明显色阶断点的渐变色带或渐变 border-image。圆角会让条纹绕过转角，无论条纹用于装饰卡片，还是标记其已选中、聚焦或激活，最终效果都像是生成出来的。应通过其他方式赋予卡片个性：使用色调表面（低透明度的单色，或表面色阶中的下一级）、用强调色文字设置眉题或标题、添加前置字形，或拉大组间距。使用不同透明度的同一颜色（悬停／选中／激活时的底色）、表示选中的勾选字形，以及色调叠层来编码状态。允许保留的彩色边缘包括：键盘 focus-visible 焦点环、表单输入项的验证状态、中性色 1px 细线和分隔线，以及表格边框。此规范也适用于你触及的任何表面上已有的实例。
• 先运行 lint，再进行视觉 QA。 对你编写的每个样式表和组件运行 bun $SKILL_DIR/scripts/perfection/check-accent-stripes.ts <changed files or dirs>。它会检查 CSS／SCSS／Less、HTML、JSX／TSX、Vue、Svelte、Astro、Tailwind 类（包括 @apply 和 cva／cn 字符串）、内联样式和 styled-components。退出码为 1 表示初稿中存在条纹：移除条纹，不要质疑检查结果。

设计系统与组件工作流

每次实现都必须在修改 UI 代码前选择以下分支之一：

1. **具体的视觉参考：**用户提供了参考——将其视为视觉规范，并根据类型处理：
   • 静态视觉参考（截图、生成的样稿、Stitch/Imagen 输出、Figma 导出、概览或带注释的素材包）：加载 references/design/image-to-code-skill.md 以及相关的设计和精修文件，提取参考中的精确设计令牌、布局几何、文案、间距、状态和响应式意图，写入 DESIGN.md，然后依据该规范实现可复用的基础组件。
   • 实时网站或 URL 参考（用户指定要克隆的网站或提供 URL）：加载 references/design/clone-from-url.md。使用真实浏览器，通过 getComputedStyle 提取运行时的实际样式——设计令牌、布局几何、默认／悬停／焦点／激活状态、过渡和关键帧，以及下载的素材——写入 DESIGN.md，然后依据该规范编写可复用基础组件的克隆代码。 两种情况的最终 QA 都要以参考还原模式运行 /visual-qa：逐像素比较实际 UI 与参考，并确认代码实现的是可扩展的设计系统，而不是只匹配截图的一次性方案。
2. **从零开始或全新设置：**如果用户没有提供具体的视觉参考，设计调研就是构建步骤，必须产出明确交付物——不能将其视为可酌情缩减的探索。此处不适用“探索足够了”或“两轮上限”等停止探索的惯例。在撰写 DESIGN.md 之前，并行启动每条调研路径；并以 ## 0. Research Log 作为 DESIGN.md 的开头，记录每条路径的交付物——没有对应 Research Log 条目的路径就视为未执行。只有在工具或网络确实不可用时才可跳过某条路径，并在 DESIGN.md 中说明跳过原因：
   • **内置参考：**使用 references/design/_INDEX.md 初步筛选 2-3 个可能适用的 Layer B 参考，然后完整阅读且仅阅读一个 Layer A 风格技能和一个 Layer B 参考——必须逐行阅读，不得只读部分内容（这些文件有 200-500 行；只读节选会产生此关卡旨在避免的扁平化设计令牌集）。记录候选列表、最终选择及选择原因。只有精选内容中没有合适参考时才使用 open-design；涉及调色板／字体／领域的问题可补充查询 ui-ux-db。
   • **Lazyweb 真实产品页面：**先阅读 references/design/lazyweb.md，并严格按照其中的流程操作——不要自行尝试调用 lazyweb.com 的 curl 命令；该流程会生成自己的匿名令牌。记录执行的查询、实际查看的页面数量，以及提炼出的布局语法——绝不复制像素。
   • **StyleGallery 空间模式：**阅读 references/design/stylegallery.md，并获取主要空间问题与当前屏幕相匹配的模式。记录采用的模式，以及负责滚动的元素。
   • **Imagen 概念草稿：**生成 2-3 个 Imagen 概念草稿，每个草稿都以已加载的 Layer A 和 Layer B 设计令牌（调色板、字体、材质）为基础；选出最佳方案，并将选定草稿视为参考还原规范。记录草稿路径和最终选择。 将每条调研路径的结果综合到 DESIGN.md 中。将参考来源视为素材，而非风格标签：提取设计令牌、布局语法、组件结构、交互状态、动效和设计取舍，再将其重新组合为适合项目的基础组件。规划版块布局前，先盘点内容块并为每块分配作用——吸引、说明、证明、比较、转化、导航或留存——然后按照访客的决策路径排列版块，而不是追求视觉对称。绝不要脱离选定的参考自由发挥，也绝不要复制徽标或品牌专属文案。之后，在任何产品屏幕开发之前运行基础组件展示关卡（references/design/README.md 的 Phase 0）。
3. **已有 DESIGN.md 或组件系统的项目：**先阅读并遵循现有规范；仅当所请求的工作需要新增设计令牌、基础组件、状态、动效规则、无障碍要求、接受的技术债务或参考还原要求时，才在实施前更新它。
4. **已有 UI，但没有 DESIGN.md 和可复用组件层的项目：**停止并向用户提出一个聚焦问题：应保留当前外观并仅调整附近的样式，还是先提炼出正式的 DESIGN.md 和可复用组件再继续？不要擅自替用户做决定。 生成的 DESIGN.md 是实现契约：在代码使用设计令牌、字体排版、间距、基础组件、动效、响应式行为、无障碍约束和已接受的技术债之前，必须先在其中明确说明。使用真实的视觉 QA 证据验证组件基础元素、状态和最终界面；对于重要的实现工作，将设计系统决策、实现证据和未解决的技术债传递给 /review-work。

规则集 1 — 设计（references/design/）

参考库包含一个架构文件、12 个风格技能（A 层——如何执行）和 70 个品牌设计系统（B 层——应该呈现什么样子）。大多数非简单任务会加载一个 A 层技能 + 一个 B 层系统。README.md 包含完整的路由流程、叠加规则、反模式和强制执行的基于浏览器的设计 QA 阶段；_INDEX.md 列出了全部 83 个文件，并提供从氛围到品牌的映射——如果无法根据下表明确路由，请阅读该文件。

第 0 层 — 架构

文件	阅读时机
design-system-architecture.md	项目没有 DESIGN.md（定义必须首先创建的结构——8 个章节，以及仅适用于绿地项目的 ## 0. Research Log），或者你正在从现有 UI 代码中提取设计系统时。

A 层 — 风格技能（最多选择一个风格技能；这些技能代表相互对立的理念）

文件	用户提到……时阅读
taste-skill.md	中性或偏功能性的 UI，没有表面表现力诉求——内部工具、仪表板、“只要能用就行”。这是安全的默认选项；如果需求体现出光鲜、高端或创业公司级别的工艺水准，就不要停留在此处。
gpt-tasteskill.md	“Awwwards 级别”“惊艳效果”“电影感”“滚动触发”的营销或落地页体验。
minimalist-skill.md	“极简”“简洁”“类似 Notion”“类似 Linear”“编辑风格”。
brutalist-skill.md	“粗野主义”“原始”“瑞士风格”“实验性”“反设计”。
soft-skill.md	“高端”“奢华”“平静”“昂贵”“优雅”，以及光鲜、玻璃质感、液态玻璃或创业公司级别的产品界面——搭配高工艺水准的 B 层系统（supabase、linear.app、vercel、stripe）。
redesign-skill.md	改进现有 UI——“这看起来很糟”“改进设计”。采用先审查的工作流；绝不要用于绿地项目。
image-to-code-skill.md	“先生成设计，再编写代码。”与下方一个 imagegen 文件搭配使用。
output-skill.md	当输出不完整时，叠加到任何风格技能上——例如占位内容、// TODO、未完成的组件。
stitch-skill.md	需要兼容 Google Stitch 或导出 DESIGN.md 文档时，叠加到任何风格技能上。stitch-design-example.md 提供了一份完整的导出示例。
interaction-skill.md	工作会新增或更改交互或动效时，叠加到任何风格技能上。以 beui.dev 为依据：设计交互前，先阅读映射组件的源码；始终支持减少动态效果。
ambience-skill.md	工作会新增主视觉氛围、动画背景、字体显现效果、滚动章节或卡片表面效果时，叠加到任何风格技能上。以 react-bits 为依据：阅读映射组件的源码，提取其机制，并运行改造检查清单；每个主视觉区域只使用一种氛围效果，隔离光标效果。
imagegen-frontend-web.md / imagegen-frontend-mobile.md / imagegen-brandkit.md	仅输出图像（模型图、应用屏幕概念图、品牌板）。这些文件绝不编写代码——如果需要代码，请改用 image-to-code-skill.md。

B 层 — 品牌设计系统（与 A 层正交；可自由叠加）

当用户提到某个品牌或网站时，例如“Linear 风格”“像 Stripe 的落地页”“Aside 风格的浏览器 Agent”，请将 references/design/<brand>.md 作为设计令牌的唯一依据（配色、字体比例、组件、注意事项）。覆盖范围包括 aside apple stripe linear.app notion vercel claude figma airbnb nike tesla spotify raycast revolut 及另外约 56 个品牌；完整列表和风格快捷方式见 _INDEX.md。提取设计令牌并应用于项目自身内容，切勿复制徽标或受商标保护的图像。如果找不到指定品牌，请选择匹配的 A 层风格，或使用 open-design 技能。

React 开发工具

文件	阅读时机
react-dev-tooling-skill.md	React 项目缺少 react-grab / react-scan / react-doctor，或需要按框架区分的安装片段以及仅在开发环境启用的模式（NODE_ENV === 'development'）时。

规则集 2 — 完美（references/perfection/）

文件	阅读时机
README.md	编写或审查任何前端代码时。包含七项原则：只进行真实浏览器审查、每个类别至少达到 100 分、从架构层面修复、绝不为了得分牺牲 UX、检查是否遵循设计系统，以及审查报告的响应格式。
react-perf-tooling.md	进行任何 React 审查之前。介绍 Playwright + playwright-lighthouse + react-scan/lite 注入方案、各路由的渲染预算，以及 React 专用的根因检查清单。Lighthouse 得分为 100，但存在 30 次以上不必要渲染，仍不算完成。

审查 CLI（先构建生产版本；绝不测量开发服务器）：

uv run $SKILL_DIR/scripts/perfection/lighthouse-audit.py https://localhost:3000

运行移动端和桌面端预设，各执行 3–5 次，取中位数，并根据 JSON 报告进行诊断。

规则集 3 — ui-ux-db（references/ui-ux-db/）

README.md 介绍搜索 CLI 和主数据加覆盖项的持久化模式。CLI（从规则集目录运行，以便找到 data/）：

python3 $SKILL_DIR/references/ui-ux-db/scripts/search.py "<query>" --design-system -p "Project"   # full design-system generation
python3 $SKILL_DIR/references/ui-ux-db/scripts/search.py "<query>" --domain <domain>             # targeted lookup
python3 $SKILL_DIR/references/ui-ux-db/scripts/search.py "<query>" --stack <stack>               # stack best practices

领域：product style typography color landing chart ux react web prompt。技术栈：html-tailwind（默认）react nextjs vue svelte astro swiftui react-native flutter shadcn jetpack-compose。

规则集 4 — designpowers（references/designpowers/）

README.md 将固定版本的 Owl-Listener/designpowers 语料库引入此工作流。它提供设计背景——人物角色、无障碍与认知限制、评审、技术债务、交接、合成用户测试、动效、角色提示词——这些内容必须先提炼到 DESIGN.md，再作为实现约定使用。它不能取代任何内容：无论是此技能，还是 /visual-qa、/ulw-plan、/ulw-execute 或 /review-work。

快速路径 — 最常见的请求

请求	加载
“构建一个落地页”（未提供方向）	design/README.md + design/_INDEX.md 候选列表 → 恰好一个 Layer B 参考 + design/taste-skill.md + perfection/README.md
“旁置式 AI 浏览器／浏览器 Agent 页面”	design/README.md + design/aside.md + design/taste-skill.md + perfection/README.md
“Linear 风格的落地页”	design/README.md + design/linear.app.md + design/taste-skill.md + perfection/README.md
“像 Stripe 一样的高端 SaaS 主视觉”	design/README.md + design/stripe.md + design/soft-skill.md + perfection/README.md
“改进这个现有仪表板”	design/README.md + design/redesign-skill.md + perfection/README.md
“添加微交互”／“为这个添加动画”／“让它更生动”／“润色交互效果”	design/README.md + 在当前风格技能之上添加 design/interaction-skill.md + perfection/README.md
“让主视觉惊艳”／“添加动态背景”／“为标题添加动画”／“数字递增／打字机／跑马灯”／“卡片聚光或倾斜效果”	design/README.md + 在当前风格技能之上添加 design/ambience-skill.md + perfection/README.md
“精确复现这张截图／Imagen 样图／Stitch 输出”	design/README.md + design/image-to-code-skill.md + perfection/README.md + /visual-qa 的参考保真模式
“审查我的网站”／“让这个页面更快”	perfection/README.md（如果使用 React，则添加 perfection/react-perf-tooling.md）
“金融科技应用的样图”——不需要代码	design/imagegen-frontend-mobile.md（如果指定了品牌，则添加一个 Layer B 品牌）
“什么配色／字体适合健康品牌？”	ui-ux-db/README.md → 搜索 CLI
“应该把这个放在哪里？”／“布局崩了”／滚动 + 容器约束	design/layout-skill.md + 当前风格技能中的 design/stylegallery.md
“这个领域已上线的应用是什么样的？”／设计方向研究	design/lazyweb.md（仅 curl）+ design/_INDEX.md 候选列表
“配置这个 React 项目”	design/README.md + design/react-dev-tooling-skill.md
“使用 designpowers”／“强化设计工作流”／“添加角色设定／无障碍／技术债／交接”	design/README.md + designpowers/README.md（如果后续涉及实现或审查，则添加 perfection/README.md）

共享公理（四套规则都认同——始终适用）

• 没有设计系统 = 不做 UI 工作。 DESIGN.md 必须先于组件创建；每种颜色、字号和间距值都必须对应其中的一个设计令牌。
• 具体参考 = 契约。 如果有截图、样稿或带注释的参考，除非用户接受偏差，否则就要匹配其像素、文案、组件结构和响应式意图。
• 绝不为了拿分而削弱 UX 或扁平化界面。 不得为了 Lighthouse 分数或赶工而移除动画、隐藏内容、简化交互，或用纯色填充和扁平几何图形取代渲染材质或带光照的材质。既要达到 100 分，又要保持界面的立体感；两者都做到，否则都不做。
• 图标不得使用表情符号。 只能使用 SVG 图标集（Lucide、Heroicons、Radix、Phosphor）。
• 圆角表面不得添加彩色边缘。 卡片上的装饰性强调条、选中行上的 border-l-2 border-primary 强调条，以及聚焦卡片上的主色调描边，本质上都是同一种明显的视觉套路。上面的 Draft 防护措施列出了替代方案和允许的例外；运行 check-accent-stripes.ts 必须退出码为 0，才能进入 /visual-qa。这既适用于你编写的代码，也适用于你接触的界面中已有的实例——请彻底清除它们。
• 动画只能使用 GPU 合成属性——transform、opacity、filter；绝不动画化布局属性。
• 禁止无意义动画——动效必须传达意义。 每个动画或悬停效果都必须对应真实的交互、状态变化或操作提示。无变化的悬停效果、非交互元素上的动效，或没有信息用途的装饰性微动画都是无意义动效——不要添加。
• 完成与否由 /visual-qa 门禁判定，而不是靠自己看一眼。 前端设计任务必须通过 /visual-qa 验证——包括基于 HIG 的清单、捕获矩阵（每个页面和每个同级界面、手机和桌面、浅色和深色、滚动到末尾、驱动并检查动效），以及基于新证据的双重判定完成门禁。此技能不会维护自己的视觉检查清单；验证器负责管理。

何时改为加载其他内容

情况	加载
references/design/ 中的 70 种风格都不符合品牌／样式，或用户说“Open Design”	open-design 技能——本地的 nexu-io/open-design 库（137+ 种设计技能、150+ 套设计系统）
在设计 QA 阶段驱动浏览器	visual-qa 技能：通过 js eval 使用 omowright（用于渲染的自有引擎；用于已登录页面的附加引擎）
纯 TypeScript／逻辑工作，完全没有视觉界面	仅使用 programming 技能——此技能对此类任务没有帮助

激活

适用于任何前端、Web UI、UX、视觉、设计、样式、布局、动画、性能、无障碍或 SEO 工作——包括构建、重新设计、审查或生成样稿。不适用于后端、CLI 或没有视觉界面的纯逻辑任务。