design-foundation

设计基础

为这个特定代码库生成可用的 token 文件，而不是编写一份介绍 token 的文档。Token 是一项有名称的设计决策（--color-text-primary、--space-4）；将它们集中管理，才能让后续的每项设计工作（布局、字体、颜色、组件）保持一致。指导原则：先提取，再创造——在现有代码库中，token 系统应将已有设计中最好的部分规范化，因此迁移应是重命名，而不是重新设计。

适用场景 / 后续衔接

• 用于从头创建 token，或从现有代码库中提取 token。
• 如果用户的问题主要是颜色（调色板、对比度、深色模式层次）→ 在 token 基础结构就绪后使用 skills/frontend-design/color-system。
• 如果主要是字体（比例、字体、可读性）→ 使用 skills/frontend-design/typography-system。
• 如果用户想基于 token 构建组件 → 接下来使用 skills/frontend-design/component-architecture。
• 对于宽泛的“从哪里开始”请求 → 使用 skills/frontend-design/frontend-orchestrator。

步骤 1 — 检查代码库

提问前先收集证据：

1. 查找当前的样式入口。 使用 Glob 查找 tailwind.config.{js,ts,cjs,mjs}、**/globals.css、**/index.css、**/app.css、**/*theme*、**/tokens*。阅读这些文件。
2. 识别技术栈。 Tailwind v4（@import "tailwindcss" + CSS 中的 @theme）、v3（配置文件中的 theme 对象），还是 CSS Modules / styled-components / 原生 CSS。检查 package.json 中的 tailwindcss 版本。
3. 衡量偏差。 在源代码中搜索 #[0-9a-fA-F]{3,8}\b、rgba?\(、hsla?\( → 统计不同颜色的数量。搜索 \d+px 和 Tailwind 任意值 \[(\d+px|#) → 统计游离的间距 / 尺寸值。这些统计数据应写入说明理由中。
4. 找出事实上的设计系统。 按出现频率排序找到的值。使用最多的字号、间距步进和颜色是候选 token。
5. 检查深色模式（dark:、prefers-color-scheme）——据此判断语义层现在是否需要同时支持两种模式。

步骤 2 — 收集需求

一次性询问尚未明确的信息：品牌色（或“由你决定”）、产品风格（密集的数据工具，还是宽敞的营销 / 消费者产品）以及现在还是之后再支持深色模式。其余内容自行推断。**不要拖延：**如果代码库已经给出答案（例如明显的品牌蓝，或已有 dark: 用法），说明假设并继续。

步骤 3 — 构建 token 系统

至少分两层；若存在组件库，则分三层：

1. 全局 token — 原始值：中性色阶（50–950，色调偏向品牌色，绝不用纯灰）、品牌色阶、语义状态色（成功 / 警告 / 错误 / 信息）、以 4px 为基准的间距比例（4、8、12、16、24、32、48、64）、字号、圆角、阴影、z-index 步进、过渡时长。
2. 语义 token — 表示含义，并引用全局 token：bg-primary/secondary、text-primary/secondary/tertiary/inverse、border-primary、interactive-primary/hover/active/disabled。深色模式切换的是这一层——组件只使用语义 token。
3. 组件 token — 仅在存在组件库或计划下一步构建组件库时使用（--button-primary-bg: var(--color-interactive-primary)）。

决策规则：

• Tailwind v4 → 在主 CSS 文件的 @theme 中将 token 定义为 CSS 变量。Tailwind v3 → 在配置中使用 theme.extend，并将语义层作为 CSS 变量供配置引用。不使用 Tailwind → 在 :root 上使用普通 CSS 自定义属性（+ .dark 或媒体查询代码块）。
• **提取规则：**如果现有值聚集在一起（15px、16px、17px），则归并为最接近出现频率最高值的比例值；在迁移映射表中列出每一项归并。
• **命名：**使用 kebab-case，以类别开头（--color-text-primary、--space-4、--radius-md）。若项目使用 Tailwind，则沿用 Tailwind 的名称，以便工具类继续生效。

