# @brightlocal/tokens 中文文档

规范地址：https://npmcn.com/package/%40brightlocal/tokens/

版本：1\.2\.0
npm 元数据更新时间：2026-11-03T10:38:32.752Z
中文译文更新时间：2026-11-08T15:39:36.728Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1 MB，67 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：tailwindcss ^4\.3\.3
- 首次发布：2025-11-14T14:40:30.735Z
- 最新版本发布：2026-11-03T10:38:32.469Z
- 近 30 天下载量：2382（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

亮度本地设计系统符号

## 安装

```sh
npm install @brightlocal/tokens
```

也可以使用：`pnpm add @brightlocal/tokens`、`yarn add @brightlocal/tokens`、`bun add @brightlocal/tokens`

## README

# @ braight local/ tokens (英语)

亮相本地设计系统令牌包包含设计令牌,CSS变量,和Tailwind CSS v4预设.

## 兼容性

| 依赖性 | 版本 |
| --- | --- |
| **尾风 CSS** | `^4.1.18` (所需v4) |
| **CSS 导入语法** | `@import` 编号 : `@theme` (Tailwind v4 CSS- first config) (中文(简体) ) |
| **构建系统** | Vite, Next.js, PostCSS — 任何带有CSS的捆绑器 `@import` 支助 |

> **重要内容:** 此软件包使用 Tailwind CSS v4 指令(`@import "tailwindcss"`, (中文(简体) ), `@theme inline`, (中文(简体) ), `@variant`) (中文(简体) ). 没错 **不兼容** 与尾风 CSS v3.

## 安装

```bash
npm install @brightlocal/tokens --registry=https://npm.pkg.github.com
```

> 这个软件包被发布到 GitHub 软件包中. 您需要通过 GitHub 包的认证来安装 .

## 快速启动( 金色路径)

遵循这些步骤,将符号包整合到您的项目中:

### 1\. 安装软件包

```bash
npm install @brightlocal/tokens tailwindcss@^4.1.18
```

### 2\. 导入您 CSS 主文件中的预设

```css
/* app.css / globals.css */
@import "@brightlocal/tokens/tailwind-preset.css";
```

此单导入给您 :

