Back to Details

designkit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

designkit

designkit

A design system that lives in someone's head, or in Figma, is invisible to the agent writing the UI. 
DESIGN.md
is what the ecosystem converged on instead: an open format from Google Labs (Apache-2.0, google-labs-code/design.md) that pairs machine-readable design tokens in YAML front matter with human-readable rationale in prose. It is deliberately the design counterpart to the agent instruction files coding agents already read (
CLAUDE.md
and its equivalents) — a persistent contract in the repo root that survives sessions, and that any DESIGN.md-aware agent reads.
designkit does the half the ecosystem left empty. Every other tool hands you a design system from somewhere else — a file reverse-engineered from Stripe, or a palette retrieved from a product-type lookup table. designkit derives yours from the UI you already shipped, and tells you later when it has gone stale.
That makes the grounding rule the whole skill: every token must be a value that appears in your codebase. Clustering forty near-identical greys into a scale is derivation. Picking a nicer neighbouring hex because it rounds better is invention, and it is the one thing designkit never does.
仅存在于某人脑海或Figma中的设计系统，对于编写UI的Agent来说是不可见的。而DESIGN.md是行业生态达成共识的替代方案：它是Google Labs推出的一种开放格式（基于Apache-2.0协议，仓库地址：google-labs-code/design.md），在YAML前置元数据中包含机器可读的设计令牌，同时搭配人类可读的文字说明。它特意作为编码Agent已读取的指令文件（如
CLAUDE.md
及其同类文件）在设计领域的对应产物——是仓库根目录中持久存在的约定，可跨会话留存，所有支持DESIGN.md的Agent均可读取。
designkit填补了行业生态中缺失的一环。其他工具都是从外部来源为你提供设计系统——比如从Stripe逆向工程得到的文件，或是从产品类型查找表中获取的调色板。designkit从你已上线的UI中提取专属设计系统，并在后续系统过时后通知你。
这就引出了本工具的核心原则：每个令牌必须是代码库中实际存在的值。将四十种近似的灰色聚类为一个梯度属于提取操作。为了更美观而选择相邻的十六进制颜色值属于创造行为，这是designkit绝对不会做的事。

What designkit is not

designkit 不是什么

  • Not a UI generator. It records the system; it writes no components, no pages, no application CSS. A skill that both defines the taste and applies it can't be held to the grounding rule.
  • Not a taste library. It ships no palettes, no font pairings, no style catalog. If your project has no design system, designkit proposes one from your own values or says it can't — it never imports someone else's.
  • Not a spec implementation. Linting, contrast checking, token export, and the schema itself belong to the official CLI. designkit shells out and reports; it is not a second, worse implementation.
  • Not a design critique. Whether the system is any good is a human's call. designkit reports what is there, including when what's there is a mess.
  • Not the glossary or the decision log. Domain vocabulary and architecture decisions belong elsewhere; a design token is neither.
  • 不是UI生成器：它仅记录设计系统，不编写任何组件、页面或应用CSS。同时定义风格并应用风格的工具无法遵循核心原则。
  • 不是风格库：它不提供任何调色板、字体组合或风格目录。如果你的项目没有设计系统，designkit会基于你项目自身的已有值提出方案，若无法提取则直接说明——绝不会引入外部的设计系统。
  • 不是规范实现工具：校验、对比度检查、令牌导出以及模式本身都属于官方CLI的功能。designkit仅调用CLI并返回结果，不会做二次实现。
  • 不是设计评审工具：设计系统的优劣由人类判断。designkit仅如实报告现有内容，包括混乱的现状。
  • 不是术语表或决策日志：领域词汇和架构决策应存放在其他位置，设计令牌不属于这两类内容。

When this fires

触发场景

  • init
     — "write a DESIGN.md", "document our design system", "we have no design tokens", "what colors does this project actually use". Derives the file from the codebase.
  • update
     — "the design system changed", "update DESIGN.md", or a design pass right after UI work lands. Applies what the code now says.
  • audit
     — "is our DESIGN.md still accurate", "check the design system against the code", "what's drifted". Read-only sweep. Writes nothing, ever.
If no mode is clear, ask. 
audit
is free and 
init
rewrites the project's design contract; never guess between them.
  • init
    模式     —— 当用户提出「编写DESIGN.md」「记录我们的设计系统」「我们没有设计令牌」「这个项目实际使用了哪些颜色」时触发。从代码库中提取内容生成DESIGN.md文件。
  • update
    模式     —— 当用户提出「设计系统已变更」「更新DESIGN.md」或UI工作完成后需要设计同步时触发。根据当前代码更新DESIGN.md内容。
  • audit
    模式     —— 当用户提出「我们的DESIGN.md是否仍准确」「检查设计系统与代码的一致性」「哪些内容已偏离」时触发。仅执行只读扫描，绝不写入任何内容。
