# @cdx-ui/styles 中文文档

规范地址：https://npmcn.com/package/%40cdx-ui/styles/

版本：0\.3\.12
npm 元数据更新时间：2026-11-04T15:33:19.737Z
中文译文更新时间：2026-11-09T10:27:45.972Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cdx-ui/styles
原文对照：https://npmcn.com/package/%40cdx-ui/styles/?lang=original
项目主页：https://github.com/dfh-candescent/forge-design-system#readme
源码仓库：https://github.com/dfh-candescent/forge-design-system

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

- 包体积（解压后）：2.1 MB，329 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0，uniwind \>=1\.0\.0，react-native \>=0\.76\.0
- 首次发布：2026-04-20T20:19:18.408Z
- 最新版本发布：2026-11-04T15:33:19.396Z
- 近 30 天下载量：2916（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：223（近 12 个月 223 个）

## 中文简介

Forge UI 设计令牌,生成 CSS,色彩公用,并运行时间主题覆盖.

## 安装

```sh
npm install @cdx-ui/styles
```

也可以使用：`pnpm add @cdx-ui/styles`、`yarn add @cdx-ui/styles`、`bun add @cdx-ui/styles`

## README

# @cdx-ui/ 风格

Forge UI 设计令牌,生成 CSS,色彩公用,并运行时间主题覆盖.

## 安装

```sh
pnpm add @cdx-ui/styles
```

## CSS 切入点

导入目标应用程序所需的文件 :

```css
@import '@cdx-ui/styles/theme.css';
@import '@cdx-ui/styles/utilities.css';
```

-   `theme.css` 登记 Tailwind 和 Uniwind 的 Forge 令牌.
-   `utilities.css` 提供生成的打字设备.
-   `web.css` 提供无层次 `.light` 财务报告和审定财务报表 `.dark` 网络应用程序的覆盖 .
-   `vanilla.css` 提供框架独立的自定义属性和打字类.
-   `mui.css` 财务报告和审定财务报表 `cds.css` bridge Forge语义符号到MUI和CDS变量.

生成的源主题也导出 :

```ts
import baseTheme from '@cdx-ui/styles/tokens/base.json';
```

## 运行时间覆盖

A 类 `ThemeOverride` 存储 FI 意图。 它的元数据只包含超度计划版本:

```ts
import { applyThemeOverride, type ThemeOverride } from '@cdx-ui/styles';

const override = {
  $extensions: {
    'com.forge.ui.themeOverride': {
      schemaVersion: '1.0.0',
    },
  },
  inputs: {
    brandPrimary: '#0052cc',
    displayFont: 'Bitter',
  },
  selections: {
    actionSurface: {
      mode: 'linked',
      source: { ref: 'color.brand.700' },
    },
  },
  overrides: {
    'color.content.link': {
      light: { value: '#0052cc' },
      dark: { value: '#80bfff' },
    },
  },
} satisfies ThemeOverride;

const result = applyThemeOverride(override);
```

扩展从生成的基础主题开始,应用输入生成,然后选择,然后 直接的标志覆盖。 运行时间写作稀疏而混凝土. 未知添加剂字段为 由解析器保存,用于前置兼容编辑.

公共显示-font目录由基主题和Figma配置生成:

```ts
import { displayFontCatalog } from '@cdx-ui/styles';

displayFontCatalog.defaultFamily;
displayFontCatalog.families;
```

每个家族条目都包含 `family`, (中文(简体) ), `normalWeights`,以及 `italicWeights`。 。 。 .

## 网页字体

`@cdx-ui/styles/fonts` 说明浏览器必须注册什么才能解决字体符号。 这个 光谱来自符号管道,所以它不能从 `theme.css`。 。 。 .

```ts
import { buildWebFontProviderUrl, forgeWebFontSpec } from '@cdx-ui/styles/fonts';

forgeWebFontSpec.platform; // the `--font-sans` / `--font-mono` families
forgeWebFontSpec.display; // every Display family a ThemeOverride can select

buildWebFontProviderUrl([...forgeWebFontSpec.platform, forgeWebFontSpec.display[0]]);
```

条目是 **基础家庭** 他们用重量和斜体船 登记每个家庭一次 重量和让 `font-weight` 选择面相——这就是浏览器如何解决重量问题,它是什么 制造 `font-medium`, (中文(简体) ), `font-semibold` 财务报告和审定财务报表 `italic` 到达正确的文件。 可获取性各有差异 如果一个家庭没有体重,一个供养者拒绝整个要求, 这就是为什么重量 旅行与姓氏.

