design-director

快速参考 (Quick Reference)

深度参考资料

在执行诊断、仲裁和审查时，参考以下深度文档获取理论支撑和实施细节：

• 融合理论与冲突解决 → references/blending-theory.md — 设计方言与语系、认知一致性理论（5 秒心智模型 / 认知断裂）、视觉重量平衡、属性分类学（硬/软/中性约束）、优先级仲裁 5 条规则、oklch 色彩空间统一的数学原理与 HSL 转换表
• 接缝设计理论 → references/seam-design.md — 建筑阈限空间理论、五种接缝策略的设计原理与性能考量与失败模式、张力-释放模型与区域序列编排
• 案例分析 → references/case-studies.md — Spotify（Expressive+Swiss）、Linear（Minimal+Swiss）、Apple（Expressive+Minimal）三个真实产品的风格配比、区域策略和接缝处理拆解
• 实施指南 → references/implementation-guide.md — 项目启动 6 步清单、Tailwind v4 CSS-First 区域作用域配置（@theme + @custom-variant + CSS Variables）、Framer Motion ZoneProvider 配置（React Context + 动效参数）、参考文献

核心指令 (Core Mandate)

本技能是指挥家 (Conductor)，而非演奏者。

职责边界：

• Director 做什么： 诊断项目需求 → 推荐风格配比 → 绘制区域地图 → 裁决属性冲突 → 设计接缝过渡 → 生成软约束覆盖参数
• Director 不做什么： 不生成组件代码、不定义视觉规范、不替代三个具体 style guide 的职责

权限层级：

WCAG AA 无障碍要求（最高优先级）
    ↓
各 style guide 的硬约束（不可覆盖）
    ↓
Director 的冲突仲裁规则（覆盖软约束）
    ↓
各 style guide 的软约束默认值（最低优先级）

与 frontend-design 的关系：

• Director 是上游：决定每个区域应该使用哪种风格、哪些软约束需要调整
• frontend-design 是下游：审查实现代码是否符合 Token 合规、组件库使用、动效质量等技术标准
• 两者不冲突：Director 的输出是策略文档（Zone Map + Override Parameters），frontend-design 的输入是实现代码
• 推荐工作流：Director 审查 → 区域实现 → frontend-design 审查

核心原则：

1. 有主导风格：每个项目必须有明确的主风格（70-80%），辅助风格（20-30%）服务于特定区域/情绪
2. 区域纯度：单个组件内部只遵循一种风格，绝不在组件层面混合
3. 有意识的借用：每个”异质元素“的引入都必须有明确的理由（用户体验提升 / 品牌调性表达 / 功能需求）
4. 一致的基础设施：无论使用几种风格，oklch 色彩空间、语义 Token 化、shadcn/ui 组件库是所有区域共享的基底

一、项目诊断矩阵 (Project Diagnosis Matrix)

诊断输入维度

分析项目时，从以下五个维度收集信息：

诊断输出：风格配比推荐

诊断提问模板

当用户需求不明确时，Director 应依次确认：

1. “这个项目的核心用途是什么？（展示品牌 / 阅读内容 / 操作数据 / 混合功能）”
2. “目标用户更偏向消费者还是专业用户/企业用户？”
3. “你希望整体感觉是沉浸/电影感、干净/克制、还是精确/高效？”
4. “项目中是否存在信息密度差异很大的不同区域？（如营销首页 vs. 数据仪表盘）”

二、区域策略 (Zone Strategy)

区域粒度原则

核心认知：风格的分界线应该对齐用户心智的上下文切换。 用户在点击导航、切换 Tab、通过登录墙时，自然预期环境变化。在同一滚动流中突然切换视觉语言则会造成认知断裂。

区域 (Zone) 的默认粒度是路由 / 页面 / 独立视图，而非同一页面内的 Section。

Section 级混合的使用条件（必须同时满足）：

1. 项目确实只有一个页面（如 Single-Page Landing）
2. 辅风格 Section 有独立的功能目标（如 Hero 需要影院冲击力，Feature 区需要清晰阅读）
3. 辅风格 Section 不超过 2 个，且有明确的接缝设计