若无法明确触发模式，请询问用户。
audit
模式不会修改文件，而
init
模式会重写项目的设计约定，切勿自行猜测。

The artifact

生成产物

DESIGN.md
lives at the repo root. That's the spec's convention and how DESIGN.md-aware tools discover it — not 
docs/
, however tempting the tidiness.
DESIGN.md
存放在仓库根目录。这是规范约定的位置，也是支持DESIGN.md的工具发现它的路径——即使
docs/
目录看起来更整洁，也不应放在此处。

The token schema

令牌模式

Front matter opens with a line of exactly 
---
and closes the same way. This is the alpha schema as captured on 2026-08-06; prefer reading it live when the CLI is available, because the format is explicitly still moving.
yaml
version: <string>          # optional, current: "alpha"
name: <string>
description: <string>      # optional
omitted: <string[] | OmittedSection[]>   # optional — sections deliberately excluded
colors:
  <token-name>: <Color>            # "#1A1C1E", "oklch(62% 0.18 250)", CSS named
typography:
  <token-name>: <Typography>       # fontFamily, fontSize, fontWeight, lineHeight,
                                   # letterSpacing, fontFeature, fontVariation
rounded:
  <scale-level>: <Dimension>       # 4px, 0.5rem, 9999px
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>   # "{colors.primary}"
Values cross-reference with 
{path.to.token}
syntax. Prefer a reference over a repeated literal — an unreferenced token trips 
orphaned-tokens
, and a duplicated literal is how a system drifts.
Recommended token names (non-normative, but follow them unless the project already has its own vocabulary): colors 
primary
, 
secondary
, 
tertiary
, 
neutral
, 
surface
, 
on-surface
, 
error
; typography 
headline-display
, 
headline-lg
, 
headline-md
, 
body-lg
, 
body-md
, 
body-sm
, 
label-lg
, 
label-md
, 
label-sm
; rounded 
none
, 
sm
, 
md
, 
lg
, 
xl
, 
full
.
前置元数据以一行
---
开头，同样以一行
---
结尾。以下是2026年8月6日记录的alpha版本模式；若CLI可用，建议直接查看实时规范，因为该格式仍在持续演进。
yaml
version: <string>          # 可选，当前版本："alpha"
name: <string>
description: <string>      # 可选
omitted: <string[] | OmittedSection[]>   # 可选——刻意排除的章节
colors:
  <token-name>: <Color>            # "#1A1C1E", "oklch(62% 0.18 250)", CSS命名色
typography:
  <token-name>: <Typography>       # fontFamily, fontSize, fontWeight, lineHeight,
                                   # letterSpacing, fontFeature, fontVariation
rounded:
  <scale-level>: <Dimension>       # 4px, 0.5rem, 9999px
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>   # "{colors.primary}"
值通过
{path.to.token}
语法进行交叉引用。优先使用引用而非重复字面量——未被引用的令牌会触发
orphaned-tokens
错误，重复的字面量是导致设计系统偏离的原因之一。
推荐的令牌名称（非强制性，但除非项目已有专属词汇，否则建议遵循）：颜色类
primary
、
secondary
、
tertiary
、
neutral
、
surface
、
on-surface
、
error
；排版类
headline-display
、
headline-lg
、
headline-md
、
body-lg
、
body-md
、
body-sm
、
label-lg
、
label-md
、
label-sm
；圆角类
none
、
sm
、
md
、
lg
、
xl
、
full
。

The sections

章节规范

Eight canonical 
##
headings, in this order. Out-of-order sections trip 
section-order
; a duplicate heading is a hard error that rejects the file.
#SectionAliasCarries
1OverviewBrand & Stylethe visual intent, in prose
2Colors—palette rationale; 
colors
tokens
3Typography—the type hierarchy; 
typography
tokens
4LayoutLayout & Spacinggrid, whitespace; 
spacing
tokens
5Elevation & DepthElevationshadow and surface hierarchy
6Shapes—corner language; 
rounded
tokens
7Components—component guidance; 
components
tokens
8Do's and Don'ts—guardrails, anti-patterns, and UI copy voice
Two further sections are permitted after Do's and Don'ts, because the spec preserves unknown headings without error: 
## Motion
 and 
