ui-ux-kit

UI/UX 套件

设计出有明确意图、彰显品牌特色的界面——绝不千篇一律——并留下唯一真实来源（DESIGN_SYSTEM.md），确保未来的每个页面都保持一致。适用于各种场景：营销、仪表盘、应用、商店、内容/文档、移动端、改版以及独立设计系统。

按顺序执行以下步骤。其中四项不可妥协：

• 步骤 1：路由 — 应用正确的规则，而不是照搬同一套方案。
• 步骤 2.7：概念 — 开始构建前，先确定一个鲜明的创意。
• 步骤 4.5：对抗式评审 — 以批评者而非作者的视角审视成果。
• 步骤 5：文档 — 始终留下 DESIGN_SYSTEM.md。

最重要的一条原则：阅读需求说明并灵活调整。 每条规则都是经过权衡的默认选项，而非条件反射。需求说明与默认选项冲突时，以需求说明为准——明确说明后再继续。

此文件是始终加载的核心内容。更详细的信息存放于 references/，按需加载：

• references/surface-rules.md — 各种场景的规则（落地页、仪表盘、应用、移动端、商店、内容）。开始构建前，加载步骤 1 中对应配置的章节。
• references/quality-floor.md — 步骤 3/4 的详细要求：对比度计算、渐变/玻璃效果、图标、图片、完整的无障碍标准、九项性能优化手段以及官方设计系统表。进入步骤 3 时加载。
• references/experiential.md — 3D/WebGL/物理效果层级。仅在步骤 2 选择这些效果时加载。
• references/component-libraries.md — 能力→库速查表。
• references/DESIGN_SYSTEM.template.md — 步骤 5 的交付物模板。

---

步骤 1 — 分析需求，然后路由（必需）

1a. 提取需求说明

明确：场景类型（落地页/营销、仪表盘/管理后台、应用/产品、移动端、商店、作品集、改版、仅设计系统）、品牌、行业、受众、设计风格、配色系统（映射到 60/30/10）、字体排版意图、动画级别、卡片/区块风格、图片策略、技术栈/平台。 如果用户只提供了颜色和名称，就根据行业和风格推断其余内容——但要列出你的推断，方便用户纠正。

1b. 给出一句话设计解读

“我的理解是：面向 <audience> 的 <surface>，采用 <style> 方向，<color/type/motion summary>，使用 <stack> 构建。”

1c. 路由到场景配置（匹配第一项优先；注明混合场景）

匹配配置后，立即使用 Read 工具打开 references/surface-rules.md 中列出的章节，再开始构建——其中的规则和场景专属门槛是必需项，不可跳过。混合需求需要阅读两个章节。

配置	适用情况	→ 立即阅读
落地页 / 营销	落地页、营销、活动、作品集、长篇内容	references/surface-rules.md §B1 — 页面结构 + 主视觉区 + 转化
仪表盘 / 管理后台 / 数据	仪表盘、管理后台、分析、控制台、内部工具	references/surface-rules.md §B2 — 信息密度、表格、图表
应用 / 产品界面	Web 应用、SaaS 界面、设置、引导流程、工作流	references/surface-rules.md §B3 — 导航 + 表单 + 完整状态集
电商 / 商店	商店、店铺、商品目录、PDP、购物车、结账	references/surface-rules.md §B5 — 商品列表、PDP、购物车、结账、信任感
内容 / 编辑 / 文档	博客、文章、文档、知识库、新闻、长篇阅读	references/surface-rules.md §B6 — 阅读宽度、目录、正文
移动端 / 原生应用	iOS、Android、React Native、Flutter	references/surface-rules.md §B4 — HIG/Material、触控、安全区域
改版	现有界面的“redesign / improve / fix / clean up”	先审查（1d），再阅读匹配配置的章节
仅设计系统	“创建设计系统 / tokens / DESIGN_SYSTEM.md”	跳过页面构建 → 步骤 3 → 4 → 5；交付物就是设计系统

1d. 重新设计审查（仅限 Redesign 配置）

修改任何内容之前，先阅读现有代码和界面，并列出：（a）可正常运行且必须保留的内容（品牌、配色、信息架构、组件）；（b）根据第 3 步和预检门槛评估出的具体设计敷衍或质量问题；（c）能以最少改动解决最多问题的方案。不要大改没有问题的部分。查看当前界面也是审查的一部分——“未经要求不要打开浏览器”规则指的是构建之后的验证表演，而不是审查。你可以渲染或截取当前状态的屏幕来支撑审查（请说明）；如果无法做到，请注明审查仅基于代码，置信度较低。

