# @aziontech/theme 中文文档

规范地址：https://npmcn.com/package/%40aziontech/theme/

版本：5\.2\.2
npm 元数据更新时间：2026-11-03T18:01:55.261Z
中文译文更新时间：2026-11-07T15:39:50.535Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：285 kB，170 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2026-03-17T15:04:11.567Z
- 最新版本发布：2026-11-03T18:01:54.936Z
- 近 30 天下载量：7150（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 47 个）

## 中文简介

Azion的设计托克系统,编成单一的 **尾风 CSS v4** 样式表:原始调色板、品牌颜色、轻度/暗度语义符号、全文版缩放、运动工具以及 `@keyframes`,则 `@font-face` 设置——外加生代号d

## 安装

```sh
npm install @aziontech/theme
```

也可以使用：`pnpm add @aziontech/theme`、`yarn add @aziontech/theme`、`bun add @aziontech/theme`

## README

# @aziontech/主题

Azion的设计托克系统,编成单一的 **尾风 CSS v4** 样式表:原始调色板、品牌颜色、轻度/暗度语义符号、全文版缩放、运动工具以及 `@keyframes`,则 `@font-face` 设置 —— 加上作为可导入 JavaScript 的原始符号数据.

货包装有一件预先建造的文物`dist/v4/globals.css`以及4个JS小切入点. 没有 Tailwind 预设, 插件, 或 `tailwind.config.js` 步骤——v4读取 `@theme` 编号 : `@utility` 定义直接取自导入的 CSS .

## 安装

```bash
npm install @aziontech/theme
# or
pnpm add @aziontech/theme
# or
yarn add @aziontech/theme
```

Tailwind CSS v4 必须在耗入的构建中存在 — 样式表以 `@import "tailwindcss"`。 。 。 .

## 快开始

### 1\. 导入样式表

在您的应用程序根 CSS 中:

```css
@import '@aziontech/theme';
```

或来自 JavaScript( Vite and friends) :

```javascript
import '@aziontech/theme'
```

该单项进口规定:

-   页:1 `@font-face` azion 类型系统的申报(不需要单独导入字体);
-   每个原始CSS变量(颜色、间隔、形状、打字、效果、断点);
-   语义上的光/暗变量(`--primary`, (中文(简体) ), `--text-default`, (中文(简体) ), `--surface-0`(......);
-   文本风格的公用事业`text-heading-2xl`, (中文(简体) ), `text-big-number-md`具有响应性大小;
-   动画公用事业及其 `@keyframes` (消费者将每门运动课与 `motion-reduce:` 倒计时).

### 2\. 切换主题

光是默认值( L)`:root`) (中文(简体) ). 黑暗模式在这些钩子上激活:

```html
<html data-theme="dark">
  <!-- or -->
  <body class="dark">
    <!-- or the legacy pair -->
    <div class="azion azion-dark"></div>
  </body>
</html>
```

```javascript
// Toggle at runtime
document.documentElement.dataset.theme = 'dark' // or 'light'
```

光模式选择器 : `:root`, (中文(简体) ), `[data-theme='light']`, (中文(简体) ), `.azion.azion-light`。 。 。 . 暗模式选择器 : `[data-theme='dark']`, (中文(简体) ), `.dark`, (中文(简体) ), `.azion.azion-dark`。 。 。 .

## 出口

整个公共表面,从 `package.json#exports`数字 :

