# @jirawatpyk/aura-tokens 中文文档

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

版本：5\.82\.0
npm 元数据更新时间：2026-11-01T09:58:54.350Z
中文译文更新时间：2026-11-01T13:49:04.398Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.4 MB，29 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-09-18T10:59:45.968Z
- 最新版本发布：2026-11-01T09:58:54.058Z
- 已发布版本数：112（近 12 个月 112 个）

## 中文简介

AURA设计系统-令牌（CSS变量，顺风预设，Figma变量），主题对比检查和令牌lint。

## 安装

```sh
npm install @jirawatpyk/aura-tokens
```

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

## README

# 〇AURA设计系统 `@jirawatpyk/aura-tokens` (进口 `@aura/tokens`）

企业规范，人类创新。标记，顺风预设，Figma变量，对比度检查和标记lint。组件存在于 [`@jirawatpyk/aura-react`](https://www.npmjs.com/package/@jirawatpyk/aura-react)； `components/` 这是他们的 `window.Aura` 包的 `<script>`标签使用。

## 里面有什么

| 文件 | 什么 |
| --- | --- |
| `tokens.json` | **真相的来源。** 3层：原始→语义（浅色/深色）→组件，加上间距，半径，阴影（每个主题），大小，运动，不透明度，z-index，排版。 |
| `aura.css` | 每个标记作为一个CSS变量。光在 `:root` / `[data-theme="light"]`，暗的 `.dark` / `[data-theme="dark"]`. **生成的。** |
| `aura-fonts.css` | 谷歌字体 `@import` （frances, Inter, JetBrains Mono, Noto Sans Thai）。保持独立，这样屏蔽b谷歌的网络就不会中断 `aura.css`. **生成的。** |
| `aura-fonts.local.css` + `fonts/` | 同样是四个家庭自办的： `@font-face` 包（4.16）中woff2文件的规则 `font-src 'self'` CSP。 `npm run check:fonts` 把它们放在CSP下面。 **生成的。** |
| `tailwind.config.ts` + `tailwind.tokens.cjs` | 顺风v3主题连接到变量(`bg-bg-surface`， `text-fg-danger`， `rounded-aura-xl`， `shadow-aura-overlay` ……)。这个 `.cjs` 是 **生成的**. |
| `aura-tailwind.css` | Tailwind v4的类名相同(`@theme inline`CSS-first)。 **生成的**;导出为 `@jirawatpyk/aura-tokens/tailwind.css`. |
| `figma-variables.csv` | 204个变量：两种模式下的所有颜色（保留别名）、间距、半径和大小。 **生成的。** |
| `components/` | `aura.bundle.js` (集 `window.Aura`)， `aura.components.css`， `index.d.ts`. |
| `eslint-plugin-aura.js` | `aura/no-hardcoded-color`：十六进制，颜色函数（rgb, hsl, oklch, color-mix…），样式值和顺风调色板中的命名颜色 `bg-[#…]` 类。ESLint 9: `import aura from '@jirawatpyk/aura-tokens/eslint-plugin'; export default [aura.configs.recommended];` (5.2)。 |
| `scripts/build-tokens.mts` | 重新生成生成的文件 `tokens.json`. |
| `scripts/a11y-check.js` | 在两个主题中检查210对：在其基础上的文本（WCAG AA），控制边缘和状态标记为3:1，相邻的图表和状态填充间距轻一步。 |
| `scripts/lint-tokens.js` | 硬编码颜色失败（必须保存它们的文件说） `aura-lint: allow-colours` 有理由)。 |

## (5)

```bash
# public on npmjs; internal projects can use GitHub Packages instead (see the repository README)
npm install @aura/tokens@npm:@jirawatpyk/aura-tokens @aura/react@npm:@jirawatpyk/aura-react
# or plain: npm install @jirawatpyk/aura-tokens @jirawatpyk/aura-react
```

```tsx
// app/layout.tsx
import '@aura/tokens/aura-fonts.local.css'; // fonts, self-hosted from the package: works under a font-src 'self' CSP
import '@aura/tokens/aura.css'; // tokens
import '@aura/react/styles.css'; // component styles (with @aura/react)
```

js可以加载相同的类 `next/font` 没有CSP的网站可以使用谷歌字体(`aura-fonts.css` 或者 `<link>` 标签)。两者都在下面的字体。

### 字体

从三种方式中选择一种加载frances， Inter， JetBrains Mono和Noto Sans Thai：

