sunwenzhe-git/atlas/frontend-design

前端设计：品味总监 + 合规基线

两个职责合在一处。一个是总监：读懂 brief，拒绝产出模板化的营销页。一个是基线：拒绝产出不可访问、慢、用不了的界面。

下面每条规则都是情境化的，不会自动触发。先读 brief，再只取用得上那部分。

阅读地图（按需打开，不要预加载）

SKILL.md 只保留生成前后必须一直在场的内容：范围路由、brief 判读、旋钮、约定、会让交付失败的硬规则、合规基线、预检闸门。所有解释、代码骨架、枚举清单都放在 references/ 里，由触发条件决定何时读。

章节号沿用原锚点，因此不是连续的。 Section 2、8、10、11、12 已移入 references/，编号作为稳定标识保留，这样被移动文件内部的所有交叉引用仍然可解析。原 Section 7（旋钮定义）并入了 Section 1，其技术细节在 references/knob-definitions.md。Section 5 只把实现细节移入 references/，摘要与两条硬禁令保留在本文件。

翻译约定： 说明文字为中文；代码、类名、API 名、CSS 属性、规则 ID、文件名、阈值一律保留原文，不得翻译。改动规则时请连代码示例一起核对。

canonical 规则： 同一规则存在多份副本时，references/ 文件为唯一权威；SKILL.md 的内联副本只写摘要，不得出现 references 里没有的数值或分档。改数值先改 references，再同步摘要。

语言现状： SKILL.md 与本目录下 11 个文件为中文（README.md、ai-tells.md、design-directives.md、motion-skeletons.md、design-system-map.md、pattern-vocabulary.md、redesign-protocol.md、block-library.md、dark-mode-protocol.md、knob-definitions.md、tuning-verbs.md）。design-systems.md（几乎全是 npm 命令与官方文档 URL）与 42 个 access- / color- / cwv- / form- / layout- / resp- / typo- / anim- 规则文件保留英文原文：那是以代码为主的标准细则（WCAG、web.dev），不参与手工调参，保留原文便于随时对照上游。

范围路由（第一步执行）

先判定表面类型，再只套用对应的层。判定结果要和 design read 写在同一行。

这里的「应用」指 Web 产品界面，不是原生 App。 指的是用 HTML、CSS、React、Tailwind 写的、跑在浏览器里、用 Core Web Vitals 衡量的 dashboard / 后台 / 向导。原生桌面与原生移动 App 完全不在本 skill 范围，请直接用 Apple HIG 或 Material 及平台自身规范。完整清单见 Section 13。

这套路由存在的意义是拦住两类错误：

• 把营销硬规则（hero 必须占满首屏、eyebrow 配额、bento 单元格数、同一意图只能有一个 CTA）套到 dashboard 上。对那个表面而言，这是错的尺子。
• 营销页 hero 根本占不满首屏、或键盘根本走不通，却把 Section 6 每一条都打了勾。Section 6 是地板，不能替代 Section 4。

0. BRIEF 判读（动手之前先读懂场面）

在碰代码或调旋钮之前，先推断用户到底想要什么。多数 LLM 设计产出之所以差，是因为模型直接跳到一个默认审美，而不是先读懂场面。

0.A 先读这些信号

1. 页面类型：landing（SaaS / 消费级 / 代理机构 / 活动）、作品集（开发者 / 设计师 / 创意工作室）、改版（保真还是推翻重做）、编辑型 / 博客。
2. 用户用的审美词：「极简」「安静」「Linear 风」「Awwwards」「野兽派」「高端消费」「Apple 感」「俏皮」「严肃 B2B」「编辑感」「代理机构感」「玻璃感」「暗黑科技」。
3. 参考信号：用户给的 URL、贴的截图、点名的产品、对标的品牌。
4. 受众：B2B 采购评审 vs 有设计意识的消费者 vs 扫一眼作品集的招聘方。受众决定审美，不是你的品味决定。
5. 已有的品牌资产：logo、色、字体、摄影。做改版时这些是起始材料，不是可选项（见 Section 11）。
6. 隐性约束：可访问性优先的受众、公共部门、受监管行业、信任优先的电商、儿童产品。这类约束优先级高于审美偏好。

0.B 生成之前先输出一行 Design Read

动手写代码之前，先用一行说明：「判读为：<页面类型>，面向 <受众>，<审美>语言，倾向 <设计系统或审美家族>。」

示例：

• 「判读为：面向技术买家的 B2B SaaS 落地页，Linear 式极简语言，倾向 Tailwind utilities + Geist + 克制动效。」
• 「判读为：面向招聘方的个人设计师作品集，编辑 / 动态字体语言，倾向原生 CSS + 滚动驱动动画 + 自定义字体。」
• 「判读为：公共部门服务网站的改版，信任优先语言，倾向 GOV.UK Frontend 或 USWDS。」

