@gitbutler/design-core

中文文档
11.3.0发布于 2026/11/04ES Module零依赖构建来源已验证近 30 天下载 3万

Design tokens for GitButler applications

此软件包已被标记为弃用

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

原始使用文档
文档目录14 节
  1. Installation
  2. Usage
  3. Single Import
  4. Design Tokens (CSS)
  5. Fonts
  6. Styles
  7. Available Exports
  8. Included Fonts
  9. Development
  10. Building
  11. Token files
  12. Pulling tokens from Figma
  13. Releasing
  14. Color Tool

@gitbutler/design-core

Design tokens and fonts for GitButler applications. This package provides CSS custom properties, design tokens in JSON format, and web fonts used across GitButler products.

Installation

npm install @gitbutler/design-core

Usage

Single Import

The easiest way to get everything — fonts, CSS reset, text utilities, and design tokens:

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

Or in JavaScript/TypeScript:

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

Design Tokens (CSS)

Import only the design tokens CSS file:

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

Or in JavaScript/TypeScript:

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

This provides CSS custom properties for colors, spacing, typography, and other design tokens with automatic light/dark mode support.

Fonts

Import all font declarations:

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

Or reference individual font files directly:

@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";

Styles

Import individual style sheets:

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

CSS Reset

The reset is scoped to @layer reset to avoid specificity conflicts with application styles. It applies the following normalizations:

  • Box sizing — box-sizing: border-box on all elements and pseudo-elements.
  • Font rendering — -webkit-font-smoothing: antialiased, -moz-osx-font-smoothing: grayscale, text-rendering: optimizeLegibility, and font size inflation prevention on html.
  • Body defaults — zero padding and margin, overflow-x: hidden, and base values for color, font-family, font-weight, and line-height pulled from design tokens.
  • Form elements — input, textarea, select, and button have their padding, border, and background stripped, and inherit color and font from the parent.
  • Headings — h1–h6 have margin-block removed.
  • Code & pre — code and pre use var(--fontfamily-mono).
  • Lists & paragraphs — ul and ol have padding-left and list-style removed; ul, pre, and p have margin-block removed.

Text Utilities

Text classes are scoped to @layer text. The layer also sets three font-family custom properties on :root:

PropertyValue
--fontfamily-basevar(--font-family-base), sans-serif
--fontfamily-monovar(--font-family-mono), monospace
--fontfamily-accentvar(--font-family-accent), serif

Size classes set font-size, font-weight: regular, line-height, and font-family: base as a self-contained unit:

ClassFont size
.text-1111px (0.6875rem)
.text-1212px (0.75rem)
.text-1313px (0.8125rem)
.text-1414px (0.875rem)
.text-1515px (0.938rem)
.text-1616px (1rem)
.text-accent-head62px (3.875rem) — display / brand heading
.text-h120px (1.25rem), semibold, 130% — markdown heading
.text-h218px (1.125rem), semibold, 130% — markdown heading
.text-h316px (1rem), semibold, 130% — markdown heading

Modifier classes are designed to be composed on top of a size class:

ClassEffect
.text-semiboldfont-weight: var(--font-weight-semibold)
.text-boldfont-weight: var(--font-weight-bold)
.text-italicfont-style: italic
.text-monospaceSwitches to var(--fontfamily-mono)
.text-bodySwitches to the looser var(--font-line-height-body) line height
.text-balancetext-wrap: balance — ideal for short headings
.text-prewhite-space: pre-wrap + word-break: break-word — preserves whitespace without overflow

Example usage:

<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>