区域分类法

区域映射规则

规则 1：单组件单风格

一个组件（Card、Button、Input 等）内部只遵循一种风格。禁止在同一个 Card 中混用 Expressive 的圆角 + Swiss 的 Mono 大写标签。

规则 2：子组件继承

子组件默认继承父区域的风格。如果需要在某个区域内嵌入不同风格的子模块（如 Minimal 文章页中嵌入一个 Swiss 数据对比表），必须使用内容换框 (Content Wrapper) 接缝策略（详见第四章）。

规则 3：全局元素跟随主风格

全局导航、全局 Toast、全局 Modal 跟随项目主风格，不因当前路由的区域风格而改变。

规则 4：优先用导航分隔风格

不同风格的区域优先通过路由切换、Tab 切换、登录墙等导航结构分隔。同一滚动流内的风格切换是最后手段，且必须有充分的接缝设计。

区域地图模板 (Zone Map Template)

Zone Map 应以项目架构为粒度，而非单页布局：

项目: [项目名]
风格配比: [主风格] XX% + [辅风格] YY%

路由结构:
├── / (Marketing Landing) — Minimal
│   ├── Nav — Minimal
│   ├── Hero — Minimal (排版比例模式)
│   ├── Features — Minimal
│   └── Footer — Minimal
│
├── /app (登录墙分隔) — Swiss
│   ├── Sidebar — Swiss
│   ├── Dashboard — Swiss
│   ├── Settings — Minimal (内容换框)
│   └── Docs — Minimal (内容换框)
│
└── 共享基础:
    ├── oklch 色彩空间
    ├── 统一 --primary 品牌色
    └── 8pt 基线网格

区域间过渡:
- Marketing → App: 登录墙（天然上下文切换）
- Dashboard → Settings: 路由切换（同一 Shell 内）
- Dashboard → Docs: 路由切换 + 内容换框（Swiss Shell 包裹 Minimal 内容）

三、融合规则 (Blending Rules)

约束 ID 速查 (Constraint ID Quick Reference)

每个 style guide 的 Composition Notes 中的约束均有唯一 ID，格式为 [风格前缀].[类型][序号]。Director 在冲突仲裁和委派指令中引用这些 ID。

H = 硬约束（不可覆盖，身份底线）| S = 软约束（可由 Director 在声明范围内覆盖） 完整约束定义见各 style guide SKILL.md 末尾 ## 合成笔记 章节

3.1 属性冲突解决矩阵 (Property Conflict Resolution Matrix)

当两种风格在同一项目中共存时，以下属性可能产生冲突。Director 按以下规则裁决：

3.2 Token 统一策略 (Token Unification Strategy)

混合项目中，所有色彩必须在 CSS Variables 层使用 oklch 色彩空间定义。

核心规则

1. Token 是项目基础设施：所有 CSS Variables（设计 Token）必须定义在项目的全局 CSS 文件（app.css / globals.css）中。禁止在组件级、页面级或局部 CSS 文件中定义 Token（反模式 #12 Token Isolation）
2. 全局共享 Token：--primary、--destructive、--foreground、--muted-foreground 等品牌/语义 Token 在所有区域中保持同一值
3. 区域可变 Token：--background、--card、--border 等表面 Token 通过 [data-zone="..."] 选择器在全局 CSS 文件中实现区域级覆盖
4. 色彩空间统一：Expressive 风格原始使用 HSL，混合项目中必须转换为 oklch

Expressive HSL → oklch 转换参考

区域作用域机制

• 使用 data-zone="expressive" / data-zone="minimal" / data-zone="swiss" HTML 属性标记区域
• 在 CSS 层通过属性选择器 [data-zone="..."] 覆盖区域内的表面 Token
• Tailwind v4 中通过 @theme 和 @custom-variant 在 CSS 文件中直接定义区域变体，无需 JS 配置文件

具体的 CSS Variables 定义、Tailwind v4 配置和代码实现模式参见 references/implementation-guide.md

3.3 动效统一策略 (Motion Unification Strategy)

区域内动效：各遵其法

每个区域内部完全遵循所属风格的动效系统：

