# @alma-oss/spirit-design-tokens 中文文档 规范地址：https://npmcn.com/package/%40alma-oss/spirit-design-tokens/ 版本：5\.2\.1 npm 元数据更新时间：2026-10-19T10:34:18.076Z 中文译文更新时间：2026-11-06T08:20:42.759Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40alma-oss/spirit-design-tokens 原文对照：https://npmcn.com/package/%40alma-oss/spirit-design-tokens/?lang=original 项目主页：https://github.com/alma-oss/spirit-design-system#readme 源码仓库：https://github.com/alma-oss/spirit-design-system ## 关键信息（来自 npm 元数据） - 包体积（解压后）：547 kB，41 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=22 - 运行依赖：0 个 - 首次发布：2025-12-15T11:36:11.140Z - 最新版本发布：2026-10-19T10:34:15.812Z - 近 30 天下载量：3896（2026-10-06 至 2026-11-04，npm 官方下载统计） - 已发布版本数：15（近 12 个月 15 个） ## 中文简介 精神设计系统设计标志 ## 安装 ```sh npm install @alma-oss/spirit-design-tokens ``` 也可以使用：`pnpm add @alma-oss/spirit-design-tokens`、`yarn add @alma-oss/spirit-design-tokens`、`bun add @alma-oss/spirit-design-tokens` ## README # @alma-oss/spirit-design-tokes (英语) > 精神设计系统的设计标志. 精神设计标志 与和生成 [超级新星](https://spirit.supernova-docs.io/). . . . . . ! ## 目录 1. [可用设计键](https://npmcn.com/package/%40alma-oss/spirit-design-tokens/#readme-available-design-tokens) 1. [全球键](https://npmcn.com/package/%40alma-oss/spirit-design-tokens/#readme-global-tokens) 2. [主题键](https://npmcn.com/package/%40alma-oss/spirit-design-tokens/#readme-theme-tokens) 2. [主题](https://npmcn.com/package/%40alma-oss/spirit-design-tokens/#readme-themes) 3. [安装](https://npmcn.com/package/%40alma-oss/spirit-design-tokens/#readme-install) 4. [基本用途](https://npmcn.com/package/%40alma-oss/spirit-design-tokens/#readme-basic-usage) 1. [在萨斯](https://npmcn.com/package/%40alma-oss/spirit-design-tokens/#readme-in-sass) 2. [在 Java 脚本中](https://npmcn.com/package/%40alma-oss/spirit-design-tokens/#readme-in-javascript) 5. [单位 - `rem`](https://npmcn.com/package/%40alma-oss/spirit-design-tokens/#readme-units--rem) 6. [重塑精神](https://npmcn.com/package/%40alma-oss/spirit-design-tokens/#readme-rebranding-spirit) 1. [使用带有类型脚本的设计套件](https://npmcn.com/package/%40alma-oss/spirit-design-tokens/#readme-using-your-design-tokens-with-typescript) 7. [财务问题](https://npmcn.com/package/%40alma-oss/spirit-design-tokens/#readme-faq) 8. [许可证](https://npmcn.com/package/%40alma-oss/spirit-design-tokens/#readme-license) ## 可用设计键 技术上,设计代币被分为两类:全球代币和主题代币. 全球地标在主题上独立共享,而主题地标则针对特定主题. 他们都由我们管理 [图片](https://www.figma.com/design/w9Ca4hvkuYLshsrHu1bYwT/) 并出口到我们 [超新星工作空间](https://spirit.design/)。 。 。 . 所有内容在 `src` 是由超新星生成的,不应手动编辑. 这个 `scss` 目录包含 `@tokens.scss` 连接所有可用的符号(包括全局和主题符号). ### 全球键 这一类别包括: - ++ 边框 - 渐变 - 其他情况 - 🎱(Radii) - \* 阴影 - \* 间距 - \* 类型 这些纪念物是在全球范围内独立分享的. ### 主题键 目前,QQ色彩组中只有符号可以被主题使用. ## 主题 您可以在 `@themes` 文档中 `scss/themes` 目录. 每个主题都有自己的目录,有同一套设计符号,但有不同的值. 目前,我们支持两个光模式色彩主题: - 光默认( 先在 `@themes`,即默认主题) - 点亮品牌 这两个主题都可以在同一页的任何地方使用,并根据需要合并. ### 使用主题 这个 `scss` 目录包含 `@themes.scss` 将所有可用的主题作为 Sass 变量链接. 从技术角度看,主题词是基于CSS变量. **然而,这个一揽子 目前不直接提供 CSS 变量.** 相反,它们产生于 页:1 `@themes` 文档中 [`spirit-web`](https://github.com/alma-oss/spirit-design-system/tree/main/packages/web#readme) 软件包. ## 安装 🙋🏻‍♂️ **坚持住! 您已经使用 [`spirit-web`](https://github.com/alma-oss/spirit-design-system/tree/main/packages/web#readme)? 吗?** 那你就不用这样了 安装此软件包是因为 `spirit-design-tokens` 自动安装 a. 附属公司 `spirit-web`。 。 。 . 如果你想使用刚刚 `spirit-design-tokens` 单枪匹马地跑 ```shell yarn add @alma-oss/spirit-design-tokens ``` 或者说 ```shell npm install --save @alma-oss/spirit-design-tokens ``` ## 基本用途 ### 在萨斯 萨斯语(有SCSS语法)是用于造型"精神"组件的主要语言. 使用设计符号的最好方法是在萨斯装入他们的路径: ```shell sass --load-path=node_modules/@alma-oss/spirit-design-tokens/scss my-styles.scss ``` 或者把它们融入你的建筑系统: 实例 : ```javascript // vite.config.js // … import { defineConfig } from 'vite'; export default defineConfig({ css: { preprocessorOptions: { scss: { includePaths: [path.resolve(__dirname, 'node_modules/@alma-oss/spirit-design-tokens/scss')], }, }, }, }); // … ``` Webpack 实例 `sass-loader`数字 : ```javascript // webpack.config.js // … module: { rules: [ { test: /\.scss$/, use: [ 'style-loader', 'css-loader', { loader: 'sass-loader', options: { sassOptions: { includePaths: [ path.resolve(__dirname, 'node_modules'), path.resolve(__dirname, 'node_modules/@alma-oss/spirit-design-tokens/scss'), ], }, }, }, ], }, ]; } // … ``` #### 使用 `sass-embedded` 图书馆 如果你在用的话 `sass-embedded`,您可以指定 API 为 `legacy`, (中文(简体) ), `modern`,或 `modern-compiler`。更多信息可在 [粗略文档](https://sass-lang.com/documentation/breaking-changes/legacy-js-api/#bundlers)。 。 。 . 我们建议使用 `modern-compiler` 选项. 请注意,这一变化还需要更新 `includePaths` 改为 `loadPaths`。 。 。 . 网络包装和 `sass-embedded`数字 : ```javascript // webpack.config.js // … module: { rules: [ { test: /\.scss$/, use: [ 'style-loader', 'css-loader', { loader: 'sass-loader', options: { api: 'modern-compiler', sassOptions: { loadPaths: [ path.resolve(__dirname, 'node_modules'), path.resolve(__dirname, 'node_modules/@alma-oss/spirit-design-tokens/scss'), ], }, }, }, ], }, ]; } // … ``` 这个 [`spirit-web`](https://github.com/alma-oss/spirit-design-system/tree/main/packages/web#readme) 软件包或您自己的组件可以简单地达到这样的符号值: ```scss @use 'sass:map'; @use '@tokens' as tokens; .MyComponentThatMightGoToSpiritInFuture { margin-bottom: tokens.$space-300; font-family: map.get(tokens.$body-medium-regular, mobile, font-family); color: tokens.$text-primary; } ``` 对于您的组件, 您也可以直接装入符号文件 : ```scss @use 'node_modules/@alma-oss/spirit-design-tokens/scss/@tokens' as tokens; ``` ### 在 Java 脚本中 此外,设计符号也作为JavaScript对象提供. ```js import * as SpiritDesignTokens from '@alma-oss/spirit-design-tokens'; const desktopBreakpoint = SpiritDesignTokens.breakpoints.desktop; ``` 其结构与萨斯语相同. ## 单位 - `rem` 所有数字"灵"设计符号(相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相相去相去相去相去相去相去相去相去相去相去相去相去相去相 `rem` 单位 相对于根字体大小,默认为 **16 个 px**。 。 。 . ```js import { space700, space1000 } from '@alma-oss/spirit-design-tokens'; console.log(space700); // → '1rem' (= 16 px at default root size) console.log(space1000); // → '2rem' (= 32 px at default root size) ``` ```scss @use '@tokens' as tokens; .MyComponent { margin-bottom: tokens.$space-700; // → 1rem } ``` 每个设备在 `fontSizeBaseMobile`, (中文(简体) ), `fontSizeBaseTablet`,以及 `fontSizeBaseDesktop` (所有项目) `16px` (默认情况下). 如果你改变了你的 项目的根字体大小, 全部 `rem` 符号值将相应缩放——这是故意的 并保持布局与用户字体大小偏好的比例. 充分解释转换如何运作以及精神中有哪些公用事业可用 软件包,参见 [单位指南](https://github.com/alma-oss/spirit-design-system/tree/main/docs/contribution/units.md)。 。 。 . ## 重塑精神 该系统的设计容易被重新命名. 为此,你需要提供 您自己的设计标志和使用 `@tokens` 财务报告和审定财务报表 `@themes` 文档。 然后把信物转过来 并设置 [正确的加载路径](https://npmcn.com/package/%40alma-oss/spirit-design-tokens/#readme-basic-usage) 你的项目. 您的标志应该包含 与精神标志相同的结构。 最简单的 这样做的方法是在您的 Figma 文件里有相同的结构并导出它 使用超新星. 如果不可能的话,你可以复制我们的代币并调整其价值 满足你的需求。 也可以添加您设计系统所需的新标志. ### 使用带有类型脚本的设计套件 如果您想要使用自己的一组设计符号, 而不是由 `@alma-oss/spirit-design-tokens`, (中文(简体) ), 您需要调整您的项目的 TypeScript 配置和构建系统设置,以正确解决导入问题. 添加以下路径到您的 `tsconfig.json`数字 : ```json { "compilerOptions": { "paths": { "@alma-oss/spirit-design-tokens": ["path-to-your-design-tokens-directory-or-package/js"], "@alma-oss/spirit-design-tokens/*": ["path-to-your-design-tokens-directory-or-package/*"] } } } ``` 然后,调整您的构建系统设置,以正确解决导入问题. 下面可以看到不同构建系统的例子: Webpack 实例 请修改您的 `webpack.config.js`数字 : ```javascript import path from 'path'; export default config({ resolve: { alias: { '@alma-oss/spirit-design-tokens': path.resolve(__dirname, 'path-to-your-design-tokens-directory-or-package'), }, }, }); ``` 虚拟示例 请修改 `vite.config.ts`数字 : ```javascript import { defineConfig } from 'vite'; import path from 'path'; export default defineConfig({ resolve: { alias: { '@alma-oss/spirit-design-tokens': path.resolve(__dirname, 'path-to-your-design-tokens-directory-or-package'), }, }, }); ``` Next.j 实例 请修改 `next.config.ts`数字 : ```javascript import type, { NextConfig } from "next"; import path, {dirname} from "path"; import { fileURLToPath } from "url"; const pathDir = dirname(fileURLToPath(import.meta.url)); const nextConfig: NextConfig = { transpilePackages: ['@alma-oss/spirit-web-react'], reactStrictMode: true, sassOptions: { implementation: 'sass-embedded', includePaths: [ path.join(pathDir, './node_modules'), path.join(pathDir, 'path-to-your-design-tokens-directory-or-package/scss'), ], }, webpack: (config) => { config.resolve.alias['@alma-oss/spirit-design-tokens'] = path.resolve('path-to-your-design-tokens-directory-or-package'); return config; }, }; export default nextConfig; ``` ### 组件半径覆盖 要覆盖所有大小的组件默认半径, 请使用此模式在设备收藏中添加一个符号 : `device//radius`。 。 。 . 要覆盖一个组件大小, 使用 : `device///radius`。 。 。 . 例如: ```text device/tag/radius device/tag/xsmall/radius ``` 每个令牌槽必须提供移动,平板和桌面模式. 当一个槽不完整时 Sass 编译失败 。 当两者 槽存在,大小特有半径优先于组件级半径. 组件默认半径 当两个槽都不存在时,仍然是倒数. 半径 CSS 仅为存在的符号槽生成. 按键和窗体字段大小槽包含在默认的精神中 符号,所以其半径CSS总是生成. 只有主表面半径受到影响。 特别是"神通"(Avatar sord)只适用于方形"神通". 纸牌 适用于盒式卡片和 `CardMedia` 每张卡上都有. `device/skeleton/radius` 适用于文本、标题和 形状骨架; `--spirit-skeleton-shape-radius` 仍然在形状上覆盖设备符号 。 组件名称通常 符合他们的CSS课程。 以下符号使用公共组件名来代替拥有地表的类: - `device/dropdown/radius` 适用于 `DropdownPopover`· ; - `device/form-field//radius` 适用于 `InputContainer`· ; - `device/form-field/medium/radius` 也适用于 `FileUploadInput__dropZone`· ; - `device/modal/radius` 适用于 `ModalDialog`· ; - `device/toast/radius` 适用于 `ToastBar`· ; - `device/tooltip/radius` 适用于 `TooltipPopover`。 。 。 . 在互动面上测试极端自定义辐射,以确保焦点指标和内容不被视觉剪接. ### 组件颜色覆盖 关于彩色方案如何运作以及这些套接字在哪些地方适合,请参见 [颜色方案](https://github.com/alma-oss/spirit-design-system/blob/main/docs/content/color-schemes.md) 向导. 要覆盖组件的默认颜色方案,您可以使用以下模式添加符号: `component---`。 。 。 . 例如,要覆盖默认的微妙颜色 [`Pill`](https://github.com/alma-oss/spirit-design-system/blob/main/packages/web/src/scss/components/Pill/README.md) 联合国 `emotion-success` 颜色,您可以添加以下符号: ```text component/pill/emotion-success-content-subtle ``` 或更改 `emotion-success` (不是微妙的)变体完全,你可以添加以下符号: ```text component/pill/emotion-success-background-basic component/pill/emotion-success-content-subtle ``` 这些符号是可选的,它们为组件生成了新的类. ## 财务问题 我为什么要重命名 `@tokens` 改为 `tokens` 何时使用? 因为 @ use the `@tokens` 不重命名模块将产生错误 : ```log Error: Invalid Sass identifier "@tokens" ╷ 1 │ @use '@tokens'; │ ^^^^^^^^^^^^^^ ``` 为什么那里 `@` 前缀吗 ? 我们的前缀 `@tokens.scss` 文件为 `@` 以区别于其他萨斯人 目录中的文件. 为了让开发者知道文件行为不同于通常的 Sass 部分,a `@` 添加前缀以标记此行为在文件系统中和 在Sass文件内。 由此可知何以如来. `@use 'tools'` 提及 本地文件和 `@use '@tokens'` 没有。 不过, **这只是一个命名 公约,** sass 部件没有特殊的工具或配置 从开始 `@`。 。 。 . 导入模块 **需要重新命名以兼容SCSS** 语法 当后用. 这就是为什么 `@use '@tokens' as tokens`。 。 。 . 看看下面的片段,比较一下哪一个更好 相会相会. 无 `@` 前缀 : ```scss // _Button.scss @use 'tools'; // Calls './_tools.scss'. You don't have to explain this to me. @use 'tokens'; // Wait, this file doesn't exist… What's going on here? Is it // an error? ``` 与 `@` 前缀 : ```scss // _Button.scss @use 'tools'; // Calls './_tools.scss'. @use '@tokens' as tokens; // OK, './_@tokens.scss' is not here, but the at-sign // prefix suggests a special behavior. Maybe I'll learn more in the docs? ``` 我如何为自己的设计系统获得设计标志? **创建由"精神"衍生的自定义设计系统? 很高兴听到这个** 虽然开发一些可能找不到的自定义组件很正常 回到精神,你的设计符号需要 **包含所有 Spirit 设计符号** 无论如何,所以所有的精神 组件,你会重新使用你的 商标. 简而言之,如果你要建立一个基于"精神"的设计系统: 1. 复制并粘贴所有设计标志 从这里, 2. 改变他们的价值观以满足你的需求, 3. 随便再加点什么, 4. 在代码中使用您的设计符号( 并用它们来编译 Spi精神) . 让你的Sass设计标志 与Spirit兼容 别忘了曝光 他们通过萨斯负载路径. 我需要主题吗? 如果是的话,有多少人? 您需要至少一个主题来定义您设计符的默认值 . 如果您想要支持多个主题,可以添加更多. 主题数量 取决于您和您的设计系统要求. 但记住,每个主题应该包含 相同的符号集,只是与不同的 数值。 这样就可以在主题之间切换,而不改变组件. ## 许可证 见 [自由主义](https://npmcn.com/package/%40alma-oss/spirit-design-tokens/LICENSE.md) 文档供参考. ## 常见问题 ### @alma-oss/spirit-design-tokens 是什么？ 精神设计系统设计标志 ### 如何安装 @alma-oss/spirit-design-tokens？ 在项目目录运行 npm install @alma-oss/spirit-design-tokens，或使用 pnpm add / yarn add / bun add。 ### @alma-oss/spirit-design-tokens 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @alma-oss/spirit-design-tokens 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @alma-oss/spirit-design-tokens 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @alma-oss/spirit-design-tokens 可以商用吗？ @alma-oss/spirit-design-tokens 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @alma-oss/spirit-design-tokens 的下载量有多少？ 根据 npm 官方下载统计，@alma-oss/spirit-design-tokens 在 2026/10/06 – 2026/11/04 这 30 天内被下载 3,896 次，日均约 130 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @alma-oss/spirit-design-tokens 还在维护吗？ 最新版本 5\.2\.1 发布于 2026/10/19（19 天前）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2025/12/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。