用途:为可扩展的设计令牌系统建立架构基础,定义原始(primitive)→语义(semantic)→组件(component)三层令牌层级,以支持主题化、多品牌与可维护的设计系统。
主要能力:三层架构中,原始层为无上下文含义的原始值(如 blue-500: #3b82f6),不随主题变化;语义层按用途引用原始层(如 color-primary 引用 blue-500),是唯一随主题变化的层;组件层为组件作用域令牌(如 button-bg 引用 color-primary),用于复杂有状态组件。支持深色主题覆盖(dark.json)、多品牌变体,并可输出 CSS 变量、Tailwind、JSON。
使用方式:按清单执行——审计现有值并建立命名约定,定义原始令牌,定义语义令牌,创建主题覆盖,为复杂组件添加组件令牌,配置构建输出。文件组织建议 tokens/ 下分 primitive、semantic(light.json、dark.json)、component 目录及 index.json。命名模式为 {category}-{property}-{variant}-{state},如 color-bg-primary、spacing-page。组件中应使用语义令牌,避免直接使用原始令牌。
适用场景:从零开始新建设计系统、重构现有令牌系统、添加多主题或多品牌支持、将硬编码值转换为令牌、制定令牌治理策略。简单单主题应用只需原始层加语义层;多主题需按主题提供语义层;复杂组件与多品牌需全部三层。
限制与反模式:语义层只能引用原始层,避免语义引用语义造成循环;组件中直接使用原始令牌会破坏主题化;语义命名应使用用途而非颜色外观;组件令牌过多会增加维护负担;跳过语义层将无法主题化。迁移时先审计、再建原始层、映射语义层、更新组件、最后添加主题。具体构建工具与命令资料未提供。