1e. 类别直觉测试（选择颜色／主题前执行）

如果仅凭领域就能猜出你的配色——“金融科技 → 海军蓝 + 金色”、“医疗保健 → 白色 + 蓝绿色”、“加密货币 → 黑底霓虹色”、“咖啡 → 奶油色 + 棕色”、“AI 初创公司 → 深色背景上的紫色渐变”——那就是训练形成的直觉，而非经过考虑的选择。重新设计，直到配色不再能从类别一眼看出。只有当需求明确指定这些颜色时，才以需求为准。

---

第 2 步——只澄清缺失信息（必需）

利用用户已提供的信息。只询问确实缺失的内容。 重复询问已提供的信息本身就是一种失误。

1. 盘点提示内容——将每项检查清单标记为已提供（即使说得比较宽泛也算，例如“金融科技初创公司”、“品牌蓝 #1A4FFF”、“Next.js 仓库”）或缺失。
2. 通过 AskUserQuestion 只询问缺失项，每批不超过 4 项（通常最多一轮，而且往往无需提问）。如果信息均已提供，则跳过提问并复述需求。
3. 绝不重复询问，也绝不覆盖已指定的框架、配色或细分领域。

检查清单（仅在缺失时询问）：

1. 细分领域／行业——决定氛围和意象。
2. 技术栈／平台——采用现有项目的技术栈，无需询问。
3. 设计方向——提供以下选项：简约、现代、编辑风、醒目、奢华、粗野主义、活泼。
4. 配色方案——不要自行假定。提出 2–3 套有名称的配色（附十六进制代码），或询问用户的配色方案。如果用户已提供，则映射到 60/30/10 比例后继续。
5. 动画程度 + 库——无／微妙／流畅／丰富动效，以及 GSAP／Framer Motion／仅 CSS。
6. 图像／素材策略——AI 生成、图库、网络资源或用户提供。
7. 体验层级——标准（DOM + CSS/GSAP/Framer——合适的默认选项）或沉浸式（3D/WebGL/物理效果——仅在用户需要沉浸式体验且内容适用时采用；如果选择此项，构建场景前先阅读 references/experiential.md）。根据需求匹配层级——绝不强行使用 3D，也绝不将沉浸式需求简化。

Logo 是单独的问题（仅在尚未明确时单独询问）：提供 AI 生成／细分领域相关网络图像／文字字标等选项，并提前告知用户需提供 SVG/PNG 格式的 Logo。

收到回答后，用一段话复述完整需求，然后继续。

---

步骤 2.5 — AI 资源生成（绝不悄悄放弃）

当用户选择 AI 生成时，请生成真实图像——不要先检查是否有 API 密钥，发现没有后就降级为占位图。按以下顺序执行：

1. /chatgpt-image-gen — 首选，无需 API 密钥。 通过浏览器驱动用户已登录的 ChatGPT。如果尚未登录，请明确告知用户（“Chrome 窗口已打开——请登录，然后告诉我”）并等待确认。非交互式／无头运行（无人可以登录）：直接跳过此选项，转到选项 2；若选项 2 不可用，则搭建一个带有明确标记的占位资源模块，并注明必须重新生成——绝不要在无头运行中等待无法进行的登录，从而阻塞运行。
2. /ai-image-generation（inference.sh）：当设置了 INFERENCE_API_KEY 或用户提供了该密钥时使用；若缺少密钥，请询问用户，或提出切换到 /chatgpt-image-gen。

在构建前生成参考图像时，可考虑使用 /imagegen-frontend-web（每个版块一张）或 /imagegen-frontend-mobile。只有在用户明确同意时，才回退为自定义 SVG／文本标记。将生成的资源隔离（放在一个 Logo 组件／资源模块中），以便只需修改一个文件即可替换。

---

步骤 2.6 — 获取真实设计参考（非简单工作必做）

以经过验证的获奖作品为设计依据，而不是依赖模型取平均值后的默认风格——这是最有效的反套路做法之一。只有用户说“无需研究”或提供了参考时，才可跳过。

