@xulthekl/team-flow 0.53.0 → 0.54.0

package/skills/prototype/references/orchestration-flow.md

@@ -20,7 +20,7 @@
 派发插件 agent `prototype-env-scout`（只读，tools 硬限 Read/Bash/Grep/Glob），传入：PRD 路径、config 的 `prototype.designSystem`/`prototype.entry`、当前 git 分支。简报写在 response，主代理按需落盘。
 
 子代理探查并产出环境简报：
-- **设计系统现状**：`design-system.md` 是否存在？9 段 schema 完整度？缺失哪些段？
+- **设计系统现状**：`.team-flow/design-system/` 是否存在（base.md + 端变体）？**合并后** 9 段 schema 完整度？`primer.md` 是否存在且 digest 未过期？契约表组件数分档（<10 / 10-14 / ≥15）？
 - **原型仓库分支**：当前分支、是否已有 `prototype/`、与 PRD 版本分支是否对齐
 - **PRD 版本**：`iteration_version`、冻结状态、UI 功能点清单（§4/§7）
 - **已有页面**：现有 prototype/ 页面/组件清单（迭代时）
@@ -50,7 +50,7 @@ LT 确认后进入 ③。**confirmed_plan 序列化**：将 scout 简报的选
 
 ## 步骤 ③ 原型绘制（子代理）
 
-派发插件 agent `prototype-builder`（有 Write），传入：已确认的原型方案（含选定方向）、`design-system.md` 路径、目标分支/版本、PRD 路径。
+派发插件 agent `prototype-builder`（有 Write），传入：已确认的原型方案（含选定方向）、`design_system_path`（`.team-flow/design-system/<variant>.md`，与 base.md 合并渲染）、`variant`、`prototype_root`、目标分支/版本、`prd_path`、`mode: default`（showcase 模式见 builder-methodology「Showcase 模式」——该模式豁免 `confirmed_plan`/`prd_path`）。
 
 **⛔ 子代理 ID 记录（v0.29.1，必须执行）**：dispatch 后**立即记录**子代理 ID，后续 ⑤ 循环修正和 ⑥ 人工评审调整**必须通过此 ID 恢复子代理**，不得启动新子代理：
 ```
@@ -58,7 +58,7 @@ builder_agent_id = <agentId>    # ③ dispatch 返回
 reviewer_agent_id = <agentId>   # ④ dispatch 返回
 ```
 
