# @gitbutler/design-core 中文文档

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

版本：11\.3\.0
npm 元数据更新时间：2026-11-04T12:30:07.173Z
中文译文更新时间：2026-11-16T10:32:38.833Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40gitbutler/design-core
原文对照：https://npmcn.com/package/%40gitbutler/design-core/?lang=original
项目主页：https://github.com/gitbutlerapp/design-core
源码仓库：https://github.com/gitbutlerapp/design-core

弃用说明：Moved to packages/design-core in gitbutlerapp/gitbutler and no longer published\. Pin a commit instead: github:gitbutlerapp/gitbutler\#\<sha\>&path:packages/design-core

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

- 包体积（解压后）：357 kB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2025-10-05T22:25:41.959Z
- 最新版本发布：2026-11-04T00:04:27.877Z
- 近 30 天下载量：29719（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：111（近 12 个月 98 个）

## 中文简介

GitButler 应用程序的设计符

## 安装

```sh
npm install @gitbutler/design-core
```

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

## README

# @ gitbutler/ 设计核心

GitButler 应用程序的设计符号和字体. 这个软件包提供了CSS自定义属性,JSON格式的设计符,以及跨GitButler产品使用的网络字体.

## 安装

```bash
npm install @gitbutler/design-core
```

## 使用量

### 单项导入

获得所有东西的最简单方法——字体、CSS重置、文本公用事业和设计符号:

```css
@import "@gitbutler/design-core/core";
```

或在JavaScript/TypeScript中:

```javascript
import "@gitbutler/design-core/core";
```

### 设计托肯斯( CSS)

只导入 CSS 文件设计符 :

```css
@import "@gitbutler/design-core/tokens";
```

或在JavaScript/TypeScript中:

```javascript
import "@gitbutler/design-core/tokens";
```

这为颜色,间距,打字等设计标志提供了CSS自定义属性,并提供了自动光/暗模式支持.

### 字体

导入所有字体声明 :

```css
@import "@gitbutler/design-core/fonts";
```

或者直接引用单个字体文件 :

```css
@import "@gitbutler/design-core/fonts/inter/Inter-Variable.woff2";
@import "@gitbutler/design-core/fonts/geist-mono/GeistMono-Variable.woff2";
@import "@gitbutler/design-core/fonts/but-head/But-Head-Regular.woff2";
```

### 样式

导入单个样式工作表 :

```css
@import "@gitbutler/design-core/styles/reset"; /* CSS reset */
@import "@gitbutler/design-core/styles/text"; /* Text utilities */
```

#### CSS 重设

重置范围为 `@layer reset` 以避免与应用程序样式的特异性相冲突。 它实行下列正常化:

-   **框大小** —— 说 `box-sizing: border-box` 所有元素和伪元素.
-   **字体渲染** —— 说 `-webkit-font-smoothing: antialiased`, (中文(简体) ), `-moz-osx-font-smoothing: grayscale`, (中文(简体) ), `text-rendering: optimizeLegibility`字体大小 `html`。 。 。 .
-   **机构默认** 零垫地和边际, `overflow-x: hidden`基准值 `color`, (中文(简体) ), `font-family`, (中文(简体) ), `font-weight`,以及 `line-height` 从设计标志上取出.
-   **表单元素** —— 说 `input`, (中文(简体) ), `textarea`, (中文(简体) ), `select`,以及 `button` 剥去他们的地盘、边界、背景和遗产 `color` 财务报告和审定财务报表 `font` 从父母.
-   **标题** —— 说 `h1`– 说吧 –`h6` 有过 `margin-block` 已删除.
-   **代码前( P)** —— 说 `code` 财务报告和审定财务报表 `pre` 使用情况 `var(--fontfamily-mono)`。 。 。 .
-   **列出段落( P)** —— 说 `ul` 财务报告和审定财务报表 `ol` 有过 `padding-left` 财务报告和审定财务报表 `list-style` 删除; `ul`, (中文(简体) ), `pre`,以及 `p` 有过 `margin-block` 已删除.

#### 文本工具

文本类的范围为 `@layer text`。该图层还设置了三个字体家庭自定义属性 `:root`数字 :

| 财产 | 数值 |
| --- | --- |
| `--fontfamily-base` | `var(--font-family-base), sans-serif` |
| `--fontfamily-mono` | `var(--font-family-mono), monospace` |
| `--fontfamily-accent` | `var(--font-family-accent), serif` |

**大小类** 设定 `font-size`, (中文(简体) ), `font-weight: regular`, (中文(简体) ), `line-height`,以及 `font-family: base` 作为自足单位:

| 类 | 字体大小 |
| --- | --- |
| `.text-11` | 11px (0. 6875雷姆) (中文(简体) ) |
| `.text-12` | 12px (0. 75雷姆) (英语) |
| `.text-13` | 13px (0. 8125雷姆) (中文(简体) ) |
| `.text-14` | 14px (0.875雷姆) (中文(简体) ) |
| `.text-15` | 15px (0. 938雷姆) (中文(简体) ) |
| `.text-16` | 16px(1雷姆) |
| `.text-accent-head` | 62px (3.875rem) — 显示/品牌标题 |
| `.text-h1` | 20px (1. 25rem), 半粗体, 130%—— 减值方向 |
| `.text-h2` | 18px(1.125雷姆),半粗体,130%-下行 |
| `.text-h3` | 16px (1雷姆), 半粗体, 130%—— 减值方向 |

**修改类别** 设计在大小类之上:

| 类 | 效果 |
| --- | --- |
| `.text-semibold` | `font-weight: var(--font-weight-semibold)` |
| `.text-bold` | `font-weight: var(--font-weight-bold)` |
| `.text-italic` | `font-style: italic` |
| `.text-monospace` | 切换到 `var(--fontfamily-mono)` |
| `.text-body` | 切换到更松的 `var(--font-line-height-body)` 线高 |
| `.text-balance` | `text-wrap: balance` - 短标题的理想 |
| `.text-pre` | `white-space: pre-wrap` + 键 `word-break: break-word` ——保持白地而不会溢出 |

示例用法:

```html
<p class="text-13 text-semibold">Label</p>
<code class="text-12 text-monospace">git commit</code>
<h1 class="text-accent-head text-italic">GitButler</h1>
```

## 可用出口

-   `@gitbutler/design-core/core` - 单项导入:字体+重置+文本工具+符号
-   `@gitbutler/design-core/tokens` - CSS自定义属性(设计符号)
-   `@gitbutler/design-core/fonts` - 所有字体 CSS 声明
-   `@gitbutler/design-core/fonts/*` - 个人字体文件
-   `@gitbutler/design-core/styles/reset` - CSS重设
-   `@gitbutler/design-core/styles/text` - 文本工具类

## 包含字体

除非注明,所有字体都是可变字体.