| 路径 | 这是什么 |
| --- | --- |
| `@aziontech/theme` | 编译的样式表(`dist/v4/globals.css`(中文(简体) ) |
| `@aziontech/theme/colors` | 颜色原始 : `primitives`, (中文(简体) ), `brandPrimitives`, (中文(简体) ), `surfacePrimitives` |
| `@aziontech/theme/animations` | 运动原始: `animate`, (中文(简体) ), `curve`, (中文(简体) ), `duration`, (中文(简体) ), `useWhen` |
| `@aziontech/theme/texts` | `textsData` – 每个文本样式的字体大小/行高/重量捆绑 |
| `@aziontech/theme/theme-colors` | 语义编译器 : `compileThemeVars`, (中文(简体) ), `compileThemeCss`, (中文(简体) ), `injectThemeCss` |

## JavaScript 令牌访问

### 颜色原始

```javascript
import { primitives, brandPrimitives, surfacePrimitives } from '@aziontech/theme/colors'

primitives.orange[500] // '#F3652B' — primary brand
primitives.blue[500] // '#0072F5' — accent
primitives.violet[500] // '#8A84EC' — brand.accent palette
primitives.gray[900] // '#141414'

brandPrimitives.primary[500] // '#F3652B'
brandPrimitives.absolute.white // '#FFFFFF'

surfacePrimitives.surface[0] // '#FFFFFF'
surfacePrimitives.surface[950] // '#0A0A0A'
```

可用的调色板 : `base`, (中文(简体) ), `blue`, (中文(简体) ), `gray`, (中文(简体) ), `slate`, (中文(简体) ), `orange`, (中文(简体) ), `violet`, (中文(简体) ), `yellow`, (中文(简体) ), `green`, (中文(简体) ), `red` - 再加上 `brand`, (中文(简体) ), `surface`,以及 `alpha` 组合.

### 原始运动

```javascript
import { curve, duration, animate } from '@aziontech/theme/animations'

curve['productive-exit'] // easing cubic-bezier
duration['fast-02'] // ms value
animate.shimmer // keyframe-backed animation definition
```

### 文本样式

```javascript
import { textsData } from '@aziontech/theme/texts'

textsData['text-heading-2xl']
// { fontSize: { _: '1.875rem', sm: '3rem', md: '3.5rem' }, lineHeight: 1.25, fontWeight: 400 }
```

响应 `fontSize` 键`_`, (中文(简体) ), `sm`, (中文(简体) ), `md`变成 `@media (min-width: …)` 超过编译的公用事业.

### 语义变量作为JS(节点/构建步骤/运行时间)

```javascript
import { compileThemeVars, compileThemeCss, injectThemeCss } from '@aziontech/theme/theme-colors'

compileThemeVars()
// → { light: { '--primary': '#F3652B', '--text-default': '#141414', … }, dark: { … } }

compileThemeCss()
// → ':root, [data-theme=light], .azion.azion-light { … }\n\n[data-theme=dark], .dark, … { … }'

injectThemeCss() // appends a <style data-azion-theme> element to <head>
```

只有在无法预先编译时才有用——生产用法应该更偏好静态样式表.

## CSS 变量

语义层在模式间自动翻转 :

```css
:root,
[data-theme='light'],
.azion.azion-light {
  --primary: #f3652b;
  --text-default: #141414;
  /* … */
}

[data-theme='dark'],
.dark,
.azion.azion-dark {
  --text-default: #fafafa;
  /* … */
}
```

直接使用它们 :

```css
.custom-component {
  color: var(--text-default);
  border-color: var(--primary);
}
```

同样式表(如:. `@utility text-default`),这样 `class="text-default"` 泰风在任何地方都行.

## 调制解析

Tokens 使用可维护性参考系统:

```javascript
// Define token reference
const textColor = tokenRef('primitives.gray.900')

// The compilers (scripts/compile-primitives.js, scripts/compile-theme.js)
// resolve refs to literal values at build time — and throw, listing every
// miss, if a ref does not resolve.
compileThemeVars()
// Output: { light: { '--text-default': '#141414', … }, dark: { … } }
```

全文——得到支持 `tokenRef` 前缀, 构建管道, 如何添加一个符号—— 生活在 [`src/tokens/README.md`](https://npmcn.com/package/%40aziontech/theme/src/tokens/README.md)。 。 。 .

## 发展

```bash
pnpm build:tokens # node src/scripts/build-tokens.mjs → dist/v4/globals.{css,scss}
pnpm build:dts    # vue-tsc --declaration (emit .d.ts next to sources)
pnpm format       # prettier over scripts/ and src/
pnpm pack:dry     # inspect the tarball contents
```

`dist/` 承诺 `prepack` 重运行 `build:tokens` + 键 `build:dts` ——每所出版的作品都从源头重建出文物,故作"活活"或"活活" `dist/` 永远不能飞船.

### 项目结构

```
packages/theme/
├── tokens.js                    # in-repo JS barrel (not shipped — use the subpath exports)
├── src/
│   ├── tokens/
│   │   ├── primitives/          # colors (brand/surface/alpha), typography, shape, effects, animations, …
│   │   ├── semantic/            # texts/containers/spacings/z-indices data + semantic color refs
│   │   ├── theme/               # light/dark semantic groups (primary, background, text, ring, feedback/…)
│   │   └── README.md            # in-depth token documentation
│   └── scripts/
│       ├── refs.js              # tokenRef + isTokenRef + assertResolvedRefs
│       ├── compile-primitives.js
│       ├── compile-theme.js     # exported as ./theme-colors
│       └── build-tokens.mjs     # main entrypoint: emits dist/v4
├── dist/v4/globals.css          # the shipped stylesheet (committed; rebuilt on publish)
└── package.json
```

## 浏览器支持

有CSS自定义属性支持的现代常绿浏览器(Chrome,Firefox,Safari,Edge).

## 版本

此软件包随后 [语义版本](https://semver.org/)。版本由 [请放行](https://github.com/googleapis/release-please): 合并为 `main` 更新一个 Release PR,并合并 Release PR 剪切版本并发布.

## 捐款

这个包是Azion WebKit monorepo的一部分. 请参看捐款准则的主要存放处.

## 许可证

麻省理工学院阿齐翁技术

## 链接

-   [GitHub 仓库](https://github.com/aziontech/webkit)
-   [国家防范机制一揽子计划](https://www.npmjs.com/package/@aziontech/theme)
-   [问题跟踪器](https://github.com/aziontech/webkit/issues)

## 更改日志

见 [变动情况](https://npmcn.com/package/%40aziontech/theme/CHANGELOG.md) 为释放历史.

## 常见问题

### @aziontech/theme 是什么？

Azion的设计托克系统,编成单一的 尾风 CSS v4 样式表:原始调色板、品牌颜色、轻度/暗度语义符号、全文版缩放、运动工具以及 @keyframes,则 @font-face 设置——外加生代号d

### 如何安装 @aziontech/theme？

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

### @aziontech/theme 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/aziontech\_\_theme 是否存在。

### @aziontech/theme 支持 ESM 还是 CommonJS？

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

### @aziontech/theme 可以商用吗？

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

### @aziontech/theme 的下载量有多少？

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

### @aziontech/theme 还在维护吗？

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