产出文案语言：默认中文。 brief 明确面向海外受众或要求其他语言时跟随 brief，并把语言写进 design read；未声明时一律按中文产出，4.7 的中文换算阈值随之生效。

0.C brief 模糊时，只问一个问题，不要猜

只问一个澄清问题，绝不要一次抛一堆。且只在 design read 真的会分叉时才问。例：「这个要更偏 Linear 那种干净，还是更偏 Awwwards 那种实验性？」

如果从上下文能自信推断，就不要问，直接声明 design read 然后往下做。

0.D 反默认纪律

不要默认以下东西：AI 紫渐变、深色网格上的居中 hero、三个等分 feature 卡片、到处糊玻璃拟态、满屏无限循环微动效、Inter + slate-900。这些都是 LLM 的默认脸。 依 design read 主动绕开它们。

1. 三个旋钮（核心配置）

design read 之后，设定三个旋钮。下文所有版面、动效、密度决定都由这三个值把关。

• `DESIGN_VARIANCE: 8` · 1 = 完全对称，10 = 艺术性混乱
• `MOTION_INTENSITY: 6` · 1 = 静态，10 = 电影感 / 物理感
• `VISUAL_DENSITY: 4` · 1 = 画廊 / 疏朗，10 = 驾驶舱 / 信息密集

基线：`8 / 6 / 4`。 除 design read 覆盖，否则用这组。不要叫用户去改这个文件，覆盖在对话里完成。

1.A 旋钮推断（design read → 旋钮值）

除上表标注「随现状」的格子外，推翻重做一律不参考现状的数值。

1.C 旋钮如何驱动产出

把这些值（或用户覆盖后的值）当成全局变量。本文档中所有交叉引用都指这些确切的变量名，不要自造别名如 LAYOUT_VARIANCE 或 ANIM_LEVEL。

1.D 旋钮定义（技术参考）

三档旋钮对应的具体写法——栅格轨道、缓动曲线、间距档位、移动端塌陷点——在 `references/knob-definitions.md`。设定旋钮值不需要读它，写对应样式时再读。其中一条对任何档位生效：4-10 档的非对称版面在 < 768px 必须塌成严格单列。

1.E 项目设计档案（跨会话持久）

判读与旋钮设定完成后，设计档案固定落「资产根/design.md」：Atlas 项目按项目根 atlas.config.yaml 的 layout.assets_root 解析（默认 product/design.md），非 atlas 项目统一落 product/design.md（相对项目根，目录不存在则创建）。atlas 项目这正是产物归属里项目级应然（产品长什么样）的位置。不叫 DESIGN.md：那个名字在 atlas 体系是源包操作契约。

• 设计档案已存在 → 先读它并沿用。除非本次 brief 明确要求改方向或用户口头覆盖，不重新判读、不默默改值；用户在对话里覆盖了旋钮，同步更新设计档案。
• 设计档案不存在 → 把本次判读结果写入设计档案（一次性 demo / 临时页除外）。只记事实不记过程，五行即可：

# 设计档案
-判读：<0.B 的那一行>
-旋钮：DESIGN_VARIANCE <n> / MOTION_INTENSITY <n> / VISUAL_DENSITY <n>（<偏离基线的理由，无则写「基线」>）
-设计系统 / 审美家族：<名称>
-强调色与主题：<色值>；<单主题锁 / 双模式>
-已有豁免：<prose 类豁免每条一行理由；detect 类写作 `detect:<rule-id> — <理由>` 并同步 `.impeccable/config.json`；无则写「无」>

后续会话、改版、调优动词（references/tuning-verbs.md）都以它为准。

detect 类豁免必须双侧落盘：档案里写 detect:<rule-id> — <理由>，同一 rule id 同步进项目根 .impeccable/config.json 的 detector.ignoreRules（没有该文件则创建）——只记档案 = 报警没真关，只关报警 = 没台账。atlas 项目由 validate_design_exemptions 机器对账，漂移即 FAIL；非 atlas 项目同形态，便于日后携带。

1.F Section 计划（≥ 5 个 section 的营销页先做这个再写代码）

旋钮设定后、写任何代码之前，先输出 section 计划表：每行一个 section——名称、内容一句话、版面家族（词汇见 references/pattern-vocabulary.md）、有无 eyebrow。

4.7 的机械规则必须在计划期就满足：8 个 section 至少 4 种版面家族、eyebrow ≤ ceil(sectionCount / 3)、无 3 个以上连续图文分栏、hero 占满首屏。计划不达标就改表，不要先写代码再到闸门前返工。闸门只验证一件事：代码是否按计划执行。

