v4-sync 🚀

将 Design Tokens 同步到 Tailwind CSS v4 的最快路径。

v4-sync 是一个轻量级 CLI 工具，旨在消除 Tailwind CSS v4 项目中冗余的样式层级。它把你的 tokens.json 直接转换为符合 Tailwind v4 规范的 @theme CSS 文件，实现 「源头即样式，定义即变量」 的一跳架构。

为什么需要 v4-sync？

在传统架构中，Token 需要经过多层转换才能到达组件：

❌ 传统路径（3-Hop）

tokens.json → CSS :root → tailwind.config.js → Tailwind Class

这种架构不仅冗余，还会造成 AI 协作时的上下文混淆。

✅ 一跳架构（Single-Hop）

v4-sync 将其缩短为：

tokens.json → design-tokens.generated.css (@theme) → Tailwind Class

核心特性

| | | | --- | --- | | ⚡ 零 JS 配置 | 无需 tailwind.config.js，直接利用 v4 的 CSS-First 特性。 | | 🤖 AI 友好 | 极简路径让 Cursor / Copilot 等工具更容易稳定理解 Token 语义。 | | 🌓 自动暗色模式 | 内置语义化暗色覆盖：根级 dark 对象会生成 .dark { ... } 覆盖变量。 | | 🧩 无缝透明度 | 与 Tailwind v4 的颜色解构配合，原生支持如 bg-primary/50 的写法。 |

快速上手

1. 安装

npm install -g v4-sync

或在克隆仓库后本地使用：

npm install
npx v4-sync --help

2. 准备你的 tokens.json

v4-sync 遵循简单的嵌套约定，键名会自动转换为 CSS 自定义属性名（例如 color.primary → --color-primary）。

{
  "color": {
    "primary": "#000000",
    "background": "#ffffff"
  },
  "spacing": {
    "sm": "12px",
    "md": "20px"
  },
  "dark": {
    "color": {
      "primary": "#dcdcdc",
      "background": "#000000"
    }
  }
}

3. 执行同步

v4-sync tokens.json ./src/styles/design-tokens.generated.css

也可使用显式参数：

v4-sync -i tokens.json -o ./src/styles/design-tokens.generated.css

不传路径时，默认读取当前目录下的 tokens.json，并输出 tokens.theme.css：

v4-sync

4. 在 CSS 中引用

在主样式入口引入生成文件即可：

@import "tailwindcss";
@import "./design-tokens.generated.css";

/* 组件中可直接使用：<div class="bg-primary p-sm"></div> */

进阶方案：配合 HarnessDesign 使用

如果你正在使用 HarnessDesign 或类似的 UI 校验 / 设计交付系统，v4-sync 可以作为流水线核心的一环：

1. 设计师在 Web 端调整颜色或 Token。
2. HarnessDesign（或 CI）触发 v4-sync，更新 design-tokens.generated.css。
3. AI 开发助手始终基于最新 Token 上下文工作，减少硬编码颜色。
4. 工程侧只维护 一份 tokens.json 真相来源。

开发者视角：一跳 vs 三跳

| 维度 | 传统三跳方案 | v4-sync 一跳方案 | | --- | --- | --- | | 文件维护 | 多个文件（JSON + :root + Config） | 单一来源（tokens.json） | | 调试路径 | 需追溯多层变量映射 | 直达数值定义 | | AI 准确率 | 中等（抽象层多，易幻觉） | 高（上下文清晰） | | 透明度支持 | 常需手动拆分 RGB 分量 | 依赖 v4 原生颜色解构（Hex / RGB / HSL） |

贡献指南

欢迎一切有助于 Tailwind v4 工程化提效的建议与代码。若有更好的 Token 映射或边界情况处理，欢迎提交 Issue 或 PR。

许可证

MIT

English