Available Exports

  • @gitbutler/design-core/core - Single import: fonts + reset + text utilities + tokens
  • @gitbutler/design-core/tokens - CSS custom properties (design tokens)
  • @gitbutler/design-core/fonts - All font CSS declarations
  • @gitbutler/design-core/fonts/* - Individual font files
  • @gitbutler/design-core/styles/reset - CSS reset
  • @gitbutler/design-core/styles/text - Text utility classes

Included Fonts

All fonts are variable fonts unless noted.

  • Inter — Primary UI font (Inter-Variable.woff2, Inter-Variable-Italic.woff2)
  • Geist Mono — Monospace font for code (GeistMono-Variable.woff2)
  • But Head — Brand display font (But-Head-Regular.woff2, But-Head-Italic.woff2)

Development

Design tokens live in Figma and flow into this repo through a fixed pipeline:

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

Nothing in tokens/ is edited by hand. tokens/json/*.tokens.json is generated by the export, and tokens/tokens.css is generated from it by the build.

Building

The repo pins pnpm (packageManager) and Node (devEngines.runtime) in package.json. pnpm install downloads that Node, so no separate Node version manager is needed.

# 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 runs scripts/postprocess-light-dark.mjs, which:

  1. runs Terrazzo (tz build) over core.tokens.json and semantic.tokens.json — see terrazzo.config.js — to write tokens/tokens.css. A color that aliases another and adds its own opacity (Figma's "opacity at scale") isn't valid DTCG, and Terrazzo rejects it, so scripts/composed-colors.mjs first lifts those out of copies in .terrazzo/, and they come back in step 2 as color-mix(in srgb, var(--base) var(--opacity), transparent), keeping both links;
  2. merges the :root and :root.dark blocks into single light-dark(…) declarations, so light and dark mode need no class switching, and adds the lifted colors;
  3. appends box-shadow custom properties generated from fx.tokens.json by scripts/generate-shadow-vars.mjs.
  4. writes each token's Figma description as a comment above its declaration, so tokens.css says when to use a token.

Aliases stay aliases: a variable that points at another in Figma comes out as var(--target), for sizes as well as colors.

Token files

FileSourceConsumed by
tokens/json/core.tokens.jsoncore variable collection — raw palette, scalesTerrazzo
tokens/json/semantic.tokens.jsonsemantic variable collection — aliases onto core, with light/dark modesTerrazzo
tokens/json/fx.tokens.jsonFigma effect styles — shadowsgenerate-shadow-vars.mjs

Pulling tokens from Figma

Exports use the tokens-bruecke CLI, the same tool as the Figma plugin, in DTCG 2025.10 format. It has to be 3.12 or later: older versions skip colors that alias another with their own opacity.

Credentials go in a gitignored .env at the repo root:

FIGMA_API_KEY=figd_…      # personal access token, must include the file_variables:read scope
FIGMA_FILE_KEY=…          # the design tokens Figma file
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

The config file pins the export settings the committed tokens were generated with — hex colors, no scopes, no Figma metadata, effect styles as fx. Changing it rewrites every token file, so leave it alone unless that is the intent.

Two gotchas:

  • The Figma variables REST API requires an Enterprise plan and a token carrying the file_variables:read scope. Without it the export fails with 403. Personal access tokens also expire every 90 days.

  • Every export rewrites a createdAt stamp in each file, so a diff alone does not mean the tokens changed. Check with:

    git diff -U0 tokens/json | grep '^[+-]' | grep -v '^[+-][+-]' | grep -v createdAt
    

    No output means only timestamps moved — revert and skip the release.

Releasing

Version bumps follow the impact on the generated CSS custom properties, since those are the public API:

ChangeBump
Token values tweakedpatch
Tokens or collections addedminor
Tokens removed or renamed (CSS var names change)major

House style: the version bump lives in the same commit as the token changes, tagged with a bare X.Y.Z annotated tag (no v prefix).

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 rebuilds the CSS, so a published package always matches its committed JSON. Pushing tokens/tokens.css also redeploys the hue-dini site via .github/workflows/deploy-hue-dini.yml.

The whole sequence — export, no-op check, build, bump, commit, tag — is automated as a Claude Code skill in .claude/skills/release-tokens/. Run it with /release-tokens; it stops before npm publish, which stays manual because npm 2FA requires a one-time code.

Color Tool

hue-dini is the tool used to preview and export the GitButler color palette. It applies a single shared luminance scale across all hues — gray, accent, and semantic — so shades at the same step feel visually equivalent regardless of hue.

Live: https://gitbutlerapp.github.io/design-core/

cd tools/hue-dini
pnpm install
pnpm dev

See tools/hue-dini/README.md for more details.

版本与发布记录

@gitbutler/design-core 共发布 111 个版本,首次发布于 2025/10/06;过去 12 个月发布了 98 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
11.3.0latest2026/11/0412 天前
11.2.02026/11/0412 天前
11.1.02026/11/0412 天前
11.0.02026/11/0213 天前
10.0.12026/10/1828 天前
10.0.02026/09/301 个月前

关于 @gitbutler/design-core 的常见问题

@gitbutler/design-core 是什么?

Design tokens for GitButler applications注意:该包已被作者标记为弃用——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。作者已将其标记为弃用,新项目建议寻找替代方案。