跨区域过渡：统一 Expo Out

当用户从一个风格区域滚动/导航到另一个风格区域时，过渡动画使用所有风格共享的通用曲线：

• 曲线： ease: [0.16, 1, 0.3, 1] (Expo Out)
• 时长： 0.3s
• 这是三种风格的唯一公共子集——Expo Out 在三个 style guide 中都出现

全局动效安全

无论使用几种风格，prefers-reduced-motion 必须在最顶层统一处理一次，所有区域的动效同时降级为零动画。不允许某些区域尊重运动安全而其他区域忽略。

具体的动效配置对象、React Context 注入模式和 reduced motion 实现参见 references/implementation-guide.md

四、过渡接缝 (Transition Seams)

接缝定义

接缝 (Seam) 是两个不同风格区域之间的过渡设计。最好的接缝是用户自己预期的上下文切换——点击导航、切换 Tab、通过登录墙。

接缝策略分层

原则：优先使用结构性接缝（导航 / 路由），其次才是视觉性接缝（渐变 / 留白）。 如果你发现自己在一个页面里需要复杂的渐变帘幕过渡，这通常意味着你应该把两个区域拆到不同的路由中。

接缝推荐矩阵

接缝处的动效规则

跨区域的过渡动效使用通用曲线：duration: 0.3s, ease: [0.16, 1, 0.3, 1] (Expo Out)。

接缝的建筑阈限理论与视觉性接缝的详细设计参数参见 references/seam-design.md

五、反模式检测 (Anti-Pattern Detection)

禁止模式清单

检测方法

Director 可通过以下方式检测反模式：

1. Radius Soup → 搜索同一 Section 内的所有 rounded-* 类，检查是否多于一种
2. Color Space Split → 搜索 CSS 文件中的 hsl() 和 oklch() 共存
3. Shadow Leak → 搜索 data-zone="swiss" 或 data-zone="minimal" 区域内的 shadow-* 类
4. Typography Contamination → 搜索 data-zone="minimal" 内的 font-mono 和 uppercase
5. Token Drift → 比较不同区域的 --primary 值是否一致
6. Token Isolation → 搜索组件/页面目录中的 .css 文件是否包含 --background / --foreground 等 Token 定义
7. Single-Page Patchwork → 检查单个 page.tsx 是否包含 3+ 个不同 data-zone 的 ZoneProvider

六、合成配方 (Composition Templates)

以下配方均以路由/视图为区域粒度。注意每个配方中风格切换是通过导航结构（路由、Tab、登录墙）实现的，而非同一页面内的滚动流接缝。

配方 1：SaaS 全栈（营销 + 应用）— 最常见

风格配比: Swiss 60% (App) + Minimal 30% (Marketing) + Expressive 10% (Hero)
分隔方式: 登录墙（Marketing ↔ App）

路由结构:
├── / (Marketing) — Minimal
│   ├── Nav, Features, Pricing, Footer — Minimal
│   └── Hero Section — Expressive (唯一的 Section 级混合，全屏影院首屏)
│
├── /app (登录墙分隔) — Swiss
│   ├── App Shell (Sidebar + Header) — Swiss
│   ├── /app/dashboard — Swiss
│   ├── /app/analytics — Swiss
│   ├── /app/settings — Minimal (内容换框: Swiss Shell 包裹 Minimal 内容面板)
│   └── /app/docs — Minimal (内容换框: Swiss Shell 包裹 Minimal 内容面板)
│
└── 共享基础: oklch · --primary 品牌色 · 8pt 基线 · Inter 字体族

区域间过渡:
- Marketing → App: 登录墙（天然上下文切换，无需视觉接缝）
- Dashboard → Settings: 路由切换（Shell 不变，内容面板切换风格）
- Marketing Hero → Features: 同页唯一的视觉接缝（渐变过渡 200px）

配方 2：创意作品集

风格配比: Expressive 80% + Minimal 20%
分隔方式: 路由切换