如果无法访问 Web： 请说明这一点，然后通过参考具体范例进行补足（“Linear 的信息密度／Stripe 的克制／Arc 的俏皮感”），并进一步依靠步骤 2.7 和类别惯性测试。明确说明无法获取参考。

风格关键词是首要搜索依据。 如果需求说明了风格方向（极简、编辑风、粗野主义、奢华、大胆、活泼、现代、瑞士风格等），则针对该风格进行三次搜索，并在构建前据此确定设计：

• 该风格的参考设计——“<style> <surface> design awards”。
• 该风格的配色方案——“best palettes for <style> <industry>”——然后在确定配色前，先用类别惯性测试筛选结果。
• 该风格的字体——“best fonts for <style> <surface>”——确认或调整从 Move A→C 得出的选择。

方法： 使用 WebSearch 搜索设计作品集，再用 WebFetch 获取热门结果中的具体设计模式。 以文本抓取以图片为主的作品集（Awwwards、Dribbble）时，能获取的视觉信息很少——如需真正以视觉为依据，请优先使用视觉浏览（通过 /use-my-browser／/agent-browser 截图）或参考具体范例；主要使用 WebFetch 获取结构、名称和文案。对于有登录限制的来源，请使用带有有效会话的浏览器技能。深入搜索：/deep-research。

来源： 落地页／品牌 → Awwwards、Godly、Land-book、Lapa Ninja、Httpster、Refero。 应用／仪表板 → Mobbin、Page Flows、UI Sources、Refero。移动端 → Mobbin、Apple／Google 作品集。灵感氛围 → Dribbble、Behance、Cosmos、Savee。

转化，不要克隆。 将每个参考都调整为适用于项目自身设计变量的形式。输出一条简短的“已获取参考”说明：附上 3–5 个链接，并说明从每个参考中借鉴的具体做法。

---

第 2.7 步 — 确定一个设计概念（必需）

避开禁用模式，仍可能得到干净却平淡的设计。解决办法是积极确立方向：开始构建之前，先确定一个独特的概念，并让它驱动具体决策。

用一句话写下来——一个具体的组织思路，而不是形容词：

“概念是：<一个具体的想法>——通过 <布局>、<字体>、 <颜色>、<动效> 来呈现。”

• 较弱：“现代、简洁、专业的金融科技仪表板。”（这是默认印象，不是概念）
• 较强：“一款充满精密仪器感的交易终端——处处使用等宽数字、纤细网格、近黑色背景搭配一种信号绿作为点缀，数据像行情 ticker 一样滚动呈现。”

概念必须可证伪（如果它可以描述任何竞品，就要进一步明确），并体现在 {布局、字体、颜色、动效、图像} 中的至少 3 项。将其记录为设计系统的“设计个性／概念”。对抗性审查会检查概念是否落实。

---

第 3 步 — 以品味进行设计（质量标准）

以下通用规则适用于所有界面。 开始构建之前，必须阅读 references/surface-rules.md 中与你在第 1 步选定的界面类型对应的章节，以及 references/quality-floor.md（对比度计算、渐变／玻璃效果、图标、图像、完整的无障碍标准、九项性能优化手段、官方设计系统表）。在遵循这些规则的基础上，再应用以下原则。如果你还没打开这些文件，现在就去阅读。

颜色——先定策略，再按 60/30/10 分配，并使用 OKLCH

• 先选定策略： 克制型（带色调的中性色 + 一种强调色，占比 ≤10%——产品／仪表板的默认方案）、鲜明型（一种饱和色占 30–60%）、全色盘型（3–4 种已命名的角色色）、浸染型（界面本身就是颜色）。≤10% 规则仅适用于克制型——不要习惯性地把所有设计都归为这种方案。
• 60/30/10： 60% 主色（背景／大面积表面）、30% 次色（凸起区域／卡片）、10% 强调色（按钮／链接／焦点环）。
• 使用 OKLCH。 当 L 接近 0 或 100 时降低色度。让每种中性色都偏向品牌色相（色度约为 0.005–0.01），而不是直接使用纯 #000／#fff——除非概念明确要求纯墨色（粗野主义、硬朗的编辑风格、真正的 OLED 黑）；在这种情况下，纯 #000／#fff 应是经过明确记录的有意选择，而非默认值。
• 每个项目使用一套色盘。 不要在暖色和冷色之间漂移；第 7 个区域也不要突然出现意料之外的 CTA 颜色。
• 深色模式应派生，而非反转。 使用主题语义令牌（--bg、--surface、--surface-raised、--text、--text-muted、--accent）——绝不直接翻转原始十六进制颜色。深色模式下：使用带色调的近黑色（L 约为 0.15–0.20），通过提亮来凸显表面（阴影应几乎不可见），降低强调色的色度／提高其亮度，并单独重新验证每组文本颜色的对比度。

