# @krizaka/tokens 中文文档

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

版本：3\.80\.0
npm 元数据更新时间：2026-11-01T15:27:27.238Z
中文译文更新时间：2026-11-01T16:24:58.365Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：256 kB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2026-10-09T18:11:14.737Z
- 最新版本发布：2026-11-01T15:27:26.908Z
- 已发布版本数：109（近 12 个月 109 个）

## 中文简介

Krizaka语义设计标记（- kz-\*）和品牌主题（Krizaka, Orazaka, Yomizaka, Akinaza）：一个编译为CSS的DTCG源（暗，光，媒体不变量），类型常量和React Native主题。

## 安装

```sh
npm install @krizaka/tokens
```

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

## README

# @ krizaka/令牌

**Krizaka语义设计令牌。** 一个词汇， `--kz-*`，写过一次 [DTCG](https://www.designtokens.org/) JSON并编译成CSS（暗、亮、媒体不变量）、类型化常量和React Native主题。是词汇 krizaka.com已经运行在 (1 974使用，零原始调色板颜色)，现在每个产品共享。

[![npm](https://img.shields.io/npm/v/@krizaka/tokens?color=3b82f6&label=npm)](https://www.npmjs.com/package/@krizaka/tokens) [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://npmcn.com/package/LICENSE)

## 规则

> **组件从不读取调色板颜色，只读取角色。** `bg-zinc-950/70 light:bg-white` → `var(--kz-surface-1)`； `text-zinc-400 light:text-slate-500` → `var(--kz-text-secondary)`； `bg-black/60 text-white` 在图像上 → `var(--kz-scrim)` + `var(--kz-text-on-media)`.

主题是一组 **值**,从来没有一套课程。一个组件针对下面的角色编写一次; 黑暗， 灯光和产品主题（覆盖） `--kz-accent`， `--kz-font-display`……) 只更改值。不 `light:` 变体，否 `dark:` 变体，否 `zinc-*` / `slate-*` / `#hex` 在一个组件中。

## 安装

```bash
npm install @krizaka/tokens
```

| 条目 | 为 | 给了 |
| :-- | :-- | :-- |
| `@krizaka/tokens/tokens.css` | Web(导入一次，通常通过 `@krizaka/tailwind`） | 这个 `--kz-*` 自定义属性。 |
| `@krizaka/tokens` | web上的TS / JS（画布、图表、电子邮件、内联样式） | `tokens` （`var(--kz-…)` 参考文献，camelCase键)， `values.dark` / `values.light` (原始CSS，别名解决)， `TokenName`. |
| `@krizaka/tokens/native` | React Native / Expo | `themes.dark` / `themes.light` (十六进制， `rgba()` 当半透明的), `radius` (dp), `typography`， `motion.ease`、类型 `Theme`； `brands.<id>` (ThemeProvider重写)； `marks.<id>` (标志的标志梯度， `[offset, #rrggbb]` 停止)。 |
| `@krizaka/tokens/brands/<id>.css` | 产品应用程序(`krizaka`， `orazaka`， `yomizaka`， `akinaza`)，在令牌之后 | 品牌的重音家族和剖面梯度，暗与亮。 |
| `@krizaka/tokens/brands/scoped.css` | 显示多个品牌的页面 | `.brand-krizaka`， `.brand-orazaka`， `.brand-yomizaka`， `.brand-akinaza` （暂停的产品的作用域仍在发货，已弃用）。 |

**品牌：** 每个品牌一种颜色，它的标志，图标和页面语言 [`BRAND.md`](https://npmcn.com/package/%40krizaka/tokens/BRAND.md).

```css
@import "@krizaka/tokens/tokens.css";

.card { background: var(--kz-surface-1); border: 1px solid var(--kz-border-default); border-radius: var(--kz-radius-lg); }
```

```ts
import { tokens, values } from "@krizaka/tokens";
element.style.color = tokens.textSecondary;  // "var(--kz-text-secondary)" — follows the theme
chart.gridColor = values.dark.borderSubtle;   // "hsl(0 0% 100% / 0.06)"

import { themes, radius, type Theme } from "@krizaka/tokens/native";
const t: Theme = scheme === "light" ? themes.light : themes.dark;
<View style={{ backgroundColor: t.surface1, borderRadius: radius.lg }} />;
```

### 主题

| 选择器 | 获取 |
| :-- | :-- |
| `:root`， `.theme-dark` | 暗-默认。 `.theme-dark` 重新声明暗值，这样玩家、编辑器或媒体在没有暗值的亮页面中仍然是暗的 `light:` 类在其子树中。 |
| `html.light` | 灯。切换 `light` 课上 `<html>`. |
| `.theme-light` | 子树上的光（暗页面内的主题预览）：光值和别名，对应于 `.theme-dark`. |
| `:root` (不变量) | 两个主题相同: 坐在什么 **在** 媒体 (稀松布、媒体上的文本、对话框叠加) 、状态、 `on-accent`，半径，放宽，字体堆。 |

`color-scheme` 跟随主题，因此滚动条和本机控件匹配。

## 角色

值是CSS写入的内容 `dist/tokens.css`； `→` 标记一个别名，该别名在每个主题中遵循其目标，并 在每个产品覆盖下。

### 颜色

| 令牌 | 关键 | 使用 | 黑暗 | 光 |
| :-- | :-- | :-- | :-- | :-- |
| `--kz-surface-0` | `surface0` | 页面背景：石板（深色），纸（浅色） | `hsl(150 12% 9.5%)` | `hsl(100 14% 96%)` |
| `--kz-surface-1` | `surface1` | 卡，面板 | `hsl(240 5% 9%)` | `hsl(0 0% 100%)` |
| `--kz-surface-2` | `surface2` | 凸起的元素，区域，悬停 | `hsl(240 5% 13%)` | `hsl(240 6% 95%)` |
| `--kz-surface-3` | `surface3` | 有源元件、芯片、轨道 | `hsl(240 4% 17%)` | `hsl(240 5% 90%)` |
| `--kz-media` | `media` | 媒体加载前的背景 | `hsl(240 5% 11%)` | `hsl(240 6% 92%)` |
| `--kz-border-subtle` | `borderSubtle` | 安静的分离器 | `hsl(0 0% 100% / 0.06)` | `hsl(240 6% 0% / 0.06)` |
| `--kz-border-default` | `borderDefault` | 卡片和字段大纲 | `hsl(0 0% 100% / 0.10)` | `hsl(240 6% 0% / 0.10)` |
| `--kz-border-strong` | `borderStrong` | 悬停轮廓，非键盘焦点 | `hsl(0 0% 100% / 0.16)` | `hsl(240 6% 0% / 0.16)` |
| `--kz-text-primary` | `textPrimary` | 标题、正文 (每面 ≥ 4.5:1): 粉笔、墨水 | `hsl(105 17% 93%)` | `hsl(212 49% 22%)` |
| `--kz-text-secondary` | `textSecondary` | 支持文字、标签（每个表面≥4.5:1） | `hsl(240 4% 64%)` | `hsl(240 4% 41%)` |
| `--kz-text-muted` | `textMuted` | 元数据，占位符，已禁用 (≥ 每个曲面上的3:1) | `hsl(240 4% 47%)` | `hsl(240 4% 52%)` |
| `--kz-text-on-media` | `textOnMedia` | 图像或视频上的文本 | `hsl(0 0% 100%)` | \=黑暗 |
| `--kz-accent` | `accent` | 主要动作、链接、选择——产品的标识 | `hsl(217 92% 53%)` | `hsl(217 92% 50%)` |
| `--kz-accent-hover` | `accentHover` | 悬停时的重音 | `hsl(217 88% 45%)` | `hsl(217 88% 42%)` |
| `--kz-accent-soft` | `accentSoft` | 有色背景 (选择，徽章) | `hsl(217 92% 53% / 0.10)` | `hsl(217 92% 50% / 0.08)` |
| `--kz-accent-text` | `accentText` | 作为文本的重音 (链接，活动标签): ≥ 4.5:1在每个表面上 | `hsl(217 92% 68%)` | `hsl(217 92% 42%)` |
| `--kz-accent-2` | `accent2` | 第二重音（梯度） | → `accent` | → `accent` |
| `--kz-on-accent` | `onAccent` | 重音上的文字和图标（≥4.5:1） | `hsl(0 0% 100%)` | \=黑暗 |
| `--kz-ring` | `ring` | 键盘聚焦环 | → `accent` | → `accent` |
| `--kz-brand-gradient-from` / `-via` / `-to` | `brandGradientFrom`… | 分段梯度的品牌-平面自页（ADR-004）：页面表面；每一站都有AA字样。 `-to` 的别名 `surface-0`: 更改其页面表面的应用程序保持无缝的部分结束 | `hsl(222 45% 10%)` → `hsl(232 24% 7%)` → `surface-0` | `hsl(214 95% 93%)` → `hsl(220 60% 97%)` → `surface-0` |
| `--kz-success` | `success` | 状态：成功-填充，边框，圆点，图标（≥3:1） | `hsl(160 84% 39%)` | \=黑暗 |
| `--kz-success-text` | `successText` | 作为小文本的成功: ≥ 4.5:1在每个表面上 | `hsl(158 64% 52%)` | `hsl(160 84% 24%)` |
| `--kz-warning` | `warning` | 状态:警告 | `hsl(38 92% 50%)` | \=黑暗 |
| `--kz-warning-text` | `warningText` | 警告为小文本: ≥ 4.5:1在每个表面上 | `hsl(38 92% 55%)` | `hsl(32 95% 30%)` |
| `--kz-danger` | `danger` | 状态: 错误，破坏性操作 | `hsl(0 84% 60%)` | \=黑暗 |
| `--kz-danger-text` | `dangerText` | 小文本错误（字段信息，紧急倒计时）：≥4.5:1在每个表面 | `hsl(0 91% 71%)` | `hsl(0 72% 40%)` |
| `--kz-info` | `info` | 状态:信息 | → `accent` | → `accent` |
| `--kz-info-text` | `infoText` | 信息作为小文本 (品牌角色) | → `accent-text` | → `accent-text` |
| `--kz-scrim` | `scrim` | 面纱后面的徽章或图片上的标题 | `hsl(0 0% 0% / 0.60)` | \=黑暗 |
| `--kz-scrim-strong` | `scrimStrong` | 更强的面纱 (图像上的长文本) | `hsl(0 0% 0% / 0.80)` | \=黑暗 |
| `--kz-overlay` | `overlay` | 对话框背景 | `hsl(0 0% 0% / 0.70)` | \=黑暗 |

### 形状，深度，运动，类型

| 令牌 | 关键 | 使用 | 黑暗 | 光 |
| :-- | :-- | :-- | :-- | :-- |
| `--kz-radius-sm` | `radiusSm` | 现场，芯片 | `2px` | \=黑暗 |
| `--kz-radius-md` | `radiusMd` | 按钮，菜单 | `2px` | \=黑暗 |
| `--kz-radius-lg` | `radiusLg` | 卡片（方纸） | `0px` | \=黑暗 |
| `--kz-radius-xl` | `radiusXl` | 对话框,单 | `0px` | \=黑暗 |
| `--kz-radius-full` | `radiusFull` | 药丸,《阿凡达》 | `9999px` | \=黑暗 |
| `--kz-shadow-sm` | `shadowSm` | 字段，静止按钮 (仅限web): 1 px墨线，无模糊 | `0 1px 0 hsl(150 30% 3% / 0.6)` | `0 1px 0 hsl(212 49% 24% / 0.12)` |
| `--kz-shadow-md` | `shadowMd` | 菜单，弹出窗口（仅限网页）：在一个工作表上的工作表 | `0 1px 0 …, 4px 5px 0 -2px hsl(150 30% 4% / 0.55)` | `0 1px 0 …, 4px 5px 0 -2px hsl(212 40% 30% / 0.14)` |
| `--kz-shadow-lg` | `shadowLg` | 对话框，工作表 (仅限web) | `0 1px 0 …, 6px 8px 0 -2px …` | `0 1px 0 …, 6px 8px 0 -2px …` |
| `--kz-ease` | `ease` | 笔画：默认曲线（画册） | `cubic-bezier(0.45, 0, 0.2, 1)` | \=黑暗 |
| `--kz-font-sans` | `fontSans` | 界面和运行文本 | `"Atkinson Hyperlegible Next", system-ui, sans-serif` | \=黑暗 |
| `--kz-font-display` | `fontDisplay` | 标题; 产品主题可能会覆盖它 | → `font-sans` | → `font-sans` |
| `--kz-font-mono` | `fontMono` | 标签、说明、脚注、代码 | `"Courier Prime", "Courier New", monospace` | \=黑暗 |

### 论文（记事，ADR-004）

| 令牌 | 本地的 | 角色 | 黑暗 (板岩) | 光(纸) |
| :-- | :-- | :-- | :-- | :-- |
| `--kz-paper-rule-major` / `-minor` | `paperRuleMajor`… | 塞耶斯裁决: 每32 px一条强线，三条细线 | 粉笔在9%/4.5% | 墨蓝色为24% / 10% |
| `--kz-paper-rule-margin` | `paperRuleMargin` | 红色边距线，边距切片编号（≥3:1） | `hsl(8 64% 66%)` | `hsl(5 56% 47%)` |
| `--kz-paper-tag` / `-tag-edge` / `-tag-ink` | `paperTag`… | 标本标签 (马尼拉)，其边缘和孔眼，其打字文本 (≥ 4.5:1) | 石板标签，粉笔墨水 | 马尼拉，近黑色墨水 |
| `--kz-paper-module` / `--kz-paper-line` | \- - - - - - | 统治的广场和线 | `32px` / `8px` | \=黑暗 |

### 材料 (BRAND.md § 6)

| 令牌 | 关键 | 使用 | 黑暗 | 光 |
| :-- | :-- | :-- | :-- | :-- |
| `--kz-radius-xs`， `--kz-radius-2xl` | `radiusXs`， `radius2xl` | 复选框，钥匙，切徽章·页 | `2px`， `0px` | \=黑暗 |
| `--kz-shadow-raised` · `-floating` · `-overlay` | `shadowRaised`… | 凸起 (按钮，卡片)·浮动 (菜单，工具提示)·在页面上 (对话框，吐司)-墨水着色，2-3层; 原生: `shadows.<theme>.raised` （`boxShadow`） | `hsl(240 30% 2% / …)` | `hsl(232 25% 25% / …)` |
| `--kz-surface-sheen` | `surfaceSheen` | 凸起表面的顶部(`bg-sheen`） | `hsl(0 0% 100% / 0.045)` | `hsl(0 0% 100% / 0.7)` |
| `--kz-fill-shade` | `fillShade` | 重音或状态填充的底部 (`bg-fill-shade`） | `hsl(0 0% 0% / 0.12)` | \=黑暗 |
| `--kz-edge-light` · `-on-fill` · `-well` | `edgeLight`… | 凸起表面的1-px顶部边缘·填充·井的内部阴影 | `/ 0.07` · `/ 0.22` ·墨水 `/ 0.5` | `/ 0.9` ·=·墨水 `/ 0.08` |
| `--kz-glass-bg` · `-border` · `-blur` | `glassBg`… | 磨砂玻璃：菜单，弹出窗口，对话框，祝酒词（88%：文本AA高于任何东西） | `hsl(240 5% 12% / 0.88)` | `hsl(0 0% 100% / 0.88)` |
| `--kz-success-soft` · `warning-soft` · `danger-soft` | `successSoft`… | 状态色调: 徽章、警报、行 | `/ 0.14` | `/ 0.10–0.12` |
| `--kz-ring-width` · `-offset` · `-halo` | `ringWidth`… | 标志性焦点环(`focus-ring`） | `2px` · `2px` · `4px` | \=黑暗 |
| `--kz-control-sm` · `md` · `lg` · `field` | `controlSm`… | 控制高度； `[data-density="compact"]` 收紧他们 | `32` · `40` · `48` · `44px` | 紧凑的 `28` · `34` · `40` · `36px` |
| `--kz-cut-shape` · `--kz-cut-size` | `cutShape`， `cutSize` | **的夹子**: 45 ° 切角 (`corner-shape`); `round` 关掉它；本机: `cut.size` | `bevel` · `10px` | \=黑暗 |
| `--kz-ease-spring` | `easeSpring` | 短弹簧：按下、拨动、选择；本地的 `motion.spring` | `cubic-bezier(0.34, 1.36, 0.64, 1)` | \=黑暗 |
| `--kz-duration-instant` · `fast` · `base` | `durationFast`… | 微相互作用≤200ms； **0 ms下 `prefers-reduced-motion`**;本地的 `motion.duration` | `90` · `150` · `200ms` | \=黑暗 |

对比 **测试**,未假定: `pnpm turbo run check` 失败，如果 `text-primary` / `text-secondary` 下降4.5:1或 `text-muted` 在任何表面上的3:1下，或 `on-accent` 在4.5:1以下的重音，在任何主题（WCAG 2.x）。 没有重音可以携带4.5:1的白色文本 _和_ 在4.5:1作为文本阅读 `surface-0`: 重音偏向文本 开始吧，然后 `accent-text` （`text-fg-accent`) 是单词的重音-在每个表面上测试为4.5:1。

## 添加或更改令牌

1.  **来源** ——编辑 `src/tokens/<category>.tokens.json` (DTCG: `$type`， `$value`， `$description`）。
    -   `$value` 是 **黑暗** 值（默认值）；这个 **光** 值进入 `"$extensions": { "com.krizaka": { "light": … } }`。没有扩展名 = 两个主题中的相同值。
    -   别名是 `"{group.token}"` （`"{accent.$root}"` 对于一个组自己的令牌); 它编译为 `var(--kz-…)` 和 可能不带轻值-它跟随它的目标。
    -   CSS名称是与连接的路径 `-` （`text.on-media` → `--kz-text-on-media`)， JS键为camelCase （`textOnMedia`）. 颜色是 `hsl()`;半径是 `px` (本机输出将它们转换为dp)。
2.  **构建** - - - - - - `pnpm --filter @krizaka/tokens build` 写 `dist/` (从不编辑 `dist/`),然后 `pnpm --filter @krizaka/tokens test`: 更新 `tokens.css` 仅在打算进行更改时生成快照 （`vitest run -u`)，并保持对比度测试为绿色。
3.  **变更集** - - - - - - `pnpm changeset`: 一个新的令牌是一个 **小**,更改的值至少为 **小** (它改变了 每个产品)，删除或重命名的令牌a **主要的**. `@krizaka/tokens` 和 `@krizaka/ui` 一起释放 （`fixed` 组)。

## 许可证

[apache - 2.0](https://npmcn.com/package/%40krizaka/tokens/LICENSE)

## 常见问题

### @krizaka/tokens 是什么？

Krizaka语义设计标记（- kz-\*）和品牌主题（Krizaka, Orazaka, Yomizaka, Akinaza）：一个编译为CSS的DTCG源（暗，光，媒体不变量），类型常量和React Native主题。

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

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

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

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

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

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

### @krizaka/tokens 需要什么版本的 Node\.js？

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

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

@krizaka/tokens 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

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

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