# @appshell/tokens 中文文档

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

版本：1\.0\.0-alpha\.148
npm 元数据更新时间：2026-10-29T16:05:34.621Z
中文译文更新时间：2026-11-06T12:29:57.959Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：37.5 kB，11 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-08-27T12:16:22.179Z
- 最新版本发布：2026-10-29T16:05:32.952Z
- 近 30 天下载量：6276（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：131（近 12 个月 131 个）

## 中文简介

Appshell 设计令牌合同、其预设和对比验证

## 安装

```sh
npm install @appshell/tokens
```

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

## README

# @ appshell/ tokens (帮助)

设计代号合同 应用程序供应 和它所制作的每个软件包消耗.

无法被寄件到主机的组件目录是不可相容的——可视的 一致性是重点。 这个软件包是能够实现的词汇: 46 CSS 自定义属性, 一组预设, 以及保留主题的对比验证 看得出来.

## 对于软件包作者

作者反对这些名字, 总是有一个倒置

```css
.button {
  background: var(--appshell-primary, #0284c7);
  color: var(--appshell-on-primary, #fff);
  border-radius: var(--appshell-radius-md, 0.5rem);
  padding: var(--appshell-space-sm, 0.5rem) var(--appshell-space-md, 1rem);
}
.button:hover {
  background: var(--appshell-primary-hover);
}
.button:focus-visible {
  outline: 2px solid var(--appshell-focus-ring);
  outline-offset: 2px;
}
```

永远不要写一个字形的颜色 你期望被他们。 这是唯一的规则.

## 有尾风v4

尾风包根本不写自定义属性 . `@appshell/tokens/tailwind.css` 将合同映射到 Tailwind 的主题上, 所以 `bg-primary`, (中文(简体) ), `text-on-surface`, (中文(简体) ), `border-border`, (中文(简体) ), `rounded-md`, (中文(简体) ), `text-h2` 财务报告和审定财务报表 `p-md` 用应用程序提供的任何油漆 :

```css
@layer theme, base, components, utilities;
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);
@import '@appshell/tokens/tailwind.css';
@source "../dist";
```

-   **没有飞行前.** 环球重置,外壳拥有一页重置. 几个 包件每发一发是数发相接和相接相接和相接外壳.
-   **一个 `@source` 自己来的.** 尾风只为它找到的类生成一个工具 写下来。 指定您所编译的目录名称, 而非缩写 : 尾风跳过一个 路径消费者的 `.gitignore` 忽略了通过光彩来达到它.
-   **自相违后.** 带有默认调色板的组件库, 如 作为 `@navaris/ui-react`,首先导入默认值,所以应用程序的主题获胜.