-   **间** ——主用户界面字体(`Inter-Variable.woff2`, (中文(简体) ), `Inter-Variable-Italic.woff2`(中文(简体) )
-   **盖斯特·莫诺** – 代码的单空间字体(`GeistMono-Variable.woff2`(中文(简体) )
-   **但头** —— 品牌显示字体( A)`But-Head-Regular.woff2`, (中文(简体) ), `But-Head-Italic.woff2`(中文(简体) )

## 发展

设计信使住在法格玛,通过固定管道流入这个回放:

```
Figma variables  ──tokens-bruecke──▶  tokens/json/*.tokens.json  ──terrazzo──▶  tokens/tokens.css
```

没有 `tokens/` 由手工编辑. `tokens/json/*.tokens.json` 由 输出,以及 `tokens/tokens.css` 由建筑产生.

### 大楼

取回的接头`packageManager`)和节点(`devEngines.runtime`(单位:千美元) `package.json`。 。 。 . `pnpm install` 下载该节点,所以不需要单独的节点版本管理器.

```bash
# Install dependencies and the pinned Node
pnpm install

# Build tokens.css from tokens/json
pnpm run build

# Rebuild on every token change
pnpm run dev:tokens
```

`pnpm run build` 运行 [`scripts/postprocess-light-dark.mjs`](https://npmcn.com/package/%40gitbutler/design-core/scripts/postprocess-light-dark.mjs),其中:

1.  运行 Terrazzo (`tz build`结束 `core.tokens.json` 财务报告和审定财务报表 `semantic.tokens.json` 看到了吗 [`terrazzo.config.js`](https://npmcn.com/package/%40gitbutler/design-core/terrazzo.config.js) - 写作 `tokens/tokens.css`。一个别名的颜色,加上了自己的不透明(Figma的"规模上的不透明"),是无效的 DTCG,Terrazzo 拒绝它,所以 [`scripts/composed-colors.mjs`](https://npmcn.com/package/%40gitbutler/design-core/scripts/composed-colors.mjs) 首先将复制件移出 `.terrazzo/`,他们回来 在第二步作为 `color-mix(in srgb, var(--base) var(--opacity), transparent)`保持这两个环节;
2.  合并 `:root` 财务报告和审定财务报表 `:root.dark` 块为单 `light-dark(…)` 声明,所以光和暗模式不需要类切换,并添加被升起的颜色;
3.  附加框阴影自定义属性 `fx.tokens.json` 以 [`scripts/generate-shadow-vars.mjs`](https://npmcn.com/package/%40gitbutler/design-core/scripts/generate-shadow-vars.mjs)。 。 。 .
4.  将每个符号的图形描述写成 上面的评论,所以 `tokens.css` 说什么时候使用一个符号.

别名仍为别名:指向Figma中另一个变量的变量为 `var(--target)`大小和颜色.

### 调试文件

| 文件 | 来源 | 使用时间 |
| --- | --- | --- |
| `tokens/json/core.tokens.json` | `core` 变量收藏——生调色板,天平 | 田园 |
| `tokens/json/semantic.tokens.json` | `semantic` 变量收藏——别名输入核心,带有 `light`编号 :`dark` 模式 | 田园 |
| `tokens/json/fx.tokens.json` | 图片 **效果样式** - 阴影 | `generate-shadow-vars.mjs` |

### 从法格玛取出信条

出口使用 [标志- bruecke](https://github.com/tokens-bruecke/figma-plugin) CLI,该 与 Figma 插件相同的工具, 在 [DTCG 2025。 10](https://www.designtokens.org/tr/2025.10/format/) 格式. 必须是3.12或更后:更古老的版本跳过以自己不透明的方式别名另一个颜色.

身份证明是一团糟 `.env` 在还原根上:

```bash
FIGMA_API_KEY=figd_…      # personal access token, must include the file_variables:read scope
FIGMA_FILE_KEY=…          # the design tokens Figma file
```

```bash
set -a && . ./.env && set +a
npx tokens-bruecke \
  -a "$FIGMA_API_KEY" \
  -f "$FIGMA_FILE_KEY" \
  -c .claude/skills/release-tokens/figma-export.config.json \
  -o tokens/json \
  --split-by-collection
```

配置文件将指定符号生成的导出设置 —— hex 颜色、 没有瞄准镜、 没有图像元数据、 效果样式 `fx`。修改它会重写 符号文件,所以别管它,除非这是意图.

两个得到了卡:

-   图片 **变量 REST API 需要一个企业计划** 和携带 `file_variables:read` 范围。 没有它,导出失败 `403`. 个人准入 纪念品也每90天过期一次.
    
-   每次导出都会重写 a `createdAt` 每个文件中的印花,所以单是diff并不意味着 信物变了 检查 :
    
    ```bash
    git diff -U0 tokens/json | grep '^[+-]' | grep -v '^[+-][+-]' | grep -v createdAt
    ```
    
    没有输出表示只移动了时间戳——回放并跳出放出.
    

### 释放

版本突起跟随对生成的 CSS 定制属性的影响,因为这些属性 公众 API:

| 变动 | 弹出 |
| --- | --- |
| 调试值 | 补丁 |
| 已添加文件夹或收藏 | 小声 |
| 已删除或更名的托肯( CSS var 名称更改) | 主要 |

房子风格:该版本在 **同样的犯罪** 标记 赤裸裸的 `X.Y.Z` 附加说明的标签( 无) `v` 前缀).

```bash
npm version <patch|minor|major> --no-git-tag-version
# commit package.json + tokens/ together
git tag -a "$(node -p "require('./package.json').version")" -m "…"

npm publish --dry-run
npm publish                  # prompts for a 2FA one-time code
git push origin main && git push --tags
```

`prepublishOnly` 重建 CSS, 因此一个已发布的软件包总是符合其承诺 贾森。 推进中 `tokens/tokens.css` 并且通过 [`.github/workflows/deploy-hue-dini.yml`](https://npmcn.com/package/%40gitbutler/design-core/.github/workflows/deploy-hue-dini.yml)。 。 。 .

整个序列——导出,无操作检查,构建,凸起,承诺,标记——是自动化的 Claude代码技巧 [`.claude/skills/release-tokens/`](https://npmcn.com/package/%40gitbutler/design-core/.claude/skills/release-tokens/)。 。 。 . 运行它 `/release-tokens`; 它停止之前 `npm publish`,因为 npm 2FA需要一次性代码.

## 颜色工具

[胡-迪尼语](https://npmcn.com/package/%40gitbutler/design-core/tools/hue-dini) 是用于预览和导出 GitButler 调色板的工具。 它在所有花色中——灰色、口音和语义——适用一个共同的光度尺度,因此同一步的荫影感觉与视觉相当,而不论色调如何.

**现场:** [https://gitbutlerapp.github.io/design-core/ 页面存档备份,存于互联网档案馆](https://gitbutlerapp.github.io/design-core/)

```bash
cd tools/hue-dini
pnpm install
pnpm dev
```

见 [工具/软件/README.md](https://npmcn.com/package/%40gitbutler/design-core/tools/hue-dini/README.md) 更多细节.

## 常见问题

### @gitbutler/design-core 是什么？

GitButler 应用程序的设计符注意：该包已被作者标记为弃用——Moved to packages/design-core in gitbutlerapp/gitbutler and no longer published\. Pin a commit instead: github:gitbutlerapp/gitbutler\#\<sha\>&path:packages/design-core

### 如何安装 @gitbutler/design-core？

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

### @gitbutler/design-core 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/gitbutler\_\_design-core 是否存在。

### @gitbutler/design-core 支持 ESM 还是 CommonJS？

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

### @gitbutler/design-core 可以商用吗？

@gitbutler/design-core 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @gitbutler/design-core 的下载量有多少？

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

### @gitbutler/design-core 还在维护吗？

最新版本 11\.3\.0 发布于 2026/11/04（12 天前）；至今共发布 111 个版本，其中过去 12 个月发布了 98 个；首次发布于 2025/10/06。作者已将其标记为弃用，新项目建议寻找替代方案。