3. 默认架构与约定

除 design read 选了真实设计系统（见 references/design-system-map.md），以下为默认。

3.A 技术栈

• 框架：React 或 Next.js，默认 Server Components（RSC）。
• RSC 安全：全局状态只能在 Client Component 里用。Next.js 下把 provider 包进 "use client" 组件。
• 交互隔离：任何用 Motion、滚动监听、指针物理的组件必须是带 'use client' 的独立叶子节点。Server Component 只渲染静态版面。
• 样式：Tailwind v4（默认）。仅当既有项目要求时用 v3。
• v4 下不要在 postcss.config.js 里用 tailwindcss 插件，改用 @tailwindcss/postcss 或 Vite 插件。
• 动画：Motion（原 Framer Motion）。从 motion/react 导入（import { motion } from "motion/react"）。framer-motion 包仍可用作兼容别名，新代码优先 motion/react。
• 字体：一律用 next/font（Next.js）或自托管 @font-face + font-display: swap。生产环境绝不通过 `<link>` 引 Google Fonts。

3.B 状态

• 孤立 UI 用局部 useState / useReducer。
• 全局状态仅用于避免深层 prop 透传：Zustand、Jotai 或 React context。
• 绝不用 useState 跟踪由用户输入驱动的连续值（鼠标位置、滚动进度、指针物理、磁性悬停）。用 Motion 的 useMotionValue / useTransform / useScroll。useState 每次变化都会重渲染整棵 React 树，移动端直接崩。

3.C 图标

• 允许的库（优先级顺序）：@phosphor-icons/react、hugeicons-react、@radix-ui/react-icons、@tabler/icons-react。
• 不推荐：lucide-react。仅当用户明确要求或项目已依赖时可用。
• shadcn/ui 例外：shadcn/ui 组件内部自带的 lucide 图标随组件保留，不必替换；自行新增的图标仍遵守本节。
• 绝不手写 SVG 图标。 缺字形就再装一个库或用基本图元拼，不要从零画路径。
• 一个项目一个图标家族，不要在同一组件树里混 Phosphor 和 Lucide。
• 全局统一 `strokeWidth`（如 1.5 或 2.0）。

3.D Emoji 政策

默认在代码、标记和可见文案中不鼓励使用。符号一律换成图标库字形。覆盖条件：仅当用户明确要求俏皮 / 聊天感 / 社交原生调性时，且即便如此也要克制、有意图。

3.E 响应式与版面机制

• 统一断点（sm 640、md 768、lg 1024、xl 1280、2xl 1536）。
• 版面容器用 max-w-[1400px] mx-auto 或 max-w-7xl。
• 视口稳定性：全高 hero 绝不用 h-screen，一律 min-h-[100dvh]，避免移动端 iOS Safari 地址栏导致的跳动。
• 栅格优先于 flex 数学：绝不用复杂的 flexbox 百分比计算（w-[calc(33%-1rem)]），一律用 CSS Grid（grid grid-cols-1 md:grid-cols-3 gap-6）。

3.F 依赖校验（强制）

导入任何第三方库之前，先查 package.json。包不存在就先输出安装命令。绝不假设某个库存在。

4. 硬规则（有一条不满足即为交付缺陷）

Section 4 的其余部分（字体池与衬线纪律 4.1、配色校准与调色板禁令 4.2、版面多样化 4.3、材质与圆角锁 4.4、交互状态与对比度检查 4.5、表单结构 4.6、图片策略 4.8、内容密度 4.9、引言 4.10）都在在 `references/design-directives.md`。写字体、配色、卡片、状态、图片或长列表之前先读它。下面这些必须在不读文件的情况下就位。

4.7 版面纪律（硬规则）

