# @gnist/themes 中文文档

规范地址：https://npmcn.com/package/%40gnist/themes/

版本：4\.4\.1
npm 元数据更新时间：2026-11-16T14:52:26.239Z
中文译文更新时间：2026-11-16T17:14:48.378Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40gnist/themes
原文对照：https://npmcn.com/package/%40gnist/themes/?lang=original

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

- 包体积（解压后）：774 kB，110 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：@vanilla-extract/css 1\.20\.1
- 首次发布：2024-11-08T12:47:49.806Z
- 最新版本发布：2026-11-16T14:52:25.922Z
- 近 30 天下载量：4133（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：78（近 12 个月 30 个）

## 中文简介

`@gnist/themes` 是一个包含主题、设计符号和原子的库,用于 `@gnist/design-system`,但也可以单独使用. 这是基于 [香草摘录](https://vanilla-extract.style/) 在引擎盖下,需要额外压缩

## 安装

```sh
npm install @gnist/themes
```

也可以使用：`pnpm add @gnist/themes`、`yarn add @gnist/themes`、`bun add @gnist/themes`

## README

# @ gnist/ 设计系统的主题

`@gnist/themes` 是一个包含主题、设计符号和原子的库,用于 `@gnist/design-system`, (中文(简体) ), 但它也可以单独使用。 这是基于 [香草摘录](https://vanilla-extract.style/) 在引擎盖下, 并需要额外的汇编步骤。 见 [设置](https://npmcn.com/package/%40gnist/themes/#readme-setup) 详细情况.

## CSS 层

这个库制作的所有风格都用 `@layer gnist { }`. 这意味着消费者可以超越任何设计系统风格而不出现特异性问题——无层样式总是优先于分层样式.

为确保正确的层顺序,请添加一个 `@layer` 在您主 CSS 文件的顶端声明( 例如) . `globals.css`:

```css
@layer base, gnist;
```

这保证 `gnist` 样式优先于 `base` 样式。 您所写的任何全局或重置的 CSS 应当被包入 `@layer base { }` 因此它不会无意地超越设计系统样式:

```css
@layer base {
  *,
  *::before,
  *::after {
    box-sizing: border-box;
    margin: 0;
  }
}
```

在外边写入样式 `@layer` 将仍然占据最高优先位置,允许您在必要时超越设计系统样式.

## 发展

当在设计系统或gnist-app内写入样式时,使用 `gnistStyle` 财务报告和审定财务报表 `gnistRecipe` 而不是香草节奏 `style` 财务报告和审定财务报表 `recipe`数字 :

```ts
import { gnistStyle, gnistRecipe } from "@gnist/themes/layers.css.js";

const myClass = gnistStyle({ color: "red" });

const myRecipe = gnistRecipe({
    base: { padding: "10px" },
    variants: {
        size: {
            small: { fontSize: "12px" },
            large: { fontSize: "18px" },
        },
    },
});
```

一个提示规则强制执行这个——导入 `style` 从 `@vanilla-extract/css` 或者说 `recipe` 从 `@vanilla-extract/recipes` 将产生一个错误.

请注意: `globalStyle` 财务报告和审定财务报表 `styleVariants` 不自动包裹,必须手动放置在内 `@layer` 需要的时候.

详情见Development.md.

## 概览

该库暴露了以下部分:主题、符号、原子、颜色和打字

### 主题

一个主题是一个 css 类,它设置了许多变量. 开发者可以通过 [键](https://npmcn.com/package/%40gnist/themes/#readme-tokens)。 。 。 .

基本用途:

```ts
import { bilholdLight } from "@gnist/themes/themes/bilholdLight.css.js";

// add the class to the <body> element either inline (e.g in a Next layout) or programatically
document.body.classList.add(bilholdLight);
```

这些主题目前存在,可以用上述方式提及

```
audi
autoria
bilholdLight
brandless
cupra
dahles
gumpen
mollerBil
seat
skoda
vw
```

### 键

Tokens允许您根据我们的设计符号结构, 以安全的方式, 对 Css 变量进行编程检查 .

示例

```ts
import { tokens } from "@gnist/themes/tokens.css.js";

const color = tokens.color.primary; // "var(--moller-color-primary)"
const size = tokens.size.xxl; // "var(--moller-size-xxl)"
```

更有用的是,这些可以直接插入 `styled-components` 或者说 `vanilla-extract` 样式.

### 原子

原子定义了一组原子 Cs 类,这些类可以在运行时查看。 这样可以再利用经常使用的基本 跨越组件和应用程序的样式。 作为奖金,像颜色,大小和间距之类的东西 都用我们的设计符号来定义.

这个 `atoms` 函数仅返回包含 css 类名称的字符串.

**说明:** 目前原子组相当小. 随着组件的再执行,将增加更多的原子. 也可以向Slack或Teams的设计系统团队推荐有用的原子!

示例

```tsx
import { atoms } from "@gnist/themes/atoms.css.js";

export const DangerComponent = ({ children }: PropsWithChildren) => (
    <div
        className={atoms({
            display: "flex",
            backgroundColor: "error-container", // refers to a color token
            paddingX: "xs", // refers to a spacing token
        })}
    >
        {children}
    </div>
);
```

### 颜色

这个 `colors` 模块导出用于设置颜色的助手.

#### 框颜色

`boxColors` 仅仅获取正确的 [原子](https://npmcn.com/package/%40gnist/themes/#readme-atoms) 用于设置 `backgroundColor`, (中文(简体) ), `color`,以及 `borderColor` 用于给定颜色类型. 颜色 `primary` 我们想要 `primary` 背景颜色,以及 `on-primary` 颜色和边框- 颜色 .

示例

```ts
import { gnistStyle } from "@gnist/themes/layers.css.js";
import { tokens } from "@gnist/themes/tokens.css.js";
import { boxColors } from "@gnist/themes/colors.css.js";

const box = gnistStyle([
    boxColors["primary-container"],
    { borderWidth: tokens.stroke.medium },
]);
```

### 类型

这个 `typography` 模块导出用于设定正确打字样式的助手( q)`responsiveTypography` 财务报告和审定财务报表 `densityTypography`, (中文(简体) ), 和用于设置全局文本样式的 css 类.

#### 响应打字

`responsiveTypography` 帮助您检索 css 类,用于根据视图大小在小/中/大之间变化的打字样式.

它是一个记录,可以让您查找为给定的打字风格设置的类名. 用这个 [`atoms`](https://npmcn.com/package/%40gnist/themes/#readme-atoms) 在引擎盖下.

一些例子:

```tsx
import { gnistStyle } from "@gnist/themes/layers.css.js";
import { atoms } from "@gnist/themes/atoms.css.js";
import { responsiveTypography } from "@gnist/themes/typography.css.js"

const someStyle = gnistStyle([
    atoms({ display: "flex", padding: "xs" }),
    responsiveTypography.lead,
])

// or inline
<div className={responsiveTypography.description}>{children}</div>
```

#### 密度打字法

`densityTypography` 帮助您创建食谱( 用于 `@vanilla-extract/recipe`) 对于给定的打字风格,它具有: `density: "default" | "compact"` 变体, 设置正确的 cs 类。 用这个 [`atoms`](https://npmcn.com/package/%40gnist/themes/#readme-atoms) 在引擎盖下.

它是一个记录,在给定了打字样式后,会将对象与 `variants` 适合合并成食谱的道具.

示例

```ts
import { gnistRecipe } from "@gnist/themes/layers.css.js";
import { atoms } from "@gnist/themes/atoms.css.js";
import { densityTypography } from "@gnist/themes/typography.css.js";

const action = gnistRecipe({
    base: atoms({ display: "block" }),
    ...densityTypography.action,
});

const className = action({ density: "default" });
```

与其他变种结合:

```ts
import { gnistRecipe } from "@gnist/themes/layers.css.js";
import { atoms } from "@gnist/themes/atoms.css.js";
import { densityTypography } from "@gnist/themes/typography.css.js";

const box = gnistRecipe({
    base: [atoms({ display: "block" })],
    variants: {
        color: {
            primary: boxColors["primary-container"],
            secondary: boxColors["secondary-container"],
        },
        ...densityTypography.notice.variants,
    },
    defaultVariants: { color: "primary", density: "default" },
});

const className = box({ color: "secondary", density: "compact" });
```

#### 全局文本样式

应在根元素中添加这些元素(例如:. `<body>`),以设置默认的打字风格和颜色. 从技术上讲,这是一份班级名称列表.

通常,您也会将主题应用于这个相同的元素,因为样式需要定义变量才能工作.

两种设置的示例:

```tsx
import { bilholdLight } from "@gnist/themes/themes.css.js";
import { globalTextStyles } from "@gnist/themes/typography.css.js";

document.body.classList.add(bilholdLight);
globalTextStyles.forEach((c) => {
    document.body.classList.add(c);
});

// In a Next layout you could rather do something like this
//...more layout
<body className={classNames(bilholdLight, globalTextStyles)}>{children}</body>;
//...more layout
```

## 设置

图书馆基于 香草摘录,它允许将样式预先编译为静态 Cs 文件。 然而,在我们 我们把汇编工作推迟到耗尽的应用程序。 这使得消费者能够编曲定义的符号和原子 在这里他们自己的 `vanilla-extract` 基于样式.

这意味着汇编步骤 `vanilla-extract` 必须添加到您的构建配置中.

### 维特

```
npm install -D @vanilla-extract/vite-plugin @vanilla-extract/esbuild-plugin
```

 `vite.config.ts` 也许是这样的:

```ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";
import { vanillaExtractPlugin as veEsbuildPlugin } from "@vanilla-extract/esbuild-plugin";

// https://vitejs.dev/config/
export default defineConfig({
    plugins: [react(), vanillaExtractPlugin()],
    optimizeDeps: {
        esbuildOptions: {
            // Handle vanilla-extract .css.js files during Vite dev mode optimization
            // This prevents error "Styles were unable to be assigned to a file." in dev mode
            // See https://github.com/vanilla-extract-css/vanilla-extract/discussions/1051
            plugins: [veEsbuildPlugin({ runtime: true })],
        },
    },
});
```

### 下一个.js

```
npm install -D @vanilla-extract/next-plugin
```

 `next.config.mjs` 也许是这样

```js
import { createVanillaExtractPlugin } from "@vanilla-extract/next-plugin";
const withVanillaExtract = createVanillaExtractPlugin();

/** @type {import('next').NextConfig} */
const nextConfig = {
    // ...your configuration here...
};

export default withVanillaExtract(nextConfig);
```

### 尾风 CSS v4

对于使用 Tailwind CSS v4 的工程,您可以直接导入主题 CSS 变量 .

#### 安装

首先,确保您在您的项目中安装了 Tailwind CSS v4 。 然后导入主题 CSS 文件 :

**在你身边 `globals.css` 或主 CSS 文件 :**

```css
@import "@gnist/themes/themes/mollerBil.tailwind.css";
```

**或者在你身边 `tailwind.config.ts`数字 :**

```typescript
import type { Config } from "tailwindcss";

export default {
    content: ["./src/**/*.{js,ts,jsx,tsx}"],
    // The CSS variables from mollerBil.tailwind.css are automatically available
    // when imported in your globals.css
} satisfies Config;
```

#### 可用的 CSS 变量

Tailwind CSS 文件包含所有设计符号,作为 Tailwind v4 常规之后的 CSS 变量 `@theme` 块 :

**颜色 :**

-   `--color-primary`, (中文(简体) ), `--color-secondary`, (中文(简体) ), `--color-tertiary`
-   `--color-primary-container`, (中文(简体) ), `--color-on-primary`
-   `--color-error`, (中文(简体) ), `--color-warning`, (中文(简体) ), `--color-success`, (中文(简体) ), `--color-info`
-   `--color-background`, (中文(简体) ), `--color-surface`
-   调色板颜色 : `--color-primary-10`, (中文(简体) ), `--color-primary-20`等 (中文(简体) ).

**间距 :**

-   `--spacing-none`, (中文(简体) ), `--spacing-base`, (中文(简体) ), `--spacing-xxs`, (中文(简体) ), `--spacing-xs`
-   `--spacing-s`, (中文(简体) ), `--spacing-m`, (中文(简体) ), `--spacing-l`, (中文(简体) ), `--spacing-xl`等 (中文(简体) ).

**类型 :**

-   字体家族 : `--font-brand`, (中文(简体) ), `--font-brand-display`
-   字体大小 : `--font-size-s`, (中文(简体) ), `--font-size-base`, (中文(简体) ), `--font-size-xl`等 (中文(简体) ).
-   字体权重 : `--font-weight-regular`, (中文(简体) ), `--font-weight-medium`, (中文(简体) ), `--font-weight-bold`

**边框半径 :**

-   `--radius-button`, (中文(简体) ), `--radius-card`, (中文(简体) ), `--radius-input`
-   `--rounded-none`, (中文(简体) ), `--rounded-small`, (中文(简体) ), `--rounded-full`

**阴影 :**

-   `--shadow-none`, (中文(简体) ), `--shadow-low`, (中文(简体) ), `--shadow-medium`, (中文(简体) ), `--shadow-high`

**其他情况:**

-   边框宽度 : `--border-width-small`, (中文(简体) ), `--border-width-medium`
-   大小 : `--size-base`, (中文(简体) ), `--size-s`, (中文(简体) ), `--size-xl`
-   不透明 : `--opacity-on-hover`, (中文(简体) ), `--opacity-on-pressed`

#### 尾风使用

使用您 Tailwind 配置中的 CSS 变量或直接在您的 CSS 配置中 :

```css
.my-component {
    background-color: var(--color-primary);
    padding: var(--spacing-m);
    border-radius: var(--radius-button);
    box-shadow: var(--shadow-medium);
}
```

或将Tailwind的主题扩展为使用语义名称:

```typescript
// tailwind.config.ts
export default {
    theme: {
        extend: {
            colors: {
                primary: "var(--color-primary)",
                secondary: "var(--color-secondary)",
            },
            spacing: {
                xs: "var(--spacing-xs)",
                s: "var(--spacing-s)",
            },
        },
    },
} satisfies Config;
```

**说明:** 这些指使符在从Figma更新设计指使符时会自动与香草-extract主题同步.

## 常见问题

### @gnist/themes 是什么？

@gnist/themes 是一个包含主题、设计符号和原子的库,用于 @gnist/design-system,但也可以单独使用\. 这是基于 香草摘录 在引擎盖下,需要额外压缩

### 如何安装 @gnist/themes？

在项目目录运行 npm install @gnist/themes，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@vanilla-extract/css（1\.20\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gnist/themes 支持 TypeScript 吗？

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

### @gnist/themes 支持 ESM 还是 CommonJS？

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

### @gnist/themes 可以商用吗？

@gnist/themes 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @gnist/themes 的下载量有多少？

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

### @gnist/themes 还在维护吗？

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