## Dark Mode
. Both are prose only — see below for why that isn't a stylistic preference.
Voice belongs in Do's and Don'ts rather than a section of its own. Rules about the strings on screen ("errors name the fix, not the failure") are guardrails, and the spec already has a section for guardrails.
共八个标准的
##
标题，需按以下顺序排列。顺序错误会触发
section-order
错误；重复标题属于严重错误，会直接拒绝文件。
序号章节名称别名内容
1OverviewBrand & Style视觉意图的文字说明
2Colors—调色板说明；
colors
令牌
3Typography—字体层级；
typography
令牌
4LayoutLayout & Spacing网格、留白；
spacing
令牌
5Elevation & DepthElevation阴影与表面层级
6Shapes—圆角规则；
rounded
令牌
7Components—组件指导；
components
令牌
8Do's and Don'ts—约束规则、反模式、以及UI文案风格
在Do's and Don'ts章节之后，还允许添加两个额外章节：
## Motion
和
## Dark Mode
。这两个章节仅包含文字说明——下文会解释这并非风格偏好。
文案风格应放在Do's and Don'ts章节而非单独章节。关于屏幕文案的规则（如“错误提示应说明修复方法而非仅指出问题”）属于约束规则，而规范中已有专门的章节存放此类内容。

What never goes in YAML

禁止放入YAML的内容

Verified by running the linter, not inferred from the docs. Two shapes look reasonable and both produce warnings on a file you'd otherwise call clean:
TemptingWhat the linter doesDo this instead
A top-level 
motion:
token map		⚠️ 
token-like-ignored
— "looks like a design-token map but is not a recognized schema key … will be silently ignored by export commands"		prose in 
## Motion
transitionDuration:
on a component		⚠️ 
broken-ref
— "not a recognized component sub-token"		prose in 
## Motion
The complete set of valid component sub-tokens is 
backgroundColor
, 
textColor
, 
typography
, 
rounded
, 
padding
, 
size
, 
height
, 
width
. There is no duration, no easing, no border, no gap. Anything else warns.
So motion has no token home anywhere in the schema. Durations and easing curves are prose, and that's the honest representation until the spec grows a place for them.
What is token-legal is interaction state, through the related-key pattern the spec defines: 
button-primary
, 
button-primary-hover
, 
button-primary-active
. Extract those as real component entries. Never invent a custom key to hold a state the pattern already expresses.
以下内容会被校验工具检测出来，而非仅从文档推断。有些内容看似合理，但会导致文件在其他情况下被判定为合规时出现警告：
易误用的内容校验工具行为正确做法
顶层
motion:
令牌映射		⚠️ 
token-like-ignored
—— “看起来像设计令牌映射，但不是已识别的模式键……导出命令会忽略此内容”		在
## Motion
章节中用文字说明
组件上的
transitionDuration:
⚠️ 
broken-ref
—— “不是已识别的组件子令牌”		在
## Motion
章节中用文字说明
有效的组件子令牌仅包括
backgroundColor
、
textColor
、
typography
、
rounded
、
padding
、
size
、
height
、
width
。不包含时长、缓动曲线、边框、间距等内容。其他任何内容都会触发警告。
因此动画在模式中没有对应的令牌存放位置。时长和缓动曲线需用文字说明，这是在规范扩展相关内容前的如实呈现方式。
符合令牌规则的是交互状态，通过规范定义的相关键模式实现：
button-primary
、
button-primary-hover
、
button-primary-active
。将这些提取为真实的组件条目。切勿为模式已覆盖的状态自定义键。

The stamp

标记信息

Every file designkit writes ends with one visible line, after the last section:
markdown
_Extracted from `main`@`a1b2c3d` on 2026-08-06._
Both halves earn their place: 
audit
 recovers the baseline with 
git show <sha>:DESIGN.md
while the SHA is reachable, and falls back to the date once a squash-merge has orphaned it. An HTML comment would be invisible in every renderer, which is exactly how a stale file comes to read as current.
A file with no stamp was written by a human. Adopt it, work with it, never silently claim it — say plainly that you're editing a file designkit didn't author.
designkit生成的每个文件都会在最后一个章节后添加一行可见内容：
markdown
_Extracted from `main`@`a1b2c3d` on 2026-08-06._
这两部分内容都有其作用：当SHA仍可访问时，
audit
可通过
git show <sha>:DESIGN.md
恢复基线；当合并提交导致SHA失效时，则可通过日期进行回溯。HTML注释在所有渲染器中都是不可见的，这正是过时文件被误以为是最新版本的原因。
没有标记信息的文件是人工编写的。应采用该文件并与之协作，但切勿擅自声明为designkit生成——需明确说明你正在编辑一个非designkit生成的文件。

The CLI is the source of truth

CLI是权威来源

