# @gainsight-hub/design-tokens 中文文档

规范地址：https://npmcn.com/package/%40gainsight-hub/design-tokens/

版本：0\.5\.1
npm 元数据更新时间：2026-10-29T10:12:35.021Z
中文译文更新时间：2026-11-15T21:32:13.522Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40gainsight-hub/design-tokens
原文对照：https://npmcn.com/package/%40gainsight-hub/design-tokens/?lang=original
项目主页：https://github.com/Gainsight/dch-sdk#readme
源码仓库：https://github.com/Gainsight/dch-sdk

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

- 包体积（解压后）：501 kB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- peer 依赖：tailwindcss \>=4\.0\.0
- 首次发布：2026-05-05T08:28:12.931Z
- 最新版本发布：2026-10-29T10:12:34.761Z
- 近 30 天下载量：3257（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

设计符: CSS变量,JSON,TypeScript常数,以及一个Tailwind v4主题.

## 安装

```sh
npm install @gainsight-hub/design-tokens
```

也可以使用：`pnpm add @gainsight-hub/design-tokens`、`yarn add @gainsight-hub/design-tokens`、`bun add @gainsight-hub/design-tokens`

## README

# @ reconsight-hub/ 设计托克

Gainsight Community Hub的设计符——CSS自定义属性,TypeScript常数,JSON,和一个Tailwind v4主题.

## 安装

```bash
npm install @gainsight-hub/design-tokens
```

这个软件包 **无运行时间依赖关系** 并自行工作: 平面 CSS 应用和 SCSS 应用 (例如服务器的 Preact 目的地) 只安装此软件包并导入 `styles.css` 和一个主题. `tailwindcss` (QQ 3) 是可选的对等点, 仅供 Tailwind 使用 预设。 安装 `@gainsight-hub/design-system` 或者说 `@gainsight-hub/theme-editor` 如果你需要的话 反应组件或主题编辑器 UI; 两者都依赖于此软件包, 所以拥有此软件的应用程序 符号也拥有其版本.

* * *

## 快开始

导入 `styles.css` 一次在你的应用程序入口。 大部分应用都这样.

```js
// main.js / main.ts
import "@gainsight-hub/design-tokens/styles.css";
```

然后通过 CSS 自定义属性在任何地方使用符号 :

```css
.button {
  background: var(--color-action-primary-default);
  color: var(--color-content-inverse);
  border-radius: var(--button-radius);
}
```

* * *

## CSS 自定义属性

### 基础( 轻主题)

定义所有符号为 CSS 自定义属性 `:root`。这是默认的光线主题.

```js
import "@gainsight-hub/design-tokens/styles.css";
```

### 所有主题已捆绑

包含一个文件中的基础符号加上所有主题覆盖 。 如果您想要在运行时切换主题而不装入额外的样式表, 请使用此选项 .

```js
import "@gainsight-hub/design-tokens/themes.css";
```

### 个别主题

只装入您需要的主题 `styles.css`数字 :

```js
import "@gainsight-hub/design-tokens/styles.css";
import "@gainsight-hub/design-tokens/themes/ocean.css";
```

现有主题——每艘船舶都有一个轻质块(`[data-theme="{name}"]`)和a 数据 暗块( e)`[data-theme="{name}"].dark`页:1 `legacy`,它只是轻 (这是移民前的搭桥——见下文):

| 导入路径 | 说明 |
| --- | --- |
| `@gainsight-hub/design-tokens/themes/ocean.css` | 海洋-蓝色调色板 |
| `@gainsight-hub/design-tokens/themes/ember.css` | Ember——暖橙色调色板 |
| `@gainsight-hub/design-tokens/themes/meadow.css` | Meadow——绿色调色板 |
| `@gainsight-hub/design-tokens/themes/violet.css` | 紫罗兰-Indigo调色板 |
| `@gainsight-hub/design-tokens/themes/slate.css` | 平板-冷却调色板 |
| `@gainsight-hub/design-tokens/themes/legacy.css` | 移民前租户定制桥梁(仅照明) |

