用途:为 Penpot 设计系统搭建并治理令牌(token)与库基础。所有下游工作都依赖受治理的令牌层,因此该技能强调先建令牌、再谈其他。
主要能力:读取令牌(penpotUtils.tokenOverview())、创建令牌集与令牌(penpot.library.local.tokens 的 addSet、set.addToken)、将令牌绑定到图形(shape.applyToken)。支持三层结构:primitive(原始尺度)、semantic(引用 primitive 的语义别名)、component(可选组件级覆盖)。可建立浅色/深色主题,也能从已有硬编码设计反推令牌系统。
使用方式:所有变更通过 execute_code 执行,用 export_shape 做视觉校验,用 penpotUtils.shapeStructure 读取结构。流程分阶段:发现(只读盘点)→ primitive → semantic → 深色模式(可选)→ 应用/反推/绑定 → 校验。每阶段设人工检查点,需确认尺度、命名与映射。脚本包括 createTokenSet.js、createSemanticTokens.js、createThemes.js、applyTokensToShapes.js、bindTokensToElements.js、inferTokensFromShapes.js、validateTokens.js。
限制与注意:applyToken 为异步(约 100ms)且按名称绑定,不可在同一 execute_code 调用中应用并读回;不可一次性批量应用数百个,需按约 25–40 个图形分块并逐块校验重试,Text/Rectangle 填充绑定最不稳定。新建令牌集默认非激活,需 toggleActive()。令牌值始终为字符串,类型字符串须用 schema 中的精确写法(如 borderRadius、fontSizes)。间距/圆角默认 4px 网格,字号默认小三度(1.2)。不得静默编造数值,新令牌须在检查点提出并经人工批准。深色模式切换需用户在 Penpot 令牌面板手动操作,插件无法持久化该切换。
适用场景:需要建立或扩展 Penpot 设计系统令牌体系、实现主题化、将现有设计令牌化的团队与设计系统工程师。