DESIGN.md导出Tailwind v4css-tailwind生成theme CSS变量命名空间的原理【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.mdDESIGN.md 是一种向编码代理coding agents描述视觉身份的格式规范它的 CLI 工具支持通过export命令的css-tailwind格式一键把设计令牌转换成 Tailwind CSS v4 的themeCSS 变量块。本文带你拆解这条导出链路的原理设计令牌是如何一步步变成--color-*、--font-*等 CSS 变量命名空间的。一键导出css-tailwind 命令怎么用安装后只需一条命令即可将 DESIGN.md 中的令牌导出为 Tailwind v4 风格的 CSSnpx google/design.md export --format css-tailwind DESIGN.md theme.css生成的产物形如theme { --color-primary: #006b5a; --font-body-lg: Inter; --spacing-unit: 8px; --radius-sm: 0.25rem; }把这段 CSS 放进项目入口样式文件后Tailwind v4 会自动为每个变量生成对应的工具类——bg-primary、text-body-lg、p-unit、rounded-sm直接可用无需再手写tailwind.config.js。导出全链路DESIGN.md 到 theme 的三步走 整条链路被拆成了三个职责单一的模块源码位于 packages/cli/src/linter/tailwind/v4/解析命令入口 export.ts 先调用lint()流水线把 DESIGN.md 的 YAML front matter 解析、解析令牌引用如{colors.primary}得到一份“已解决”的设计系统状态DesignSystemState。映射TailwindV4EmitterHandler是一个纯函数式处理器负责把状态对象转换成按类别组织的主题数据并顺带完成合法性校验。序列化serializeToCss()把主题数据拍平成一个theme { ... }字符串交给 stdout 输出。这种“解析 → 映射 → 序列化”的分层设计让每一步都可独立测试也方便未来扩展新的导出格式。核心原理8 个 CSS 变量命名空间的前缀映射 命名空间的本质就在 serialize.ts 里的一张映射表DESIGN.md 的令牌类别 → CSS 变量前缀。DESIGN.md 令牌类别主题数据字段CSS 变量前缀生成的工具类示例colorscolors--color-bg-primarytypography.fontFamilyfontFamily--font-font-headline-lgtypography.fontSizefontSize--text-text-headline-lgtypography.lineHeightlineHeight--leading-leading-body-lgtypography.letterSpacingletterSpacing--tracking-tracking-label-smtypography.fontWeightfontWeight--font-weight-字重工具类roundedborderRadius--radius-rounded-mdspacingspacing--spacing-p-gutter两个值得注意的细节输出顺序固定类别按映射表数组顺序输出colors → 字体族 → 字号 → 行高 → 字距 → 字重 → 圆角 → 间距与文件书写顺序无关保证多次导出结果稳定、便于 diff 对比类别内部则保留声明顺序。空类别自动跳过某个类别没有任何令牌时整段不输出不会产生空行。映射处理器做了哪些“脏活”handler.ts 这个映射环节看似简单实则承担了所有“安全兜底”工作令牌名校验所有令牌名必须匹配/^[a-zA-Z0-9][a-zA-Z0-9-]*$/字母数字开头只含字母、数字、连字符。这是 CSS 标识符的硬性要求——不合法时直接报INVALID_TOKEN_NAME错误绝不输出可能破坏 CSS 语法的变量名。颜色归一化颜色统一以十六进制小写输出如#647D66→#647d66。排版令牌拆分为 5 个变量一个 typography 令牌最多拆成 font-family、font-size、line-height、letter-spacing、font-weight 五条声明缺哪个字段就少生成一条不会补默认值。字体族值的引号转义font-family 会被包进双引号内部的引号、反斜杠会被转义换行符更会被转成 CSS 十六进制转义如\a防止值“逃逸”出字符串、破坏整段 CSS见 cssStringLiteral。输出格式洁癖结尾恰好一个换行符——测试用例专门断言了这一点确保重定向到文件时不会多出空行。动手验证用内置测试样例看看效果仓库自带的测试夹具 DESIGN-test.md 定义了“Pacific Mint Dental”设计系统50 个颜色、7 组排版、6 级圆角、5 档间距。执行导出后你会在theme块中看到类似这样的变量--color-primary: #006b5a; --color-surface: #f9f9ff; --font-display-lg: Manrope; --text-headline-md: 24px; --spacing-unit: 8px; --radius-full: 9999px;对应的单元测试export.test.ts、serialize.test.ts逐条验证了前缀映射、类别顺序与换行行为可以放心参考。与 Tailwind v3 的 json-tailwind 有何不同 ⚖️export命令同时支持 v3 路线--format json-tailwind别名tailwind会输出theme.extend结构的 JSON用于tailwind.config.js由 TailwindEmitterHandler 处理。两者的分工非常清晰v3 项目用json-tailwind令牌进入 JS 配置对象v4 项目用css-tailwind令牌直接成为 CSS 变量命名空间零配置生效另外还支持dtcgW3C 设计令牌和css-vars原生 CSS 自定义属性两种格式。相关文件速查 模块路径export 命令入口packages/cli/src/commands/export.tsv4 映射处理器packages/cli/src/linter/tailwind/v4/handler.tstheme 序列化器packages/cli/src/linter/tailwind/v4/serialize.ts主题数据 Schemapackages/cli/src/linter/tailwind/v4/spec.ts官方格式规范docs/spec.md示例设计系统examples/atmospheric-glass/DESIGN.md一句话总结css-tailwind导出的“魔法” 一份固定的“类别 → 前缀”映射表 严格的令牌名校验与值转义。理解这张表你就掌握了 DESIGN.md 与 Tailwind v4 之间的翻译规则。【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考