优先通过深度区分，而不是条件反射地加边框

• 背景对比 +（带色相的）阴影是区分容器和凸显层级的主要方式，而不是给所有元素都画上边框。 边框并非一概禁止，但不该是凸显层级的默认手段。以下场景合理且适合使用边框：需要在平面表面上提供可感知边缘的输入项／控件轮廓、密集数据界面中的细分隔线、表格单元格／行分隔线，以及 :focus-visible 焦点环。在这些场景中使用边框；不要把它当作分隔卡片和区域的首选手段。
• 不要在凸起表面内部再嵌套凸起表面（不要卡片套卡片再套卡片）。
• 只使用一个深度层级：页面基底 → 凸起区域 → 浮动元素。
• 通过背景颜色变化来呈现凸起／选中状态，不要通过开关装饰性边框来实现。

文本对比度（强制执行——绝不发布灰字白底的正文）

• 正文／辅助文本须满足 WCAG AA（≥4.5:1）；大号文本（≥24px 或 ≥19px 粗体）以及 UI／图形元素须达到 ≥3:1。浅灰色文字搭配近白背景（例如 #9aa 搭配 #fff）不合格。
• 通过计算验证，而非目测，并分别检查浅色和深色模式——线性化公式和 OKLCH-Δ45 预检见 references/quality-floor.md。没有具体数值时，不要声称“符合 AA”。
• 弱化／次要文本也须具有高对比度——加深颜色，直到清晰易读。

字体排印——根据品牌选择字体，然后固定一套字号比例

字体排印是设计显得千篇一律的最快原因。**绝不要凭习惯重复使用相同字体。**分三步选择：

步骤 A — 确定个性（1–2 个词）：企业简洁、编辑奢华、温暖亲和、大胆张扬、俏皮／怪趣／卡通、瑞士极简、粗野技术、优雅时尚。设计总有其个性——如果设计简报没有说明，就根据行业和受众推断。正是这种推断，让字体看起来是经过选择的，而不是套用模板。

没有明显信号时的默认选择 = 中性无衬线体，绝不选衬线体。当个性偏中性／现代／企业／极简（常见的“专业／简洁／未说明”情形）时，从下方“企业简洁”一行中选择可自托管的无衬线体，并说明选择了哪款以及原因——根据细微差异轮换选择（Geist、Hanken Grotesk、Mona Sans、Neue Montreal、Space Grotesk 均符合要求），不要每次都选同一款；强制指定单一字体本身也是一种惯性。只有当个性明确偏编辑奢华、优雅时尚或传统传承时，才选择衬线体／展示字体——在“现代极简”的设计简报中使用衬线体属于错误推断，不合格。

步骤 B — 将个性映射到类别，再选择字体（可自托管／Google Fonts，除非品牌拥有自有字体）。个性→类别→字体对照表见 references/quality-floor.md——选择符合当前设计简报细微特点的行，并用一句话说明字体与个性的契合之处（如果这款字体放在任何设计简报中都一样合适，那就是凭惯性选择的）。

步骤 C — 有意搭配。标题体现个性；正文字体应低调、易读；两者情绪基调一致。最多使用 2 个字体系列（可选加等宽字体）。强调文字使用同一字体系列的斜体／粗体。

避免惯性选择（强制执行）：不要默认使用 Inter；对于没有明显信号的设计简报，选择无衬线体（绝不选衬线体），并说明选择具体字体的理由；不要仅仅因为设计简报提到“有创意／高端”就选择衬线体；俏皮／卡通风格的品牌不得使用企业风格的无衬线体。

