# @design-parity/catalog-export 中文文档

规范地址：https://npmcn.com/package/%40design-parity/catalog-export/

版本：1\.18\.0
npm 元数据更新时间：2026-11-07T13:53:38.084Z
中文译文更新时间：2026-11-12T01:03:20.732Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40design-parity/catalog-export
原文对照：https://npmcn.com/package/%40design-parity/catalog-export/?lang=original
项目主页：https://github.com/yschimke/design-parity/tree/main/packages/catalog-export#readme
源码仓库：https://github.com/yschimke/design-parity

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：410 kB，82 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-06-23T14:20:37.976Z
- 最新版本发布：2026-11-07T13:53:37.723Z
- 近 30 天下载量：9145（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：82（近 12 个月 82 个）

## 中文简介

将制成的编译元件系统(编译-审查数据产品)转换为可导入的设计-艺术目录:每个元件贴纸单分两个变体(理想+布局),W3C DTCG符号集,以及无障碍的"绿线"注释层-l

## 安装

```sh
npm install @design-parity/catalog-export
```

也可以使用：`pnpm add @design-parity/catalog-export`、`yarn add @design-parity/catalog-export`、`bun add @design-parity/catalog-export`

## README

# @ design- parity/ catalog- 导出

转出一个完成的作曲 **组件系统** 可导入 **设计艺术 目录** ——代码 设计-工具方向 设计-平等.

其余设计均等证明 公关与设计是等同的 软件包走另一条路:它需要整个组件系统(组成 M3, 穿戴) 由上游制成 M3, 闪光, 闪光,.. [`compose-preview`](https://github.com/yschimke/compose-ai-tools) CLI,还有 它是一个 **标签页** 设计者可以导入到Figma,Google Stitch,或者 克劳德设计公司.

输油管是 **代码引导**: 每个值来自渲染器自己的数据 产品,所以目录通过构建是正确的. 已出版设计包 种子/仅参考——见 [`docs/design-artifacts/REFERENCE_KITS.md`](https://npmcn.com/package/docs/design-artifacts/REFERENCE_KITS.md)。 。 。 .

## 产生的东西

对于每个组件,按其主模式(状态×主题×大小):

-   **两个变体** - 那个 `ideal` 制作(捕获PNG)和 `layout` 转让 `compose/semantics-wireframe` 边框视图, 因此绑定/ 空白 / 结构可见).
-   **绿线层** - 以下列内容为根据的无障碍说明: _问题_ 绿线来自渲染器的 a11y / 对比 / i18n 发现,以及 `info` _光谱_ 记录每个交互式节点作用并测量的绿线 触控目标大小.
-   **红线层** ——布局间距谱:每个有几何特征的节点,其 框加内容 `padding`间槽 `gap` (单位:千美元)`Arrangement.spacedBy`),以及 角半径——所以一个组件及其槽每个带可导入的框 + 间隔,不只是一张相片。 (去掉语义树,所以没有) 语义学——装饰性图标——没有框;全插槽覆盖是一个 渲染器侧后继. )
-   **符号集** - 系统解决了 `colors` 编号 : `typography` 编号 : `radius` (形状),出口为W3C **技术合作组** 文件加一个 **图集变量** 投影(浅/暗作为模式).
-   **来源身份** - 每一个构象都保留了完全合格的构图 `previewId` 这导致了它。 这是每个图像, 所以单独的光/暗或 状态预览仍可通过机器解析 `design-map.json` 即使当 该目录使用更友好的组件 id.

磁盘捆绑是超级组合 `@design-parity/adapter-bundle` `manifest.json`,所以通过平分流返回目录.

## 使用

```ts
import {
  buildCatalog,
  writeCatalog,
  type ComponentSource,
} from "@design-parity/catalog-export";

// `sources` are normalized via @design-parity/candidate's data-product mappers
// (nativeFindings, semanticsToSemanticTree, composeThemeToTokens).
const catalog = buildCatalog(
  { system: "compose-m3", title: "Compose Material 3" },
  sources satisfies ComponentSource[],
);

await writeCatalog(catalog, ".design-artifacts/compose-m3", {
  sourceRoot: "build/compose-previews",
});
```

输出 :

```
catalog.json            # the index: provenance, components, variants, greenlines
tokens.dtcg.json        # the system token set (W3C DTCG)
themes/<theme>.dtcg.json # one per alternate named theme, when the system declares any
figma-variables.json    # Figma variable-collection projection
images/<component>/<variant>__<state>[__theme][__size].png
```

### 备选主题

`tokens.dtcg.json` 这是 **系统** 符号集: 解决的主题 贴纸在下面 宣布交替主题的系统——作曲 `@ThemeCatalog` 编号 : `@WearThemeCatalog` 提供方 (Brand Light, 高对比度, a) 守望相机的夜间调色板)——有多个相机,它们完全不同於: 符号集描述的方式: 颜色, 也常常是类型面, 因为主题是 自由交换类型缩放.

