# @design-parity/diff 中文文档

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

版本：1\.18\.0
npm 元数据更新时间：2026-11-07T13:54:48.341Z
中文译文更新时间：2026-11-12T02:04:20.395Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：272 kB，62 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2026-06-14T05:42:40.500Z
- 最新版本发布：2026-11-07T13:54:47.971Z
- 近 30 天下载量：3724（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：102（近 12 个月 102 个）

## 中文简介

Source-anogistic diff引擎:先消耗一对(设计参考,ConferentRender)并放出一对确定性的判罚——a11y + i18n先,再象征性地遵守,再视觉diff.

## 安装

```sh
npm install @design-parity/diff
```

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

## README

# @ design- parity/ diff (英语)

来源不可知的diff引擎. 假设a `(DesignReference, CandidateRender)` 配对——来自任何适配器和候选的渲染器,并发射定型器 [`Verdict`](https://npmcn.com/package/%40design-parity/core/src/types.ts)、减记摘要和 参考/candidate/diff 每个图像的三进制.

人数 [文件/文件](https://npmcn.com/package/docs/PRINCIPLES.md): 引擎运行 **仅限 承诺、决定性规则/配置——运行时无模式呼叫**,则 判决 **a11y + i18n 的线索**,然后表示遵守,然后原始视觉 d.

## 使用

```ts
import { diff } from "@design-parity/diff";

const { verdict, summary, triptychs } = await diff(reference, candidate, {
  repoRoot,          // image `uri`s resolve against this (default: cwd)
  outDir: "out",     // optional: write triptych-<key>.png here
  // config: { spacingTolerance: 0, pixelThreshold: 0.05, ... },
  // checksConfig: { contrastLevel: "AAA" },  // a11y/i18n thresholds
  // checks: myProvider,   // swap the default @design-parity/checks provider
});
```

`verdict.status` 实值 `pass | warn | fail` (任何项目) `error` 发现 qq `fail`(b) 调查结果 命令为11y / 符号 / 语义 / 视觉 ; `verdict.visualScores` 每个地图 `state/theme/size` 键到其不同的像素分数.

## 尺寸

-   **a11y + i18n 键** 授权 [`@design-parity/checks`](https://npmcn.com/package/%40design-parity/checks) (第10号) 通过a [`ChecksProvider`](https://npmcn.com/package/%40design-parity/diff/src/checks.ts) 接合: WCAG 对比, 触摸 目标、语义角色/标签和i18n风险. `defaultChecks` 连接真实的 软件包; 插入自定义提供者( 或 `checksConfig`),以推翻.
-   **合规情况** - 平整候选人的花花样,并与 参考谱: 数字符号 尊重承诺的容忍度,打字 匹配, 颜色匹配 modulo 的全 alpha 后缀( 具有相同的作用) 值倒计时)。 当设计和代码符号词汇表不同时, a `design-map.json` `tokens` 化名(代码-名称-设计-名称) 首先提及代号,例如设计 `color/on-surface` 线条 代码 `onSurface`。 。 。 .
-   **设计系统** ——全表审计:参考解析符号表 (单位:千美元)`DesignReference.themeTokens`,例如Figma变量 + 类型坡道)对 代码解析的主题( n)`SemanticTree.themeTokens`),通过同一键 别名。 覆盖颜色(模式意识)、类型坡道(精确、光谱驱动)和 数字 `radius`编号 :`spacing` (在承诺的容忍范围内)。 类型 和形状/相距名称首先通过别名,然后通过物质作用来决定 它们表示(`Body/Large` → `bodyLarge`, (中文(简体) ), `radius/medium` → `medium`) (中文(简体) ). 调查结果 携带 `detail.scope: "design-system"` 所以管弦乐师报告每个漂移 一次运行,不是一次每个屏幕.
-   **语义** ——主题覆盖和结构(作用/标签)三角洲.
-   **视觉** – 每像素 diff通过 `pixelmatch`加上三脚架 一个向量 引用以候选人的宽度为光线,对齐对齐 左上方,所以候选人的框架很重要: `Image.gutter` 已裁剪 首先关闭, 和回波, 其渲染器捕获 在固定帆布 `.design-parity.json`是因为 `visual.candidateFrame: "crop-to-content"` 用于裁剪 可选内容——仅针对其内容本身的参考文献 到达每一个边缘,所以一个有指定透明比值的引用是: 仍作整体比较`DiffConfig.visualCandidateFrame`) (中文(简体) ).

所有事情都经过了配置(参见: [`config.ts`](https://npmcn.com/package/%40design-parity/diff/src/config.ts)页:1 两人总是做出同样的判决.

## 已知差异的范围

为任何需要消耗的视觉配对通过精确目录范围 `.design-parity/known-differences.json`数字 :

```ts
const result = await diff(reference, candidate, {
  repoRoot,
  knownDifferences: {
    scopes: {
      "default/light": {
        system: "m3",
        component: "IconButton/Tonal",
        previewId: "iconbutton-tonal__ideal__default__light",
        referenceId: "iconbutton-tonal-ideal-light",
        variant: "ideal/default/light",
        overrides: {},
        referenceSha256,
      },
    },
  },
});
```

地图密钥是相同的 `state/theme/size` 键 `visualScores`范围是: 明确,因为这些目录身份无法从 源代码手柄. `result.acceptances` 报告 `raw`, (中文(简体) ), `accepted`,以及 `unaccepted` 加上每个记录的状态 原画 `verdict.visualScores`,视觉发现,和 三脚架没有变化: 差异绝不删除原始查找.

仅 `valid` 口罩进入得分联盟. 门评估之前,工会, 并且两个输入在重新复制前被分割,所以一个解析/失效的口罩 无法压制相邻像素, 接受的三角洲无法取消一个 在面具边缘反向回归.

## 开发

```sh
npm run build --workspace @design-parity/diff
npm test --workspace @design-parity/diff
```

## 常见问题

### @design-parity/diff 是什么？

Source-anogistic diff引擎:先消耗一对\(设计参考,ConferentRender\)并放出一对确定性的判罚——a11y \+ i18n先,再象征性地遵守,再视觉diff\.

### 如何安装 @design-parity/diff？

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

### @design-parity/diff 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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