-**prompt 组装顺序契约（v0.18.0, v0.24.0 扩展）**：`design-system.md → references/template.html → references/layouts.md → references/checklist.md → references/craft/（按页面类型选择注入）→ references/interactive-prototype.md（按需）→ references/wireframe.md（按需）→ PRD`。
+**prompt 组装顺序契约（v0.18.0, v0.24.0 扩展）**：`.team-flow/design-system/`（base + 变体）→ references/template.html → references/layouts.md → references/checklist.md → references/craft/（按页面类型选择注入）→ references/interactive-prototype.md（按需）→ references/wireframe.md（按需）→ PRD`。
 
 craft 注入策略：仪表盘→laws-of-ux+state-coverage；表单→state-coverage+accessibility-baseline；列表→typography-hierarchy；通用→anti-ai-slop（始终注入）。
 
@@ -107,6 +107,15 @@ agent 直接写审查报告到 `requirement/vN/prototype-auto-review.md`。
 - **PRD 有问题** → 回 orchestrator S2 修订 PRD（**vN 内修订 + 变更履历，非升版**；见 feedback-loops 设计）→ PRD 更新后再回 ① 更新原型。**独立调用 fallback**（非 orchestrator 触发时）：无 S2 可回，直接提示 LT 修订 `requirement/vN/prd.md` 后重入本 skill。
 - **原型需调整**（美观/体验/品牌/信息密度等自动评审查不到的维度）→ **⛔ 必须通过 SendMessage 恢复原 prototype-builder 实施调整**（`SendMessage(to: builder_agent_id, message: "用户评审反馈：{调整意见}。请修改原型。")`），修改后 SendMessage 恢复原 prototype-reviewer 重新评审。**禁止启动新子代理**（唯一例外：SendMessage 恢复失败时的 fallback）
 - **通过** → 冻结：PRD frontmatter `frozen: true`（frozen_downstream），prototype 定版
+- **设计系统增量确认（v0.54.0，新增分支）**：若 builder handoff 的 `outstanding_questions` 含 `ds_increment` 条目（`missing_component` / `outdated_token` / `new_variant`），在本次 AskUserQuestion 中**并入**呈现：
+
+  > 「原型绘制中发现 N 项设计系统增量：① {描述}（{workaround}） ② … — [全部确认 | 逐项确认 | 暂不处理]」
+
+  - **全部确认 / 逐项确认** → 主代理调 `/team-flow:design-system`（iterate 模式）传入确认项。
+    - **时序约束**：iterate 一律**延迟到 builder 任务终态交接后**执行（避免绘制中途 primer 变更导致产出与白名单版本不一致）
+    - **并发提示**：iterate 前检查活跃 change（`${CLAUDE_PLUGIN_ROOT}/scripts/lib/state-loader.mjs`）→ 提示"本次设计系统变更会影响进行中的 change: X/Y"
+  - **暂不处理** → 由 **design-system skill**（唯一写者）追加到 `.team-flow/design-system/pending.md`；条目格式 `{描述} | 来源: <change-id 或 s2-prototype> | 时间: <ISO>`
+  - **不追溯重构**：已冻结原型不自动重绘——workaround 保留至该页下次进入绘制时替换
 
 ## 子代理阻断处理（§18.1）
 

package/skills/prototype/references/prototype-scaffold/assets/design-tokens.css

@@ -1,5 +1,5 @@
 :root{
-  /* A1-identity：由 design-system.md 渲染覆盖，此处为骨架占位 */
+  /* A1-identity：由 .team-flow/design-system/ 渲染覆盖，此处为骨架占位 */
   --color-primary: #c96442;   /* 占位，渲染时替换为品牌主色 */
   --color-neutral-900: #1a1916;
   --bg: #fafaf7; --surface: #ffffff; --fg: #1a1916; --muted: #6b6964; --border: #e8e5df;
@@ -15,5 +15,5 @@
   --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px;
   --radius-1: 4px; --radius-2: 8px;
   --font-base: 16px;
-  /* 由 design-system.md 渲染；修改走 design-system，不在此硬编码新值 */
+  /* 由 .team-flow/design-system/ 渲染；修改走 design-system，不在此硬编码新值 */
 }

package/skills/prototype/references/template.html

@@ -1,4 +1,4 @@
-<!-- 种子模板（v0.18.0）：builder 从此模板组合，不从零写 CSS。token 由 design-system.md 渲染覆盖。 -->
+<!-- 种子模板（v0.18.0）：builder 从此模板组合，不从零写 CSS。token 由 .team-flow/design-system/ 渲染覆盖。 -->
 <!-- 零外部依赖、可离线：CSS 进 <style>、JS 进 <script>，无 CDN / 外部字体 / 外部脚本。 -->
 <!doctype html>
 <html lang="zh-CN" data-theme="light" data-density="comfortable">
@@ -8,16 +8,16 @@
 <title>team-flow prototype · seed template</title>
 <style>
 /* ============================================================
-   TOKENS — 由 design-system.md 渲染覆盖，禁止在此硬编码新值。
+   TOKENS — 由 .team-flow/design-system/ 渲染覆盖，禁止在此硬编码新值。
    占位默认值为「中性陶土」基调（非 indigo），保证模板离线可渲染。
    ============================================================ */
 :root{
-  /* —— 品牌/中性色（design-system.md 覆盖位）—— */
-  --color-primary: #c96442;        /* 由 design-system.md 渲染覆盖 */
-  --color-neutral-900: #1a1916;    /* 由 design-system.md 渲染覆盖 */
+  /* —— 品牌/中性色（.team-flow/design-system/ 覆盖位）—— */
+  --color-primary: #c96442;        /* 由 .team-flow/design-system/ 渲染覆盖 */
+  --color-neutral-900: #1a1916;    /* 由 .team-flow/design-system/ 渲染覆盖 */
 
   /* —— 单一 accent：每屏 ≤2 处 —— */
-  --accent: #c96442;               /* 由 design-system.md 渲染覆盖（terracotta 中性暖色占位） */
+  --accent: #c96442;               /* 由 .team-flow/design-system/ 渲染覆盖（terracotta 中性暖色占位） */
   --accent-hover:  color-mix(in oklab, var(--accent), black 8%);
   --accent-active: color-mix(in oklab, var(--accent), black 14%);
   --accent-soft:   color-mix(in oklab, var(--accent), transparent 86%);
@@ -32,8 +32,8 @@
   --border: #e8e5df;
 
   /* —— 字体（系统栈，零外部字体）—— */
-  --font-display: ui-sans-serif, 'PingFang SC', 'Microsoft YaHei', system-ui, sans-serif; /* 由 design-system.md 渲染覆盖 */
-  --font-body:    ui-sans-serif, 'PingFang SC', 'Microsoft YaHei', system-ui, sans-serif; /* 由 design-system.md 渲染覆盖 */
+  --font-display: ui-sans-serif, 'PingFang SC', 'Microsoft YaHei', system-ui, sans-serif; /* 由 .team-flow/design-system/ 渲染覆盖 */
+  --font-body:    ui-sans-serif, 'PingFang SC', 'Microsoft YaHei', system-ui, sans-serif; /* 由 .team-flow/design-system/ 渲染覆盖 */
   --font-mono:    ui-monospace, 'JetBrains Mono', monospace;
 
   /* —— 字号阶梯（type scale）—— */
@@ -369,7 +369,7 @@ code{ font-family: var(--font-mono); font-size: 0.9em; }
     <div class="container hero-center">
       <p class="eyebrow">team-flow · seed template</p>
       <h1>从种子模板组合页面，不从零写 CSS</h1>
-      <p class="lead">所有 section 直接落入 main，token 由 design-system.md 渲染覆盖，零外部依赖、可离线。</p>
+      <p class="lead">所有 section 直接落入 main，token 由 .team-flow/design-system/ 渲染覆盖，零外部依赖、可离线。</p>
       <div class="hero-cta">
         <a class="btn btn-primary" href="#content">主操作</a>
         <a class="btn btn-secondary" href="#content">次要操作</a>
@@ -383,7 +383,7 @@ code{ font-family: var(--font-mono); font-size: 0.9em; }
 <footer class="pagefoot" data-testid="P-00-pagefoot">
   <div class="container row-between">
     <span>© team-flow prototype</span>
-    <span class="meta">由 seed template (v0.18.0) 组合 · token 由 design-system.md 渲染</span>
+    <span class="meta">由 seed template (v0.18.0) 组合 · token 由 .team-flow/design-system/ 渲染</span>
   </div>
 </footer>
 

package/skills/release-archivist/SKILL.md

@@ -157,6 +157,7 @@ If implementation diverged from the contract, return to `bridging` before closur
 ③ tf prototype-sync <change-dir>
 ④ tf test-merge <change-dir>
 ⑤ tf solutions promote（compound promotion）
+⑥ 设计系统待办检查（v0.54.0）              ← 只读检查 + 报告，不执行 iterate
 ```
 
 （各步详细说明见下方对应节标题的 ①–⑤ 编号。）
