@gnist/themes

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

@gnist/themes is a library containing themes, design tokens and atomic css used by @gnist/design-system, but which can also be used on its own. It is based on vanilla-extract under the hood, and requires an extra comp

原始使用文档
文档目录12 节
  1. CSS Layers
  2. Development
  3. Overview
  4. Themes
  5. Tokens
  6. Atoms
  7. Colors
  8. Typography
  9. Setup
  10. Vite
  11. Next.js
  12. Tailwind CSS v4

Themes for @gnist/design-system

@gnist/themes is a library containing themes, design tokens and atomic css used by @gnist/design-system, but which can also be used on its own. It is based on vanilla-extract under the hood, and requires an extra compilation step. See Setup for details.

CSS Layers

All styles produced by this library are wrapped in @layer gnist { }. This means consumers can override any design system style without specificity issues — unlayered styles always take precedence over layered styles.

To ensure correct layer ordering, add a @layer declaration at the top of your main CSS file (e.g. globals.css):

@layer base, gnist;

This guarantees that gnist styles take precedence over base styles. Any global or reset CSS you write should be wrapped in @layer base { } so it doesn't unintentionally override design system styles:

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

Styles written outside any @layer will still take the highest precedence, allowing you to override design system styles when needed.

Development

When writing styles within the design system or gnist-app, use gnistStyle and gnistRecipe instead of vanilla-extract's style and 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" },
        },
    },
});

A lint rule enforces this — importing style from @vanilla-extract/css or recipe from @vanilla-extract/recipes will produce an error.

Note that globalStyle and styleVariants are not wrapped automatically and must be manually placed inside @layer when needed.

See DEVELOPMENT.md for more details.

Overview

This library exposes the following parts: themes, tokens, atoms, colors, and typography

Themes

A theme is a css class which sets a number of variables. Developers can refer to these through Tokens.

Basic usage:

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

These themes currently exist and can be referred to in the way described above

audi
autoria
bilholdLight
brandless
cupra
dahles
gumpen
mollerBil
seat
skoda
vw

Tokens

Tokens allow you to programatically look up css variables based on our design token structure, in a type safe manner.

Example:

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

More usefully, these can be interpolated directly in a styled-components or vanilla-extract style.

Atoms

Atoms define a set of atomic css classes which can be looked up at runtime. This allows reuse of frequently used basic styling across components and apps. As a bonus, things like colors, sizes and spacing are defined in terms of our design tokens.

The atoms function simply returns a string containing the css class names required.

Note: The current set of atoms is quite small. More atoms will be added as components are reimplemented. You can also suggest useful atoms to the design system team on Slack or Teams!

Example:

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

The colors module exports helpers for setting colors.

Box colors

boxColors simply retrieves the correct atoms for setting backgroundColor, color, and borderColor for a given color type. E.g. for the color primary we want primary background-color, and on-primary color & border-color.

Example:

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

The typography module exports helpers for setting correct typography styles (responsiveTypography and densityTypography), and a css class for setting global text styles.

Responsive typography

responsiveTypography helps you retrieve css classes for the typography styles that change between small/medium/large based on viewport size.

It is a record which lets you look up the class names to set for the given typography style. It uses atoms under the hood.

Some examples:

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>

Density typography

densityTypography helps you create a recipe (for use with @vanilla-extract/recipe) for the given typography styles, which has the density: "default" | "compact" variants, and sets the correct css classes. It uses atoms under the hood.

It is a record which, when given a typography style, returns an object with the variants prop which is suitable for merging into a recipe.

Example:

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

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

Global text styles

These should be added to the root element (e.g. <body>) in order to set the default typography styles and colors. Technically, this is a list of class names.

Usually, you would also apply the theme to this same element, as variables need to be defined for the styles to work.

Example of setting both:

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

Setup

The library is based on vanilla-extract, which allows pre-compiling the styles to static css files. However, in our case we defer compilation to the consuming application. This allows the consumer to compose the tokens and atoms defined here in their own vanilla-extract based styles.

This means a compilation step for vanilla-extract must be added to your build configuration.

Vite

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

Your vite.config.ts might look like this:

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 })],
        },
    },
});

Next.js

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

Your next.config.mjs might look like this

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

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

export default withVanillaExtract(nextConfig);

Tailwind CSS v4

For projects using Tailwind CSS v4, you can import theme CSS variables directly.

Installation

First, ensure you have Tailwind CSS v4 installed in your project. Then import the theme CSS file:

In your globals.css or main CSS file:

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

Or in your 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;

Available CSS Variables

The Tailwind CSS files contain all design tokens as CSS variables following Tailwind v4 conventions in an @theme block:

Colors:

  • --color-primary, --color-secondary, --color-tertiary
  • --color-primary-container, --color-on-primary
  • --color-error, --color-warning, --color-success, --color-info
  • --color-background, --color-surface
  • Palette colors: --color-primary-10, --color-primary-20, etc.

Spacing:

  • --spacing-none, --spacing-base, --spacing-xxs, --spacing-xs
  • --spacing-s, --spacing-m, --spacing-l, --spacing-xl, etc.

Typography:

  • Font families: --font-brand, --font-brand-display
  • Font sizes: --font-size-s, --font-size-base, --font-size-xl, etc.
  • Font weights: --font-weight-regular, --font-weight-medium, --font-weight-bold

Border Radius:

  • --radius-button, --radius-card, --radius-input
  • --rounded-none, --rounded-small, --rounded-full

Shadows:

  • --shadow-none, --shadow-low, --shadow-medium, --shadow-high

Other:

  • Border widths: --border-width-small, --border-width-medium
  • Sizing: --size-base, --size-s, --size-xl
  • Opacity: --opacity-on-hover, --opacity-on-pressed

Usage in Tailwind

Use the CSS variables in your Tailwind configuration or directly in your CSS:

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

Or extend Tailwind's theme to use semantic names:

// 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;

Note: These tokens stay in sync with the vanilla-extract themes automatically when design tokens are updated from Figma.

版本与发布记录

@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 is a library containing themes, design tokens and atomic css used by @gnist/design-system, but which can also be used on its own. It is based on vanilla-extract under the hood, and requires an extra comp

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