@gnist/themes

中文文档
4.4.1发布于 2026/11/16UNLICENSEDTypeScriptES Module近 30 天下载 4133

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

中文使用文档
文档目录12 节
  1. CSS 层
  2. 发展
  3. 概览
  4. 主题
  5. 键
  6. 原子
  7. 颜色
  8. 类型
  9. 设置
  10. 维特
  11. 下一个.js
  12. 尾风 CSS v4

@ gnist/ 设计系统的主题

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

CSS 层

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

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

@layer base, gnist;

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

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

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

发展

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

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 类,它设置了许多变量. 开发者可以通过 键。 。 。 .

基本用途:

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 变量进行编程检查 .

示例

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的设计系统团队推荐有用的原子!

示例

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 仅仅获取正确的 原子 用于设置 backgroundColor, (中文(简体) ), color,以及 borderColor 用于给定颜色类型. 颜色 primary 我们想要 primary 背景颜色,以及 on-primary 颜色和边框- 颜色 .

示例

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 在引擎盖下.

一些例子:

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 在引擎盖下.

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

示例

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" });

与其他变种结合:

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>),以设置默认的打字风格和颜色. 从技术上讲,这是一份班级名称列表.

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

两种设置的示例:

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 也许是这样的:

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 也许是这样

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 文件 :

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

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

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 配置中 :

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

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

// 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 共发布 78 个版本,首次发布于 2024/11/08;过去 12 个月发布了 30 个版本。

版本发布日期距今
4.4.1latest2026/11/16今天
4.4.02026/11/0610 天前
4.3.22026/11/0610 天前
4.3.12026/10/161 个月前
4.3.02026/10/011 个月前
4.2.02026/09/181 个月前

其他发布通道:next → 4.0.0-alpha.1。

关于 @gnist/themes 的常见问题

@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 和提交记录判断。