规范形态（CSS 变量；根据检测到的技术栈调整）

:root {
  /* global */
  --gray-50: #F8FAFC;  --gray-500: #64748B;  --gray-900: #0F172A; /* full 50–950 ramp, brand-tinted */
  --brand-500: #3B82F6; --brand-600: #2563EB; /* full ramp */
  --space-1: 0.25rem; --space-2: 0.5rem; --space-4: 1rem; --space-8: 2rem;
  --radius-md: 0.375rem; --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.10);

  /* semantic — the only layer components touch */
  --color-bg-primary: var(--gray-50);
  --color-text-primary: var(--gray-900);
  --color-text-secondary: var(--gray-600);
  --color-border-primary: var(--gray-200);
  --color-interactive-primary: var(--brand-600);
  --color-interactive-hover: var(--brand-700);
}
.dark {
  --color-bg-primary: var(--gray-950);   /* dark gray, never #000 */
  --color-text-primary: var(--gray-50);
  --color-text-secondary: var(--gray-300);
  --color-border-primary: var(--gray-700);
}

完整的三层分类、Tailwind v3/v4 接线方式，以及变体／响应式令牌模式：构建完整文件时，请阅读 references/token-architecture.md。

第 4 步——编写文件并迁移最突出的问题

1. 将令牌写入检测到的入口点（不要在现有系统旁另建一套系统，而应在其基础上扩展）。
2. 迁移流量最高的 1–3 个文件（即 grep 结果显示偏差最大、最明显的文件）作为示例，用令牌替换原始值。
3. 为其余部分生成迁移映射。

必需的输出格式

提供代码和以下摘要：

## Tokens file
[path written, e.g. src/app/globals.css or tailwind.config.ts — full contents]

## Decisions
| Decision | Choice | Why |
| Stack wiring | Tailwind v4 @theme / v3 config / CSS vars | [detected how] |
| Neutral tint | [hue] | matches brand [color] |
| Spacing base | 4px | [most existing values already multiples / default] |
| Dark mode | now via .dark class / deferred | [user answer or inference] |

## Migration map (worst drift first)
| Found in code | Count | Replace with |
| #3c82f7, #3B82F6, #3a80f0 | 23 | var(--color-interactive-primary) |
| padding: 13px / p-[13px] | 9 | var(--space-3) (12px) |
| ... |

## Migrated now
[files actually edited as demonstration]

## Next step
[Which skill consumes this — typically skills/frontend-design/typography-system or color-system]

质量标准（交付前检查）

• 如果已提供暗色模式，则两种模式下每组语义文本／背景搭配均符合 WCAG AA（普通文本对比度为 4.5:1，大号文本为 3:1）
• 间距刻度采用基于同一基数的单一、近似几何级数；没有游离的刻度
• 中性色带有品牌色调（饱和度非零），不使用 #808080／纯黑 #000
• 组件／示例仅引用语义令牌，绝不直接引用全局令牌
• 令牌名称不会与现有名称冲突；Tailwind 工具类仍可正常解析
• 迁移映射涵盖第 1 步中发现的每个值簇，且每个值簇恰好映射到一个令牌
• 没有引入第二套并行令牌系统

集成

• 消耗：来自 skills/frontend-design/frontend-orchestrator 的成熟度诊断和偏差计数（如果运行了该工具）。
• 生成由以下工具使用的令牌文件：skills/frontend-design/typography-system（扩展类型令牌）、skills/frontend-design/color-system（扩展色阶和暗色模式）、skills/frontend-design/layout-system（间距和断点）、skills/frontend-design/visual-hierarchy-refactoring（将屏幕重构为使用令牌）以及 skills/frontend-design/component-architecture（组件层）。

参考资料

• references/token-architecture.md——包含完整列表的三层令牌分类、Tailwind v3 和 v4 接线方式，以及暗色模式、组件变体和响应式令牌模式。编写完整的令牌文件或为不熟悉的技术栈配置接线时，请阅读。