用途：为已有设计令牌编写参考文档，说明令牌的语义意图、使用场景与使用规则，而不只是解析值。适用于已定义令牌集；不创建新令牌、不重设计令牌架构、不校验文件结构（结构校验用 schema-validator，架构评估用 token-audit）。若仅有原始令牌（无语义层），文档价值有限，建议先建立语义层。
主要能力：按层级编写文档——原始令牌（尺度概览、来源、仅通过语义令牌引用）；语义令牌（意图、解析值、引用、使用/禁用场景、组件关联）；组件令牌（所属组件、控制的属性或状态、引用的语义令牌、是否建议覆盖）。可记录主题契约（跨主题解析、新增主题要求、回退行为），并附误用参考，标注来源或“anticipated”。
使用方式：先核对 frontmatter 中 references 路径是否存在，缺失则停止并提示按 1-INSTALL.md 重装并运行 verify-install.sh。若存在 .ds-ops-config.yml，按 knowledge-notes 配置说明加载。可自动接入 Style Dictionary/Terrazzo 解析完整令牌树、Figma 变量做交叉核对、已有文档平台避免覆盖。令牌来源格式支持 JSON、DTCG、Tokens Studio、CSS 自定义属性、SCSS、TypeScript/JavaScript、Tailwind config。若系统支持多主题，记录主题契约；文档文件通常写入 docs/tokens/ 下的 README、primitives、semantic、components、quick-reference、misuse。最后把意图写回令牌源（DTCG 的 $description、Style Dictionary 的 comment、CSS/TS 注释、Figma 变量描述），先展示 diff 并经确认再写入；仅在用户要求时生成 .ai/tokens/token-reference.json。
限制：本技能只文档化已有令牌；令牌集为空或未定义时不适用。意图若仅由名称推断需标为 proposed；误用条目非来自合规/漂移检测或用户时应标为 anticipated；“Used by”需经源码检索确认，无法确认时写“not determined”。治理字段未知时留 [TBC]。具体平台、收费、效果等未提供。