路由结构:
├── / (Home) — Expressive
│   ├── Nav — Expressive (透明覆盖)
│   ├── Hero Reel — Expressive (全屏影院)
│   └── Project Gallery — Expressive (Bento)
│
├── /about — Minimal
│   └── Bio, Philosophy, Contact — Minimal (排版比例模式)
│
├── /project/:id — Expressive
│   └── 项目详情 — Expressive (影院级案例展示)
│
└── 共享基础: oklch · --primary · Expressive 圆角 8-12px / Minimal 8px

区域间过渡:
- Home → About: 路由切换（暗→亮的上下文切换自然发生）
- Home → Project: 路由切换（暗→暗，同风格无需接缝）

Director 覆盖:
- E.S3 色彩空间 → oklch（从 HSL 转换）
- M.S2 留白率维持 40%+

配方 3：编辑 / 博客平台

风格配比: Minimal 80% + Expressive 20%
分隔方式: 路由切换

路由结构:
├── / (Home) — Minimal
│   ├── Nav — Minimal
│   ├── Featured Article Banner — Expressive (唯一的 Section 级混合)
│   └── Article Grid — Minimal (Bento 网格)
│
├── /article/:id — Minimal
│   └── Article Body — Minimal (排版比例 + 分割线)
│
├── /featured/:id — Expressive (特色长文的影院级阅读体验)
│   └── 全屏封面 + 沉浸阅读 — Expressive
│
└── 共享基础: oklch · --primary · Inter

区域间过渡:
- Home → Article: 路由切换（同风格 Minimal）
- Home → Featured: 路由切换（Minimal → Expressive，亮→暗切换自然发生）

Director 覆盖:
- E.S2 动效时长上限降至 0.8s（匹配 Minimal 整体节奏）
- E.S4 暗色背景 oklch(0.08 0 0)

配方 4：电商平台

风格配比: Minimal 70% + Swiss 30%
分隔方式: 路由切换 + 内容换框

路由结构:
├── / (Home) — Minimal
│   ├── Nav (含搜索) — Minimal
│   ├── Hero Banner — Minimal
│   └── Product Grid — Minimal (Bento)
│
├── /product/:id — Minimal
│   ├── 产品介绍、图片 — Minimal
│   └── Specs / Compare 表格 — Swiss (内容换框: Minimal 页面内嵌 Swiss 对比模块)
│
├── /cart — Swiss
│   └── 购物车、结算流程 — Swiss (数据精度 + 功能性操作)
│
└── 共享基础: oklch · --primary · 8pt 基线

区域间过渡:
- Product → Cart: 路由切换
- Product 介绍 → Specs 表格: 内容换框（Swiss 表格有明确边框容器）

Director 覆盖:
- S.S1 圆角放宽至 6px（匹配 Minimal 整体柔和感）
- S.S6 边框厚度统一为 1px
- M.S5 Bento 网格对齐到 8pt 基线

配方 5：音乐 / 媒体应用

风格配比: Expressive 80% + Swiss 20%
分隔方式: Tab / 视图切换（同一 Shell 内）

路由结构:
├── App Shell — Expressive (暗色全局 Shell + Mini Sidebar)
│   ├── Now Playing (视图) — Expressive (全屏影院, Spotlight + 氛围渐变)
│   ├── Library (视图) — Swiss (Data Grid + 高密度曲目列表)
│   ├── Search (视图) — Swiss (搜索结果表格)
│   └── Playlist (视图) — Expressive (播放列表氛围)
│
└── 共享基础: oklch · --primary · 暗色统一基调

区域间过渡:
- Now Playing ↔ Library: Tab/侧边栏切换（不在同一滚动流中）
- Library ↔ Search: Tab 切换（同风格 Swiss）
- 所有视图切换使用 Expo Out 通用过渡动画

Director 覆盖:
- S.S4 Swiss 暗色背景暗化至 oklch(0.12 0 0)（与 Expressive 暗色调和谐）
- S.S1 Swiss 圆角维持 0px（暗色环境中直角更显精密）

七、Director 审查清单 (The Director Audit)

风格配比

• 主次明确 — 项目是否定义了主风格（70-80%）和辅风格（20-30%）？是否存在 50/50 无主次情况？
• 配比合理 — 风格选择是否与项目类型、受众、品牌调性匹配（参照第一章诊断矩阵）？
• 风格数量 — 是否超过 2 种风格（除非使用明确的三区域策略）？

