@gnist/themes
Advanced tools
`@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](https://vanilla-extract.style/) under the hood, and requires an extra comp
@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.
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.
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.
This library exposes the following parts: themes, tokens, atoms, colors, and typography
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 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 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>
);
The colors module exports helpers for setting 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 },
]);
The typography module exports helpers for setting correct typography styles (responsiveTypography and densityTypography),
and a css class for setting global text styles.
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>
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" });
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
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.
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 })],
},
},
});
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);
For projects using Tailwind CSS v4, you can import theme CSS variables directly.
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;
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--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-brand, --font-brand-display--font-size-s, --font-size-base, --font-size-xl, etc.--font-weight-regular, --font-weight-medium, --font-weight-boldBorder Radius:
--radius-button, --radius-card, --radius-input--rounded-none, --rounded-small, --rounded-fullShadows:
--shadow-none, --shadow-low, --shadow-medium, --shadow-highOther:
--border-width-small, --border-width-medium--size-base, --size-s, --size-xl--opacity-on-hover, --opacity-on-pressedUse 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.
FAQs
`@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](https://vanilla-extract.style/) under the hood, and requires an extra comp
We found that @gnist/themes demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
npm v12 is generally available, turning install scripts off by default and beginning the deprecation of 2FA-bypass publishing tokens.
Research
/Security News
Socket tracks the activity as Operation “Muck and Load”: a threat actor uses commit-farming workflows, public dead drops, and protected archives to stage Windows RAT and infostealer malware.
Security News
pnpm 11.10 hardens registry auth to block token redirection, tightens pack-app and deploy, and makes the Rust port (v12) installable.