基本主题本身的暗模式不需要额外导入 `styles.css`作为 `:where(:root:not([data-theme])).dark` 挡住灯光 `:root` 缺省数(`:where()` 保持与光块相同的特异性,因此运行时的覆盖仍然取胜.

### 运行时主题切换

`data-theme` 总是持有所选主题的 id( 或为 默认主题); `.dark` 是一种独立、添加剂的暗模式类—— 永远不是值 `data-theme` 它本身需要。 都活下来了 `document.documentElement`。 。 。 .

```css
/* A named theme, dark mode: */
/* (written :where([data-theme="ocean"]).dark in the generated files) */
[data-theme="ocean"].dark { /* ... */ }

/* The default theme, dark mode (no data-theme attribute): */
:root.dark { /* ... (generated as :where(:root:not([data-theme])).dark) */ }

/* Scope to a tenant / white-label */
[data-tenant="acme"] {
  --color-action-primary-default: #e63946;
  --button-primary-background-color-default: #e63946;
}
```

* * *

## 脚本命名

名称是公共合同:重命名是针对主题覆盖和客户风格的突破性更改.

| 层 | 图案 | 示例 |
| --- | --- | --- |
| 主题投入 | `--theme-{scale}-{step}` | `--theme-brand-700` |
| 颜色原始 | `--color-{palette}-{step}` | `--color-brand-700`, (中文(简体) ), `--color-neutral-a100` |
| 语义颜色 | `--color-{role}-{purpose}[-{state}]` | `--color-action-primary-hover` |
| 缩放 | `--{category}-{step}` | `--space-200`, (中文(简体) ), `--radius-100`, (中文(简体) ), `--font-size-300` |
| 类型样式 | `--text-{style}-{font-size|font-weight|line-height}` | `--text-heading-small-font-size` |
| 组件符号 | `--{component}-{variant}-{property}-{state}` | `--button-primary-background-color-hover` |
| 组件几何 | `--{component}-{property}` | `--button-radius`, (中文(简体) ), `--sidebar-radius` |

组件符号规则 :

-   **命名 CSS 属性, 最后状态 .** 颜色表示哪个颜色 : `background-color`, (中文(简体) ), `border-color`, (中文(简体) ), `content-color` (文字和图标), `title-color`, (中文(简体) ), `subtitle-color`, (中文(简体) ), `icon-color`,以及 `border-top-color` 编号 : `border-bottom-color` 对于单边. `--button-primary-background-color-hover`, (中文(简体) ), `--sidebar-border-color-default`. 国家(`default`, (中文(简体) ), `hover`, (中文(简体) ), `pressed`)总是最后一句话.
-   **为什么 `-color`数字 :** 一个赤 `background` 或者说 `border` 可以是颜色、图像或宽度. `--widget-hero-background-image` 这是一个图像, `--sidebar-border-width` 是一个宽度, `--sidebar-border-color-default` 是一种颜色.
-   **其他属性保留自己的单词 :** `border-width`, (中文(简体) ), `radius`, (中文(简体) ), `shadow`, (中文(简体) ), `font-family`, (中文(简体) ), `font-weight`, (中文(简体) ), `text-transform`, (中文(简体) ), `height`。具有单一价值的财产不需要状态后缀(`--sidebar-radius`) (中文(简体) ).
-   **一个变体是名称的一部分,而不是状态:** `--button-vote-selected-background-color-default` 是投票按钮的"投票"变体,它本身默认,徘徊并按下状态.
-   **命名空间 :** `sidebar` 是一个内容区域部件, `sidenav` 是应用程序壳侧导航,以及 `navigation` 是顶端的栏杆及其下垂.

值得了解的天平 :

-   **阿尔法:** `--color-neutral-a100` 改为 `a500` 中性 1000 在 4, 8, 16, 32 和 48% 不透明 .
-   **行高 :** `--line-height-ratio-*` 无单位倍数(头部使用紧凑,身体和代码使用放松); `--line-height-grid-*` 是4px网格(标签、标题、菜单、导航、按钮)上固定的还原值.
-   **`--font-size-base`** 这是故意的。 它是每个 rem 步骤产生的根大小,主题编辑器的文本大小设置会写出它.

CSS 注释和 `token-catalog.json`。 。 。 .

* * *

## 类型脚本 / Java 脚本

直接导入已键入的符数常数 。 所有出口都通过捆绑输入 `tokens.d.ts`。 。 。 .

```ts
import {
  ColorActionPrimaryDefault,
  ColorSurfacePage,
  RadiusFull,
} from "@gainsight-hub/design-tokens";

// Use in JS logic — e.g. canvas drawing, charting libs
ctx.fillStyle = ColorActionPrimaryDefault; // "#0C66E4"
```

* * *

## 尾风 v4

只有尾风v4。 在您的 CSS 条目中先导入变量, 然后导入主题文件 :

```css
@import "tailwindcss";
@import "@gainsight-hub/design-tokens/styles.css";        /* defines the CSS custom properties */
@import "@gainsight-hub/design-tokens/tailwind-theme.css"; /* maps them to Tailwind utilities */
```

`tailwind-theme.css` 是一个 `@theme inline` 块,每个条目都是 `var(--token)` 引用,所以没有重复值。 在任何范围内更改一个符号(例如带有一个主题),以及每一个使用它更新的效用,没有重建.

```html
<!-- Colours: the full token name, including -default -->
<div class="bg-action-primary-default text-content-inverse">Primary</div>
<div class="bg-surface-default text-content-default border border-line-default">Card</div>

<!-- Spacing, radius, elevation -->
<div class="p-space-200 gap-space-100 rounded-100 shadow-elevation-1">Layout</div>

<!-- Type styles: one class sets size, line height and weight -->
<h2 class="text-heading-small">Heading</h2>
<p class="font-sans text-body-medium">Body text</p>
```

| 尾风类 | CSS 变量 |
| --- | --- |
| `bg-action-primary-default` | `var(--color-action-primary-default)` |
| `bg-surface-page` | `var(--color-surface-page)` |
| `text-content-subtle` | `var(--color-content-subtle)` |
| `border-line-default` | `var(--color-line-default)` |
| `text-heading-small` | `--text-heading-small-font-size`, (中文(简体) ), `-line-height` 财务报告和审定财务报表 `-font-weight` |
| `font-sans` | `var(--font-family-sans)` |
| `leading-grid-100` | `var(--line-height-grid-100)` |
| `rounded-100` | `var(--radius-100)` |

库存规模公用事业`rounded-md`, (中文(简体) ), `text-sm`, (中文(简体) ), `p-3`, (中文(简体) ), `shadow-lg`)也与符相接,因此一个主题可以改变形状,密度和高地.