• 将字号比例一次性定义为设计令牌（display、h1、h2、h3、body-lg、body、body-sm、caption、button），并在所有地方引用——不要使用一次性的内联字号；相同角色在所有区块中须使用相同字号。
• **最小值：**正文不得小于 16px；说明文字约为 13–14px；行高约为 1.5；行长为 60–75ch。
• 响应式缩放属于字号比例的一部分——优先使用流式 clamp()；标题在移动端缩小；绝不裁切或截断。

组件（构建可复用组件）

按钮、卡片、徽章、导航栏、页脚、表单、输入框、功能／CTA 区块，以及反馈基础组件（Toast、Spinner、Modal、Skeleton、空状态／错误状态）——每种组件仅定义一次并重复使用。交互状态应包含在基础组件中。不要使用一次性的内联变体。根据功能选择组件基础库（见 references/component-libraries.md）；每个项目只使用一种带样式的基础库，并依据设计令牌重新设置主题——绝不使用库的默认外观。

交互反馈与状态（没有静态或无响应的元素）

• **每个交互元素都应包含完整的状态集：**默认、悬停、焦点（:focus-visible，而非 :focus）、激活／按下（清晰可见——轻微缩小并改变阴影，立即触发）、禁用。
• **使用 :focus-visible 设置焦点环，使其仅在键盘／程序化聚焦时显示，鼠标点击时保持隐藏。**每次鼠标点击都闪现的焦点环会显得粗糙——正确的解决方式是使用 :focus-visible，绝不要使用 outline:none 或移除焦点环（这会违反 WCAG 2.4.7，并阻碍键盘用户）。许多组件库默认提供 :focus（鼠标操作时也会显示）——请将其改为 :focus-visible。
• **浮动元素必须始终位于屏幕内。**工具提示、下拉菜单、弹出框、菜单、选择器和日期选择器都必须使用能感知碰撞的位置布局——翻转／偏移以保持在视口内，绝不溢出或在边缘被裁切。请使用 Popover API／anchor 定位，或定位引擎（Floating UI，或内置此类引擎的 Radix／Headless UI）；绝不要使用固定偏移手动定位，以免靠近边缘时跑到屏幕外。
• 异步操作必须在开始时立即显示加载状态（标签改为描述进行中操作的动词并显示微调器，或使用骨架屏）。绝不要让界面毫无解释地卡住。
• 每个操作都必须明确反馈成功／失败（toast／行内提示／微交互反馈），并搭配图标或标签，绝不能只用颜色表达。
• **表单：**失焦时进行行内验证（不要在输入时验证），在字段下方显示错误，清晰标示必填项，提供辅助文本，标签置于输入框上方（绝不用占位符代替标签）。只有在提供可见原因时，才禁用提交。
• **数据视图需设计三种状态：**空状态（提供有用信息并符合品牌风格）、加载状态（骨架屏／微调器）、错误状态（可恢复并提供重试）。所有状态均由共享组件和动效令牌驱动。

动效

• 保持一致且有明确目的；重复使用相同的时长／缓动曲线。微交互约为 150–300ms；进入时使用缓出，退出时使用缓入；避免线性动效。仅为 transform／opacity 添加动画。
• 动效必须有意义——用于传达层级、反馈、叙事或状态。如果无法用一句话说明它传达了什么，就去掉它。
• 始终支持 prefers-reduced-motion——立即显示，内容完全可见。所有交互元素都应使用指针光标。

UX 文案与内容（像真人一样写，不要像占位符）

• 具体胜过笼统。标题应说明该产品为当前受众做什么，不要写“提升工作流／无缝解决方案／下一代平台”。如果任何同类公司都能使用这句话，就重写。
• CTA 以动词开头：“开始 14 天试用”优于“开始使用”；每种意图只使用一个标签。
• 使用真实数据或明确标记的模拟数据——绝不要把“Acme／John Doe／Lorem ipsum”作为真实内容发布；不要编造精确到离谱的统计数据。
• **微文案承载 UX：**空状态说明下一步操作；错误说明发生了什么以及如何修复（绝不能只写“出了点问题”）；加载中的按钮说明正在进行什么操作。

图标、图片、渐变／玻璃效果、完整的无障碍底线要求，以及官方设计系统诚信表，现已统一收录于 references/quality-floor.md——请在此步骤中一并应用。

---

第 4 步 — 构建（先以事实来源为准，始终保持模块化）