-   尾风 CSS v4 基础样式
-   所有语义色彩符号( 轻 + 暗模式)
-   类型、相距、半径和阴影符号
-   所有符号的尾风工具映射
-   **自动托管字体** —— 说 `@font-face` 规则和woff2文件 Inter, Poppins, 盖斯·莫诺被捆绑起来 `font-sans`, (中文(简体) ), `font-display`,以及 `font-mono` 为终端用户正确渲染 **无额外设置** (无谷歌字体) `<link>`,没有手动 `@font-face`) (中文(简体) ). 见 [自动托管字体](https://npmcn.com/package/%40brightlocal/tokens/#readme-self-hosted-fonts)。 。 。 .

### 3\. 启用暗模式

添加数据 `.dark` 分类到根元素 :

```html
<!-- Light mode (default) -->
<html>
  <body class="bg-background text-foreground">...</body>
</html>

<!-- Dark mode -->
<html class="dark">
  <body class="bg-background text-foreground">...</body>
</html>
```

### 4\. 与 `@brightlocal/ui-components`

```tsx
import { Button } from "@brightlocal/ui-components/button";

// Components automatically use the semantic tokens from the preset
<Button variant="default">Primary Action</Button>
```

## 使用量

### 核心托肯( CSS 变量)

导入单个令牌 CSS 文件用于颗粒控制 :

```css
@import "@brightlocal/tokens/core-tokens/colors.css";
@import "@brightlocal/tokens/core-tokens/spacing.css";
@import "@brightlocal/tokens/core-tokens/typography.css";
```

### 尾风 CSS 预设

```css
/* Standard preset (recommended) */
@import "@brightlocal/tokens/tailwind-preset.css";

/* Lab preset (experimental features) */
@import "@brightlocal/tokens/tailwind-preset-lab.css";
```

## 可用出口

| 导出路径 | 说明 |
| --- | --- |
| `@brightlocal/tokens/tailwind-preset.css` | 主 Tailwind CSS v4 预设( 包括所有符号) **和自行托管的字体**(中文(简体) ) |
| `@brightlocal/tokens/tailwind-preset-lab.css` | 实验尾风 CSS 预设 |
| `@brightlocal/tokens/fonts.css` | 独立 `@font-face` inter, Poppins, Geist Mono 的规则( 已包含在预设中) |
| `@brightlocal/tokens/core-tokens/colors.css` | 色彩设计符号( CSS 变量) |
| `@brightlocal/tokens/core-tokens/spacing.css` | 边界半径、阴影、断点和集装箱标志 |
| `@brightlocal/tokens/core-tokens/typography.css` | 打字符 (发音、大小、重量) |
| `@brightlocal/tokens/tokens.json` | AI工具和MCP服务器的机器可读符号参考(**不用于运行时代码——只读引用**(中文(简体) ) |

## 调试引用

### 语义色彩

设计系统使用 **语义色彩符号** ——不是原始调色板值. 总是使用这些 :

| 托肯语( CSS) | 尾风工具 | 目的 |
| --- | --- | --- |
| `var(--background)` | `bg-background` | 页面/应用程序背景 |
| `var(--foreground)` | `text-foreground` | 默认文本颜色 |
| `var(--primary)` | `bg-primary`, (中文(简体) ), `text-primary` | 主要品牌/行动颜色 |
| `var(--primary-foreground)` | `text-primary-foreground` | 关于主要背景的文字 |
| `var(--secondary)` | `bg-secondary` | 次要行动 |
| `var(--secondary-foreground)` | `text-secondary-foreground` | 关于次要背景的文字 |
| `var(--muted)` | `bg-muted` | 静音/低音背景 |
| `var(--muted-foreground)` | `text-muted-foreground` | 变音/变音文本 |
| `var(--accent)` | `bg-accent` | 突出/突出背景 |
| `var(--accent-foreground)` | `text-accent-foreground` | 关于重音背景的文字 |
| `var(--destructive)` | `bg-destructive`, (中文(简体) ), `text-destructive` | 错误/危险状态 |
| `var(--destructive-foreground)` | `text-destructive-foreground` | 关于破坏性背景的文本 |
| `var(--border)` | `border-border` | 默认边框颜色 |
| `var(--input)` | `border-input` | 输入字段边框 |
| `var(--outline)` | `shadow-default` | 焦点环颜色( 通过阴影工具使用) |
| `var(--card)` | `bg-card` | 纸牌背景 |
| `var(--card-foreground)` | `text-card-foreground` | 纸牌背景的文字 |
| `var(--card-border)` | `border-card-border` | 卡片边框颜色 |
| `var(--popover)` | `bg-popover` | 弹出/下拉背景 |
| `var(--popover-foreground)` | `text-popover-foreground` | 关于弹出背景的文本 |
| `var(--link)` | `text-link` | 链接颜色 |
| `var(--link-visited)` | `text-link-visited` | 访问链接颜色 |

### 状态颜色

| 托肯语( CSS) | 尾风工具 | 目的 |
| --- | --- | --- |
| `var(--success-background)` | `bg-success-background` | 成功通知背景 |
| `var(--success-foreground)` | `text-success-foreground` | 成功文本 |
| `var(--info-background)` | `bg-info-background` | 信息通知背景 |
| `var(--info-foreground)` | `text-info-foreground` | 信息文本 |
| `var(--warning-background)` | `bg-warning-background` | 通知背景 |
| `var(--warning-foreground)` | `text-warning-foreground` | 警告文本 |

### 带有 CSS 自定义属性

```css
.my-component {
  color: var(--foreground);
  background: var(--background);
  border: 1px solid var(--border);
  border-radius: var(--radius-md);
}

.my-button {
  background: var(--primary);
  color: var(--primary-foreground);
}
```

### 带有 Tailwind CSS 公用事业

```html
<!-- Page layout -->
<div class="bg-background text-foreground min-h-screen">

  <!-- Card -->
  <div class="bg-card text-card-foreground rounded-md border border-border p-4">
    <h2 class="text-lg font-semibold">Title</h2>
    <p class="text-muted-foreground text-sm">Description</p>
  </div>

  <!-- Button -->
  <button class="bg-primary text-primary-foreground rounded-md px-4 py-2">
    Click me
  </button>

  <!-- Destructive action -->
  <button class="bg-destructive text-destructive-foreground rounded-md px-4 py-2">
    Delete
  </button>
</div>
```

### 类型

使用 `font-display` 包含标题的文本大小和重量工具:

| 标题 | 类 | 大小 |
| --- | --- | --- |
| 四十届 | `font-display text-5xl font-medium` | 48px 坐标 |
| 语言 | `font-display text-4xl font-medium` | 36个px |
| 货币 | `font-display text-3xl font-medium` | 30px 时速 |
| 系统 | `font-display text-2xl font-medium` | 24px (英语) |

字体家族 : `font-sans` (机构间), `font-serif` (格鲁吉亚), `font-mono` (Geist Mono), (英语), `font-display` (诗)

### 自动托管字体

预设的舰只自行托管 `@font-face` 声明和woff2文件 3个品牌字体,所以它们为终端用户制作 **字体不为 本地安装且无需任何 CDN 请求**。导入 `@brightlocal/tokens/tailwind-preset.css` 不需要谷歌 字体 `<link>`,没有手动 `@font-face`。 。 。 .

被捆绑的重量(纬度子集,正常样式, `font-display: swap`:

| 家属 | 工具 | 运出重量 |
| --- | --- | --- |
| 间 | `font-sans` | 300、400、500、600、700 |
| 弹出 | `font-display` | 400,500,600,700 (英语) |
| 盖斯特·莫诺 | `font-mono` | 300,400 (英语) |

这些覆盖了设计系统通过改变字体的重量而使用的每个重量 比额表(`font-normal` - 300个, `font-medium` - 400个, `font-semibold` − 500人, `font-bold` - 600个, `font-extrabold` – 700). 罕见的极端(100/200/800/900), 为保留有效载荷而故意省略了斜体和非正线子集 体积小;它们回到最接近的重量. `font-serif` 使用该 佐治亚系统堆栈,并非自行托管.

Woff2 文件由您的捆绑者( Vite, Next.js等) 作为资产发布 懒惰的每个重量——消费者只下载实际的重量 使。 。 。 字体在SIL Open Font许可证1.1下获得许可(见 `*-LICENSE.txt` 文件已运入 `fonts/`) (中文(简体) ).

### 边框半径

| 尾风工具 | 数值 |
| --- | --- |
| `rounded-none` | 0px (单位:秒) |
| `rounded-xs` | 2px 时速 |
| `rounded-sm` | 6个px |
| `rounded-md` | 8个px |
| `rounded-lg` | 10px (英语) |
| `rounded-xl` | 14px 时速 |
| `rounded-2xl` | 16px 时 |
| `rounded-3xl` | 24px (英语) |
| `rounded-4xl` | 32px 密码 |
| `rounded-full` | 9999px (英语) |

## AI 使用规则

见 [AI USAGE.md (英语)](https://npmcn.com/package/%40brightlocal/tokens/AI_USAGE.md) 对于完整的AI使用指南,包括语义符号引用,常见错误,以及设置指令.

关键规则 :

1.  **从不硬码颜色** – 总是使用语义符号或者它们的 Tailwind 等效工具
2.  **使用 `bg-background text-foreground`** 作为页面基线
3.  **比调色板还偏好语义符号** ——使用 `bg-primary` 没有 `bg-blue-600`
4.  **暗模式使用 `.dark` 类** ——指使自动切换,无手动操作 `dark:` 所需变式
5.  **导入预设** - 单身 `@import "@brightlocal/tokens/tailwind-preset.css"` 提供一切

## 发展

这个软件包是亮相本地设计系统单列波的一部分. 键是生成自 [托肯斯工作室](https://tokens.studio/) 定义 `src/core-tokens/tokens-studio/`。 。 。 .

构建管道: Tokens Studio JSON → 样式词典 → CSS变量 → Tailwind v4 预设

```bash
# Build all tokens (from packages/tokens/)
pnpm build:tokens

# Full build (tokens + copy to dist + tokens.json)
pnpm build

# From monorepo root
pnpm --filter @brightlocal/tokens build
```

## 仓库

[GitHub 仓库](https://github.com/BrightLocal/design-system/tree/main/packages/tokens)

## 许可证

私人软件包——仅使用亮度本地内部.

## 常见问题

### @brightlocal/tokens 是什么？

亮度本地设计系统符号

### 如何安装 @brightlocal/tokens？

在项目目录运行 npm install @brightlocal/tokens，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：tailwindcss（^4\.3\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @brightlocal/tokens 支持 TypeScript 吗？

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

### @brightlocal/tokens 支持 ESM 还是 CommonJS？

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

### @brightlocal/tokens 可以商用吗？

@brightlocal/tokens 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @brightlocal/tokens 的下载量有多少？

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

### @brightlocal/tokens 还在维护吗？

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