DESIGN.md结构全解Impeccable如何Token化描述颜色与字体【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccableImpeccable是面向 AI 编码助手的设计指导技能Design Skill它通过一个名为 DESIGN.md 的设计令牌文件把项目的颜色、字体、圆角、间距全部Token化——用机器可读的 YAML 令牌 人类可读的文字规则让 AI 生成的前端页面始终保持品牌一致。本文带你完整拆解 DESIGN.md 的每一个区块以及颜色与字体是如何被精确描述的。为什么 AI 需要一个 DESIGN.mdAI 模型训练时见过太多同质化的 SaaS 模板Inter 字体 everywhere、紫蓝渐变、卡片套卡片……Impeccable 的解法是在动手写代码之前先给 AI 一份设计规范合同。运行/impeccable init或/impeccable document后项目根目录会生成一份 DESIGN.md后续所有 23 条设计命令polish、audit、typeset……都会先读它。它的核心定位一句话Tokens 是规范normative文字只是解释prose provides context。也就是说令牌值才是权威正文只是帮你理解为什么这样用。DESIGN.md 的两层结构先机器后人类打开根目录的 DESIGN.md你会看到它由两个层次组成层次位置作用消费者YAML Frontmatter文件顶部---之间机器可读的设计令牌colors、typography、rounded、spacing、components解析器、实时面板、Lint 工具Markdown 正文文件下半部分8 个固定顺序章节的设计哲学与规则人 AI Agent这个双层设计是理解全文的钥匙。解析器 design-parser.mjs 会先把 Frontmatter 解析成结构化 JSON 模型再扫描正文的 8 个标准章节Overview、Colors、Typography、Layout、Elevation、Shapes、Components、Dos and Donts正文中的值作为 Frontmatter 缺失时的回退方案。颜色 Token 化从blue-800到kinpaku-gold描述性命名是第一原则看官方 DESIGN.md 的颜色令牌colors: kinpaku-gold: oklch(84% 0.19 80.46) # 主强调色 verdigris-patina: oklch(70% 0.12 188) # 次强调色/状态 lacquer-black: oklch(7% 0.006 95) # 页面底色 champagne: oklch(91% 0 0) # 标题文字注意几个刻意的设计决策✅用意象命名不用色阶编号kinpaku-gold金缮金而非blue-800lacquer-deep深漆而非gray-900✅统一使用 OKLCH 色彩空间感知均匀的亮度/饱和度/色相比 hex 更适合做色阶派生✅每个令牌标注用途注释写清它是干嘛的AI 才知道何时该用它颜色的语义化角色颜色不只是值还带角色语义。正文 Colors 章节会把颜色分组为 Ground底色、Gold System品牌金、Text文字层级 5 档亮度、State状态色并配上命名规则Named RulesThe Gold Carries Brand Rule.金是主品牌信号——如果整屏只能有一个强调色用金不是品红也不是青。这类规则让 AI 不仅知道颜色还知道颜色的纪律。字体 Token 化角色驱动而非字号驱动DESIGN.md 的 typography 区块展示了一种优雅的字体 Token 化方式1️⃣ 字号刻度scale离散阶梯杜绝随手写typography: scale: 14: 0.875rem # 紧凑正文、列表行 16: 1rem # 默认正文 24: 1.5rem # 小节标题 72: 4.5rem # 英雄区展示关键点代码库里出现的每一个字号都必须落在刻度阶梯上检测器允许 ±0.5px 容差。官方注释里写得很直白——旧系统曾有过 86 个不同字号其中 6 个挤在 13.7px~15.4px 之间读者根本分辨不出区别。加一档刻度是设计决策不是方便。2️⃣ 角色令牌roles字号、字重、行高、字距打包display: fontFamily: Alumni Sans, Albert Sans, Arial, sans-serif fontSize: clamp(3.4rem, 6.5vw, 5.6rem) # 流式响应式 fontWeight: 100 letterSpacing: -0.01em lineHeight: 1.02每个角色display / headline / title / body / eyebrow / mono是一个完整的排版对象。其中 display 和 headline 用clamp()实现流式缩放其余角色锚定在离散刻度上——这是流式与阶梯并存的混合策略。3️⃣ 字重反转规则连反直觉都被 Token 化了The Weight-Inversion Rule.英雄区 h1 用极细的 100 字重而章节 h2 用更重的 300。这不是错误是刻意设计hero 要轻盈透气章节锚点要稳住每块内容。不要修正这两个字重。这条规则如果不写进 DESIGN.mdAI 大概率会好心地把 h1 加粗——Token 化不仅描述是什么更保护为什么。组件如何引用 Token{colors.x}语法最巧妙的部分在 components 区块。看 demos/landing-demo/DESIGN.md 的演示项目components: button-primary: backgroundColor: {colors.ink} textColor: {colors.cream} rounded: {rounded.pill} padding: 14px 28px组件本身不写死值而是用{colors.X}/{rounded.Y}引用令牌——改主题色时所有组件自动跟随。这正是设计令牌体系Design Token System的核心思想单一数据源处处引用。配套文件 demos/landing-demo/DESIGN.json 则是由解析器生成的 JSON 侧车sidecar为实时面板提供色相角色、色调阶梯等扩展元数据——每次重新生成 DESIGN.md 时一并更新。rounded 与 spacing小令牌大纪律颜色字体之外还有两组常被忽视的令牌rounded圆角刻度none → xs → sm → lg → pill官方明确小圆角 克制边框 几乎无装饰性阴影spacing间距节奏xs 8px → 3xl 112px共 7 档它们与字号刻度同理把随手写的像素值收敛成有限的、有名字的选项AI 只能选择题不能填空题。✍️如何生成与验证你的 DESIGN.md场景命令 / 路径说明初始化生成/impeccable init提问后写出 PRODUCT.md DESIGN.md从现有代码提取/impeccable document扫描 CSS 变量、Tailwind 配置、主题文件自动抽取令牌格式规范参考skill/reference/document.md完整的扫描模式与 4 步写入流程解析实现skill/scripts/lib/design-parser.mjs零依赖、确定性地把 DESIGN.md 解析为 JSON 模型生成流程值得新手记住的两条纪律描述性命名需人工确认——自动抽取能拿到值但editorial-magenta这样的名字需要创意输入不要静默覆盖已有 DESIGN.md——官方文档明确要求先展示现有文件让用户选择刷新、覆盖还是合并总结DESIGN.md 给新手的 5 个可复用套路双层结构YAML Frontmatter 给机器Markdown 正文给人值以令牌为准意象化命名lacquer-black好过gray-900名字自带使用说明色彩空间统一新颜色一律 OKLCHhex 只留给第三方示例刻度化一切字号、圆角、间距都收敛为离散阶梯禁止散落值组件引用令牌{colors.x}保持单一数据源命名规则Named Rules把禁止做什么写成加粗的强制条款防 AI 好心办坏事把这份文件放进项目根目录你的 AI 编码助手就从凭印象画图升级为照规范施工。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DESIGN.md结构全解：Impeccable如何Token化描述颜色与字体
DESIGN.md结构全解Impeccable如何Token化描述颜色与字体【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccableImpeccable是面向 AI 编码助手的设计指导技能Design Skill它通过一个名为 DESIGN.md 的设计令牌文件把项目的颜色、字体、圆角、间距全部Token化——用机器可读的 YAML 令牌 人类可读的文字规则让 AI 生成的前端页面始终保持品牌一致。本文带你完整拆解 DESIGN.md 的每一个区块以及颜色与字体是如何被精确描述的。为什么 AI 需要一个 DESIGN.mdAI 模型训练时见过太多同质化的 SaaS 模板Inter 字体 everywhere、紫蓝渐变、卡片套卡片……Impeccable 的解法是在动手写代码之前先给 AI 一份设计规范合同。运行/impeccable init或/impeccable document后项目根目录会生成一份 DESIGN.md后续所有 23 条设计命令polish、audit、typeset……都会先读它。它的核心定位一句话Tokens 是规范normative文字只是解释prose provides context。也就是说令牌值才是权威正文只是帮你理解为什么这样用。DESIGN.md 的两层结构先机器后人类打开根目录的 DESIGN.md你会看到它由两个层次组成层次位置作用消费者YAML Frontmatter文件顶部---之间机器可读的设计令牌colors、typography、rounded、spacing、components解析器、实时面板、Lint 工具Markdown 正文文件下半部分8 个固定顺序章节的设计哲学与规则人 AI Agent这个双层设计是理解全文的钥匙。解析器 design-parser.mjs 会先把 Frontmatter 解析成结构化 JSON 模型再扫描正文的 8 个标准章节Overview、Colors、Typography、Layout、Elevation、Shapes、Components、Dos and Donts正文中的值作为 Frontmatter 缺失时的回退方案。颜色 Token 化从blue-800到kinpaku-gold描述性命名是第一原则看官方 DESIGN.md 的颜色令牌colors: kinpaku-gold: oklch(84% 0.19 80.46) # 主强调色 verdigris-patina: oklch(70% 0.12 188) # 次强调色/状态 lacquer-black: oklch(7% 0.006 95) # 页面底色 champagne: oklch(91% 0 0) # 标题文字注意几个刻意的设计决策✅用意象命名不用色阶编号kinpaku-gold金缮金而非blue-800lacquer-deep深漆而非gray-900✅统一使用 OKLCH 色彩空间感知均匀的亮度/饱和度/色相比 hex 更适合做色阶派生✅每个令牌标注用途注释写清它是干嘛的AI 才知道何时该用它颜色的语义化角色颜色不只是值还带角色语义。正文 Colors 章节会把颜色分组为 Ground底色、Gold System品牌金、Text文字层级 5 档亮度、State状态色并配上命名规则Named RulesThe Gold Carries Brand Rule.金是主品牌信号——如果整屏只能有一个强调色用金不是品红也不是青。这类规则让 AI 不仅知道颜色还知道颜色的纪律。字体 Token 化角色驱动而非字号驱动DESIGN.md 的 typography 区块展示了一种优雅的字体 Token 化方式1️⃣ 字号刻度scale离散阶梯杜绝随手写typography: scale: 14: 0.875rem # 紧凑正文、列表行 16: 1rem # 默认正文 24: 1.5rem # 小节标题 72: 4.5rem # 英雄区展示关键点代码库里出现的每一个字号都必须落在刻度阶梯上检测器允许 ±0.5px 容差。官方注释里写得很直白——旧系统曾有过 86 个不同字号其中 6 个挤在 13.7px~15.4px 之间读者根本分辨不出区别。加一档刻度是设计决策不是方便。2️⃣ 角色令牌roles字号、字重、行高、字距打包display: fontFamily: Alumni Sans, Albert Sans, Arial, sans-serif fontSize: clamp(3.4rem, 6.5vw, 5.6rem) # 流式响应式 fontWeight: 100 letterSpacing: -0.01em lineHeight: 1.02每个角色display / headline / title / body / eyebrow / mono是一个完整的排版对象。其中 display 和 headline 用clamp()实现流式缩放其余角色锚定在离散刻度上——这是流式与阶梯并存的混合策略。3️⃣ 字重反转规则连反直觉都被 Token 化了The Weight-Inversion Rule.英雄区 h1 用极细的 100 字重而章节 h2 用更重的 300。这不是错误是刻意设计hero 要轻盈透气章节锚点要稳住每块内容。不要修正这两个字重。这条规则如果不写进 DESIGN.mdAI 大概率会好心地把 h1 加粗——Token 化不仅描述是什么更保护为什么。组件如何引用 Token{colors.x}语法最巧妙的部分在 components 区块。看 demos/landing-demo/DESIGN.md 的演示项目components: button-primary: backgroundColor: {colors.ink} textColor: {colors.cream} rounded: {rounded.pill} padding: 14px 28px组件本身不写死值而是用{colors.X}/{rounded.Y}引用令牌——改主题色时所有组件自动跟随。这正是设计令牌体系Design Token System的核心思想单一数据源处处引用。配套文件 demos/landing-demo/DESIGN.json 则是由解析器生成的 JSON 侧车sidecar为实时面板提供色相角色、色调阶梯等扩展元数据——每次重新生成 DESIGN.md 时一并更新。rounded 与 spacing小令牌大纪律颜色字体之外还有两组常被忽视的令牌rounded圆角刻度none → xs → sm → lg → pill官方明确小圆角 克制边框 几乎无装饰性阴影spacing间距节奏xs 8px → 3xl 112px共 7 档它们与字号刻度同理把随手写的像素值收敛成有限的、有名字的选项AI 只能选择题不能填空题。✍️如何生成与验证你的 DESIGN.md场景命令 / 路径说明初始化生成/impeccable init提问后写出 PRODUCT.md DESIGN.md从现有代码提取/impeccable document扫描 CSS 变量、Tailwind 配置、主题文件自动抽取令牌格式规范参考skill/reference/document.md完整的扫描模式与 4 步写入流程解析实现skill/scripts/lib/design-parser.mjs零依赖、确定性地把 DESIGN.md 解析为 JSON 模型生成流程值得新手记住的两条纪律描述性命名需人工确认——自动抽取能拿到值但editorial-magenta这样的名字需要创意输入不要静默覆盖已有 DESIGN.md——官方文档明确要求先展示现有文件让用户选择刷新、覆盖还是合并总结DESIGN.md 给新手的 5 个可复用套路双层结构YAML Frontmatter 给机器Markdown 正文给人值以令牌为准意象化命名lacquer-black好过gray-900名字自带使用说明色彩空间统一新颜色一律 OKLCHhex 只留给第三方示例刻度化一切字号、圆角、间距都收敛为离散阶梯禁止散落值组件引用令牌{colors.x}保持单一数据源命名规则Named Rules把禁止做什么写成加粗的强制条款防 AI 好心办坏事把这份文件放进项目根目录你的 AI 编码助手就从凭印象画图升级为照规范施工。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考