区域纯度

• Zone Map 存在 — 是否为项目绘制了区域地图，明确每个区域的风格归属？
• 单组件单风格 — 是否有组件内部混用两种风格属性（Frankenstein Card）？
• 圆角一致 — 同一区域内的 rounded-* 值是否统一？
• 动效一致 — 同一区域内的动效是否遵循该区域风格的系统？
• 排版一致 — 同一区域内的排版系统是否遵循该区域风格（如 Mono 不泄漏到 Minimal 区域）？

Token 统一

• 色彩空间统一 — 所有 CSS Variables 是否统一使用 oklch？是否存在 HSL/oklch 混用？
• 品牌色一致 — --primary 品牌色是否全局一致？
• 暗色模式统一 — 全局暗色基准是否为 oklch(0.145 0 0)？Expressive 区域的暗化值是否在合规范围内？
• Token 使用 — 组件层是否全部使用语义 Token（bg-background 等），禁止硬编码 Hex？

接缝质量

• 接缝存在 — 所有不同风格区域之间是否有明确的接缝设计？
• 接缝类型合适 — 使用的接缝策略是否与风格组合匹配（参照第四章推荐矩阵）？
• 接缝动效 — 跨区域过渡动效是否使用 Expo Out 通用曲线？
• 接缝留白 — 接缝两侧的留白是否大于区域内部标准留白？

反模式扫描

• 无 Frankenstein Card — 单组件不混用多风格属性
• 无 Motion Clash — 区域内动效系统一致
• 无 Radius Soup — 区域内圆角统一
• 无 Color Space Split — 全局 oklch 统一
• 无 Shadow Leak — 投影仅限 Expressive 区域
• 无 Typography Contamination — 排版不跨区域污染
• 无 Density Mismatch — 信息密度匹配区域风格
• 无 Token Drift — --primary 全局一致

无障碍

• 对比度 — 所有文本 WCAG AA (≥4.5:1)，尤其是 Expressive 暗色区域的浅色文字
• 运动安全 — prefers-reduced-motion 是否在全局顶层统一处理？
• OLED 安全 — 暗色模式是否避免纯黑（使用 oklch(0.145 0 0) 或更亮）？

八、Skill 关联与委派模型 (Skill Delegation Model)

关联的 Style Guide Skills

本技能在策略层编排以下三个实现层 skill。当需要为某个区域生成具体的组件代码或审查实现时，必须委派给对应的 style guide skill：

审查配合： 实现完成后，可使用 frontend-design skill 审查代码层面的 Token 合规、组件库使用和动效质量。

Director 工作流

强制规则：在完成阶段 [1]–[3] 并输出完整策略文档之前，禁止编写任何组件代码或页面布局代码。 跳过诊断直接写代码会导致信息架构混乱、接缝 hack、Token 碎片化等问题。

用户描述项目需求
    ↓
[1] 诊断阶段 — 运行项目诊断矩阵（第一章）
    → 必须输出：推荐主辅风格 + 配比 + 简要理由
    ↓
[2] 区域映射阶段 — 定义区域策略（第二章）
    → 必须输出：Zone Map（ASCII 图），标注每个区域的风格归属和接缝类型
    ↓
[3] 委派指令阶段 — 为每个区域生成完整的委派指令
    → 必须输出：每个区域的软约束覆盖参数（引用约束 ID）+ 接缝策略
    ↓
── CHECKPOINT ──────────────────────────────────────────
    以上三个阶段的输出构成「策略文档」。
    在策略文档完成之前，不得进入下一阶段。
    策略文档必须包含：
    ✓ 风格配比（含百分比）
    ✓ 完整 Zone Map（路由结构图，标注每个路由/视图的风格归属）
    ✓ 分隔方式（路由切换 / Tab 切换 / 登录墙，而非同页滚动流接缝）
    ✓ 每个区域的委派指令（含约束 ID 引用）
    ✓ 每条过渡的类型（优先结构性接缝，必要时才用视觉性接缝）
