DESIGN.md Tailwind发射器深度剖析令牌到theme.extend的映射细节【免费下载链接】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 是一个面向 AI 编码代理的设计系统描述格式规范它的 CLI 内置了 Tailwind 发射器Emitter能将设计令牌design tokens一键导出为 Tailwind 的theme.extend配置或 v4 的theme块。本文带你拆解这套从 DESIGN.md 到 Tailwind 的完整映射规则看懂每个令牌去了哪里、为什么这样转换。为什么需要 Tailwind 发射器写一份 DESIGN.md 后通常还要手工把它翻译成tailwind.config.js既繁琐又容易抄错色值。Tailwind 发射器解决的正是这个问题npx google/design.md export --format json-tailwind DESIGN.md tailwind.theme.json npx google/design.md export --format css-tailwind DESIGN.md theme.css两种格式对应两条技术路线格式参数目标版本输出内容json-tailwind别名tailwindTailwind v3theme.extendJSON 配置对象css-tailwindTailwind v4CSStheme { ... }自定义属性块完整命令选项见 export.ts完整规范见 docs/spec.md。v3 路线令牌如何进入 theme.extendv3 发射器的核心是一个纯函数类把解析后的设计系统状态DesignSystemState映射为theme.extend对象源码在 handler.ts。映射规则非常直接——DESIGN.md 的五大令牌分区一一对应theme.extend的五个键DESIGN.md 分区theme.extend 键转换细节colorscolors每个颜色统一输出为 hex 字符串typography.*.fontFamilyfontFamily包成单元素数组如[Inter]typography.*字号等fontSize转为[字号, 元数据]元组roundedborderRadius数值单位原样拼接如8pxspacingspacing同上如16px其中fontSize的元组结构最值得一提Tailwind v3 允许一个字号携带lineHeight、letterSpacing、fontWeight元数据发射器会把 typography 令牌中的这些字段全部收进第二个元素headline-lg: [32px, { lineHeight: 40px, letterSpacing: -0.02em, fontWeight: 600 }]这样写出来的 class如text-headline-lg就自动带上了行高、字重和字距一行样式不用额外声明。真实产物可以参考示例项目 atmospheric-glass/tailwind.config.js里面有完整的colors/fontFamily/fontSize/borderRadius/spacing五个分区正是发射器输出的典型形态。输出的 JSON 形状由 Zod schema 约束定义在 spec.ts保证结构稳定可预测。v4 路线令牌如何变成 theme 自定义属性Tailwind v4 改用 CSS 变量命名空间所以 v4 发射器走的是「令牌 → CSS 变量」的路线由两个文件协作完成映射v4/handler.ts序列化v4/serialize.ts第一步令牌名校验。v4 的变量名最终会成为 CSS 标识符发射器在输出任何内容之前会先用正则/^[a-zA-Z0-9][a-zA-Z0-9-]*$/校验所有颜色、字体、圆角、间距令牌名。任一名称不合法比如以-开头或含下划线立即返回INVALID_TOKEN_NAME错误并终止导出不会产出半成品。第二步字体族安全引用。字体名可能含空格甚至特殊字符发射器会将其包装为 CSS 字符串字面量内嵌的和\会被转义换行等行终止符会被转成\a这类十六进制转义避免破坏引号边界。第三步排版拆分为五个独立类别。与 v3 把排版塞进一个fontSize元组不同v4 发射器把 typography 拆成fontFamily、fontSize、lineHeight、letterSpacing、fontWeight五个平级记录每个类别独立判断「有值才输出」。第四步类别到 CSS 变量前缀的固定映射。序列化器维护一张「类别 → 前缀」对照表按固定顺序展平进theme块类别CSS 变量前缀示例colors--color---color-primary: #0b1326;fontFamily--font---font-display-lg: Inter;fontSize--text---text-headline-lg: 32px;lineHeight--leading---leading-headline-lg: 40px;letterSpacing--tracking---tracking-label-sm: 0.05em;fontWeight--font-weight---font-weight-headline-lg: 600;borderRadius--radius---radius-md: 0.75rem;spacing--spacing---spacing-card-gap: 16px;这份对照表就写在 v4/serialize.ts 的CATEGORIES数组里数组顺序即输出顺序。若所有分区都为空输出一个空的theme {}块且整个输出严格保证只有一个尾部换行符有专门的回归测试 v4/fixture.test.ts 兜底。错误处理与退出码速查 export命令的退出码约定清晰方便接入 CI退出码含义0导出成功即使源文件存在 lint 告警也不阻断1--format非法或发射器报错如INVALID_TOKEN_NAME2输入文件无法读取注意一个实用细节导出成功与否不取决于 lint 结果——设计质量把关交给lint命令导出只管「能不能翻译」。相关行为测试见 export.test.ts。快速上手三步接入你的项目按规范写好 DESIGN.md令牌在 YAML front matter说明在 Markdown 正文完整字段参考 docs/spec.md运行npx google/design.md lint DESIGN.md确认结构无误选择版本执行导出v3 项目用--format json-tailwind得到theme.extendv4 项目用--format css-tailwind得到theme块粘贴进你的 CSS 即可。源码导读路线图想深入阅读建议按数据流顺序走一遍命令入口与格式分发commands/export.tsv3 发射器映射 schematailwind/handler.ts、tailwind/spec.tsv4 发射器校验 转义 前缀映射v4/handler.ts、v4/serialize.ts真实输入输出样例examples/atmospheric-glass/tailwind.config.js、examples/paws-and-paths/tailwind.config.js掌握了「分区 → 键名 → 值格式」这条主线你就完全读懂了 DESIGN.md 到 Tailwind 的翻译逻辑——无论后续令牌 schema 如何演进这套映射思路都不会变。【免费下载链接】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），仅供参考 DESIGN.md Tailwind发射器深度剖析：令牌到theme.extend的映射细节
DESIGN.md Tailwind发射器深度剖析令牌到theme.extend的映射细节【免费下载链接】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 是一个面向 AI 编码代理的设计系统描述格式规范它的 CLI 内置了 Tailwind 发射器Emitter能将设计令牌design tokens一键导出为 Tailwind 的theme.extend配置或 v4 的theme块。本文带你拆解这套从 DESIGN.md 到 Tailwind 的完整映射规则看懂每个令牌去了哪里、为什么这样转换。为什么需要 Tailwind 发射器写一份 DESIGN.md 后通常还要手工把它翻译成tailwind.config.js既繁琐又容易抄错色值。Tailwind 发射器解决的正是这个问题npx google/design.md export --format json-tailwind DESIGN.md tailwind.theme.json npx google/design.md export --format css-tailwind DESIGN.md theme.css两种格式对应两条技术路线格式参数目标版本输出内容json-tailwind别名tailwindTailwind v3theme.extendJSON 配置对象css-tailwindTailwind v4CSStheme { ... }自定义属性块完整命令选项见 export.ts完整规范见 docs/spec.md。v3 路线令牌如何进入 theme.extendv3 发射器的核心是一个纯函数类把解析后的设计系统状态DesignSystemState映射为theme.extend对象源码在 handler.ts。映射规则非常直接——DESIGN.md 的五大令牌分区一一对应theme.extend的五个键DESIGN.md 分区theme.extend 键转换细节colorscolors每个颜色统一输出为 hex 字符串typography.*.fontFamilyfontFamily包成单元素数组如[Inter]typography.*字号等fontSize转为[字号, 元数据]元组roundedborderRadius数值单位原样拼接如8pxspacingspacing同上如16px其中fontSize的元组结构最值得一提Tailwind v3 允许一个字号携带lineHeight、letterSpacing、fontWeight元数据发射器会把 typography 令牌中的这些字段全部收进第二个元素headline-lg: [32px, { lineHeight: 40px, letterSpacing: -0.02em, fontWeight: 600 }]这样写出来的 class如text-headline-lg就自动带上了行高、字重和字距一行样式不用额外声明。真实产物可以参考示例项目 atmospheric-glass/tailwind.config.js里面有完整的colors/fontFamily/fontSize/borderRadius/spacing五个分区正是发射器输出的典型形态。输出的 JSON 形状由 Zod schema 约束定义在 spec.ts保证结构稳定可预测。v4 路线令牌如何变成 theme 自定义属性Tailwind v4 改用 CSS 变量命名空间所以 v4 发射器走的是「令牌 → CSS 变量」的路线由两个文件协作完成映射v4/handler.ts序列化v4/serialize.ts第一步令牌名校验。v4 的变量名最终会成为 CSS 标识符发射器在输出任何内容之前会先用正则/^[a-zA-Z0-9][a-zA-Z0-9-]*$/校验所有颜色、字体、圆角、间距令牌名。任一名称不合法比如以-开头或含下划线立即返回INVALID_TOKEN_NAME错误并终止导出不会产出半成品。第二步字体族安全引用。字体名可能含空格甚至特殊字符发射器会将其包装为 CSS 字符串字面量内嵌的和\会被转义换行等行终止符会被转成\a这类十六进制转义避免破坏引号边界。第三步排版拆分为五个独立类别。与 v3 把排版塞进一个fontSize元组不同v4 发射器把 typography 拆成fontFamily、fontSize、lineHeight、letterSpacing、fontWeight五个平级记录每个类别独立判断「有值才输出」。第四步类别到 CSS 变量前缀的固定映射。序列化器维护一张「类别 → 前缀」对照表按固定顺序展平进theme块类别CSS 变量前缀示例colors--color---color-primary: #0b1326;fontFamily--font---font-display-lg: Inter;fontSize--text---text-headline-lg: 32px;lineHeight--leading---leading-headline-lg: 40px;letterSpacing--tracking---tracking-label-sm: 0.05em;fontWeight--font-weight---font-weight-headline-lg: 600;borderRadius--radius---radius-md: 0.75rem;spacing--spacing---spacing-card-gap: 16px;这份对照表就写在 v4/serialize.ts 的CATEGORIES数组里数组顺序即输出顺序。若所有分区都为空输出一个空的theme {}块且整个输出严格保证只有一个尾部换行符有专门的回归测试 v4/fixture.test.ts 兜底。错误处理与退出码速查 export命令的退出码约定清晰方便接入 CI退出码含义0导出成功即使源文件存在 lint 告警也不阻断1--format非法或发射器报错如INVALID_TOKEN_NAME2输入文件无法读取注意一个实用细节导出成功与否不取决于 lint 结果——设计质量把关交给lint命令导出只管「能不能翻译」。相关行为测试见 export.test.ts。快速上手三步接入你的项目按规范写好 DESIGN.md令牌在 YAML front matter说明在 Markdown 正文完整字段参考 docs/spec.md运行npx google/design.md lint DESIGN.md确认结构无误选择版本执行导出v3 项目用--format json-tailwind得到theme.extendv4 项目用--format css-tailwind得到theme块粘贴进你的 CSS 即可。源码导读路线图想深入阅读建议按数据流顺序走一遍命令入口与格式分发commands/export.tsv3 发射器映射 schematailwind/handler.ts、tailwind/spec.tsv4 发射器校验 转义 前缀映射v4/handler.ts、v4/serialize.ts真实输入输出样例examples/atmospheric-glass/tailwind.config.js、examples/paws-and-paths/tailwind.config.js掌握了「分区 → 键名 → 值格式」这条主线你就完全读懂了 DESIGN.md 到 Tailwind 的翻译逻辑——无论后续令牌 schema 如何演进这套映射思路都不会变。【免费下载链接】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），仅供参考