* * *

## 组件符号( CSS 模块)

对于组件内部,使用CSS模块,其中 `var()` 直接 :

```css
/* Button.module.css */
.root {
  background: var(--button-primary-background-color-default);
  color: var(--button-primary-label-default);
  border-radius: var(--button-radius);
  padding: var(--space-100) var(--space-200);
}

.root:hover {
  background: var(--button-primary-background-color-hover);
}
```

```tsx
// Button.tsx
import styles from "./Button.module.css";

export function Button({ children }: { children: React.ReactNode }) {
  return <button className={styles.root}>{children}</button>;
}
```

* * *

## 贾森

原始符号值作为嵌入的 JSON 值 。 用于工具化,构建脚本,或非网络目标(如React Introduct,Figma插件).

```js
import tokens from "@gainsight-hub/design-tokens/tokens.json" with { type: "json" };

const primary = tokens.color.action.primary.default.value; // "#0C66E4"
const gutter = tokens.space.layout.gutter.value;            // "12px"
```

## 托肯目录

结构化目录,包含已解析的值,描述,别名链条,以及遗留的映射. 被设计门户和设计工具使用.

```js
import catalog from "@gainsight-hub/design-tokens/token-catalog.json" with { type: "json" };

// 224 tokens with cssVar, path, type, value, description, references, legacyMapping
catalog.all.forEach(token => console.log(token.cssVar, token.value));
```

## 运行时主题切换

`applyThemeConfig(config, mode)` 应用已保存 `ThemeConfig` (主题 id + 任意) 每款模式覆盖)到当前页面——同步,不重装页面. 它设置 `data-theme` 改为真实的主题 id(或为默认主题删除)和 切换 `.dark` 独立类 `mode`,然后插入主题的 自己的变量加上任何作为 CSS 自定义属性的覆盖 .

