# @design-parity/kit-index 中文文档 规范地址：https://npmcn.com/package/%40design-parity/kit-index/ 版本：1\.18\.0 npm 元数据更新时间：2026-11-07T13:54:59.182Z 中文译文更新时间：2026-11-12T06:42:56.189Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40design-parity/kit-index 原文对照：https://npmcn.com/package/%40design-parity/kit-index/?lang=original 项目主页：https://github.com/yschimke/design-parity/tree/main/packages/kit-index#readme 源码仓库：https://github.com/yschimke/design-parity ## 关键信息（来自 npm 元数据） - 包体积（解压后）：274 kB，43 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：3 个 - 首次发布：2026-08-15T10:11:35.068Z - 最新版本发布：2026-11-07T13:54:58.889Z - 近 30 天下载量：2767（2026-10-12 至 2026-11-10，npm 官方下载统计） - 已发布版本数：57（近 12 个月 57 个） ## 中文简介 工具包词汇 设计地图 解决变体 对照: 走设计工具包的页面, 将引用的组件组合成承诺的工具包索引, 将目录变量 knob 解决到工具包的确切节点( 变量轴、 组件属性或配置) ## 安装 ```sh npm install @design-parity/kit-index ``` 也可以使用：`pnpm add @design-parity/kit-index`、`yarn add @design-parity/kit-index`、`bun add @design-parity/kit-index` ## README # `@design-parity/kit-index` 设计包是自己的 **词汇**如此的目录 6个变体的组件可以说明6个变体中每个变体的哪个是工具包节点 相反,没有人手持这份清单. ## 问题 A 类 `design-map.json` 条目将代码组件绑定为 **一个** 设计节点 : ```jsonc { "code": "ui/Button.kt#FilledButton", "source": "figma", "ref": "figma:AbCdEf/57994:2324" } ``` 这完全正确,对于对等 diff,而不足以为组件 生成多个变体。 描述目录 `Button` 3个大小和 两个形状有6个调子和1个调子, 没有说明哪一个套件节点 其他五个属于。 用手来想象它们,就是地图配置的扩展a 设计图的存在是为了避免——它静悄悄地漂移在工具包获得时 变量,因为缺少的条目读作 _"没有对应的装备"_ 相当 比起来 _"没有人看"_。 。 。 . 因此,这个包 来源于工具包本身的出版. ## 输油管 ```text design kit │ dump ── walk every page, deep ▼ figma-inventory.json disposable, megabytes │ build ── keep only what design-map.json references │ + fetch the component properties the walk cannot see ▼ figma-kit-index.json COMMITTED, tens of kilobytes │ resolve ── project a code knob onto it ▼ { nodeId, name } ``` 只有两代的台阶触动网络 两者都是故意的 "更新词汇"操作 登陆一个承诺 一个审查者可以看到. **解析度与承诺指数相悖,从不使用活套**,因此,对等 运行报告对每个人都一样 不需要设计工具的证书. ## 代码边从哪里来 地图及其变种声明 **来源于 说明** 而不是写作。 那半个住在上游 [`compose-ai-tools`](https://github.com/yschimke/compose-ai-tools),因为 它所读的每个字段(`@CatalogComponent(reference = …)`, (中文(简体) ), `@CatalogVariant`, (中文(简体) ), `@OverrideVariant`)是在那里定义的——它止于设计时 工具包的词汇需要: ```text previews.json │ emit-design-map.mjs compose-ai-tools: knows the ANNOTATIONS ├──▶ design-map.json base refs, one per component └──▶ design-map-variants.json "same component, these knobs turned" — (compose-preview-design-map- unresolved, because `size=l` is a variants/v1) Compose fact and `Size=Large` is a │ kit fact │ design-parity-kit-index resolve THIS PACKAGE: knows the KIT ▼ design-map.json with a tagged ref/previewId pair per variant ``` `resolve` 只读已承诺的文件,所以与 `dump`编号 :`build` 它需要没有 证书,在每个建筑上都是安全的: ```console $ design-parity-kit-index resolve Wrote design-map.json: 1 variant reference(s) across 1 component(s). 1 variant(s) are a component PROPERTY in the kit, not a variant beside it. A definition node renders at the defaults, and no exact configured instance was indexed for these values, so they remain unpaired: - Button/Filled / true (icon=true) — Button: `Icon` (INSTANCE_SWAP, default "54616:25409") 1 reference(s) draw optional content by default. Every render made from them includes it, so a sticker that leaves it out is compared against something it never claimed: - Button/Filled — Button: `Show icon` ``` 三种错失的报告是分开的,因为他们的主人不同:a 变换工具包模型 **绝对不行** 是一个真正的空白; a **属性形状** 一个 意思是这个工具箱有它,一个节点的参考点就是不能要求它 **默认内容** 表示已解决但绘制多于代码的引用 对 把它们拼凑在一起 就会把退休的图案看成是疏忽. `--check` 把它变成一个漂移的大门 而不是一个作家。 A 类 **碰撞** - 两个 解析到一个节点的预览被断然拒绝( exit 2, 无写入) : 相同的节点不能既是预览的对应点, 也可以是一幅这样写的地图 要求二人之一的 diff 报告是错的. 一种情况不是碰撞: **明确要求**种子全名的变种 他们的套装财产完全`kitAxis` + 键 `kitValue`,哪个 `@OverrideVariant(kitProps = …)` 写入) 从预览中取出一个单元格 是通过翻译达到的,无论是基础预览还是隐含的变体. 因此,在一个状态下绘制的工具包单元格无法被捕获(a) 焦取出第一个项目,如)与驱动它的变体相配. 插槽保留着 校正并标记, 只更改其预览 。 每件索赔都作了报告,第二件索赔则作了报告 对同一个牢房的明确索赔仍然相互碰撞. ## 三种变异——只有两种是可以解决的 | | 这是什么 | 可以吗? | | --- | --- | --- | | **变位轴** (单位:千美元)`Size=Large`(中文(简体) ) | 一个有自己身份的兄弟姐妹节点 | 直译: | | **构成部分财产** (单位:千美元)`Show icon`(中文(简体) ) | 节点上的开关 | 只通过一个实例 | | **间隔/ 实例交换** | 一个区域,或哪个子组件的巢 | 从来没有 | 中行是静静地毒害等分结果的一行. `GET /v1/images` 在其 **属性默认**,而一个引用是一个节点代号 无处可挂 覆盖。 所以一个工具箱 `Button` 默认 `Show icon` 改为 `true` 为名称只表示的变体创建图标+标签引用 `Type=Round, Size=Small` 仅标有标签的代码显示 缺少图标 _代码_ 错了. 出路不是改变装备 是有人已经放过 实例页,以及 **那个实例的节点 id 是属性空间点的可渲染的控点 表达式**。 。 。 . `resolvePropertyInstance` 找到它, 匹配 _整体_ 属性 矢量,所以一个接近的失分 从来没有像一个精确的. 第三行是故意不放过. `leading=icon` 说内容 _表示_绝不是哪个节点能供给它 提到错误的事情. ## 支配规则 > **一个错误的翻译必须无所作为,而不是产生自信的坏 参考文献.** A 项下 `design-led` 一个错误的引用驱动 代码远离工具包 它正在复制,同时报告一个干净的对等结果,即: 现有最坏的结果。 每个未解决的种子被浮出水面作为未解决. 表面 _有个原因_但是,因为"没有对应的包"是真实的 几乎无一幸免. `resolve` 每个都分类 (单位:千美元)[`explainUnresolved`](https://npmcn.com/package/%40design-parity/kit-index/src/resolve.ts): | 原因 | 这是什么意思 | 怎么办 | | --- | --- | --- | | `… declares a kit axis/value the set does not publish` | A 类 `kitAxis` 编号 : `kitValue` 此集没有的名称 | 修正声明——原因列出该套出版物 | | `the reference already draws this` | 基准变体携带每个种子值——渲染物重复参考 | 没什么 不是空档. | | `each of … exists, but no node carries them together` | 这两个值都是真实的;工具包的矩阵跳过它们的相交点 | 这里什么也没有, 包必须画出细胞 | | `no counterpart for …` | 这些种子完全没有对应物 | 实际铅: 映射值, 或接受空格 | 第三列为分. 在一个真正的目录上,它变成了 `error-unselected (state=unselected, status=error)` - 在哪个地方 `state=unselected` 以自己的方式完全解决 `no counterpart for status=error`, (中文(简体) ), 拦住两个 `size=small` 使当 参考文献 _实值_ 小变体. ### 当表格无法到达时:命名工具箱自己的拼写 一些没有翻译的值 。 3号材料包拼出一个取枣人 变体 `Type=Full-screen (range)`; 目录种子 `type=range` 决定: 无所事事,而且——在以上理由表之前——默默无声地放弃了 比较中的节点. 工作比问题更糟糕:种子 `type=full-screen (range)` 在克特林, 和一个包 拼写,括号和所有, 成为目录来源中的负载, 下次套件会腐烂 重命名一个值. 因此,一个种子除了自己的外,还可以携带包名: ```ts resolver.resolveVariant("figma:AbCdEf/53977:33595", { key: "action", raw: "longer", // what the Compose knob is called kitAxis: "Configuration", // what the kit calls the axis kitValue: "Text & longer action", // …and the value }); // → { nodeId: "53977:33576", name: "Configuration=Text & longer action, …" } ``` 三个属性值得了解: - **权威而非暗示.** 声明 _替换_ 表格的别名 那个种子. `size=l` 自行决定罚款; `size=l` 声明 `kitAxis: "Sise"` 决定: **无**倒地会打字 与正确的声明无法区分. - **仍然检查与工具包.** 宣布的轴或值必须是 因此,执政规则是: 没有人能宣布他们 到节点的方法 工具包不绘制。 他们得到的是 `declared` 上面的原因, 命名错失的拼写 和集的出版内容. - **在任何剧本中都无标注或大小写匹配.** `of lines` 发现 装箱 `# of lines`; 声明轴不应是打字工作。 仅 分隔器和分音符被忽略了——一个将轴归档为 `サイズ` 财务报告和审定财务报表 `状態` 在别处使用的涕丸正常化时,保持它们的差异 既去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去. 同一准确性适用于申报的任何地方。 已宣布名称到达 (单位:千美元) **组成部分财产** 与轴线一样容易——两个工具箱中的哪个是 它自己的生意,但它必须是财产的真名,所以 `kitAxis: "focus"` 不再通过 `Show focus indicator` 键的方式 `focus` 已经 打开 家庭 工具箱模型为 **文件夹兄弟姐妹** 而不是一套,一个宣布 值名 兄弟姐妹直截了当(`Middle-inset`,而不是 `Inset` 即将到来的人 搜索将会发现) _轴_ 拒绝:没有轴 名称。 并检查已声明的另一种子在轴上的声明 通过与任何其他人相同的聚变规则—— `Type=Selected` 外加一个声明 `Error unselected` 宁可默默地抛弃第一个 种子 . 任意一个字段都可以单独给出:只有 _名称_ 不同,一个 单值,只有拼写才有. 一种情况是,一项声明蓄意无法达到: **两个种子相接一个 写入空格的脚本中的值**。核聚变规则问: 公布的数值 完全说两个种子 在一起说,它答案 比较词组——和 `エラー選択済み` 是一个单一的征兆 不管字有多多 一个读者看到它。 封闭是明显的替代物,不安全: `選択` (所选)是 `未選択` (未选中),所以一个支票 建在它上 接受绘制相反状态的节点。 将语言约束从 语义核聚变需要一个分解器 这个包没有业务携带,所以 a 矢量未解决,报为未解决。 空格分隔脚本 保险丝一般,不管字母. 这个规则就是为什么 匹配比最初看起来要大惊小怪的原因 布尔轴 接受 `True` 从 _任意_ 把手,一个天真的配对者 `footer=true` 解决 改为 `Show back=True` 财务报告和审定财务报表 `supporting=on` 决心 `Leading icon=True` 两者 真实的节点, 两者都是错误的 。 因此,候选人轴必须共享a 整体 **单词** 与取号或取值相匹配的单词而不是 子字符串( e)`Leading icon` 包含 `on`) (中文(简体) ). ## 使用量 ```ts import { KitIndexResolver, loadKitIndex } from "@design-parity/kit-index"; const resolver = new KitIndexResolver(await loadKitIndex("figma-kit-index.json")); // A rendered cross-product cell — every seed must map to a distinct axis, and // the exact resulting vector must name a real sibling. resolver.resolveVariant("figma:AbCdEf/57994:2324", [ { key: "size", raw: "l" }, { key: "shape", raw: "square" }, ]); // → { nodeId: "57994:2310", name: "Type=Square, Size=Large, State=Enabled" } // A property-shaped variant, paired with an instance configured that way. resolver.resolveVariant("figma:AbCdEf/57994:2324", { key: "icon", raw: "false" }); // → { nodeId: "…", name: "State=Enabled (configured instance)" } — or undefined // What a reference draws whether or not the code asked for it. resolver.defaultedContent("figma:AbCdEf/57994:2324"); // → [{ name: "Show icon", setName: "Button" }] ``` 解析器拿走索引 **对象**而不是一条路,它是一个坚定的文物 呼叫者已经读取了, 可能是从捆绑、缓存或测试中读取 fixture — 从工作目录读取固定文件名的解析器 在一个过程中无法使用两次,或者在没有真正工具包的情况下无法进行测试. ## 国 际 ```console $ export FIGMA_TOKEN=figd_… $ design-parity-kit-index dump --file AbCdEf --depth 8 31 page(s) in AbCdEf [1/31] Buttons (11:1833): 42 component(s), 0 hidden-variant example(s), 7 configured instance(s), deepest 6 … $ design-parity-kit-index build --file AbCdEf Wrote figma-kit-index.json: 55 set(s), 1284 variant(s), 6 hidden variant render alias(es), 43 standalone component(s), 3 specimen node(s), 38 set(s) carrying component properties, 61 configured instance render handle(s). $ design-parity-kit-index validate figma-kit-index.json is a valid kit index. $ design-parity-kit-index resolve --check # CI: fail if the committed map drifted design-map.json is up to date. ``` 两步而不是一步,因为它们失败不同: `dump` 是昂贵的 整个文件的行走,其输出是可支配的; `build` 这是便宜的 当设计图仍在变化时, 投影值值会重新运行 . `build` 无符号的降解——写一个没有属性词汇的索引,以及 这么说.. `validate` 永远不要接触网络. ## 词汇 Knob 轴和值 spelling 表格是数据,而不是逻辑,默认 与3型材料包相接。 装入变体的套件 不同的供给覆盖, 每个密钥合并, 因此重命名一个轴 但不表示重复其他30个: ```ts new KitIndexResolver(index, { vocabulary: { axes: { density: ["Density", "Compactness"] } }, }); ``` `resolve` 读取相同的形状从一个 **`kit-vocabulary.json`** 索引旁边 ——在出现时自动取出,或以下列方式命名: `--vocabulary`数字 : ```jsonc { "axes": { "density": ["Density", "Compactness"] }, "values": { "cosy": ["Comfortable"] } } ``` 这个文件是存在的,所以一个目录可以学习一个工具箱的拼写,而不使用 等待这个软件包的发布. 只有 _图表_ 生活在那里——一个规则 关于数值的匹配方式(多字相配、引信轴) 搜索)是逻辑,属于这里可以测试的地方. ## 文件 `figma-kit-index.json` 实值 **生成** ——再生出它,从不手剪. 这个 对照 [`schema/kit-index.schema.json`](https://npmcn.com/package/%40design-parity/kit-index/schema/kit-index.schema.json) 满载, 对于生成的文件来说,它比手写文件更重要:无人 校对 半写索引失败 无法作为解析器 没什么. ## 常见问题 ### @design-parity/kit-index 是什么？ 工具包词汇 设计地图 解决变体 对照: 走设计工具包的页面, 将引用的组件组合成承诺的工具包索引, 将目录变量 knob 解决到工具包的确切节点\( 变量轴、 组件属性或配置\) ### 如何安装 @design-parity/kit-index？ 在项目目录运行 npm install @design-parity/kit-index，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 design-parity-kit-index，可以用 npx design-parity-kit-index 直接运行。 ### @design-parity/kit-index 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @design-parity/kit-index 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @design-parity/kit-index 可以商用吗？ @design-parity/kit-index 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @design-parity/kit-index 的下载量有多少？ 根据 npm 官方下载统计，@design-parity/kit-index 在 2026/10/12 – 2026/11/10 这 30 天内被下载 2,767 次，日均约 92 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @design-parity/kit-index 还在维护吗？ 最新版本 1\.18\.0 发布于 2026/11/07（4 天前）；至今共发布 57 个版本，其中过去 12 个月发布了 57 个；首次发布于 2026/08/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。