静态注册您可以在哪里, 因此预装扫描器在 HTML 解析时会找到字体 : 粘贴已建 URL 为 `<link>`,或者自己写 `@font-face` 对自寄文件的规则 (每张脸一个规则,在基底家族之下 `font-weight` 财务报告和审定财务报表 `font-style` 说明. `loadForgeWebFonts` 在运行时注入链接,并提供给在此之前未知的家庭,例如: FI字体取取器.

## 字体重量和样式

字体符号每个角色命名一个家族—— `--font-sans`, (中文(简体) ), `--font-body`, (中文(简体) ), `--font-mono`, (中文(简体) ), `--font-display`设置重量和样式 `font-medium` 编号 : `font-semibold` 编号 : `font-bold` 编号 : `italic` 在家庭之上已经应用了复合打字工具;每个平台都会解决 他们在一个家庭里登记着所有的脸 原住建筑从 `@cdx-ui/native` 配置插件 .

一个没有斜体表情的家庭 使斜体文字直立而不是斜出 显示 家庭在运行时可以改变,因此其支持随即随行 `--font-display-italic-style` (单位:千美元)`italic` 或者说 `normal`; 以斜体显示文本样式 `[font-style:var(--font-display-italic-style)]` 改为 `italic`桑斯家族和单家家族总是用斜体船,所以 `italic` 对身体是正确的 和单文本.

## 目标适配器

软件包包括Uniwind和MUI的适配器:

```ts
import { expandThemeOverride, toMuiThemeOptions, toUniwindMaps } from '@cdx-ui/styles';
```

当编辑器必须清除先前写的值时, 覆盖 Uninwind 会话即可使用 不触及无关的 CSS 变量的预览 .

## 托肯管线

`tokens/base.json` 是构建的符号源 。 多数符号镜像图像变量并且是 由取来书写; `figma.config.json` 将稳定的收集角色映射到 Figma 收集名称 设置 `outputFile`。 。 。 .

仅存在于代码中的键被添加到 `tokens/base.json` 由手和标记的代号拥有:

```json
"ai-start": {
  "$type": "color",
  "$value": "{color.brand.400}",
  "$extensions": { "com.forge.ui.token": { "source": "code" } }
}
```

抓取时保留了每个标记符号不变,并放下了法格玛不再留下的标记符号 定义。 当 Figma 定义一个代码拥有路径的变量时, 获取失败, 所以一个人决定 其中的值获胜并去除标记。 标记每个模式( E)`modes.light`, (中文(简体) ), `modes.dark`)分别.

```sh
# Fetch and atomically write tokens/base.json
FIGMA_VARIABLES_TOKEN=... pnpm --filter @cdx-ui/styles tokens:fetch

# Validate the complete result without writing
FIGMA_VARIABLES_TOKEN=... pnpm --filter @cdx-ui/styles tokens:fetch -- --dry-run

# Inspect one configured role without writing
FIGMA_VARIABLES_TOKEN=... pnpm --filter @cdx-ui/styles tokens:fetch -- --dry-run --role semantics

# Generate CSS and runtime artifacts
pnpm --filter @cdx-ui/styles tokens:build

# Verify generated artifacts are current and deterministic
pnpm --filter @cdx-ui/styles tokens:check
```

辅助检查作用 `primitives`, (中文(简体) ), `fiPrimitives`, (中文(简体) ), `semantics`,以及 `platform`。 。 。 . 缺少已配置的收藏或所需模式时, 完全获取失败 .

生成的产出 :

-   `css/theme.css`
-   `css/utilities.css`
-   `css/web.css`
-   `css/vanilla.css`
-   `css/mui.css`
-   `css/cds.css`
-   `runtime/token-to-css-var.json`
-   `runtime/override-artifacts.json`

不用手编辑生成的输出 。 单位 `tokens/base.json`手工编辑的只是密码上的代号; 下个获取覆盖编辑到 Figma 拥有的符号.

## 发展

从工作空间根 :

```sh
pnpm --filter @cdx-ui/styles test
pnpm --filter @cdx-ui/styles lint
pnpm --filter @cdx-ui/styles build
```

## 常见问题

### @cdx-ui/styles 是什么？

Forge UI 设计令牌,生成 CSS,色彩公用,并运行时间主题覆盖\.

### 如何安装 @cdx-ui/styles？

在项目目录运行 npm install @cdx-ui/styles，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cdx-ui/styles 支持 TypeScript 吗？

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

### @cdx-ui/styles 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cdx-ui/styles 可以商用吗？

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

### @cdx-ui/styles 的下载量有多少？

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

### @cdx-ui/styles 还在维护吗？

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