@@ -165,7 +166,7 @@ If implementation diverged from the contract, return to `bridging` before closur
 >
 > **为何 ① 必须在 ② 之前**（v0.53.0 变更，务必遵守）：`executing→closing` 现挂 **`arch-merged` 门禁维度**——转换时校验全局台账已含本 change 增量。**未回写则转换被拒**。完整论证（含与 `arch-snapshot` 的无数据依赖关系）见 `references/closing-procedures.md`。
 
-**架构快照门禁（arch-snapshot，v0.36.0 / v0.36.3）**：本轮迭代产品级架构快照 `iterations/vN/architecture.md` 必须已落盘（"先快照后回写"强制化）。**FAIL 升级路径**：回 orchestrator 的 ARCH 阶段补快照；存量升级在途 change（快照缺失但 change 有增量产物）→ WARN 兜底放行；`arch_baseline` 缺失 → WARN 不阻断。hotfix/tweak 豁免（不挂该维度）。判定逻辑见 `scripts/guard/checks/arch-gate-exemptions.mjs`。
+**架构快照门禁（arch-snapshot，v0.36.0 / v0.36.3）**：本轮迭代产品级架构快照 `iterations/vN/architecture.md` 必须已落盘（"先快照后回写"强制化）。**FAIL 升级路径**：回 orchestrator 的 ARCH 阶段补快照；存量升级在途 change（快照缺失但 change 有增量产物）→ WARN 兜底放行；`arch_baseline` 缺失 → WARN 不阻断。hotfix/tweak 豁免（不挂该维度）。判定逻辑见插件内 `scripts/guard/checks/arch-gate-exemptions.mjs`（引用，非调用）。
 
 ### ① Architecture Merge (v0.10 §28-§31) — MUST run first
 
@@ -230,12 +231,18 @@ Promote change-level learnings to the global solutions library:
 tf solutions promote <change-dir>
 ```
 
-读取 change 根目录的 `learnings.md`（v0.49.0 §83.3.5 路径统一）——`severity ≥ medium` 且 `type = pitfall|pattern` 者晋升全局 `docs/solutions/`；命中既有条目则标记 confirmed pattern 并升级 severity。severity 序 `critical > high > medium > low` 定义在 `scripts/lib/severity.mjs`（v0.23 §91，单一来源）。
+读取 change 根目录的 `learnings.md`（v0.49.0 §83.3.5 路径统一）——`severity ≥ medium` 且 `type = pitfall|pattern` 者晋升全局 `docs/solutions/`；命中既有条目则标记 confirmed pattern 并升级 severity。severity 序 `critical > high > medium > low` 定义在插件内 `scripts/lib/severity.mjs`（引用，非调用）（v0.23 §91，单一来源）。
 
 **Compound Capture Check（v0.5）**：closing 前自检本 change 是否产生了可沉淀的经验（强制回退 / 复发根因 / 范围外扩 / 契约漂移）；有则写入 change 根的 `learnings.md`，每条 `## <title>` 带 frontmatter（`phase`/`domain`/`type`/`severity`/`date`）。该文件正是 `compound-captured` guard 检查、`tf solutions promote` 读取的对象。
 
 > **本节的展开版（条目质量要求、`tf solutions capture` 与 `learnings.md` 的分工、Prototype Sync / Worktree Deisolation / Code Landing 全流程）见 `references/closing-procedures.md`**——该处为超集，本节不再重复（v0.53.0 §115.10：同名节曾两处各自维护，属根因 Ⅲ 的同一类漂移）。
 
+### ⑥ 设计系统待办检查（v0.54.0）— 只读检查 + 报告
+
+检查 `.team-flow/design-system/pending.md` 非空时，在 closing summary 的 `design_system_pending` 中报告条目数并标注 `needs user confirmation`（报告触发条件与细节见 `references/closing-procedures.md`）。
+
+**只读，不执行 iterate**（由 design-system skill 在用户确认后触发）；**单写者约束**：写入/移除一律由 design-system skill 执行。快速 closing 时 pending.md 保留不动。
+
 ### 阶段产物同步门禁点（v0.37.0 §68.2 G5）
 
 回写链（顺序见 `### ⚠ 执行顺序` 的 ①–⑤）**全部完成后**，**阻塞确认**（AskUserQuestion）是否同步 change 实施结果（团队协作：落地结果是团队最需要看的内容）：
@@ -278,7 +285,7 @@ Verify files exist and are non-empty, run `node --check` on code files, skip 5-s
 
 **回写链前置判据（v0.22 §87）**：先按下表判断适用性，**不适用则不执行命令**（v0.22 实测：逐项跑完才知道不适用，占 release-archivist 80% 耗时）。本表 4 行判据**仅在 Lightweight Closure 适用**；其中 arch-merge 与 test-merge 两行的 "Skip silently" 见 `### ① Architecture Merge` 与 `### ④ Test Merge` 两节各自的正文句。
 
