Token CSS 使用教程

1. 项目介绍

Token CSS 是一个新颖的工具，它能够无缝地将设计令牌（Design Tokens）集成到您的开发工作流程中。它与 Tailwind、Styled System 以及许多 CSS-in-JS 库类似，都提供了样式化的约束，但 Token CSS 最大的不同在于它完全拥抱了 .css 文件和 <style> 标签。

设计令牌是代表设计决策（如颜色、字体大小、间距等）的可重用变量。Token CSS 使得在整个项目中统一和修改这些设计属性变得简单。

2. 项目快速启动

首先，您需要安装 Token CSS。如果您使用的是 Astro 框架，可以直接添加官方的 Astro 集成。否则，您需要安装 @tokencss/postcss 插件并将其添加到您的 PostCSS 配置中。

使用 Astro

npm run astro add @tokencss/astro

使用 PostCSS

npm install @tokencss/postcss

然后在您的 PostCSS 配置文件中添加以下内容：

const tokencss = require('@tokencss/postcss');

module.exports = {
  plugins: [
    tokencss()
  ],
};

接下来，在项目根目录下创建一个 token.config.json 文件。Token CSS 插件将自动读取这个文件。

{
  "$schema": "https://tokencss.com/schema@0.0.1",
  "extends": ["@tokencss/core/preset"],
  "color": {
    "gray": {
      "0": { "value": "#f8f9fa" },
      "1": { "value": "#f1f3f5" },
      // 更多颜色定义...
    }
  },
  // 更多配置...
}

在您的样式表中，您可以通过 @inject 指令注入基础样式：

@inject "tokencss:base";

然后就可以开始使用 Token CSS 的变量了：

.box {
  background: red.5;
  border-radius: md;
  width: lg;
  height: lg;
}

3. 应用案例和最佳实践

在项目中使用 Token CSS，可以创建一个统一的样式指南，并确保整个项目中的样式保持一致。以下是一些最佳实践：

• 定义清晰的设计令牌： 在 token.config.json 中定义所有设计元素，确保它们清晰、一致且易于维护。
• 使用变量而非硬编码值： 在 CSS 中使用 Token CSS 变量而非直接书写样式值，以便于未来全局修改。
• 保持简洁： 尽量保持令牌配置的简洁性，避免过多的复杂配置。

4. 典型生态项目

Token CSS 适用于任何需要全局样式管理的大型项目。以下是一些可能受益于 Token CSS 的典型生态项目：

• 企业级应用： 对于拥有复杂样式指南的大型企业应用，Token CSS 可以确保品牌一致性。
• 设计系统： 如果您正在开发一个设计系统，Token CSS 可以帮助您创建和管理可重用的设计令牌。
• 跨平台应用： 对于需要在多个平台和设备上保持一致体验的应用，Token CSS 提供了跨平台的样式支持。