色彩角色保留他们的名字(`--color-primary`, (中文(简体) ), `--color-on-surface`页:1 `text-muted`,这是 `--color-muted` 因此工具读取 `text-muted`,以及 `border-control`, (中文(简体) ), 这是 `--color-control` 这么说 `border-control`家庭是 `--font-sans` 财务报告和审定财务报表 `--font-mono`,类型大小 `--text-h1`.`--text-small`,线高 `--leading-tight` 财务报告和审定财务报表 `--leading-normal`和天平 `--spacing-xs`.`xl` 财务报告和审定财务报表 `--radius-sm`编号 :`md`编号 :`lg`。文档来自合同,因为 `TAILWIND_NAMES`,以及 在合同中添加一个没有Tailwind名的角色是不编译的.

## 合同

**颜色为语义;尺寸为尺度.** `--appshell-surface` 说什么颜色 _表示_· ; `--appshell-space-md` 老实说,只是一个尺寸。 没有人愿意 `--appshell-space-card-padding`。 。 。 .

**每个带文字的颜色都有 `on-` 搭档.** 写入 `background: var(--appshell-primary); color: var(--appshell-on-primary)` 你无法 生成一个无法识别的控制器 无论应用程序的调色板。 这也是什么 使暗模式成为价值观的改变而不是逻辑的改变.

| 组 | 作用 |
| --- | --- |
| 表面 | `surface-sunken`, (中文(简体) ), `surface`, (中文(简体) ), `surface-raised` 联合国 `on-` 合作伙伴 |
| 文本行( L) | `text-muted`, (中文(简体) ), `border`, (中文(简体) ), `border-control` |
| 行动 | `primary`, (中文(简体) ), `on-primary`, (中文(简体) ), `secondary`, (中文(简体) ), `on-secondary` |
| 衍生 | `primary-hover`, (中文(简体) ), `primary-active`, (中文(简体) ), `secondary-hover`, (中文(简体) ), `secondary-active`, (中文(简体) ), `focus-ring` |
| 状态 | `danger`, (中文(简体) ), `warning`, (中文(简体) ), `success`, (中文(简体) ), `info` 联合国 `on-` 合作伙伴 |
| 类型 | `font-body`, (中文(简体) ), `font-mono`, (中文(简体) ), `font-size-h1`.`h6`, (中文(简体) ), `-body`, (中文(简体) ), `-small`, (中文(简体) ), `line-height-tight`, (中文(简体) ), `-normal` |
| 尺寸 | `space-xs`.`xl`, (中文(简体) ), `radius-sm`编号 :`md`编号 :`lg` |

**3个地表,通过高地.** `surface` 是页面; `surface-raised` 坐在上面(a) 牌、对话框、菜单)和 `surface-sunken` 下方(页的铬:一个侧边栏,a 导航铁路,一个内置面板. 将文字放入 `on-` 表面的伴侣 它的上.

**两地相接,由所取取.** `border` 是一个分裂者的边缘, 这不需要 查看该页面. `border-control` 是一个控件的边缘,这就是一个字段,一个选择或 发现了一个被概括的按钮, 所以它被保持到3:1 每个表面.

类型大小因其作用而命名,而不是一个 `sm/md/lg` 缩放。 数字 缩放重现合同中存在的差异,以防止——一张作者地图 `h1` 改为 `2xl`,另一个改为 `xl`,标题则停止在由编曲的页面上匹配.

**衍生出的角色成本 一个主题什么都没有.** {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}我们很活跃 `color-mix` 从他们的 重音,焦点环按基调和口音选择. 主题可以覆盖其中任何 它们;不需要供应。 因此,合同公布46人名 而应用程序 作者最多为41人——通常没有,因为它选取了预设.

## 预设:基础 ×口音

主题有两个选择,而不是46个值:

```ts
import { toCss } from '@appshell/tokens';

toCss({ base: 'midnight', accent: 'ice' });
```

**基础** 携带表面、文字、边框和状态,作为浅/暗对: `neutral`, (中文(简体) ), `midnight`。 。 。 . **分数** 带有两个动作颜色: `ice`, (中文(简体) ), `ember`, (中文(简体) ), `emerald`, (中文(简体) ), `violet`, (中文(简体) ), `steel`。两个槽都接受原始符号值,并且 `overrides` 调整预设 却又不放弃它.

每种组合都经过核实——见下文——和 `midnight`编号 :`ice` 来源于第一个 计划迁移的申请.

## 对比性是最重要的验证

语法检查挣得很少。 钓到鱼了 `--appshell-primary: bananas`; 它错过了 `--appshell-on-primary: #fff` 打开 `--appshell-primary: #fff`,这是完全有效的 CSS 和隐形文字.

```ts
import { composeTheme, validateTheme, describeFinding } from '@appshell/tokens';

validateTheme(composeTheme({ base: 'neutral', accent: 'ice' }, 'light')).map(describeFinding);
```

WCAG AA(4.5:1)检查了文本对并读出状态颜色 作为每个表面的文字: 其下的一个填充状态 `on-` 颜色仍然可以 在字段下作为错误消息失败。 重点环和管制边界在 3:1(1.4.11,非正文)在每一地平面上,因为焦点在对话框和边栏中着陆 如页上。 报告一个不会解析的值或一个存储主题之前的角色 而不是抛出, 所以一个坏的标志 不隐藏其余.

预设中夹了四样东西 每样东西本可以运出

-   **尾风 `indigo-500` 对黑白都失败了** —— 4.28和4.22 (中文(简体) ). 有一个 它没有清晰的文本颜色。 这个 `violet` 口音用法 `indigo-600` 换句话说.
-   **重音的焦点戒指消失了** 20个预设组合中的7个. 取而代之的是: 花被保留了,光线只移动到它必须到达的地方 清除3:1.
-   **光电模式 `danger` 原文为4.36:1 `surface-raised`**: 可读取为按钮, 不 作为对话框中字段下的错误。 它从57.7%的光度升至56.7%.
-   **戒指被单在页面上检查过**,20个组合中有8个低于3:1 在对话中,降至2.83。 每一个都只迁移到清理每个需要的地表的地方 冰和翡翠环的光线模式, 它坐在SRGB外面, 它回到里面.

预设与其他人的主题标准相同——测试套房 由20种组合组成,没有发现.

## 颜色格式

值为 `oklch`并使用 `color-mix` 其不透明度 修饰相. 尾风 v3 工具 `bg-primary/50` 作为 `rgb(var(--x) / <alpha-value>)` 财务报告和审定财务报表 需要频道分隔值, 所以一个 v3 软件包要么放弃不透明修改对象 颜色或生成其样式表中的频道分割本地化。 合同不是变形的 对于旧版本.

## 模式

3个状态,而不是2个——明确选择两个方向,加上系统默认:

```css
:root {
  /* light */
}
@media (prefers-color-scheme: dark) {
  :root:not([data-appshell-theme='light']) {
    /* dark, unless light was chosen */
  }
}
:root[data-appshell-theme='dark'] {
  /* dark, chosen */
}
```

只有实际不同的角色在暗块中重现. 类型和维度 永不改变,重复它们会 三倍大小的东西的注册 内含 每页它服务.

## 常见问题

### @appshell/tokens 是什么？

Appshell 设计令牌合同、其预设和对比验证

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

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

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

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

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

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

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

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

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

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

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

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