展开本页目录
开始前准备什么
- Node.js与npm已可运行；练习只需本地文本文件和官方@google/design.md CLI，不需要Stitch账号或付费生成。
- 固定当前CLI版本并保留版本号；DESIGN.md仍为alpha格式，升级前先在练习副本复核。
- 本课给出作者自制规则文件和预期，不把预期JSON冒充已执行的官方CLI返回。
- 列清要交换的token
- 运行源规范校验
- 导出标准交换文件
- 检查值与类型对应
- 做一次消费端读取
- 比较错误类型反例
- 交付交换范围说明
1. 列清要交换的token
准备primary、surface和radius-sm三个规则项，另列组件使用关系。
本课只交换设计token，不把交互流程或布局HTML塞进token值。
2. 运行源规范校验
先lint源文件，核对引用和尺寸格式。
出现坏引用时先修源规范，不在导出的JSON里补一份临时颜色。
3. 导出标准交换文件
运行designmd export --format dtcg DESIGN.md，保存tokens.json。
保留原始输出与CLI版本，后续处理另存副本。
官方界面与功能位置
以下为官方文档配图，具体版本与账号入口以当前产品为准。本课练习输入与验收对照见相邻步骤。
4. 检查值与类型对应
逐项核对颜色值、尺寸单位和导出类型字段，确认没有把8px写成普通字符串备注。
引用的表示形式以当前实际输出为准，不假设所有发射器都保留完全相同的字面写法。
5. 做一次消费端读取
运行python3 check-consumer.py tokens.json，按consumer-map.json核对primary、surface与rounded.sm三行；这是作者项目门槛，非官方CLI或完整DTCG验证器。
解析失败要保留原异常，不用截图看起来相近代替机器读取成功。
6. 比较错误类型反例
分别运行包内negative-type.json、negative-unit.json、negative-reference.json，核对作者检查器的实际非零退出与错误路径；正例及三负例的真实stdout和退出码见consumer-check-receipt.json。
不要擅自把负例接受结果说成官方支持该类型。
7. 交付交换范围说明
同时提供规范、tokens.json、类型核对表和一个消费端示例。
本课0.4.0实测DTCG包含颜色、圆角、间距和部分typography，但没有源lineHeight=1.6；必须另记导出缺项，不能承诺完整往返或完整UI页面。
下载本课材料并开始操作
练习包包含本课的具体输入、可编辑数据、正反样例与七步说明。index.html 可离线查看原件和验收参考，actual-results.csv 用于记录你实际操作后的结果。
怎样确认已经完成
- 颜色与尺寸的导出值和类型可以逐项追溯。
- 下游实际读取记录与原始tokens.json保留。
- 交付说明不声称DTCG包含完整UI页面。
- 0.4.0导出未包含lineHeight的边界被明确记录。
常见问题
DESIGN.md导出DTCG以后，页面也会一起带走吗？
先校验源规范，再用 export --format dtcg 保存 tokens.json，逐项检查颜色、尺寸的 $type、值与引用。让下游实际读取同一语义值；token 交换文件不是设计稿截图，也不自动修复源规范。
下游工具显示错了，直接改tokens.json行不行？
先查源规范和发射器的映射，再看消费端是否支持相关类型。需要临时转换时另存适配副本，保留原始输出，否则下次重新导出会覆盖手工补丁。