1. 先处理令牌。 为每种颜色、字体比例、间距、圆角、阴影、动效时长和缓动设置一层令牌（CSS 变量／主题／Tailwind 配置）。任何值都不得硬编码。 与 DESIGN_SYSTEM.md 完全一致。
2. 组件模块化，文件保持精简。 先创建可复用的基础组件，再组合成页面。每个文件只负责一项职责；文件变大时就拆分。状态由基础组件管理。
3. 仅使用获批的颜色和已定义的组件；使用共享的动效令牌；使用匹配的图像；让每个页面都能响应式适配（按断点验证每个区块）。
4. 清晰分层 — 基础组件不包含业务逻辑或数据获取；功能模块负责数据和状态；共享逻辑放在公共位置，而不是通过交叉导入共享。
5. 验证依赖项 — 导入前检查 package.json；如果缺少依赖项，输出安装命令。使用与项目相同的包管理器（根据锁文件判断；没有锁文件时使用 pnpm）。
6. 体验层应进行代码拆分并隔离（参见 references/experiential.md）— 标准页面无需 3D 层即可渲染并正常使用。

性能与交付（生产就绪意味着速度快）

目标 Core Web Vitals：LCP < 2.5s，CLS < 0.1，INP < 200ms。 应用全部 九项优化措施 — 完整列表见 references/quality-floor.md。简而言之：提升感知速度、缩小首次加载内容、优先处理关键路径 CSS、减少交付的 JS、延迟加载首屏以下内容、保护主线程、保持布局稳定（CLS）、优化图像、智能缓存。

工程原则

• DRY / KISS / YAGNI — 同一值／逻辑出现两次时就只声明一次；用最简单可行的方法；只构建当前所需内容。
• 延迟编写代码（/ponytail 阶梯）： 优先使用原生 HTML/CSS，再考虑 JS 库（先用 <dialog>、<details>、scroll-snap、:has()，再引入依赖）；优先使用已安装的依赖，而不是新增依赖；一行代码优于五十行；尽量减少文件数量。用 ponytail: 注释标记有意采用的捷径。如果已安装 /ponytail，则在处理非简单组件时调用它；如果未安装，就按阶梯执行。
• Ponytail 决定的是 如何实现，而不是 设计要求什么。 绝不可为了省事而省略令牌层、可复用基础组件、完整状态集、空／加载／错误状态、无障碍支持、对抗性审查或 DESIGN_SYSTEM.md。机制上可以精简，但绝不能忽略设计系统本身。

---

步骤 4.5 — 对抗性审查（记录文档前必须完成）

以对手的视角评判，而不是以作者的视角。此轮的目标是证明设计很普通。 任何“是的，它很独特”的判断都是需要修正的问题：

1. 概念测试。 遮住品牌名称——它可能属于任何竞争对手吗？如果是，强化并重新应用步骤 2.7 中的概念。
2. 直觉测试（1e），以攻击者的视角进行。 能否根据类别猜出配色？字体是否是熟悉的默认选择？先假定答案是肯定的，再用具体细节证明自己错了。
3. 参考测试。 指出每个部分采用的具体高级设计手法。任何诚实的答案是“默认 AI 布局”的部分都要返工。
4. 指出一个真实弱点。 大声说出最薄弱的部分并修复它。什么都没发现的审查不算审查。
5. 首屏构图自检（落地页／营销页）。 大声说出首屏采用的构图——居中编辑式／超大字体式／全出血式／非对称网格外式／分栏式。如果答案是“分栏式”， 写出让它脱颖而出的具体手法；如果说不出来，那它就是“左侧文字／右侧图片”的直觉模板——请重构为非分栏式构图。同时确认：首屏垂直居中，上方没有空白带，也没有闪光／AI 图标或含糊的标语眉题。（无法使用浏览器截图时，这项明确的自检是防止只在渲染效果上敷衍首屏的最后一道防线。）

对于高风险需求，请将此审查作为真正独立的一轮进行（重新阅读或使用子 Agent）。 在设计系统中记录概念测试的结论，然后运行可计数的检查关卡。

---

步骤 5 — 在 DESIGN_SYSTEM.md 中记录文档（必须完成）

每次完整设计或改进后，都要根据 references/DESIGN_SYSTEM.template.md 在项目根目录创建 DESIGN_SYSTEM.md，并在全部 14 个部分中填写实际使用的值（真实的 HEX／OKLCH 值、真实字体、真实组件规格）。在第 1 节记录表面配置（步骤 1），以便后续工作采用相同的处理方式。然后逐字告知用户：