传为 `buildCatalog`第四个论据(或 `catalogFromCandidates`' `themes` 选项),每个选项都作为自己的 DTCG 文件在 `themes/`列表 在仪表上

```jsonc
"tokensFile": "tokens.dtcg.json",        // still the system token set
"themes": [
  {
    "id": "com.example.BrandDarkThemeCatalog",  // the provider FQN
    "name": "Brand Dark",
    "dark": true,
    "tokensFile": "themes/com.example.branddarkthemecatalog.dtcg.json"
  }
]
```

他们是 **从不解开** 路边 `themeTokens` 编号: a 组件的语义性记录了它提供的一个主题,所以 发电机——它知道哪一个部件属于哪个申报的主题——用品 他们。 这包括: `dark`: 生成器持有由渲染器组成的表面 每一个标本,所以它回答一次在这里 而不是让每个消费者 把它从调色板上弄出来 并不同意。 缺席 _不详_不轻。 空的代号或空的指针集的主题被丢弃而不是 作为消费者可以选择和找到的东西 后面什么都没有,以及 重复的 id 保留它的第一个条目.

这个 `id` 是提供商FQN,因为这是预览服务器的 `?theme=theme:<providerFqn>` 深度链接已经命名, 这样消费者就可以加入 页面显示的主题的这些符号没有第二次映射。 这是 任何想要显示主题的东西 **实值** 而不是所谓的——一个用主题本身的颜色所绘取的芯片 和打字机,每组主题图像变量模式,每组图像的对比性审计 以系统船为主题——需要指使符,重新交付以收回它们就是 这种导出是用来避免的 .

`figma-variables.json` 保留投影 **系统** 仅设定符号 : 风扇每个主题是一个变量 -_模式_ 由进口商回答的问题, 这里没人能猜到.

## 版式

| 模块 | 作用 |
| --- | --- |
| `types.ts` | 这个 `Catalog` 编号 : `CatalogComponent` 编号 : `Greenline` 型号. |
| `ingest.ts` | `buildCatalog` 编号 : `buildComponent` 从正常输入. |
| `greenlines.ts` | 发现 + 语义 → 绿线注释层. |
| `redlines.ts` | 语义 → 红线 (放出) 注释层. |
| `annotations.ts` | 红线+打字机 + `compose-preview-annotations/v1` 显出. |
| `parityFindings.ts` | 跑步判决 `compose-preview-parity-findings/v1` 显而易见的是,每个发现都集中在该地区. |
| `manifest.ts` | 纯洁 `catalog.json` 建设者(仅路径,无I/O). |
| `figma.ts` | `DesignTokens` • 图片变量集. |
| `write.ts` | 一步一步:实现捆到盘. |

仅取决于 `@design-parity/core`。 。 。 .

## 平等判决`parity/findings.json`(中文(简体) )

上面的注解层 说每一边 **实值**。还需要进行比较 跑这么快 **结 论** - 标签一旦本地化, 粘贴是 24,spec声称16, 这两条框架从不可比——和 注释和视觉分数都无法得出:注释报告 以及一个百分比移动 相同,用于补丁变化和颜色变化.

这么说吧 `parityFindings.ts` 运行项目 `Verdict`进入 `compose-preview-parity-findings/v1`,以 id 键入预览服务器路径 与每项判决相对照并按参照范围进行. `writeCatalog` 来电者过后写下 `parityFindings` - 一个简单的贴纸表导出 没有判决,没有写作, 和运行,它的组件全部 通过了.

有趣的是,这一半 **锚**:一个发现必须说它在哪里,在 每个面板的自有像素空间,或者服务器只能将其打印为道具. 调查结果 上面没有几何图案,所以它从已经消失的树上取回—— 所测量的复选框(`detail.bounds`,该a11y检查发出)作为 状态; a `detail.label` 用标签与每棵树匹配, 相同的匹配 `@design-parity/report-html`上面刻着 而不是一秒钟 可能不同意的规则 `token` 寻找每棵树的锚 根框,因为这是索赔的范围。 其他的都无锚 并读作传言——指错内容的突出点比 没有,因为读者没有办法告诉.

## 注释层和他们所许下的诺言

比较页画出两个附加说明的栏目——渲染(`previews`)和 设计参考`references`)——从同出行相去相去相去 两种标签在规格上是不同的,而不是在每一边是如何的 测量。 两个属性都保持这个真实性,两者都可见于输出中:

-   **单位.** 裁决 `dp`编号 :`sp`; 设计会报告自己的像素. 一棵树,背着一棵 `density` (source px per dp) 转换为代码的 单位,以及 `detail` 记录 `density` + 键 `sourceUnit` 所以原始号码是 可收回来。 无密度的一棵树有它自己的单位命名(`text 52.5px`(中文(简体) ) 而不是猜测——引用一款3×板的像素为: `sp` 将发明一种 3个差异.
-   **证相.** 间距来源 _已声明_ 是一个Spec。 间距测量 儿童几何——手放(非自发放出)设计框架如何实现 排版层 – 是观测, 前缀 `≈` 标签和标签 `detail.spacingSource = "derived"`。 。 。 .

## 常见问题

### @design-parity/catalog-export 是什么？

将制成的编译元件系统\(编译-审查数据产品\)转换为可导入的设计-艺术目录:每个元件贴纸单分两个变体\(理想\+布局\),W3C DTCG符号集,以及无障碍的"绿线"注释层-l

### 如何安装 @design-parity/catalog-export？

在项目目录运行 npm install @design-parity/catalog-export，或使用 pnpm add / yarn add / bun add。

### @design-parity/catalog-export 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @design-parity/catalog-export 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @design-parity/catalog-export 可以商用吗？

@design-parity/catalog-export 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @design-parity/catalog-export 的下载量有多少？

根据 npm 官方下载统计，@design-parity/catalog-export 在 2026/10/12 – 2026/11/10 这 30 天内被下载 9,145 次，日均约 305 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @design-parity/catalog-export 还在维护吗？

最新版本 1\.18\.0 发布于 2026/11/07（4 天前）；至今共发布 82 个版本，其中过去 12 个月发布了 82 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。