用途:为 Astro 站点生成设计系统 CSS,校验分层设计令牌,并保留类型化别名与浅色、深色两种模式。
输入:读取 design-system.json、paths.json、已生成的 CSS、清单文件以及令牌使用方。若实际路径与示例不同,使用 .astrofy/config/paths.json 中定义的路径。应用在线文档中的 API 前,先核对 lockfile 与 node_modules 中的已安装版本。
执行:该文件是 Astrofy 信封格式,使用 DTCG 2025.10 令牌。按类型在各模式下解析别名。覆盖项只能修改已存在的令牌,不新建路径、也不改变其类型。对原始值与语义函数建模,检查两种模式中已有的覆盖项。依次执行 tokens validate、tokens build --dry-run 和 tokens build,对比 CSS 与清单,并检查使用组件。
推荐顺序:先校验 JSON 中的类型、单位与别名,再生成 CSS;整理基础、语义与组件令牌;仅在会随模式变化的令牌上应用覆盖;连续生成两次 CSS 并比对输出后再接入站点。
改造现有实现:将当前颜色映射到原始值与语义函数,逐个迁移使用方,用 CLI 生成 CSS 并比较字节与外观,保持 JSON 为可编辑来源。
验证:循环别名必须在生成前失败;修复后,两次生成需产出相同字节,且 tokens check 有效。生成具有确定性:别名不成环、类型得以保留,tokens check 确认同步。命令:astrofy tokens check。实现前请查阅该领域的 API 与规则,并在核对输出时参考验证场景。