"Your project now includes a DESIGN_SYSTEM.md file. Use this file as the design guide for future pages, sections, and components so the full website remains visually consistent."

---

上线前检查 — 可计数的反敷衍检查关卡（唯一真实依据）

反敷衍检查必须计数。任何一项不通过都意味着尚未完成。此检查关卡是权威清单—— DESIGN_SYSTEM.template.md §12 会指回此处，而不会重复列出，因此只需维护一份清单。运行下面的通用检查关卡，并运行 references/surface-rules.md 对应表面配置部分末尾的检查关卡。

严格禁令（命中任意一项即不合格）

• ❌ 使用批准调色板之外的任何颜色；默认使用紫色／蓝紫色渐变（除非已获批准）；默认使用原始 #000／#fff；只有当概念明确要求（粗野主义／硬派编辑风格／真正的 OLED）且有文档说明时，才允许使用纯黑。
• ❌ 默认使用 Lucide；混用图标系列；使用表情符号作为结构性图标。
• ❌ 文本对比度过低（正文／辅助文本对比度低于 4.5:1，无论浅色还是深色）。
• ❌ 正文字号小于 16px；使用任何未映射到字号阶梯的内联单次字号。
• ❌ 字体排印与品牌个性不符（企业级无衬线字体搭配活泼品牌；通用无衬线字体搭配编辑风格；在适合粗笔画无衬线字体的场景中，默认使用没有明确依据的衬线字体）；不通过 Move A→C 进行选择，而是习惯性重复使用同一字体组合。
• ❌ 将边框作为分隔或凸显卡片和区块的主要手段，或通过切换装饰性边框改变层级／选中状态。（输入框轮廓、设计令牌分隔线、表格线和焦点环都可以——它们不用于营造层级。）
• ❌ 嵌套的凸显表面（卡片中套卡片，再套卡片）。
• ❌ 静态的交互元素（缺少悬停／焦点／激活／禁用状态）；无提示的异步操作（没有加载和成功／错误状态）；空白的空状态／加载状态／错误状态屏幕。
• ❌ 英雄区文字被裁切；移动端文字被截断；任何断点下的内容被裁切／溢出——包括英雄区在约 700–800px 的笔记本电脑屏幕高度下纵向溢出、未居中而是顶部对齐，或英雄区上方出现全宽空白带／间隙（多余的间隔元素或空区块把内容向下推，导致内容偏离中心）。
• ❌ 默认情况下，左侧文字／右侧图片（或右侧模型图／视频）的英雄区分栏设计不合格——这是网络上最模板化的英雄区设计。只有写明让它脱颖而出的具体独特手法（不对称比例、图片延伸至边缘、重叠／景深或动态效果），且设计确实实现了这一点，才算合格。普通的左侧文字 + 右侧圆角图片卡片，各占 50%，直接不合格——应改用其他构图（居中编辑风格、超大字体、全幅、不对称／脱离网格）。
• ❌ 在眉题、徽章或药丸标签中使用装饰性闪光／✨／✦／魔杖／「AI」星形图标（「✨ AI-powered」这类明显标记）；眉题使用含糊的标语（如「从色彩到完整系统」），而非明确的区块标签／类别。眉题用于传递信息，而非装饰。
• ❌ 点击鼠标时出现焦点环（使用了 :focus 而非 :focus-visible，或使用了库中默认会通过鼠标显示焦点环的样式）——应通过 :focus-visible 修复，绝不能移除焦点环。
• ❌ 浮动元素（工具提示／下拉菜单／弹出层／菜单／选择器／日期选择器）溢出或被视口边缘裁切——必须通过考虑碰撞的定位方式进行翻转／偏移，确保元素留在屏幕内。
• ❌ 设计好的水平卡片行带有可见的原生滚动条（包括由 overflow-x:auto 产生的虚假垂直滚动条——应设置 overflow-y:hidden 并隐藏滚动条）；只用 overflow-x，却没有吸附／控件／平滑滚动；边缘被硬切而没有 mask-image 渐隐；滚动条旁边的卡片有一半被裁切。
• ❌ 渐变文字（background-clip:text）；装饰性玻璃效果；侧边条纹 border-left/right 点缀。
• ❌ 巨型的包办式文件。
• ❌ 在需求未要求时强行加入 3D 效果，或把沉浸式需求做得过于扁平；WebGL 场景没有后备方案／未针对移动端降级／没有减少动态效果时的静态版本；将文案直接烘焙进画布；将大型 3D／动画包放在关键路径上。
• ❌ 直接套用通用 AI SaaS 布局而不做调整；配色能从所属类别中一眼猜出；设计未通过概念测试；使用通用填充文案。
• ❌ 使用处于默认主题的库／注册表组件（现成的 shadcn／Aceternity／Magic UI、默认渐变、演示文案）；一个项目中使用多套经过样式化的组件基础。
• ❌ 在已有可访问原语时，手工编写 div+onClick 小部件；或为了原生 HTML／CSS 或已安装依赖就能实现的功能，引入整个库。