-> **v0.53.0 修正**：此处原用行号引用（`（:164 正文句）`/`（:196 正文句）`），本次改动插入段落使其失效。**行号引用在密集改动期必然漂移，已改为按标题引用**——同轮 `docs/architecture-api-db-design-enhancement-v0.25.md` 亦把 45 处行号引用全量改为符号引用。
+> **v0.53.0 修正**：此处原用行号引用（`（:164 正文句）`/`（:196 正文句）`），本次改动插入段落使其失效。**行号引用在密集改动期必然漂移，已改为按标题引用**——同轮 `team-flow-workspace/docs/architecture-api-db-design-enhancement-v0.25.md` 亦把 45 处行号引用全量改为符号引用。
 
 | 回写项 | 前置判据 | 不满足时登记 |
 |---|---|---|

package/skills/release-archivist/references/closing-procedures.md

@@ -96,3 +96,13 @@ If an `e2e/` suite exists for the change:
 ## Lightweight Closure (hotfix/tweak)
 
 Verify files exist and are non-empty, run `node --check` on code files, skip 5-step verification. Still record DP-6 and DP-7.
+
+## ⑥ 设计系统待办检查（v0.54.0）
+
+`Post-Verification` 顺序的 ⑥（只读检查 + 报告，不执行 iterate）。检查 `.team-flow/design-system/pending.md`（原型阶段"暂不处理"的设计系统增量暂存）：
+
+1. **非空时**：读取未处理条目（格式 `{描述} | 来源: <change-id 或 s2-prototype> | 时间: <ISO>`），在 closing summary 的 `design_system_pending` 字段列出并标注 `needs user confirmation`
+   - **报告触发条件（防仪式膨胀）**：仅当「本 change 产生过 `ds_increment`（来源标注含本 change-id）」**或**「pending.md 非空且本次会话未询问过」时显式列出并建议确认；其余情况仅记录条目数
+2. **不执行 iterate**——iterate 由 design-system skill 在用户确认后另行触发；主代理提示二选一：closing 等待执行 / 保留 pending 待下次绘制处理
+3. **快速 closing（无交互路径）**：pending.md **保留不动**（不丢失，下次生效）
+4. **单写者约束**：本步**只读**——写入/移除一律由 design-system skill 的 iterate 流程执行（避免多 change 并发读改写导致丢失更新）

package/skills/workflow-bootstrap/SKILL.md

@@ -12,7 +12,7 @@ description: 既有项目接入初始化器。在首次使用 team-flow 时执
 ```
 workflow-bootstrap（一次性，手动触发）
   → B1 代码库侦察 → B1.5 conventions → B2 架构基线 → B3 领域词汇 → B4 目录初始化
-  → B4.5 CLAUDE.md 初始化 → B5 路径判断
+  → B4.5 CLAUDE.md 初始化 → B4.6 Design System 起点选择 → B5 路径判断
   → 进入 workflow-orchestrator S1（注入 baseline 上下文）
 ```
 
@@ -218,6 +218,18 @@ Step 2: 确定性提取（兜底）
 
 **不做的事**：不写 SOP 流程（由 skill 负责）、不写变更级状态机（由 workflow skill 负责）、不列可自动发现的文件清单。
 
+### B4.6: Design System 起点选择（advisory，v0.54.0 新增）
+
+> 编号说明：B4.5 已被占用（CLAUDE.md 初始化），本步骤为 B4.6。
+
+`.team-flow/design-system/` 不存在时，AskUserQuestion 呈现起点四选一（**不阻断**，延续 advisory 约定）：
+
+> 「检测到项目尚无设计系统。选择起点方式：[从模板库选择 | 逆向建库 | 从零创建 | 跳过]」
+
+- **模板库**：调 `/team-flow:design-system`（起点=模板库）——由该 skill 呈现 `${CLAUDE_PLUGIN_ROOT}/templates/design-systems/registry.json`（8 个参考设计系统），选定后执行导入并**续跑 Step 5 评审 → Step 6 落盘**（含 primer 生成 + guard 校验）。**本步骤不直接调转换器**：转换器只产 base.md，缺少 primer 会让后续 prototype Step 0 对 `contract: v1` 系统直接 blocked（v0.54.0 P4 实证死路）
+- **逆向建库 / 从零创建**：调 `/team-flow:design-system`（create-from-code / 交互式 6 步）
+- **跳过** → 继续 B5；**已存在** → 跳过
+
 ### B5: Path Decision（路径判断，v0.42.0 重构：降级路径设计）
 
 询问用户。**分组展示**——用户先决定"要不要把地基打牢"（第一组），再决定"打完地基做什么"（第二组）：
@@ -258,7 +270,7 @@ Step 2: 确定性提取（兜底）
 ## Output Standard
 
 每次交互结束时说明：
-1. 已完成的阶段（B1-B1.5-B2-B3-B4-B4.5-B5）
+1. 已完成的阶段（B1-B1.5-B2-B3-B4-B4.5-B4.6-B5）
 2. 已产出的制品（baseline.md / conventions / ARCHITECTURE.md / PHYSICAL-MODEL.md / schema-baseline.sql / API-INDEX.md / INDEX.md / CONCEPTS.md / CLAUDE.md / cross-check-report.md（如执行 B）/ 目录结构）
 3. 下一步建议（调用哪个 skill）
 

package/templates/design-systems/references/claude.md