• 词数阈值针对英文。 中文按 1 词 ≈ 2 字换算：副文案 ≤ 40 字，主 CTA ≤ 6 字，副段落 ≤ 50 字。行数限制与 eyebrow 计数和语言无关。
• hero 必须占满首屏。 桌面端标题最多 2 行，副文案最多 20 个词 且最多 3-4 行，CTA 不滚动就能看到。文案太长就砍文案或降字号，绝不让 hero 溢出。
• hero 字号与图片尺寸一起规划。 默认 text-4xl md:text-5xl lg:text-6xl；仅当标题 3-5 个词时才用 text-6xl md:text-7xl。hero 标题到第 4 行，永远是字号错误，不是文案长度错误。
• hero 顶部留白上限：桌面端最多 pt-24（约 6rem）。超过这个值视觉上就是版面 bug，不是留白。
• hero 文本栈纪律，最多 4 个文本元素：（1）eyebrow 或品牌条 或都不要；（2）标题；（3）副文案；（4）CTA（1 主 + 最多 1 次）。hero 内禁止：CTA 下方的小标语、信任微条、价格提示、feature 列表、social proof 头像行。这些一律下移到紧邻的 section。
• 「Used by / Trusted by」logo 墙放在 hero 下方，绝不放进 hero，且只放 logo，不要在 logo 下方印行业或品类标签。
• 导航在桌面端必须一行排完，lg 以下压缩标签或收进汉堡。高度上限 80px，默认 64-72px。
• bento 栅格要有节奏，不能一边倒重复。 交替全宽行、非对称瓦片、纵向断点。
• bento 单元格数：有几个内容就几个格子。中间或末尾出现空格即规划错误，重排栅格，绝不贴空白瓦片。
• section 版面家族不得重复：同一版面家族一页最多出现一次。8 个 section 至少要用 4 种不同家族。
• zigzag 交替上限：图文左右交替最多连续 2 个 section，第 3 个连续图文分栏即为预检失败。
• eyebrow 克制，每 3 个 section 最多 1 个（hero 算 1 个）。预检时机械计数：统计所有 section 标题上方的 uppercase tracking 小标签数量，若大于 ceil(sectionCount / 3) 即失败。不要每个 section 标题上都有 eyebrow。
• 分栏标题禁令：「左边大标题 + 右边小解释段」不得用作 section 标题。真的需要就上下堆叠。
• bento 背景多样性：任何多格栅格里至少 2-3 个格子要有真实视觉变化（图片、品牌渐变、图案、色块）。全是白底文字卡片读起来就是无聊的 AI 默认。
• 移动端塌陷必须逐 section 显式声明 < 768px 的降级方案，写在同一个组件里。不要「Tailwind 会处理」。

4.11 页面主题锁

整页只有一个主题，section 不得反转。 深色 section 中间夹一个浅色 section 即为破损。同族内的背景色差可以（bg-zinc-950 紧挨 bg-zinc-900），但深色页中间翻成 bg-amber-50 不行。用带主题的设计系统（Radix Themes、shadcn/ui <Theme>）时，在页面根节点只设一次主题，不要让各 section 各自覆盖。

配色 / 圆角 / CTA / 交互状态的一致性锁（4.2、4.4、4.5）：一个强调色、一套圆角体系、CTA 一行放下且一个意图一个标签、表单控件对背景满足 WCAG AA、loading / 空 / 错误状态齐全——这些锁的完整定义以 references/design-directives.md 为 canonical，不在此重复数值；预检闸门的「各锁成立」一项负责逐条勾验。

5. 动效（实现细节在 references）

可用的滚动动效骨架，含 sticky-stack、horizontal-pan、scroll-reveal stagger，都在 `references/motion-skeletons.md`。写滚动编排之前先读它。以下两条必须不读文件就位：

• `window.addEventListener('scroll', ...)` 是禁令。 它每帧都跑，极易掉帧。改用 Motion 的 useScroll()、GSAP ScrollTrigger、IntersectionObserver，或 CSS 滚动驱动动画（animation-timeline）。同样禁止在 React state 里存 window.scrollY，以及用 requestAnimationFrame 循环碰 state。
• 动效必须有理由。 加任何动画之前先回答「它传达了什么」。成立的答案：层级、叙事、反馈、状态迁移。不成立的答案：「看着酷」。一句话说不清就删掉。marquee 一页最多一个。

6. 合规基线（可访问性、性能、动效、暗色模式）

这是地板的唯一规范副本。Section 4 说的是设计意图，这一节说的是意图底下必须成立的东西。每条规则都点出它在 references/ 里对应的文件，那里有具体数值、错误/正确代码对照和出处。准备写那段代码时再打开那个文件。6.K 记录了「两份源 skill 打架的地方」的裁决结果，覆盖任何东西之前先读它。

6.A 动画性能

• 只动 transform 和 opacity。绝不动 top、left、width、height。
• will-change 克制使用，只给真正会动的元素，绝不全局 will-change: *。
• 细则：references/anim-gpu-properties.md、references/anim-will-change.md

6.B 降低动效（强制）

• 任何 `MOTION_INTENSITY > 3` 的动效都必须尊重 `prefers-reduced-motion`。 这条没有商量余地。
• Motion 下用 useReducedMotion() 降级为静态。CSS 下用 @media (prefers-reduced-motion: no-preference) 包裹，或在 reduce 覆盖块里关掉。
• 无限循环、视差、滚动劫持、磁性物理，在降低动效下必须塌成静态或瞬时。

6.C 动效时长与缓动