要求主题的自有CSS已经装入(例如. `themes.css`,或 具体 `themes/{name}.css` )——此函数只管理 `data-theme`编号 :`.dark` 和上层配置级别覆盖; 它不获取 样式表.

```js
import "@gainsight-hub/design-tokens/themes.css"; // base + all themes
import { applyThemeConfig } from "@gainsight-hub/design-tokens";

// Switch to Ocean, light mode
applyThemeConfig({ themeId: "ocean", overrides: { light: {}, dark: {} } }, "light");

// Same theme, dark mode
applyThemeConfig({ themeId: "ocean", overrides: { light: {}, dark: {} } }, "dark");

// Default theme + a custom brand color override
applyThemeConfig(
  { themeId: "gainsight-light", overrides: { light: { "--theme-brand-700": "#FF6600" }, dark: {} } },
  "light",
);
```

可用的主题ID : `gainsight-light` (违约), `ocean`, (中文(简体) ), `ember`, (中文(简体) ), `meadow`, (中文(简体) ), `violet`, (中文(简体) ), `slate`, (中文(简体) ), `legacy`。 。 。 .

* * *

## 可用出口

| 导入 | 说明 |
| --- | --- |
| `@gainsight-hub/design-tokens` | `applyThemeConfig` + 类型脚本/ JS 命名常数 |
| `@gainsight-hub/design-tokens/styles.css` | CSS自定义属性——基础光主题 |
| `@gainsight-hub/design-tokens/themes.css` | CSS 自定义属性——所有主题捆绑 |
| `@gainsight-hub/design-tokens/themes/*` | 单个主题覆盖( 加载在 `styles.css`(中文(简体) ) |
| `@gainsight-hub/design-tokens/tailwind-theme.css` | 尾风 v4 `@theme inline` 映射( 导入后) `styles.css`(中文(简体) ) |
| `@gainsight-hub/design-tokens/tokens.json` | Nested JSON — 原始符号值 |
| `@gainsight-hub/design-tokens/token-catalog.json` | 包含已解析值、描述、别名链的完整目录 |

* * *

## 软件包结构

```
packages/design-tokens/
├── src/                   Token source files (Style Dictionary format)
│   ├── primitive/         Raw scales — color, space, radius, font, shadow
│   ├── semantic/          Semantic roles — action, surface, content, line, status
│   └── component/         Component tokens — button, card, feed, navigation, widget
├── config/                Style Dictionary config and custom formats
│   └── themes/            Theme override definitions
├── migration/             Legacy variable mapping tools
├── build.js               Build entry point
└── dist/                  Published output (generated, do not edit)
    ├── index.js            Root entry — applyThemeConfig + token constants
    ├── index.d.ts          TypeScript declarations for root entry
    ├── applyTheme.js       Runtime theme switcher (lazy CSS loading)
    ├── applyTheme.d.ts     TypeScript declarations for applyThemeConfig
    ├── tokens.js           JS named constants
    ├── tokens.d.ts         TypeScript declarations for token constants
    ├── styles.css          CSS custom properties (base light theme)
    ├── themes.css          All themes combined (styles.css + all theme overrides)
    ├── tokens.json         Nested JSON
    ├── token-catalog.json  Full token catalog
    ├── tailwind-theme.css    Tailwind v4 theme mapping
    └── themes/             Individual theme CSS files
```

## 建筑和出版

```bash
# Build from the monorepo root
turbo run build --filter=@gainsight-hub/design-tokens

# Publish
npm publish --access public -w packages/design-tokens
```

## 常见问题

### @gainsight-hub/design-tokens 是什么？

设计符: CSS变量,JSON,TypeScript常数,以及一个Tailwind v4主题\.

### 如何安装 @gainsight-hub/design-tokens？

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

### @gainsight-hub/design-tokens 支持 TypeScript 吗？

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

### @gainsight-hub/design-tokens 支持 ESM 还是 CommonJS？

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

### @gainsight-hub/design-tokens 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @gainsight-hub/design-tokens 可以商用吗？

@gainsight-hub/design-tokens 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @gainsight-hub/design-tokens 的下载量有多少？

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

### @gainsight-hub/design-tokens 还在维护吗？

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