css-tokens

CSS 设计令牌技能

用途

此技能提供一套全面的 CSS 设计令牌（自定义属性），为 Web 项目建立一致的设计基础。用户需要基础令牌系统或 CSS 设计令牌时，请使用此技能。

何时使用此技能

用户提出以下请求时，请使用此技能：

• “为我的项目添加设计令牌”
• “设置 CSS 令牌”
• “创建令牌文件”
• “添加基础 CSS 变量”
• 类似的基础 CSS 自定义属性需求

何时不使用此技能

• 用户已有设计令牌系统（建议修改现有系统）
• 用户明确要求特定框架的令牌系统（例如 Tailwind 配置、CSS-in-JS 令牌）
• 用户只需要部分令牌（可提出为其提取特定类别的令牌）

此技能提供的内容

一个完整的 tokens.css 文件，包含一套全面的设计令牌系统：

• 排版：字体系列、字重和模块化字号比例（从 xs 到 4xl）
• 间距：从 4px 到 96px 的一致尺寸比例，并以像素值命名
• 颜色：使用 oklch() 颜色空间提供感知上均匀的颜色，并为表面、文本、品牌、交互元素和语义状态提供浅色／深色模式变体
• 边框：根据尺寸比例定义的圆角值（从 sm 到 full）
• Z-index：用于堆叠上下文的命名层（dropdown、modal、toast 等）
• 过渡：标准时长值（fast、base、slow）

用户可以使用 CSS 自定义属性语法引用单个令牌：var(--token-name)

令牌内容

完整的令牌定义位于此技能目录中的 references/tokens.css。此文件按类别组织，包含所有 CSS 自定义属性声明。

如何使用此技能

1. 检测 CSS 目录

在项目中搜索常见的 CSS 目录名称：

• css/
• styles/
• assets/css/
• stylesheets/
• src/css/
• src/styles/

检查多个层级的目录（根目录、src/、public/、assets/）。

2. 与用户确认位置

如果找到 CSS 目录：

告知用户发现的位置并请求确认：

I found a CSS directory at [path]. Should I add the design tokens to this directory in a file named `tokens.css`?

If you'd like a different location or filename, please specify both.

如果未找到 CSS 目录：

直接询问用户：

I couldn't find an existing CSS directory in your project. Please specify:
1. The directory path where you'd like the tokens file (I can create it if needed)
2. The filename (e.g., `tokens.css`, `design-tokens.css`)

3. 写入令牌文件

确认后，将完整的令牌文件写入指定位置。使用此技能目录中 references/tokens.css 的确切内容。

4. 告知用户如何导入

成功写入文件后，告知用户：

✓ 设计令牌已写入 [full-path]

若要在项目中使用这些令牌，请在主 CSS 文件或 HTML 中导入此文件：

在 CSS 中：

@import url('path/to/tokens.css');

在 HTML 中：

<link rel="stylesheet" href="path/to/tokens.css" />

现在，整个项目都可以使用这些 CSS 自定义属性（例如，var(--color-primary)、var(--size-16)）。

自定义

这些令牌提供了坚实的基础，但应根据项目进行自定义：

• 调整颜色值以匹配品牌
• 修改间距比例以适应设计系统
• 根据需要添加项目专属令牌
• 扩展类别并添加其他令牌（动画、阴影等）

这是一项脚手架技能——用于搭建初始结构，但不负责后续修改。

重要说明

• 如果用户未指定目录结构或文件名，请勿自行假设
• 务必先确认位置，再写入文件
• 如有需要，且经用户确认后，创建目录
• 令牌文件使用 prefers-color-scheme 同时包含浅色和深色模式配色方案
• oklch() 颜色空间可提供感知上均匀的颜色，从而提升可访问性和一致性