@gnist/themes

v3.28.1

Published

17 days ago

`@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

0High
0Medium
0Low

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.

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 { style } from "@vanilla-extract/css";
import { tokens } from "@gnist/themes/tokens.css.js";
import { boxColors } from "@gnist/themes/colors.css.js";

const box = style([
    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 { style } from "@vanilla-extract/css";
import { atoms } from "@gnist/themes/atoms.css.js";
import { responsiveTypography } from "@gnist/themes/typography.css.js"

const someStyle = style([
    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 { recipe } from "@vanilla-extract/recipes";
import { atoms } from "@gnist/themes/atoms.css.js";
import { densityTypography } from "@gnist/themes/typography.css.js";

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

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

Combining with other variants:

import { recipe } from "@vanilla-extract/recipes";
import { atoms } from "@gnist/themes/atoms.css.js";
import { densityTypography } from "@gnist/themes/typography.css.js";

const box = recipe({
    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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Themes for @gnist/design-system

Overview

Themes

Tokens

Atoms

Colors

Box colors

Typography

Responsive typography

Density typography

Global text styles

Setup

Vite

Next.js

Tailwind CSS v4

Installation

Available CSS Variables

Usage in Tailwind