The format is at version 
alpha
and openly under active development. Hardcoding the schema into a skill is how the skill becomes confidently wrong, so read the spec at run time and treat the summary above as a dated fallback:
CommandUse
npx @google/design.md spec [--rules] [--format json]
the current schema and rule set
npx @google/design.md lint <file> [--format json]
validate; JSON by default
npx @google/design.md diff <before> <after>
compare two versions
npx @google/design.md export --format {json-tailwind|css-tailwind|dtcg} <file>
emit tokens
Exit codes: 
0
success, 
1
errors or regressions, 
2
file read failure. On Windows PowerShell use the 
designmd
alias — 
.md
file association hijacks the other form.
The eleven lint rules run on every file: 
broken-ref
(error), 
contrast-ratio
, 
orphaned-tokens
, 
missing-primary
, 
missing-typography
, 
section-order
, 
unknown-key
, 
token-like-ignored
(warnings), and 
token-summary
, 
missing-sections
, 
omitted-rules
(info). 
contrast-ratio
already enforces WCAG AA at 4.5:1 — never write your own contrast math.
当前格式处于
alpha
版本，正在积极开发中。将模式硬编码到工具中会导致工具出现错误，因此应在运行时从CLI读取规范，并将上述摘要视为过时的备用方案：
命令用途
npx @google/design.md spec [--rules] [--format json]
获取当前模式和规则集
npx @google/design.md lint <file> [--format json]
验证文件；默认输出JSON格式
npx @google/design.md diff <before> <after>
对比两个版本
`npx @google/design.md export --format {json-tailwind\css-tailwind\
退出码：
0
表示成功，
1
表示存在错误或退化，
2
表示文件读取失败。在Windows PowerShell中使用
designmd
别名——
.md
文件关联会影响其他调用方式。
每个文件都会运行11条校验规则：
broken-ref
（错误）、
contrast-ratio
、
orphaned-tokens
、
missing-primary
、
missing-typography
、
section-order
、
unknown-key
、
token-like-ignored
（警告），以及
token-summary
、
missing-sections
、
omitted-rules
（信息）。
contrast-ratio
已强制遵循WCAG AA标准（对比度4.5:1）——无需自行编写对比度计算逻辑。

The extraction engine

提取引擎

One engine, shared by all three modes. 
init
writes its output, 
update
diffs and applies it, 
audit
diffs and reports it. There is no manifest of watched paths to maintain, and therefore no change that goes unnoticed because a glob failed to cover it.
所有三种模式共享同一个提取引擎。
init
模式写入输出结果，
update
模式对比差异并应用更新，
audit
模式对比差异并生成报告。无需维护监控路径清单，因此不会因为glob模式未覆盖而遗漏任何变更。

Find the token home

查找令牌来源

First rung that matches, and say which one matched before writing anything:
#RungLooks like
1Tailwind
@theme
in CSS (v4), or 
tailwind.config.*
theme.extend
(v3)
2CSS custom propertiesa 
:root
block of 
--token: value
3Preprocessor variablesSCSS 
$vars
, Less 
@vars
, a map file
4CSS-in-JS themea theme object passed to a provider
5WordPress
theme.json
settings.color.palette
, 
settings.typography
6Nothingno declared tokens anywhere — see when there's no system
匹配到第一个层级后，在写入任何内容前说明匹配到的层级：
序号层级特征
1TailwindCSS中包含
@theme
（v4版本），或
tailwind.config.*
中的
theme.extend
（v3版本）
2CSS自定义属性
:root
块中包含
--token: value
格式的内容
3预处理器变量SCSS的
$vars
、Less的
@vars
，或映射文件
4CSS-in-JS主题传递给Provider的主题对象
5WordPress
theme.json
中的
settings.color.palette
、
settings.typography
6无来源未找到任何已声明的令牌——详见无设计系统时的处理

Derive from usage, not declarations

从实际使用中提取，而非声明内容

A declared token nobody uses is not the design system; forty hardcoded hexes are. Read both:
  • every color literal in stylesheets, templates, and components — hex, 
    rgb()
    , 
    hsl()
    , 
    oklch()
    , and named colors
  • the font sizes, weights, and line heights actually applied
  • the padding, margin, and gap values that recur
  • corner radii and shadows in use
  • the interaction states actually styled — 
    :hover
    , 
    :focus-visible
    , 
    :active
    , 
    disabled
    , and their framework equivalents
  • dark mode: grep 
    .dark
    , 
    prefers-color-scheme
    , 
    dark:
    variants, 
    [data-theme]
Count occurrences. A value used ninety times and a value used once are not equally part of the system, and the counts are what make the next part defensible.
已声明但未被使用的令牌不属于设计系统；四十个硬编码的十六进制颜色值才是。需同时读取以下内容：
  • 样式表、模板和组件中所有的颜色字面量——十六进制、
    rgb()
    、
    hsl()
    、
    oklch()
    以及命名颜色
  • 实际应用的字体大小、字重和行高
  • 重复出现的内边距、外边距和间距值
  • 实际使用的圆角半径和阴影
  • 实际设置样式的交互状态——
    :hover
    、
    :focus-visible
    、
    :active
    、
    disabled
    及其框架等效状态
  • 深色模式：搜索
    .dark
    、
    prefers-color-scheme
    、
    dark:
    变体、
    [data-theme]
统计出现次数。使用九十次的值和使用一次的值在设计系统中的重要性不同，统计结果是后续操作的依据。

Classify every token

分类每个令牌

Each token carries one of three states, and the classification is shown at the consent gate:
StateMeans
extracted
the value appears in the code as-is, used enough to be systematic
consolidated
clustered from N near-duplicates — list them, so the merge is reviewable and reversible
omitted
not derivable from the code; goes in the spec's native 
omitted
field, never invented
omitted
is a feature, not a failure. The field exists precisely to declare deliberate exclusions and to suppress missing-section warnings. A DESIGN.md that honestly omits elevation beats one that invents a shadow scale.
每个令牌包含三种状态之一，分类结果会在确认环节展示：
状态含义
extracted
该值在代码中原样存在，且使用次数足够多，属于系统性内容
consolidated
从N个近似值聚类而来——需列出这些值，以便合并操作可被评审和回滚
omitted
无法从代码中提取；放入规范原生的
omitted
字段，绝不凭空创造
omitted
是功能而非缺陷。该字段的存在正是为了声明刻意排除的内容，并抑制缺失章节的警告。如实省略层级的DESIGN.md文件，比凭空创造阴影梯度的文件更有价值。

When there's no system

无设计系统时的处理

The likeliest real input: hundreds of hardcoded values, no token home, no consistency. designkit clusters and proposes — it does not refuse, and it does not fall through to an interview when the taste is already on screen, just messily.
The proposal is bound by the grounding rule: every proposed token is a value that occurs in the code. Cluster near-duplicates, choose the most-used member of each cluster as the representative, and list the members it absorbs. Never emit a value the codebase has never contained.
Tune the cluster threshold to the project and state the threshold you used — it's a judgment call, and an unstated one is unreviewable. Perceptual distance for color, nearest-step for spacing and type. When a cluster is too loose to call one system, split it rather than forcing a merge, and say so.
最常见的输入情况：数百个硬编码值，无令牌来源，无一致性。designkit会聚类并提出方案——不会拒绝处理，也不会因为风格混乱而陷入询问环节。
方案需遵循核心原则：每个提出的令牌都是代码库中存在的值。将近似值聚类，选择每个聚类中使用次数最多的值作为代表，并列出被合并的其他值。绝不要输出代码库中从未出现过的值。
根据项目调整聚类阈值，并说明你使用的阈值——这是主观判断，未说明的阈值无法被评审。颜色使用感知距离，间距和字体使用最近步长。当聚类过于松散无法归为一个系统时，应拆分而非强制合并，并说明情况。

Show the work

展示处理过程

Before writing anything, emit a disposable swatch sheet — a plain HTML page of color chips, type specimens, spacing bars, and radii, each labelled with its token name, its state, and the values it absorbed. Reviewing "forty greys became six" as a YAML diff is not realistic; as swatches it takes seconds.
This is review scaffolding, not a deliverable. Write it to a gitignored scratch path, add that path to 
.gitignore
if it isn't covered, name it in the consent ask, and don't keep it. It is emphatically not the generated UI this skill refuses to write — it's a proof sheet for a decision.
在写入任何内容前，生成一份一次性样本表——一个包含颜色块、字体样本、间距条和圆角的纯HTML页面，每个元素都标注令牌名称、状态以及被合并的值。通过YAML差异评审“四十种灰色合并为六种”并不现实，但通过样本表只需几秒即可完成。
这是评审脚手架，而非交付物。将其写入被git忽略的临时路径，若该路径未被覆盖则添加到
.gitignore
中，在确认请求中说明其名称，且无需保留。这绝非本工具拒绝生成的UI，而是决策的验证表。

Mode: 
init

init
模式

1. Ground it

1. 确立基础

Run the extraction engine. Name the rung that matched, the number of distinct values found per category, and the dark-mode verdict, before proposing anything.
运行提取引擎。在提出任何方案前，说明匹配到的层级、每个类别中找到的不同值数量，以及深色模式的判定结果。

2. Interview only when there's nothing to read

2. 仅在无内容可读取时询问

No UI in the repo means nothing to extract. Ask for the essentials — brand intent, an existing palette, type preferences — and say plainly in the report and in the file's Overview that the result is proposed, not extracted. Anything still unknown is 
omitted
.
仓库中无UI意味着无内容可提取。询问核心信息——品牌意图、现有调色板、字体偏好——并在报告和文件的Overview章节中明确说明结果是提议内容，而非提取内容。任何仍不明确的内容都标记为
omitted
。

3. Propose, and gate on it

3. 提出方案并等待确认

Show the swatch sheet plus the 
extracted
/ 
consolidated
/ 
omitted
breakdown, the cluster threshold, and every inconsistency found. This is the gate that matters — the user accepts, trims, or redirects before a file exists.
展示样本表以及
extracted
/
consolidated
/
omitted
的分类结果、聚类阈值和发现的所有不一致之处。这是关键的确认环节——用户需先接受、调整或重新定向，才能生成文件。

4. Write, stamp, validate

4. 写入、标记、验证

Write 
DESIGN.md
at the repo root, append the stamp, then run 
lint
and report its findings verbatim — including any that remain. A warning you chose to accept is reported as accepted, never suppressed.
在仓库根目录写入
DESIGN.md
，添加标记信息，然后运行
lint
并如实报告结果——包括所有剩余的问题。若选择接受警告，需在报告中说明已接受该警告，切勿隐瞒。

5. Hand off

5. 交付说明

Write every hand-off in this skill in the procedural register: one instruction per sentence, active voice, present tense, no metaphor.
What changed — the file created, the rung that matched, how many tokens landed in each state, and what was omitted.
Where it landed — 
DESIGN.md
at the repo root, the swatch sheet's scratch path (and that it's disposable), and the lint result.
Next — read the file. It's a claim about your project's visual identity and it's the one thing here a human should actually check. Then commit it with commitkit when installed, otherwise 
git add DESIGN.md
and commit. If the project has a token home and the file's values differ from it, token sync is the follow-up; if it doesn't, there is nothing to sync and no next step to invent.
本工具的所有交付说明均采用流程化表述：每句一个指令，主动语态，现在时态，无隐喻。
变更内容——创建的文件、匹配到的层级、每个状态下的令牌数量，以及被省略的内容。
存放位置——仓库根目录的
DESIGN.md
、样本表的临时路径（说明其为一次性文件），以及校验结果。
后续操作——阅读该文件。它是关于项目视觉标识的声明，是唯一需要人工检查的内容。若已安装commitkit，则使用它提交；否则执行
git add DESIGN.md
并提交。若项目已有令牌来源且文件值与来源不同，后续需进行令牌同步；若没有令牌来源，则无需同步，也无需额外操作。

Mode: 
update

update
模式

1. Resolve the target

1. 确定目标版本

Uncommitted working-tree changes first (
git status --porcelain
non-empty → 
git diff HEAD
, plus untracked files, which 
git diff
never shows). Otherwise the branch diff against the base ref — from gitkit when it's installed, else the repo's default branch via 
gh repo view --json defaultBranchRef
. Never assume 
main
. Say which target you chose in one line.
优先处理未提交的工作区变更（
git status --porcelain
非空 → 
git diff HEAD
，包括未跟踪文件，
git diff
不会显示这些文件）。否则对比分支与基准引用的差异——若已安装gitkit则使用其结果，否则通过
gh repo view --json defaultBranchRef
获取仓库默认分支。切勿默认使用
main
分支。用一句话说明你选择的目标版本。

2. Re-extract and diff

2. 重新提取并对比差异

Run the engine against the current code and diff its result against the committed 
DESIGN.md
. Where the stamped SHA is still reachable, also run 
npx @google/design.md diff <baseline> <current>
for the structured token-level comparison.
针对当前代码运行提取引擎，并将结果与已提交的
DESIGN.md
对比。若标记的SHA仍可访问，还需运行
npx @google/design.md diff <baseline> <current>
进行结构化的令牌级对比。

3. Apply, with restraint

3. 谨慎应用更新

A changed brand color edits the color token. It does not regenerate the file. State which sections are affected and which are deliberately untouched before editing — the untouched list is the load-bearing half, because it's what shows the skill knew what it was leaving alone.
Edits to existing tokens and prose land directly; they're bounded by that restraint and land in a reviewable diff. New sections and deletions are consent-gated. A skill that rewrites a design system because one button changed is worse than no skill.
品牌颜色变更只需编辑颜色令牌，无需重新生成整个文件。在编辑前说明受影响的章节和刻意保留的章节——保留的章节是关键部分，因为它表明工具清楚自己在保留哪些内容。
对现有令牌和文字的编辑可直接进行——这些操作受约束规则限制，且生成的差异可被评审。新增章节和删除操作需等待用户确认。仅因一个按钮变更就重写设计系统的工具比没有工具更糟。

4. Re-stamp and validate

4. 重新标记并验证

Re-stamp with the current ref and SHA, run 
lint
, report.
使用当前引用和SHA重新添加标记信息，运行
lint
并报告结果。

5. Hand off

5. 交付说明

What changed — tokens edited (one line each, naming the value that moved), sections proposed and their verdict, sections deliberately untouched.
Where it landed — 
DESIGN.md
, and the lint result.
Next — commitkit, then prkit if this is branch work (otherwise 
git commit
and 
gh pr create
). The design system lands in the same commit as the UI change that moved it; that's the point of keeping it in the repo.
变更内容——编辑的令牌（每个令牌用一句话说明变更后的值）、提议的章节及其结果、刻意保留的章节。
存放位置——
DESIGN.md
以及校验结果。
后续操作——使用commitkit提交；若为分支工作，则使用prkit（否则执行
git commit
和
gh pr create
）。设计系统应与导致其变更的UI变更提交到同一个提交中——这正是将其存放在仓库中的意义。

Mode: 
audit

audit
模式

Read-only. Writes nothing, ever. It reports and routes; fixing is a separate invocation, deliberately.
Three checks:
  • Lint — 
    npx @google/design.md lint
    , findings reported as-is.
  • Drift — the check only designkit can do, because the linter validates the file against itself and has no view of the codebase. Two directions: tokens in the file that no longer appear in the code, and values in the code that no token covers.
  • Baseline — 
    npx @google/design.md diff
    against 
    git show <stamped-sha>:DESIGN.md
    , when the SHA is reachable.
只读模式，绝不写入任何内容。仅生成报告并给出建议；修复操作需单独触发，这是刻意设计的流程。
包含三项检查：
  • 校验 —— 运行
    npx @google/design.md lint
    ，如实报告结果。
  • 偏离检查 —— 这是只有designkit能完成的检查，因为校验工具仅验证文件本身，无法查看代码库。检查两个方向：文件中存在但代码中已不再使用的令牌，以及代码中使用但无令牌覆盖的值。
  • 基线对比 —— 若SHA仍可访问，运行
    npx @google/design.md diff
    对比
    git show <stamped-sha>:DESIGN.md
    。

The report

报告结果

VerdictMeans
current
the file's tokens match what the code uses
stale
a token's value has moved in the code
orphaned
a token in the file appears nowhere in the code
uncovered
a value used in the code that no token covers
unverified
a human-written file designkit has never checked
Open with a coverage line — how many files were scanned and how many skipped — because an audit that silently covered a fraction of the UI reads exactly like a clean bill of health. Then crown one next move.
结论含义
current
文件中的令牌与代码使用的值一致
stale
代码中令牌的值已变更
orphaned
文件中的令牌在代码中无任何使用场景
uncovered
代码中使用的值无对应的令牌覆盖
unverified
人工编写的文件，designkit从未检查过
报告开头需包含覆盖范围说明——扫描的文件数量和跳过的文件数量，因为仅覆盖部分UI的审计会被误以为是全面合规。然后给出首要建议。

Hand off

交付说明

What changed — nothing. Say it outright; a reader should never have to wonder whether a read-only mode wrote something.
Where it landed — inline in this reply. There's no audit artifact by default; offer to save one only if asked.
Next — crown the single worst drift and route it to 
update
, or to 
init
 when the file is missing rather than wrong. "Nothing has drifted" is a valid, stated result — say the system is current and stop.
变更内容——无任何变更。需明确说明；读者不应怀疑只读模式是否写入了内容。
存放位置——直接在回复中展示。默认无审计产物；仅在用户要求时才提供保存选项。
后续操作——指出最严重的偏离问题，并引导至
update
；若文件缺失而非错误，则引导至
init
。“无任何偏离”是有效的结果——说明设计系统是最新的即可。

Token sync

令牌同步

On consent, and only where a token home already exists. designkit never introduces a token system to a project that doesn't have one — that's a build-tooling decision, not a documentation one.
Token homeHow
Tailwindthe official 
export --format json-tailwind
or 
css-tailwind
Plain 
:root
custom properties		written directly — 
css-tailwind
emits a v4 
@theme
block of custom properties, so this is transcription, not conversion
SCSS maps, CSS-in-JS, WordPress 
theme.json
export --format dtcg
, then route to a translator such as Style Dictionary
The seam is transformation, not framework: if the official exporter already emits the shape, designkit writes it; if it needs real conversion, designkit emits DTCG and names the tool. Hand-rolled converters drift the moment either format moves.
仅在用户确认且项目已有令牌来源时执行。designkit绝不会为没有令牌系统的项目引入令牌系统——这是构建工具的决策，而非文档决策。
令牌来源同步方式
Tailwind使用官方
export --format json-tailwind
或
css-tailwind
命令
纯
:root
自定义属性		直接写入——
css-tailwind
会导出v4版本的
@theme
块（包含自定义属性），因此只需转录而非转换
SCSS映射、CSS-in-JS、WordPress 
theme.json
使用
export --format dtcg
命令，然后使用Style Dictionary等转换工具处理
关键在于转换而非框架适配：若官方导出工具已支持对应格式，designkit直接写入；若需要真正的转换，designkit导出DTCG格式并说明使用的工具。自行编写的转换工具会在任一格式变更时失效。

Degrade loudly

降级提示

No 
npx
, no network, or no CLI is a normal condition, not an error. Extract and write from the fallback schema above, skip lint and export, and name the gap in the same breath as the result:
Wrote 
DESIGN.md
(12 colors, 6 type styles). 
lint
not run — no 
npx
available. Schema from the bundled 
alpha
fallback captured 2026-08-06.
Never claim validation that didn't happen. A file reported as clean when nothing checked it is worse than a file reported as unchecked.
No filesystem at all (a browser-based agent)? Print the finished 
DESIGN.md
as a fenced block labelled with its path, describe the swatch sheet rather than writing it, and name the commands the user should run themselves.
无
npx
、无网络或无CLI是正常情况，而非错误。使用上述备用模式提取并写入内容，跳过校验和导出操作，并在给出结果的同时说明缺失的功能：
已写入
DESIGN.md
（12种颜色，6种字体样式）。未运行
lint
——无
npx
可用。使用的是2026年8月6日记录的内置alpha版本备用模式。
切勿声称未执行的验证操作。报告为合规但未经过检查的文件，比报告为未检查的文件更糟。
完全无文件系统（如基于浏览器的Agent）？将最终的
DESIGN.md
作为带路径标记的代码块输出，描述样本表而非写入，并说明用户应自行运行的命令。

Notes

注意事项

  • The grounding rule outranks completeness. A sparse, honest file beats a full, invented one. When the choice is between omitting a scale and guessing at it, omit and say so.
  • Consent by operation. The 
    init
    proposal, new sections, deletions, and any token sync all ask. Edits to existing tokens in 
    update
    don't — they're bounded by the restraint rule and land in a reviewable diff. 
    audit
    asks for nothing, because it changes nothing.
  • Report warnings, never suppress them. If a lint warning survives, it goes in the report with the reason it was accepted.
  • Existing project convention wins. A repo with its own token names, its own file location, or its own design-doc layout gets followed — and designkit says which convention it followed.
  • The spec is alpha. Sections, schema keys, and rules move. Read them from the CLI at run time; when the bundled fallback is what ran, say so.
  • Prose is for rationale, tokens are for values. An agent needs the hex, not the story behind the hex. Keep prose to what a token can't carry: intent, and when not to reach for something. For a general pass over that prose, humankit when installed.
  • 核心原则优先于完整性：稀疏但如实的文件比完整但虚构的文件更有价值。当选择省略某个梯度还是猜测时，应选择省略并说明情况。
  • 操作即确认：
    init
    模式的方案、新增章节、删除操作以及任何令牌同步都需询问用户。
    update
    模式中对现有令牌的编辑无需询问——这些操作受约束规则限制，且生成的差异可被评审。
    audit
    模式无需询问任何内容，因为它不会修改任何内容。
  • 报告警告，切勿隐瞒：若校验警告未被修复，需在报告中说明接受该警告的原因。
  • 现有项目约定优先：已有专属令牌名称、文件位置或设计文档布局的仓库，需遵循其约定——designkit需说明遵循的约定。
  • 规范处于alpha版本：章节、模式键和规则仍在变化。运行时从CLI读取规范；若使用内置备用模式，需说明情况。
  • 文字用于说明理由，令牌用于存储值：Agent需要的是十六进制颜色值，而非颜色背后的故事。文字仅用于令牌无法承载的内容：意图，以及何时不应使用某项内容。若需对文字进行通用优化，已安装humankit时可使用该工具。",