────────────────────────────────────────────────────────
    ↓
[4] 基础设施阶段 — 配置项目级 Token 和区域变体
    → 在项目全局 CSS 文件（app.css / globals.css）中定义：
      · @theme 注册语义色彩 Token
      · @custom-variant 注册区域变体
      · :root 和 [data-zone="..."] 的 CSS Variables
    → 禁止在组件级或页面级文件中定义 Token（反模式 #12 Token Isolation）
    ↓
[5] 区域实现阶段 — 按区域逐一委派给具体 style guide skill
    → 每个区域严格遵循阶段 [3] 的委派指令
    → 接缝组件按阶段 [2] 的标注实现
    ↓
[6] 审查阶段 — 运行 Director 审查清单（第七章）
    → 随后可运行 frontend-design 进行技术合规审查

委派指令格式

当 Director 委派给具体 style guide skill 时，使用以下格式传递上下文：

区域: [区域名称，如 Hero / Dashboard / Content Body]
委派 Skill: [expressive-style-guide / minimal-style-guide / swiss-style-guide]

软约束覆盖（引用约束 ID，在声明的可调范围内）:
- [ID] [属性]: [调整后的值] ← 原因: [为什么调整]
- [ID] [属性]: [调整后的值] ← 原因: [为什么调整]

相邻区域的接缝:
- 上方接缝: [接缝类型]，连接 [上方区域风格]
- 下方接缝: [接缝类型]，连接 [下方区域风格]

示例 — 策展平台 Exhibition 路由的委派指令：

区域: /exhibition/:id (虚拟展览沉浸体验)
委派 Skill: expressive-style-guide

软约束覆盖:
- E.S3 色彩空间: oklch ← 原因: 混合项目统一色彩空间
- E.S4 暗色背景: oklch(0.08 0 0) ← 原因: 影院画布
- E.S2 动效时长上限: 0.8s ← 原因: 匹配项目整体节奏
- E.S5 Bento 网格: 对齐 8pt 基线 ← 原因: 项目中包含 Swiss 区域

相邻区域的接缝:
- 与 Bidding 页面通过路由切换分隔（无需视觉接缝）

示例 — 完整 Zone Map 输出（策展平台）：

项目: Galerie — 线上策展平台
风格配比: Expressive 70% + Swiss 30%
分隔方式: 路由切换 + Tab 切换

路由结构:
├── / (Home) — Expressive
│   ├── Nav — Expressive (透明覆盖)
│   ├── Hero — Expressive (全屏影院)
│   └── Exhibition Grid — Expressive (Bento 画廊)
│
├── /exhibition/:id — Expressive
│   └── 虚拟展览沉浸浏览 — Expressive (全屏暗色, 作品大图)
│
├── /auction (Tab: Live Bidding) — Swiss
│   ├── Bidding Panel — Swiss (竞拍数据表, 实时出价)
│   └── Lot Detail — Swiss (规格, 出价历史)
│
├── /collection (Tab: My Collection) — Swiss
│   └── 藏品管理 — Swiss (数据表格, 物流状态)
│
├── /about — Expressive
│   └── 策展人介绍 — Expressive (排版 + 影院级人像)
│
└── 共享基础: oklch · --primary · 暗色全局基调

区域间过渡:
- Exhibition → Auction: Tab 切换（Expressive 暗 → Swiss 暗, Expo Out 过渡）
- Home → Exhibition: 路由切换（同风格 Expressive）
- 所有 Swiss 区域暗色背景统一为 oklch(0.12 0 0)

职责边界

• Director 做什么： 诊断需求 → 推荐配比 → 绘制 Zone Map → 裁决属性冲突 → 设计接缝 → 生成覆盖参数 → 审查区域纯度
• Director 不做什么： 不生成组件代码、不定义视觉规范细节、不替代三个 style guide skill 的职责
• Director 不知道的： 具体组件怎么写、shadcn/ui 组件的具体改造方式、Framer Motion 的具体动画代码——这些都由被委派的 style guide skill 负责
• 不存在循环依赖： Director 是单向调度上游，不被其他 skill 反向调用