@@ -0,0 +1,315 @@
+# Design System Inspired by Claude (Anthropic)
+
+> Category: AI & LLM
+> Anthropic's AI assistant. Warm terracotta accent, clean editorial layout.
+
+## 1. Visual Theme & Atmosphere
+
+Claude's interface is a literary salon reimagined as a product page — warm, unhurried, and quietly intellectual. The entire experience is built on a parchment-toned canvas (`#f5f4ed`) that deliberately evokes the feeling of high-quality paper rather than a digital surface. Where most AI product pages lean into cold, futuristic aesthetics, Claude's design radiates human warmth, as if the AI itself has good taste in interior design.
+
+The signature move is the custom Anthropic Serif typeface — a medium-weight serif with generous proportions that gives every headline the gravitas of a book title. Combined with organic, hand-drawn-feeling illustrations in terracotta (`#c96442`), black, and muted green, the visual language says "thoughtful companion" rather than "powerful tool." The serif headlines breathe at tight-but-comfortable line-heights (1.10–1.30), creating a cadence that feels more like reading an essay than scanning a product page.
+
+What makes Claude's design truly distinctive is its warm neutral palette. Every gray has a yellow-brown undertone (`#5e5d59`, `#87867f`, `#4d4c48`) — there are no cool blue-grays anywhere. Borders are cream-tinted (`#f0eee6`, `#e8e6dc`), shadows use warm transparent blacks, and even the darkest surfaces (`#141413`, `#30302e`) carry a barely perceptible olive warmth. This chromatic consistency creates a space that feels lived-in and trustworthy.
+
+**Key Characteristics:**
+- Warm parchment canvas (`#f5f4ed`) evoking premium paper, not screens
+- Custom Anthropic type family: Serif for headlines, Sans for UI, Mono for code
+- Terracotta brand accent (`#c96442`) — warm, earthy, deliberately un-tech
+- Exclusively warm-toned neutrals — every gray has a yellow-brown undertone
+- Organic, editorial illustrations replacing typical tech iconography
+- Ring-based shadow system (`0px 0px 0px 1px`) creating border-like depth without visible borders
+- Magazine-like pacing with generous section spacing and serif-driven hierarchy
+
+## 2. Color Palette & Roles
+
+### Primary
+- **Anthropic Near Black** (`#141413`): The primary text color and dark-theme surface — not pure black but a warm, almost olive-tinted dark that's gentler on the eyes. The warmest "black" in any major tech brand.
+- **Terracotta Brand** (`#c96442`): The core brand color — a burnt orange-brown used for primary CTA buttons, brand moments, and the signature accent. Deliberately earthy and un-tech.
+- **Coral Accent** (`#d97757`): A lighter, warmer variant of the brand color used for text accents, links on dark surfaces, and secondary emphasis.
+
+### Secondary & Accent
+- **Error Crimson** (`#b53333`): A deep, warm red for error states — serious without being alarming.
+- **Focus Blue** (`#3898ec`): Standard blue for input focus rings — the only cool color in the entire system, used purely for accessibility.
+
+### Surface & Background
+- **Parchment** (`#f5f4ed`): The primary page background — a warm cream with a yellow-green tint that feels like aged paper. The emotional foundation of the entire design.
+- **Ivory** (`#faf9f5`): The lightest surface — used for cards and elevated containers on the Parchment background. Barely distinguishable but creates subtle layering.
+- **Pure White** (`#ffffff`): Reserved for specific button surfaces and maximum-contrast elements.
+- **Warm Sand** (`#e8e6dc`): Button backgrounds and prominent interactive surfaces — a noticeably warm light gray.
+- **Dark Surface** (`#30302e`): Dark-theme containers, nav borders, and elevated dark elements — warm charcoal.
+- **Deep Dark** (`#141413`): Dark-theme page background and primary dark surface.
+
+### Neutrals & Text
+- **Charcoal Warm** (`#4d4c48`): Button text on light warm surfaces — the go-to dark-on-light text.
+- **Olive Gray** (`#5e5d59`): Secondary body text — a distinctly warm medium-dark gray.
+- **Stone Gray** (`#87867f`): Tertiary text, footnotes, and de-emphasized metadata.
+- **Dark Warm** (`#3d3d3a`): Dark text links and emphasized secondary text.
+- **Warm Silver** (`#b0aea5`): Text on dark surfaces — a warm, parchment-tinted light gray.
+
+### Semantic & Accent
+- **Border Cream** (`#f0eee6`): Standard light-theme border — barely visible warm cream, creating the gentlest possible containment.
+- **Border Warm** (`#e8e6dc`): Prominent borders, section dividers, and emphasized containment on light surfaces.
+- **Border Dark** (`#30302e`): Standard border on dark surfaces — maintains the warm tone.
+- **Ring Warm** (`#d1cfc5`): Shadow ring color for button hover/focus states.
+- **Ring Subtle** (`#dedc01`): Secondary ring variant for lighter interactive surfaces.
+- **Ring Deep** (`#c2c0b6`): Deeper ring for active/pressed states.
+
+### Gradient System
+- Claude's design is **gradient-free** in the traditional sense. Depth and visual richness come from the interplay of warm surface tones, organic illustrations, and light/dark section alternation. The warm palette itself creates a "gradient" effect as the eye moves through cream → sand → stone → charcoal → black sections.
+
+## 3. Typography Rules
+
+### Font Family
+- **Headline**: `Anthropic Serif`, with fallback: `Georgia`
+- **Body / UI**: `Anthropic Sans`, with fallback: `Arial`
+- **Code**: `Anthropic Mono`, with fallback: `Arial`
+
+*Note: These are custom typefaces. For external implementations, Georgia serves as the serif substitute and system-ui/Inter as the sans substitute.*
+
+### Hierarchy
+
+| Role | Font | Size | Weight | Line Height | Letter Spacing | Notes |
+|------|------|------|--------|-------------|----------------|-------|
+| Display / Hero | Anthropic Serif | 64px (4rem) | 500 | 1.10 (tight) | normal | Maximum impact, book-title presence |
+| Section Heading | Anthropic Serif | 52px (3.25rem) | 500 | 1.20 (tight) | normal | Feature section anchors |
+| Sub-heading Large | Anthropic Serif | 36–36.8px (~2.3rem) | 500 | 1.30 | normal | Secondary section markers |
+| Sub-heading | Anthropic Serif | 32px (2rem) | 500 | 1.10 (tight) | normal | Card titles, feature names |
+| Sub-heading Small | Anthropic Serif | 25–25.6px (~1.6rem) | 500 | 1.20 | normal | Smaller section titles |
+| Feature Title | Anthropic Serif | 20.8px (1.3rem) | 500 | 1.20 | normal | Small feature headings |
+| Body Serif | Anthropic Serif | 17px (1.06rem) | 400 | 1.60 (relaxed) | normal | Serif body text (editorial passages) |
+| Body Large | Anthropic Sans | 20px (1.25rem) | 400 | 1.60 (relaxed) | normal | Intro paragraphs |
+| Body / Nav | Anthropic Sans | 17px (1.06rem) | 400–500 | 1.00–1.60 | normal | Navigation links, UI text |
+| Body Standard | Anthropic Sans | 16px (1rem) | 400–500 | 1.25–1.60 | normal | Standard body, button text |
+| Body Small | Anthropic Sans | 15px (0.94rem) | 400–500 | 1.00–1.60 | normal | Compact body text |
+| Caption | Anthropic Sans | 14px (0.88rem) | 400 | 1.43 | normal | Metadata, descriptions |
+| Label | Anthropic Sans | 12px (0.75rem) | 400–500 | 1.25–1.60 | 0.12px | Badges, small labels |
+| Overline | Anthropic Sans | 10px (0.63rem) | 400 | 1.60 | 0.5px | Uppercase overline labels |
+| Micro | Anthropic Sans | 9.6px (0.6rem) | 400 | 1.60 | 0.096px | Smallest text |
+| Code | Anthropic Mono | 15px (0.94rem) | 400 | 1.60 | -0.32px | Inline code, terminal |
+
+### Principles
+- **Serif for authority, sans for utility**: Anthropic Serif carries all headline content with medium weight (500), giving every heading the gravitas of a published title. Anthropic Sans handles all functional UI text — buttons, labels, navigation — with quiet efficiency.
+- **Single weight for serifs**: All Anthropic Serif headings use weight 500 — no bold, no light. This creates a consistent "voice" across all headline sizes, as if the same author wrote every heading.
+- **Relaxed body line-height**: Most body text uses 1.60 line-height — significantly more generous than typical tech sites (1.4–1.5). This creates a reading experience closer to a book than a dashboard.
+- **Tight-but-not-compressed headings**: Line-heights of 1.10–1.30 for headings are tight but never claustrophobic. The serif letterforms need breathing room that sans-serif fonts don't.
+- **Micro letter-spacing on labels**: Small sans text (12px and below) uses deliberate letter-spacing (0.12px–0.5px) to maintain readability at tiny sizes.
+
+## 4. Component Stylings
+
+### Buttons
+
+**Warm Sand (Secondary)**
+- Background: Warm Sand (`#e8e6dc`)
+- Text: Charcoal Warm (`#4d4c48`)
+- Padding: 0px 12px 0px 8px (asymmetric — icon-first layout)
+- Radius: comfortably rounded (8px)
+- Shadow: ring-based (`#e8e6dc 0px 0px 0px 0px, #d1cfc5 0px 0px 0px 1px`)
+- The workhorse button — warm, unassuming, clearly interactive
+
+**White Surface**
+- Background: Pure White (`#ffffff`)
+- Text: Anthropic Near Black (`#141413`)
+- Padding: 8px 16px 8px 12px
+- Radius: generously rounded (12px)
+- Hover: shifts to secondary background color
+- Clean, elevated button for light surfaces
+
+**Dark Charcoal**
+- Background: Dark Surface (`#30302e`)
+- Text: Ivory (`#faf9f5`)
+- Padding: 0px 12px 0px 8px
+- Radius: comfortably rounded (8px)
+- Shadow: ring-based (`#30302e 0px 0px 0px 0px, ring 0px 0px 0px 1px`)
+- The inverted variant for dark-on-light emphasis
+
+**Brand Terracotta**
+- Background: Terracotta Brand (`#c96442`)
+- Text: Ivory (`#faf9f5`)
+- Radius: 8–12px
+- Shadow: ring-based (`#c96442 0px 0px 0px 0px, #c96442 0px 0px 0px 1px`)
+- The primary CTA — the only button with chromatic color
+
+**Dark Primary**
+- Background: Anthropic Near Black (`#141413`)
+- Text: Warm Silver (`#b0aea5`)
+- Padding: 9.6px 16.8px
+- Radius: generously rounded (12px)
+- Border: thin solid Dark Surface (`1px solid #30302e`)
+- Used on dark theme surfaces
+
+### Cards & Containers
+- Background: Ivory (`#faf9f5`) or Pure White (`#ffffff`) on light surfaces; Dark Surface (`#30302e`) on dark
+- Border: thin solid Border Cream (`1px solid #f0eee6`) on light; `1px solid #30302e` on dark
+- Radius: comfortably rounded (8px) for standard cards; generously rounded (16px) for featured; very rounded (32px) for hero containers and embedded media
+- Shadow: whisper-soft (`rgba(0,0,0,0.05) 0px 4px 24px`) for elevated content
+- Ring shadow: `0px 0px 0px 1px` patterns for interactive card states
+- Section borders: `1px 0px 0px` (top-only) for list item separators
+
+### Inputs & Forms
+- Text: Anthropic Near Black (`#141413`)
+- Padding: 1.6px 12px (very compact vertical)
+- Border: standard warm borders
+- Focus: ring with Focus Blue (`#3898ec`) border-color — the only cool color moment
+- Radius: generously rounded (12px)
+
+### Navigation
+- Sticky top nav with warm background
+- Logo: Claude wordmark in Anthropic Near Black
+- Links: mix of Near Black (`#141413`), Olive Gray (`#5e5d59`), and Dark Warm (`#3d3d3a`)
+- Nav border: `1px solid #30302e` (dark) or `1px solid #f0eee6` (light)
+- CTA: Terracotta Brand button or White Surface button
+- Hover: text shifts to foreground-primary, no decoration
+
+### Image Treatment
+- Product screenshots showing the Claude chat interface
+- Generous border-radius on media (16–32px)
+- Embedded video players with rounded corners
+- Dark UI screenshots provide contrast against warm light canvas
+- Organic, hand-drawn illustrations for conceptual sections
+
+### Distinctive Components
+
+**Model Comparison Cards**
+- Opus 4.5, Sonnet 4.5, Haiku 4.5 presented in a clean card grid
+- Each model gets a bordered card with name, description, and capability badges
+- Border Warm (`#e8e6dc`) separation between items
+
+**Organic Illustrations**
+- Hand-drawn-feeling vector illustrations in terracotta, black, and muted green
+- Abstract, conceptual rather than literal product diagrams
+- The primary visual personality — no other AI company uses this style
+
+**Dark/Light Section Alternation**
+- The page alternates between Parchment light and Near Black dark sections
+- Creates a reading rhythm like chapters in a book
+- Each section feels like a distinct environment
+
+## 5. Layout Principles
+
+### Spacing System
+- Base unit: 8px
+- Scale: 3px, 4px, 6px, 8px, 10px, 12px, 16px, 20px, 24px, 30px
+- Button padding: asymmetric (0px 12px 0px 8px) or balanced (8px 16px)
+- Card internal padding: approximately 24–32px
+- Section vertical spacing: generous (estimated 80–120px between major sections)
+
+### Grid & Container
+- Max container width: approximately 1200px, centered
+- Hero: centered with editorial layout
+- Feature sections: single-column or 2–3 column card grids
+- Model comparison: clean 3-column grid
+- Full-width dark sections breaking the container for emphasis
+
+### Whitespace Philosophy
+- **Editorial pacing**: Each section breathes like a magazine spread — generous top/bottom margins create natural reading pauses.
+- **Serif-driven rhythm**: The serif headings establish a literary cadence that demands more whitespace than sans-serif designs.
+- **Content island approach**: Sections alternate between light and dark environments, creating distinct "rooms" for each message.
+
+### Border Radius Scale
+- Sharp (4px): Minimal inline elements
+- Subtly rounded (6–7.5px): Small buttons, secondary interactive elements
+- Comfortably rounded (8–8.5px): Standard buttons, cards, containers
+- Generously rounded (12px): Primary buttons, input fields, nav elements
+- Very rounded (16px): Featured containers, video players, tab lists
+- Highly rounded (24px): Tag-like elements, highlighted containers
+- Maximum rounded (32px): Hero containers, embedded media, large cards
+
+## 6. Depth & Elevation
+
+| Level | Treatment | Use |
+|-------|-----------|-----|
+| Flat (Level 0) | No shadow, no border | Parchment background, inline text |
+| Contained (Level 1) | `1px solid #f0eee6` (light) or `1px solid #30302e` (dark) | Standard cards, sections |
+| Ring (Level 2) | `0px 0px 0px 1px` ring shadows using warm grays | Interactive cards, buttons, hover states |
+| Whisper (Level 3) | `rgba(0,0,0,0.05) 0px 4px 24px` | Elevated feature cards, product screenshots |
+| Inset (Level 4) | `inset 0px 0px 0px 1px` at 15% opacity | Active/pressed button states |
+
+**Shadow Philosophy**: Claude communicates depth through **warm-toned ring shadows** rather than traditional drop shadows. The signature `0px 0px 0px 1px` pattern creates a border-like halo that's softer than an actual border — it's a shadow pretending to be a border, or a border that's technically a shadow. When drop shadows do appear, they're extremely soft (0.05 opacity, 24px blur) — barely visible lifts that suggest floating rather than casting.
+
+### Decorative Depth
+- **Light/Dark alternation**: The most dramatic depth effect comes from alternating between Parchment (`#f5f4ed`) and Near Black (`#141413`) sections — entire sections shift elevation by changing the ambient light level.
+- **Warm ring halos**: Button and card interactions use ring shadows that match the warm palette — never cool-toned or generic gray.
+
+## 7. Do's and Don'ts
+
+### Do
+- Use Parchment (`#f5f4ed`) as the primary light background — the warm cream tone IS the Claude personality
+- Use Anthropic Serif at weight 500 for all headlines — the single-weight consistency is intentional
+- Use Terracotta Brand (`#c96442`) only for primary CTAs and the highest-signal brand moments
+- Keep all neutrals warm-toned — every gray should have a yellow-brown undertone
+- Use ring shadows (`0px 0px 0px 1px`) for interactive element states instead of drop shadows
+- Maintain the editorial serif/sans hierarchy — serif for content headlines, sans for UI
+- Use generous body line-height (1.60) for a literary reading experience
+- Alternate between light and dark sections to create chapter-like page rhythm
+- Apply generous border-radius (12–32px) for a soft, approachable feel
+
+### Don't
+- Don't use cool blue-grays anywhere — the palette is exclusively warm-toned
+- Don't use bold (700+) weight on Anthropic Serif — weight 500 is the ceiling for serifs
+- Don't introduce saturated colors beyond Terracotta — the palette is deliberately muted
+- Don't use sharp corners (< 6px radius) on buttons or cards — softness is core to the identity
+- Don't apply heavy drop shadows — depth comes from ring shadows and background color shifts
+- Don't use pure white (`#ffffff`) as a page background — Parchment (`#f5f4ed`) or Ivory (`#faf9f5`) are always warmer
+- Don't use geometric/tech-style illustrations — Claude's illustrations are organic and hand-drawn-feeling
+- Don't reduce body line-height below 1.40 — the generous spacing supports the editorial personality
+- Don't use monospace fonts for non-code content — Anthropic Mono is strictly for code
+- Don't mix in sans-serif for headlines — the serif/sans split is the typographic identity
+
+## 8. Responsive Behavior
+
+### Breakpoints
+| Name | Width | Key Changes |
+|------|-------|-------------|
+| Small Mobile | <479px | Minimum layout, stacked everything, compact typography |
+| Mobile | 479–640px | Single column, hamburger nav, reduced heading sizes |
+| Large Mobile | 640–767px | Slightly wider content area |
+| Tablet | 768–991px | 2-column grids begin, condensed nav |
+| Desktop | 992px+ | Full multi-column layout, expanded nav, maximum hero typography (64px) |
+
+### Touch Targets
+- Buttons use generous padding (8–16px vertical minimum)
+- Navigation links adequately spaced for thumb navigation
+- Card surfaces serve as large touch targets
+- Minimum recommended: 44x44px
+
+### Collapsing Strategy
+- **Navigation**: Full horizontal nav collapses to hamburger on mobile
+- **Feature sections**: Multi-column → stacked single column
+- **Hero text**: 64px → 36px → ~25px progressive scaling
+- **Model cards**: 3-column → stacked vertical
+- **Section padding**: Reduces proportionally but maintains editorial rhythm
+- **Illustrations**: Scale proportionally, maintain aspect ratios
+
+### Image Behavior
+- Product screenshots scale proportionally within rounded containers
+- Illustrations maintain quality at all sizes
+- Video embeds maintain 16:9 aspect ratio with rounded corners
+- No art direction changes between breakpoints
+
+## 9. Agent Prompt Guide
+
+### Quick Color Reference
+- Brand CTA: "Terracotta Brand (#c96442)"
+- Page Background: "Parchment (#f5f4ed)"
+- Card Surface: "Ivory (#faf9f5)"
+- Primary Text: "Anthropic Near Black (#141413)"
+- Secondary Text: "Olive Gray (#5e5d59)"
+- Tertiary Text: "Stone Gray (#87867f)"
+- Borders (light): "Border Cream (#f0eee6)"
+- Dark Surface: "Dark Surface (#30302e)"
+
+### Example Component Prompts
+- "Create a hero section on Parchment (#f5f4ed) with a headline at 64px Anthropic Serif weight 500, line-height 1.10. Use Anthropic Near Black (#141413) text. Add a subtitle in Olive Gray (#5e5d59) at 20px Anthropic Sans with 1.60 line-height. Place a Terracotta Brand (#c96442) CTA button with Ivory text, 12px radius."
+- "Design a feature card on Ivory (#faf9f5) with a 1px solid Border Cream (#f0eee6) border and comfortably rounded corners (8px). Title in Anthropic Serif at 25px weight 500, description in Olive Gray (#5e5d59) at 16px Anthropic Sans. Add a whisper shadow (rgba(0,0,0,0.05) 0px 4px 24px)."
+- "Build a dark section on Anthropic Near Black (#141413) with Ivory (#faf9f5) headline text in Anthropic Serif at 52px weight 500. Use Warm Silver (#b0aea5) for body text. Borders in Dark Surface (#30302e)."
+- "Create a button in Warm Sand (#e8e6dc) with Charcoal Warm (#4d4c48) text, 8px radius, and a ring shadow (0px 0px 0px 1px #d1cfc5). Padding: 0px 12px 0px 8px."
+- "Design a model comparison grid with three cards on Ivory surfaces. Each card gets a Border Warm (#e8e6dc) top border, model name in Anthropic Serif at 25px, and description in Olive Gray at 15px Anthropic Sans."
+
+### Iteration Guide
+1. Focus on ONE component at a time
+2. Reference specific color names — "use Olive Gray (#5e5d59)" not "make it gray"
+3. Always specify warm-toned variants — no cool grays
+4. Describe serif vs sans usage explicitly — "Anthropic Serif for the heading, Anthropic Sans for the label"
+5. For shadows, use "ring shadow (0px 0px 0px 1px)" or "whisper shadow" — never generic "drop shadow"
+6. Specify the warm background — "on Parchment (#f5f4ed)" or "on Near Black (#141413)"
+7. Keep illustrations organic and conceptual — describe "hand-drawn-feeling" style