可计数限制

• 眉题（小号大写字母标签，带字距）：≤ ceil(章节数 ÷ 3)，且每个都必须是 真正的标签／类别——不能是装饰性的闪光／AI 图标，也不能用含糊的标语充当眉题。
• 连续之字形布局（图片与文本交替排列的行）：连续最多 2 行；第 3 行必须打破 这一模式。
• 整个页面中，每种 CTA 意图只能使用一个标签。
• 主要 CTA 样式只能有一种，并重复使用；次要 CTA 应更低调；CTA 文案不得换行（主要 CTA ≤3 个词）。
• **每页最多 1 个跑马灯。****主题：**浅色／深色反转必须是有意且重复的体系，不能无意漂移；每组文本都必须在两种主题下通过 AA 对比度检查。实用界面在单个视图中必须保持单一主题。
• **布局家族重复：**包含多个区块的页面必须使用 ≥3 种不同的区块布局家族。
• 假精确数字／通用名称／填充文案 = 0，除非是真实内容或明确标注为模拟内容。

性能门槛

• ❌ 任何没有 width／height 或 aspect-ratio 的图片／媒体／嵌入内容。
• ❌ Hero／LCP 图片未设为优先加载；首屏以下的图片／组件未采用懒加载。
• ❌ 动画属性不是 transform／opacity。
• ❌ Web 字体未设置 display: swap；关键路径上存在阻塞渲染的非关键 CSS／JS。
• ❌ 初始路径中包含较重的／3D 资源包；通过组件状态持续响应滚动／鼠标输入。
• ✅ 已应用全部九项优化措施。 CWV 数值是这些措施旨在实现的目标——表述为“通过这些措施进行优化”；只有实际测量过，才报告具体数值。

---

完成前验证

1. 类型检查。 使用检测到的包管理器运行项目的类型检查（<pm> run typecheck、<pm> exec tsc --noEmit 或 lint 命令）。不要仅为查找错误而运行生产构建。
2. 能计算的就计算，不要凭目测判断。 使用一次性脚本运行对比度比率（公式见 references/quality-floor.md）。这项要求必须执行，不是可选项。
3. 对只有布局完成后才能观察到的内容进行渲染验证——这不是走过场，而是唯一能确认这些内容的方式。 门槛要求满足若干渲染后的结果，而这些无法从源代码中判断：Hero 在约 700px 和 800px 的笔记本屏幕高度下能完整显示在 100svh 内；在 375／768／1280px 宽度下没有裁切／溢出；水平滚动栏不会出现异常滚动条。对于这些特定项目，使用这些视口尺寸快速截取无头浏览器截图（/use-my-browser、/agent-browser 或 Playwright）并确认；或者，如果确实无法渲染，请明确说明，并将“已验证”的表述降级为“按目标构建，未经视觉确认”。没有实际查看渲染结果，不得声称仅能通过渲染验证的门槛项目已通过。（这是“不为验证而打开浏览器”规则中唯一获准的例外；该规则仍禁止对已能从代码中确认的内容事后装饰性地截图。）
4. 在宣布完成前，最后再进行一次对抗性审查（4.5）和可计数门槛检查。

后续工作与更新

今后每个页面都必须沿用 DESIGN_SYSTEM.md 中的颜色、排版、间距、组件、图标、卡片、动画和图片风格——除非用户更新要求，否则不得引入新的视觉风格。若有任何变更，立即更新 DESIGN_SYSTEM.md，避免风格漂移。