| 选项 | 时使用 | 如何 |
| --- | --- | --- |
| 自托管(4.16) | 您的CSP只允许 `font-src 'self'`，或者您不想要第三方请求 | `import '@jirawatpyk/aura-tokens/aura-fonts.local.css'` - woff2文件在包中发布(`fonts/`（odl -1.1），按unicode范围分割，因此页面只下载它使用的内容 |
| `next/font` | 需要预加载和零布局移位的Next.js应用程序 | 给家庭带来负担 `next/font` 并将AURA字体变量指向它们（如下） |
| 谷歌字体 | 没有CSP，或者允许 `fonts.googleapis.com` 和 `fonts.gstatic.com` | `aura-fonts.css`，或 `<link>` 下面的标签（更快；被阻塞的主机悄悄地失败） |

```html
<!-- Google Fonts from <head> (only without a strict CSP) -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,600&family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400&family=Noto+Sans+Thai:wght@400;500;600&display=swap"
/>
```

```tsx
// app/layout.tsx — next/font (downloads at build time and self-hosts, so font-src 'self' is enough)
import { Fraunces, Inter, JetBrains_Mono, Noto_Sans_Thai } from 'next/font/google';
const display = Fraunces({ subsets: ['latin', 'latin-ext'], axes: ['opsz'], variable: '--next-display' });
const sans = Inter({ subsets: ['latin', 'latin-ext'], variable: '--next-sans' });
const mono = JetBrains_Mono({ subsets: ['latin', 'latin-ext'], weight: '400', variable: '--next-mono' });
const thai = Noto_Sans_Thai({ subsets: ['thai'], variable: '--next-thai' });
// <html className={[display, sans, mono, thai].map((f) => f.variable).join(' ')}>
```

```css
/* app/globals.css, after aura.css — AURA's stacks now use the next/font families */
:root {
  --font-display: var(--next-display), var(--next-thai), serif;
  --font-sans: var(--next-sans), var(--next-thai), sans-serif;
  --font-mono: var(--next-mono), monospace;
  --font-thai: var(--next-thai), sans-serif;
}
```

黑暗主题：放 `class="dark"` (或 `data-theme="dark"`) `<html>`.

### 顺风v4

```css
/* app/globals.css */
@import 'tailwindcss';
@import '@jirawatpyk/aura-tokens/tailwind.css'; /* imports aura.css too */
```

类: `bg-bg-surface`， `text-fg-primary`， `border-border-strong`， `text-fg-danger`， `bg-alert-warning-bg`， `fill-chart-1`， `p-aura-6`， `gap-aura-4`， `rounded-aura-xl`， `shadow-aura-overlay`， `ease-aura-ease`， `duration-aura-fast`， `z-aura-dialog`， `font-display` / `font-sans` / `font-mono`。他们指着 `--aura-*` 变量,所以 `.dark` 或者 `data-theme="dark"` 用no来切换 `dark:` 前缀;该文件还使 `dark:` 跟随这两个开关。 `npm run check:tailwind4` 在CI中使用Tailwind v4编译它。

在现有的顺风主题（shadcn）旁边使用 `@jirawatpyk/aura-tokens/tailwind.prefixed.css` (4.17)。每个名字都承载着 `aura-` （`bg-aura-bg-surface`， `border-aura-border-strong`， `bg-aura-chart-1`， `font-aura-sans`)，没有 `@custom-variant` 也没有 `@import`。进口 `aura.css` 让你自己处于早期阶段，这样你的主题就可以保持它 `--font-*`。React包README中有完整的设置 `@jirawatpyk/aura-react/styles.layer.css`.

### 顺风v3

```ts
// tailwind.config.ts — copy this file, or spread the maps from '@jirawatpyk/aura-tokens/tailwind'
```

```tsx
// ❌ ห้าม
<div className="bg-[#18181b] text-white">
// ✅ ต้อง
<div className="bg-bg-surface-strong text-fg-inverted rounded-aura-xl p-aura-6">
```

### 组件

这个包是一个经典的脚本，如下所示 `window.React` / `window.ReactDOM` 并设置 `window.Aura`：

```tsx
import React from 'react';
import ReactDOM from 'react-dom';
(window as any).React = React;
(window as any).ReactDOM = ReactDOM;
import '@aura/tokens/components.js';
const { Button, TextField, DataTable, Dialog, toast, Toaster } = (window as any).Aura;
```

每个组件的类型都在 `components/index.d.ts`.

## 更改令牌

1.  编辑 `tokens.json` (从来没有 `aura.css`， `tailwind.tokens.cjs`， `aura-tailwind.css` 或CSV)。
2.  `npm run build:tokens` （重新生成生成的文件）。
3.  `npm run a11y` （两个主题中的每个文本/地面对都必须通过AA）。
4.  开一个公关；看到 `GOVERNANCE.md`.

## 构建和发布

```bash
npm run build      # build:tokens + contrast check + dist/
npm publish        # to your private registry
```

## 常见问题

### @jirawatpyk/aura-tokens 是什么？

AURA设计系统-令牌（CSS变量，顺风预设，Figma变量），主题对比检查和令牌lint。

### 如何安装 @jirawatpyk/aura-tokens？

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

### @jirawatpyk/aura-tokens 支持 TypeScript 吗？

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

### @jirawatpyk/aura-tokens 支持 ESM 还是 CommonJS？

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

### @jirawatpyk/aura-tokens 可以商用吗？

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

### @jirawatpyk/aura-tokens 还在维护吗？

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