尧图网站建设 
DESIGN.md 设计哲学深度解析为什么文字叙述才是视觉身份规范的核心【免费下载链接】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 是一种用于向编码 Agent 描述视觉身份的格式规范而 PHILOSOPHY.md 记录了这套规范背后的核心设计哲学设计的灵魂存在于文字叙述prose之中设计令牌tokens只是支撑叙述的上下文。读完本文你将理解为什么一句具体的参照胜过一打精确的数值、为什么负面约束donts能自动随引用而来以及这个格式如何在不修改规范的前提下通过用户自定义扩展生长出属于自己的设计语言——每一条结论都会结合本仓库的源码、测试与示例给出可验证的依据。一句话抓住 DESIGN.md 的哲学核心DESIGN.md captures how a design looks, feels, and behaves. The prose is where the design lives. Everything else in the document exists to support it.翻译过来即DESIGN.md 记录的是一个设计看起来、感觉起来、行为起来的样子设计活在叙述文字里文档中的其他一切令牌、结构、规范都只是为叙述服务。这句开宗明义的话直接决定了 PHILOSOPHY.md 全文的论述方向也解释了为什么 DESIGN.md 会同时包含两种截然不同的内容层——机器可读的 YAML 令牌与人类以及 Agent可读的 Markdown 叙述。哲学落地的最小示例Technical Handout原文档用一个极简示例展示了叙述即设计的含义--- name: Technical Handout --- ## Overview A graduate-level computer science lecture handout in the tradition of an old established university. The audience is graduate students and research engineers reading a printed handout distributed at the beginning of a seminar. The handout is austere, informationally dense, and proudly unconcerned with first impressions. The audience knows why they are there and the handouts job is to do work, not to seduce.请注意这个示例的精妙之处front matter 里只有一个name没有任何颜色、字体、间距令牌。整份文档的设计意图完全由 Overview 中的三段叙述承载——老牌大学研究生级别的课堂讲义信息密集、毫不讨好第一印象。austere朴素克制、proudly unconcerned with first impressions骄傲地不关心第一印象这些措辞向 Agent 传递的是一种完整的态度而非一组数值。由此引出全文最重要的一句话生成设计质量的优劣更多取决于意图被描述得有多清晰而非数值有多精确。仓库层面的呼应DESIGN.md 的双层结构README.md 将这种哲学固化为格式本身A DESIGN.md file combines machine-readable design tokens (YAML front matter) with human-readable design rationale (markdown prose). Tokens give agents exact values. Prose tells themwhythose values exist and how to apply them.而规范文档 docs/spec.md 中说得更直接The tokens are the normative values; the prose provides context for how to apply them.令牌是规范性数值叙述为如何应用它们提供上下文。normative / context 的措辞与价值观/为什么的措辞一脉相承——数值负责精确叙述负责意义两者缺一不可。Prose, not Tokens叙述才是规范的主角原文档明确划分了 DESIGN.md 的两大组成tokens与prose。规范存在的意义是描述设计语境——既要让设计在不同生成会话之间保持一致性又要为创造性探索留出空间。而其中prose 是最关键的部分。一个完整的 Colors 对照示例原文档给出了一个同时包含令牌与叙述的典型段落## Colors yaml # Tokens colors: paper: #F4F0E4 ink: #1E1A14 vermilion: #C3402A rule-gray: #B8B0A2 !-- Prose -- A single-ink-plus-accent system. - **Paper** {colors.paper} is the canvas — warmed xerox stock, never pure white. - **Ink** {colors.ink} is graphite-warm and carries all typography, all rules, all diagram strokes; never pure black. - **Vermilion** {colors.vermilion} is the single accent and appears only inside diagrams and chart annotations — never on typography, never on page numerals, never on metadata of any kind. - **Rule gray** {colors.rule-gray} is reserved for hairline rules inside content (chart baselines, table dividers); never used as page-frame chrome.注意这里出现了 DESIGN.md 特有的语法{colors.paper}这样的花括号令牌引用让叙述能够动态指向 front matter 中的精确值。同一段文字里warmed xerox stock, never pure white温暖的复印纸质感绝非纯白这类描述承载了#F4F0E4这个十六进制值背后的全部理由——为什么是它、它应该被用在什么场合、绝对不能用在什么场合。在仓库的真实示例 examples/atmospheric-glass/DESIGN.md 中可以看到同样的结构front matter 定义了全套 Material 风格的颜色令牌surface-container-lowest、on-primary、error-container等与 Inter 字体排印令牌正文则用 vibrant-minimalist、frosted crystalline lenses磨砂水晶透镜等叙述交代了玻璃拟态美学的完整意图。另一个测试夹具 packages/cli/src/linter/fixtures/ALPINE_OBSERVATORY.md 则展示了Scientific Alpinism科学式阿尔卑斯登山这种风格#0a1325的深海军蓝被称为The Void虚空#f6bb81的古董黄铜被称为The Instrument仪器——数值与叙事互相锚定。令牌是上下文不是渲染指令这是全文最容易被误解、也最值得强调的论点令牌值作为上下文存在而非渲染指令。一般而言规范并不要求也不建议你在规范里硬性规定令牌。把令牌当作叙述中引用的参考物DESIGN.md 的职责就聚焦在记录设计的本质上而不是去重复语言和工具生态早已耕耘几十年的工作——字体加载、颜色空间转换、间距计算这些事交给 CSS、Tailwind、Figma 或设计令牌工具链去解决。本仓库恰好用代码证明了这种分工packages/cli/src/linter/tailwind/v4/serialize.ts 与 packages/cli/src/linter/dtg/handler.ts 负责把令牌导出为 Tailwind v4 的theme块或 W3C DTCGtokens.json——格式本身只负责定义与描述真正的渲染由这些成熟的既有工具完成。叙述语法的规范依据从 docs/spec.md 可以看到这种叙述为主、令牌为辅的结构被固化为规范Color任何合法 CSS 颜色字符串Hex、命名色、rgb()/hsl()/hwb()、宽色域oklch()/oklab()/lch()/lab()、以及color-mix(in srgb, ...)混合Hex#RRGGBB被推荐为默认写法。Dimension带单位后缀的字符串正式支持的单位为px、em、rem见 packages/cli/src/linter/spec-config.yaml 中的units定义。TypographyfontFamily、fontSize、fontWeight、lineHeight、letterSpacing、fontFeature、fontVariation七个属性lineHeight既可写24px这类 Dimension也可写1.6这种无单位倍数。Token Reference{path.to.token}花括号引用语法在components内允许引用复合值如{typography.label-md}。一个具体参照胜过一打形容词原文档用一个尖锐的对比论证了具体参照的价值A design that references A 1970s graduate lecture handout in the tradition of an old and established university evokes a complete world: the one color of ink, the generous margins, the serif set at a reading size, and the absence of decoration. That single sentence carries more useful information than a dozen metric values. It carries the reasoning behind the values.一份 1970 年代老牌大学的研究生课堂讲义这句话唤起的是一整个完整的世界单一颜色的墨水、宽大的页边距、以阅读字号排版的衬线字体、以及完全没有装饰。这一句话携带的有用信息超过一打度量值——因为它携带了数值背后的推理过程。反过来Modern, clean, trustworthy, premium evokes nothing specific. A model creates something in the center of what those words describe, creating an output that is typically generic. Adjectives describe a region. A specific reference describes a point.现代、干净、可信、高级这类形容词唤不起任何具体画面。模型会在这个词所描述的区域正中央生成一个东西——通常是平庸的、随大流的结果。形容词描述的是一个区域具体参照描述的是一个点。这个观点可以直接指导写作实践与其罗列border-radius: 8px、box-shadow参数不如写像一本学术期刊的版面与其堆砌优雅、极简、专业不如写像 1970 年代老牌大学的课堂讲义。Agent 对具体参照的理解能力本质上来自它对现实世界物体的海量训练知识——命名一个对象就等于同时传递了它的全部隐含属性。在 examples/paws-and-paths/DESIGN.md、examples/totality-festival/DESIGN.md 这些示例中可以看到同样的手法每个设计系统都用一句它是什么来锚定全部后续决策而不是用形容词清单。负面约束你省略掉的东西定义了性格一个清晰的设计参照会自动携带它的限制。原文档的论证如下A model knows what a lecture handout is, and it knows what a lecture handout is not. It does not glow or use a gradient. You dont have to list these. Naming the object names them, the same way naming a dog tells the model that dogs dont meow.模型知道课堂讲义是什么也知道它不是什么——它不会发光、不会用渐变。这些根本不需要你列举。命名即命名就像你说了狗模型自然知道狗不会喵喵叫。由此得出两条实用结论当参照足够具体时负面约束是免费附赠的。一个具体的参照讲座讲义本身就排除了大量的错误方向。有意的不要做清单是有用的冗长的流水账式清单往往是描述过于模糊的信号。如果你需要靠十几条禁令才能防止 Agent 跑偏通常说明你的正面描述还不够具体。两者的理想配合是一个强参照 一份有意为之的 Dos and Donts 清单。原文档的完整 Dos and Donts 示例## Dos and Donts - **Dont** add a hero moment to the title page. A real handout title page is the first page of content, not a magazine cover. - **Dont** reach for an italic standfirst beneath a large title. That is the Substack register. - **Dont** add corner ornaments, chapter marks, or abstract glyphs in the margins. - **Dont** color the page numeral or any other piece of metadata. Vermilion lives in diagrams only. - **Dont** use a display-class serif. One family at four modest sizes. - **Dont** use Bold. Anywhere. - **Dont** use sans-serif for any role other than monospace metadata. - **Dont** introduce dark mode, gradients, glows, glass surfaces, drop shadows, or rounded corners. - **Do** treat the handout as a printed object. The screen is the substrate; the design is the page. - **Do** keep vermilion inside diagrams. Its scarcity outside is what makes its presence inside meaningful. - **Do** trust modest size differences. The section title is only ~1.9× body, not 5× body. - **Do** let pages have visible white space. A page that ends two-thirds of the way down is correct, not under-filled.这份清单的每个条目都值得品味它不是在罗列不允许出现的 CSS 属性而是在陈述性格——标题页不是杂志封面屏幕只是载体设计是纸张本身朱红色的稀缺性正是其内部出现时有意义的原因。注意那些明确的参照点That is the Substack register那是 Substack 的腔调、One family at four modest sizes单一字体家族、四个克制的字号、~1.9× body正文的约 1.9 倍。每条禁令都指向一个可被模型精确理解的参照物而不是一个抽象形容词。规范层面docs/spec.md 将 Dos and Donts 列为八个标准小节中的最后一个第 8 位定位是创建设计时的护栏guardrailspackages/cli/src/linter/spec-config.yaml 中的sections定义确认了它的规范名称与别名而section-order这一条 lint 规则见 packages/cli/src/linter/linter/rules/section-order.ts会校验小节是否按规范顺序出现。格式通过用户生长而不是通过规范生长结构最小主义只标准化通用到值得统一的部分原文档指出规范定义的只是每一份 DESIGN.md 都共享的结构性最小集一个name一小撮足够通用、值得标准化的类别colors、typography、spacing、rounded、components。除此之外一切都是你的自由。格式接受你的设计系统需要的任何键、任何小节、任何结构。规范在一致性有帮助的地方做标准化在灵活性更有帮助的地方保持开放。原文档特别点名了这些开放领域motion动效、iconography图标、elevation层级、text casing文字大小写、paragraph measure段落行长。理由很实际同一类令牌在不同团队里形态天差地别。一个团队的 motion 令牌是 CSS 动画曲线另一个团队的则是以缓冲块buffer blocks为单位的音频域时间常数。正确的形态取决于每个系统自身而格式本身已经允许你定义它。Motion 扩展示例原文档用动效这个自定义类别演示了如何不修改规范就完成扩展## Motion yaml motion: feedback: 120ms content: 250ms easing: cubic-bezier(0.2, 0, 0, 1) Transitions are quick and mechanical. Nothing bounces, nothing overshoots, nothing lingers. State changes should feel like a light switch, not a door closing. - Interactive feedback (hover, press, toggle): {motion.feedback}, always {motion.easing}. - Content transitions (page, panel, modal): {motion.content}, same curve. - Nothing in the UI animates longer than 300ms. If something takes longer, cut it. - Respect prefers-reduced-motion: all durations collapse to 0ms.这个示例完美体现了全部哲学motion不是规范预定义的键规范只定义了 colors/typography/spacing/rounded/components 五个令牌组但格式允许它存在{motion.feedback}引用语法与规范内令牌完全一致而叙述部分——像电灯开关而不是关门、任何动画超过 300ms 就砍掉、尊重prefers-reduced-motion——才是这份设计真正有灵魂的地方。源码证据扩展如何被 linter 优雅地接受格式接受任何键不是一句空话仓库的 lint 规则实现给出了两条精妙的佐证1. 自定义键保持静默。packages/cli/src/linter/linter/rules/unknown-key.ts 中的unknown-key规则只对长得像已知键拼写错误的顶层键发出警告它用莱文斯坦编辑距离levenshtein见 packages/cli/src/linter/linter/rules/levenshtein.ts把未知键与colors/typography/spacing/rounded/components等 schema 键做相似度比对距离阈值MAX_TYPO_DISTANCE 2——colours:会被提示是不是想写colors:而motion:、iconography:这类真正的自定义扩展键不会被误报。这正是格式生长于用户在代码层的落地有意的扩展零打扰无意的拼写错误被温柔捕获。2. 令牌样值兜底提醒。packages/cli/src/linter/linter/rules/token-like-ignored.ts 中的token-like-ignored规则更进一步如果某个未知顶层键的值看起来像令牌映射含 Hex 颜色、CSS 尺寸等令牌样叶子值而它又不属于受支持的导出 schema就警告它会被export命令静默忽略建议改名或移入受支持的区块——例如base_colors: { light: { ink: #0B0F14 } }这种值会被识别出来。两条规则合在一起的效果是格式开放但不糊涂。此外packages/cli/src/linter/spec-config.ts 中定义了两个与开放性配套的保护性限制MAX_TOKEN_NESTING_DEPTH 20令牌最大嵌套深度与MAX_REFERENCE_DEPTH 10引用最大解析深度防止恶意或病态结构导致解析器栈溢出——开放不等于无防护。Tokens are context 在规范层的确证回到 docs/spec.md 的 Consumer Behavior for Unknown Content 一节可以看到 linter 与解析器对未知内容的既定态度场景行为未知小节标题如## Iconography保留不报错未知颜色令牌名值合法即可接受未知排印令牌名作为合法排印接受未知间距值接受若非合法尺寸则以字符串存储未知组件属性如borderColor接受但给出警告重复小节标题报错拒绝该文件这张表是对格式通过用户生长的最直接背书除重复小节这一结构性错误外其余一切未知内容都以保留 接受的方式温和对待。而整套 11 条 lint 规则的完整清单与各自严重级别记录在 packages/cli/src/linter/linter/rules/index.tsDEFAULT_RULE_DESCRIPTORS与 README.md 的 Linting Rules 一节中——从broken-ref断引用error到omitted-rulesomitted配置校验info每一条规则的职责边界都被明确固定。给 Agent 与写作实践者的可操作结论综合原文档的哲学论述与仓库的工程实现可以提炼出四条落地准则先写叙述再补令牌。用一句具体参照锚定整个设计像 1970 年代老牌大学的讲义然后用{tokens}引用把精确值挂到叙述上参照越具体负面约束越免费。形容词只描述区域参照物才描述点。现代、干净、可信必然产出平庸的中间值像一份印刷的学术讲义才能把设计推向精确的位置。用有意的 Dos and Donts 收尾而不是流水账。正面参照负责定调负面清单负责守住边界二者配合才是sweet spot如果禁令列表长得失控优先回头打磨正面描述。放心扩展格式但不制造困惑。motion、iconography、elevation等自定义键完全合法linter 会静默接受唯一要注意的是别把自定义键拼写成近似内置键会触发unknown-key警告也别让令牌样值的自定义键被export静默丢弃token-like-ignored会提醒你。最终回到原文档的收尾语这份文档传达的是 DESIGN.md 的叙事与哲学以厘清它解决什么问题、以及目前如何尝试解决这些问题。这份哲学不是理论空谈——它被完整地编码进了规范docs/spec.md、规范配置packages/cli/src/linter/spec-config.yaml、lint 规则实现与三个实战示例examples/atmospheric-glass/DESIGN.md、examples/paws-and-paths/DESIGN.md、examples/totality-festival/DESIGN.md之中。理解这套哲学你就理解了为什么一份 DESIGN.md 的价值不在它的十六进制值而在于那些让数值活起来的句子。【免费下载链接】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 设计哲学深度解析：为什么“文字叙述“才是视觉身份规范的核心
DESIGN.md 设计哲学深度解析为什么文字叙述才是视觉身份规范的核心【免费下载链接】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 是一种用于向编码 Agent 描述视觉身份的格式规范而 PHILOSOPHY.md 记录了这套规范背后的核心设计哲学设计的灵魂存在于文字叙述prose之中设计令牌tokens只是支撑叙述的上下文。读完本文你将理解为什么一句具体的参照胜过一打精确的数值、为什么负面约束donts能自动随引用而来以及这个格式如何在不修改规范的前提下通过用户自定义扩展生长出属于自己的设计语言——每一条结论都会结合本仓库的源码、测试与示例给出可验证的依据。一句话抓住 DESIGN.md 的哲学核心DESIGN.md captures how a design looks, feels, and behaves. The prose is where the design lives. Everything else in the document exists to support it.翻译过来即DESIGN.md 记录的是一个设计看起来、感觉起来、行为起来的样子设计活在叙述文字里文档中的其他一切令牌、结构、规范都只是为叙述服务。这句开宗明义的话直接决定了 PHILOSOPHY.md 全文的论述方向也解释了为什么 DESIGN.md 会同时包含两种截然不同的内容层——机器可读的 YAML 令牌与人类以及 Agent可读的 Markdown 叙述。哲学落地的最小示例Technical Handout原文档用一个极简示例展示了叙述即设计的含义--- name: Technical Handout --- ## Overview A graduate-level computer science lecture handout in the tradition of an old established university. The audience is graduate students and research engineers reading a printed handout distributed at the beginning of a seminar. The handout is austere, informationally dense, and proudly unconcerned with first impressions. The audience knows why they are there and the handouts job is to do work, not to seduce.请注意这个示例的精妙之处front matter 里只有一个name没有任何颜色、字体、间距令牌。整份文档的设计意图完全由 Overview 中的三段叙述承载——老牌大学研究生级别的课堂讲义信息密集、毫不讨好第一印象。austere朴素克制、proudly unconcerned with first impressions骄傲地不关心第一印象这些措辞向 Agent 传递的是一种完整的态度而非一组数值。由此引出全文最重要的一句话生成设计质量的优劣更多取决于意图被描述得有多清晰而非数值有多精确。仓库层面的呼应DESIGN.md 的双层结构README.md 将这种哲学固化为格式本身A DESIGN.md file combines machine-readable design tokens (YAML front matter) with human-readable design rationale (markdown prose). Tokens give agents exact values. Prose tells themwhythose values exist and how to apply them.而规范文档 docs/spec.md 中说得更直接The tokens are the normative values; the prose provides context for how to apply them.令牌是规范性数值叙述为如何应用它们提供上下文。normative / context 的措辞与价值观/为什么的措辞一脉相承——数值负责精确叙述负责意义两者缺一不可。Prose, not Tokens叙述才是规范的主角原文档明确划分了 DESIGN.md 的两大组成tokens与prose。规范存在的意义是描述设计语境——既要让设计在不同生成会话之间保持一致性又要为创造性探索留出空间。而其中prose 是最关键的部分。一个完整的 Colors 对照示例原文档给出了一个同时包含令牌与叙述的典型段落## Colors yaml # Tokens colors: paper: #F4F0E4 ink: #1E1A14 vermilion: #C3402A rule-gray: #B8B0A2 !-- Prose -- A single-ink-plus-accent system. - **Paper** {colors.paper} is the canvas — warmed xerox stock, never pure white. - **Ink** {colors.ink} is graphite-warm and carries all typography, all rules, all diagram strokes; never pure black. - **Vermilion** {colors.vermilion} is the single accent and appears only inside diagrams and chart annotations — never on typography, never on page numerals, never on metadata of any kind. - **Rule gray** {colors.rule-gray} is reserved for hairline rules inside content (chart baselines, table dividers); never used as page-frame chrome.注意这里出现了 DESIGN.md 特有的语法{colors.paper}这样的花括号令牌引用让叙述能够动态指向 front matter 中的精确值。同一段文字里warmed xerox stock, never pure white温暖的复印纸质感绝非纯白这类描述承载了#F4F0E4这个十六进制值背后的全部理由——为什么是它、它应该被用在什么场合、绝对不能用在什么场合。在仓库的真实示例 examples/atmospheric-glass/DESIGN.md 中可以看到同样的结构front matter 定义了全套 Material 风格的颜色令牌surface-container-lowest、on-primary、error-container等与 Inter 字体排印令牌正文则用 vibrant-minimalist、frosted crystalline lenses磨砂水晶透镜等叙述交代了玻璃拟态美学的完整意图。另一个测试夹具 packages/cli/src/linter/fixtures/ALPINE_OBSERVATORY.md 则展示了Scientific Alpinism科学式阿尔卑斯登山这种风格#0a1325的深海军蓝被称为The Void虚空#f6bb81的古董黄铜被称为The Instrument仪器——数值与叙事互相锚定。令牌是上下文不是渲染指令这是全文最容易被误解、也最值得强调的论点令牌值作为上下文存在而非渲染指令。一般而言规范并不要求也不建议你在规范里硬性规定令牌。把令牌当作叙述中引用的参考物DESIGN.md 的职责就聚焦在记录设计的本质上而不是去重复语言和工具生态早已耕耘几十年的工作——字体加载、颜色空间转换、间距计算这些事交给 CSS、Tailwind、Figma 或设计令牌工具链去解决。本仓库恰好用代码证明了这种分工packages/cli/src/linter/tailwind/v4/serialize.ts 与 packages/cli/src/linter/dtg/handler.ts 负责把令牌导出为 Tailwind v4 的theme块或 W3C DTCGtokens.json——格式本身只负责定义与描述真正的渲染由这些成熟的既有工具完成。叙述语法的规范依据从 docs/spec.md 可以看到这种叙述为主、令牌为辅的结构被固化为规范Color任何合法 CSS 颜色字符串Hex、命名色、rgb()/hsl()/hwb()、宽色域oklch()/oklab()/lch()/lab()、以及color-mix(in srgb, ...)混合Hex#RRGGBB被推荐为默认写法。Dimension带单位后缀的字符串正式支持的单位为px、em、rem见 packages/cli/src/linter/spec-config.yaml 中的units定义。TypographyfontFamily、fontSize、fontWeight、lineHeight、letterSpacing、fontFeature、fontVariation七个属性lineHeight既可写24px这类 Dimension也可写1.6这种无单位倍数。Token Reference{path.to.token}花括号引用语法在components内允许引用复合值如{typography.label-md}。一个具体参照胜过一打形容词原文档用一个尖锐的对比论证了具体参照的价值A design that references A 1970s graduate lecture handout in the tradition of an old and established university evokes a complete world: the one color of ink, the generous margins, the serif set at a reading size, and the absence of decoration. That single sentence carries more useful information than a dozen metric values. It carries the reasoning behind the values.一份 1970 年代老牌大学的研究生课堂讲义这句话唤起的是一整个完整的世界单一颜色的墨水、宽大的页边距、以阅读字号排版的衬线字体、以及完全没有装饰。这一句话携带的有用信息超过一打度量值——因为它携带了数值背后的推理过程。反过来Modern, clean, trustworthy, premium evokes nothing specific. A model creates something in the center of what those words describe, creating an output that is typically generic. Adjectives describe a region. A specific reference describes a point.现代、干净、可信、高级这类形容词唤不起任何具体画面。模型会在这个词所描述的区域正中央生成一个东西——通常是平庸的、随大流的结果。形容词描述的是一个区域具体参照描述的是一个点。这个观点可以直接指导写作实践与其罗列border-radius: 8px、box-shadow参数不如写像一本学术期刊的版面与其堆砌优雅、极简、专业不如写像 1970 年代老牌大学的课堂讲义。Agent 对具体参照的理解能力本质上来自它对现实世界物体的海量训练知识——命名一个对象就等于同时传递了它的全部隐含属性。在 examples/paws-and-paths/DESIGN.md、examples/totality-festival/DESIGN.md 这些示例中可以看到同样的手法每个设计系统都用一句它是什么来锚定全部后续决策而不是用形容词清单。负面约束你省略掉的东西定义了性格一个清晰的设计参照会自动携带它的限制。原文档的论证如下A model knows what a lecture handout is, and it knows what a lecture handout is not. It does not glow or use a gradient. You dont have to list these. Naming the object names them, the same way naming a dog tells the model that dogs dont meow.模型知道课堂讲义是什么也知道它不是什么——它不会发光、不会用渐变。这些根本不需要你列举。命名即命名就像你说了狗模型自然知道狗不会喵喵叫。由此得出两条实用结论当参照足够具体时负面约束是免费附赠的。一个具体的参照讲座讲义本身就排除了大量的错误方向。有意的不要做清单是有用的冗长的流水账式清单往往是描述过于模糊的信号。如果你需要靠十几条禁令才能防止 Agent 跑偏通常说明你的正面描述还不够具体。两者的理想配合是一个强参照 一份有意为之的 Dos and Donts 清单。原文档的完整 Dos and Donts 示例## Dos and Donts - **Dont** add a hero moment to the title page. A real handout title page is the first page of content, not a magazine cover. - **Dont** reach for an italic standfirst beneath a large title. That is the Substack register. - **Dont** add corner ornaments, chapter marks, or abstract glyphs in the margins. - **Dont** color the page numeral or any other piece of metadata. Vermilion lives in diagrams only. - **Dont** use a display-class serif. One family at four modest sizes. - **Dont** use Bold. Anywhere. - **Dont** use sans-serif for any role other than monospace metadata. - **Dont** introduce dark mode, gradients, glows, glass surfaces, drop shadows, or rounded corners. - **Do** treat the handout as a printed object. The screen is the substrate; the design is the page. - **Do** keep vermilion inside diagrams. Its scarcity outside is what makes its presence inside meaningful. - **Do** trust modest size differences. The section title is only ~1.9× body, not 5× body. - **Do** let pages have visible white space. A page that ends two-thirds of the way down is correct, not under-filled.这份清单的每个条目都值得品味它不是在罗列不允许出现的 CSS 属性而是在陈述性格——标题页不是杂志封面屏幕只是载体设计是纸张本身朱红色的稀缺性正是其内部出现时有意义的原因。注意那些明确的参照点That is the Substack register那是 Substack 的腔调、One family at four modest sizes单一字体家族、四个克制的字号、~1.9× body正文的约 1.9 倍。每条禁令都指向一个可被模型精确理解的参照物而不是一个抽象形容词。规范层面docs/spec.md 将 Dos and Donts 列为八个标准小节中的最后一个第 8 位定位是创建设计时的护栏guardrailspackages/cli/src/linter/spec-config.yaml 中的sections定义确认了它的规范名称与别名而section-order这一条 lint 规则见 packages/cli/src/linter/linter/rules/section-order.ts会校验小节是否按规范顺序出现。格式通过用户生长而不是通过规范生长结构最小主义只标准化通用到值得统一的部分原文档指出规范定义的只是每一份 DESIGN.md 都共享的结构性最小集一个name一小撮足够通用、值得标准化的类别colors、typography、spacing、rounded、components。除此之外一切都是你的自由。格式接受你的设计系统需要的任何键、任何小节、任何结构。规范在一致性有帮助的地方做标准化在灵活性更有帮助的地方保持开放。原文档特别点名了这些开放领域motion动效、iconography图标、elevation层级、text casing文字大小写、paragraph measure段落行长。理由很实际同一类令牌在不同团队里形态天差地别。一个团队的 motion 令牌是 CSS 动画曲线另一个团队的则是以缓冲块buffer blocks为单位的音频域时间常数。正确的形态取决于每个系统自身而格式本身已经允许你定义它。Motion 扩展示例原文档用动效这个自定义类别演示了如何不修改规范就完成扩展## Motion yaml motion: feedback: 120ms content: 250ms easing: cubic-bezier(0.2, 0, 0, 1) Transitions are quick and mechanical. Nothing bounces, nothing overshoots, nothing lingers. State changes should feel like a light switch, not a door closing. - Interactive feedback (hover, press, toggle): {motion.feedback}, always {motion.easing}. - Content transitions (page, panel, modal): {motion.content}, same curve. - Nothing in the UI animates longer than 300ms. If something takes longer, cut it. - Respect prefers-reduced-motion: all durations collapse to 0ms.这个示例完美体现了全部哲学motion不是规范预定义的键规范只定义了 colors/typography/spacing/rounded/components 五个令牌组但格式允许它存在{motion.feedback}引用语法与规范内令牌完全一致而叙述部分——像电灯开关而不是关门、任何动画超过 300ms 就砍掉、尊重prefers-reduced-motion——才是这份设计真正有灵魂的地方。源码证据扩展如何被 linter 优雅地接受格式接受任何键不是一句空话仓库的 lint 规则实现给出了两条精妙的佐证1. 自定义键保持静默。packages/cli/src/linter/linter/rules/unknown-key.ts 中的unknown-key规则只对长得像已知键拼写错误的顶层键发出警告它用莱文斯坦编辑距离levenshtein见 packages/cli/src/linter/linter/rules/levenshtein.ts把未知键与colors/typography/spacing/rounded/components等 schema 键做相似度比对距离阈值MAX_TYPO_DISTANCE 2——colours:会被提示是不是想写colors:而motion:、iconography:这类真正的自定义扩展键不会被误报。这正是格式生长于用户在代码层的落地有意的扩展零打扰无意的拼写错误被温柔捕获。2. 令牌样值兜底提醒。packages/cli/src/linter/linter/rules/token-like-ignored.ts 中的token-like-ignored规则更进一步如果某个未知顶层键的值看起来像令牌映射含 Hex 颜色、CSS 尺寸等令牌样叶子值而它又不属于受支持的导出 schema就警告它会被export命令静默忽略建议改名或移入受支持的区块——例如base_colors: { light: { ink: #0B0F14 } }这种值会被识别出来。两条规则合在一起的效果是格式开放但不糊涂。此外packages/cli/src/linter/spec-config.ts 中定义了两个与开放性配套的保护性限制MAX_TOKEN_NESTING_DEPTH 20令牌最大嵌套深度与MAX_REFERENCE_DEPTH 10引用最大解析深度防止恶意或病态结构导致解析器栈溢出——开放不等于无防护。Tokens are context 在规范层的确证回到 docs/spec.md 的 Consumer Behavior for Unknown Content 一节可以看到 linter 与解析器对未知内容的既定态度场景行为未知小节标题如## Iconography保留不报错未知颜色令牌名值合法即可接受未知排印令牌名作为合法排印接受未知间距值接受若非合法尺寸则以字符串存储未知组件属性如borderColor接受但给出警告重复小节标题报错拒绝该文件这张表是对格式通过用户生长的最直接背书除重复小节这一结构性错误外其余一切未知内容都以保留 接受的方式温和对待。而整套 11 条 lint 规则的完整清单与各自严重级别记录在 packages/cli/src/linter/linter/rules/index.tsDEFAULT_RULE_DESCRIPTORS与 README.md 的 Linting Rules 一节中——从broken-ref断引用error到omitted-rulesomitted配置校验info每一条规则的职责边界都被明确固定。给 Agent 与写作实践者的可操作结论综合原文档的哲学论述与仓库的工程实现可以提炼出四条落地准则先写叙述再补令牌。用一句具体参照锚定整个设计像 1970 年代老牌大学的讲义然后用{tokens}引用把精确值挂到叙述上参照越具体负面约束越免费。形容词只描述区域参照物才描述点。现代、干净、可信必然产出平庸的中间值像一份印刷的学术讲义才能把设计推向精确的位置。用有意的 Dos and Donts 收尾而不是流水账。正面参照负责定调负面清单负责守住边界二者配合才是sweet spot如果禁令列表长得失控优先回头打磨正面描述。放心扩展格式但不制造困惑。motion、iconography、elevation等自定义键完全合法linter 会静默接受唯一要注意的是别把自定义键拼写成近似内置键会触发unknown-key警告也别让令牌样值的自定义键被export静默丢弃token-like-ignored会提醒你。最终回到原文档的收尾语这份文档传达的是 DESIGN.md 的叙事与哲学以厘清它解决什么问题、以及目前如何尝试解决这些问题。这份哲学不是理论空谈——它被完整地编码进了规范docs/spec.md、规范配置packages/cli/src/linter/spec-config.yaml、lint 规则实现与三个实战示例examples/atmospheric-glass/DESIGN.md、examples/paws-and-paths/DESIGN.md、examples/totality-festival/DESIGN.md之中。理解这套哲学你就理解了为什么一份 DESIGN.md 的价值不在它的十六进制值而在于那些让数值活起来的句子。【免费下载链接】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），仅供参考