# @sps-woodland/tokens 中文文档

规范地址：https://npmcn.com/package/%40sps-woodland/tokens/

版本：8\.56\.21
npm 元数据更新时间：2026-11-02T13:15:50.268Z
中文译文更新时间：2026-11-02T13:19:21.326Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：7.2 MB，121 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2023-01-03T21:13:20.848Z
- 最新版本发布：2026-11-02T13:15:50.064Z
- 已发布版本数：457（近 12 个月 137 个）

## 中文简介

SPS设计系统设计令牌

## 安装

```sh
npm install @sps-woodland/tokens
```

也可以使用：`pnpm add @sps-woodland/tokens`、`yarn add @sps-woodland/tokens`、`bun add @sps-woodland/tokens`

## README

# @sps-woodland /令牌

_SPS林地设计系统设计令牌_

1.  [什么是设计标记？](https://npmcn.com/package/%40sps-woodland/tokens/#readme-one-oh-one)
2.  [这个包是如何工作的](https://npmcn.com/package/%40sps-woodland/tokens/#readme-how-it-works)
3.  [可用的格式](https://npmcn.com/package/%40sps-woodland/tokens/#readme-formats)
    1.  [JavaScript /打印稿](https://npmcn.com/package/%40sps-woodland/tokens/#readme-formats--js-ts)
    2.  [CSS](https://npmcn.com/package/%40sps-woodland/tokens/#readme-formats--css)
    3.  [香草精](https://npmcn.com/package/%40sps-woodland/tokens/#readme-formats--vanilla-extract)
    4.  [萨斯](https://npmcn.com/package/%40sps-woodland/tokens/#readme-formats--sass)

## 什么是设计标记？

设计令牌是设计系统的基本要素。它们是设计决策的记录——字体大小、间距值、边框半径等——以人类和机器都可读的格式记录。它们是生成可消费工件的唯一来源，例如CSS类、设计工具的调色板或用于移动应用程序开发的XML文件。

## 这个包是如何工作的

令牌源文件位于 `src/tokens` 目录中。为了从中生成消耗品，我们使用了一个叫做 [风格的字典](https://amzn.github.io/style-dictionary/)，由亚马逊开发。Style Dictionary配置位于包的根目录， `config.js`。Style Dictionary自带许多可以生成的内置格式，您也可以轻松添加自己的格式。在 `src/formats` 您将找到我们创建的自定义格式。

Style Dictionary还有一个“转换”的概念，它适用于标记值。例如，您可能希望在源文件中使用十六进制定义颜色，但在生成的消耗品中输出hsla格式。每种格式都有一组默认的转换。在我们的例子中，我们正在修改我们使用的自定义转换组，将源中的大小值作为像素处理，并将其转换为输出中的rem。 (默认是将大小标记的值视为rem并简单地附加 `"rem"` 为它们提供输出。)

此外，我们还有 [香草精洒](https://vanilla-extract.style/documentation/sprinkles-api/) 其中没有生成定义它们的文件，但是该文件导入了一个生成的文件，该文件在对象中包含令牌，该对象的形状根据洒定义的需要进行了定制。

这意味着构建过程按照特定顺序遵循一系列阶段：

1.  运行 `style-dictionary build` 从令牌源文件生成文件。非typescript输出进入 `lib` 从git中排除，TS输出到 `src` 并且是忠诚的。
2.  运行 `vite build` 提供的TypeScript导出 `src/index.ts` 成 `lib`.
3.  运行 `tsc` 使用标记只发出要生成的声明 `.d.ts` 文件 `lib` 对于使用TypeScript的消费者来说。

## 格式

### JavaScript /打印稿

对于JS/TS代码，我们导出一个简单的令牌值对象，以及它的TypeScript类型。

```typescript
import { tokens } from "@sps-woodland/tokens";

console.log(tokens.size.spacing.lg); // "2rem"
```

### CSS

提供了两个CSS文件：一个文件将令牌声明为 [CSS自定义属性](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)另一个定义了实用程序类来应用它们。实用程序类是使用自定义属性定义的，因此如果希望使用这些属性，则必须包含这两个文件。

```typescript
// in index.tsx or App.tsx for your application
import "@sps-woodland/tokens/lib/css/tokens.css";
import "@sps-woodland/tokens/lib/css/utils.css";
```

```css
/* usage in CSS */
.some-element {
  color: var(--color-blue-medium);
}
```

```jsx
// usage in JSX
<div className="mt-sm type-body-md">...</div>
```

#### 可用的实用程序类

-   的颜色, `.COLOR-VARIANT`,如。 `.purple-dark` 或者 `.grey-medium-light`
-   背景颜色，如 `.bg-COLOR-VARIANT`,如。 `.bg-blue-light`
-   bootstrap风格的边距和间距类，如 `.PREFIX-SIZE`,在那里 `PREFIX` 要么是 `m` 保证金或 `p` 用于填充，可选后跟 `t`/`b`/`l`/`r` 上/下/左/右或 `x`/`y` 对于x（左+右）/y（上+下）。例如:
    -   `.my-sm` = margin- y, small （margin-top和margin-bottom的间距较小）
    -   `.p-md` = padding medium（中等间距的填充）
    -   `.ml-xs` =左边距，特别小
-   字体粗细(`.fw-normal` 和 `.fw-bold`）
-   字体大小+行高组合，例如： `.type-body-md` 对于中等体型， `.type-title-lg` 适用于大标题字体等。
-   字体大小和行高，例如： `.fs-body-sm` 对于小字体， `.lh-title-sm` 对于小标题行高度等。

### 香草精

SPS未来UI样式的工具是 [香草精](https://vanilla-extract.style/)，因此我们提供我们的设计令牌为 [洒](https://vanilla-extract.style/documentation/sprinkles-api/).

要使它们工作，你需要在你的索引或主应用组件中导入与它们一起的CSS文件：

```typescript
import "@sps-woodland/tokens/lib/vanilla-extract/style.css";
```

然后，在你的 `.css.ts` 文件，你可以导入我们的sprinkles，并根据上面的sprinkles文档链接使用它们。

```typescript
import { style } from "@vanilla-extract/css";
import { sprinkles, rem } from "@sps-woodland/tokens";

export const fooClass = sprinkles({
  color: "blue-medium",
  marginTop: "md",
});

// or with additional custom styles - again, see the vanilla-extract docs
export const barClass = style([
  sprinkles({
    color: "red-dark",
    type: "title-xl",
  }),
  /* We also export this utility function for your custom style
   * definitions in vanilla-extract. It will find all the pixel values
   * within and convert them to rem. */
  rem({
    maxWidth: "200px",
  }),
]);
```

### 萨斯

Sass的消耗品本质上与CSS相同。有一个文件是用于令牌的Sass变量，还有一个文件是使用这些变量定义的实用程序类。

```scss
// in your root scss file
@import "@sps-woodland/tokens/lib/scss/tokens";
@import "@sps-woodland/tokens/lib/scss/utils";
```

## 常见问题

### @sps-woodland/tokens 是什么？

SPS设计系统设计令牌

### 如何安装 @sps-woodland/tokens？

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

### @sps-woodland/tokens 支持 TypeScript 吗？

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

### @sps-woodland/tokens 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @sps-woodland/tokens 可以商用吗？

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

### @sps-woodland/tokens 还在维护吗？

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