vanilla-extract

Vanilla Extract attempts to generate the smallest possible CSS output by merging styles assigned to the same layer within the same file, provided it doesn't impact rule precedence.

Crucially, the order of layers declared via globalLayer determines precedence. A style assigned to a layer declared later in the stylesheet will take precedence over styles in layers declared earlier, regardless of the order in which the style() functions were called in the code.

In the following example, themedHeading will appear later in the CSS and take precedence over heading because the theme layer is declared after the base layer:

import { style, globalLayer } from '@vanilla-extract/css';

const base = globalLayer('base');
const theme = globalLayer('theme');

const text = style({
  '@layer': {
    [base]: { fontSize: '1rem' }
  }
});

const themedHeading = style({
  '@layer': {
    [theme]: { color: 'rebeccapurple' }
  }
});

const heading = style({
  '@layer': {
    [base]: { fontSize: '2.4rem' }
  }
});

Since theme variables in vanilla-extract are opaque CSS Variables (e.g., var(--g7vce91)), you cannot perform arbitrary JavaScript calculations on them at runtime.

Using calc()

For simple arithmetic (addition, subtraction, multiplication, division), use the calc function from @vanilla-extract/css-utils to generate a valid CSS calc() expression.

Advanced Calculations

For complex logic (like color manipulation or rounding) that CSS cannot handle, you must perform the calculation at build time and include the result as a new CSS Variable in your theme definition.

import { style } from '@vanilla-extract/css';
import { calc } from '@vanilla-extract/css-utils';
import { vars } from '../vars.css';

// Simple calculation
const className = style({
  marginTop: calc.negate(vars.space.small)
});

// Advanced: Hoist logic to theme definition
// vars.css.ts
export const vars = createGlobalTheme(':root', {
  color: {
    brand: 'blue',
    brandLight: lighten(0.2, 'blue') // Calculated at build time
  }
});

// usage.css.ts
export const className = style({
  background: vars.color.brandLight
});

Vanilla Extract optimizes CSS output by merging styles assigned to the same layer within the same file, provided it doesn't impact rule precedence.

Crucially, the order of styles in the final stylesheet is determined by the order in which the layers themselves are declared. A style assigned to a layer declared later in your code will appear later in the CSS, even if the style() call occurred earlier in the file.

import { style, layer } from '@vanilla-extract/css';

const base = layer();
const theme = layer();

// This appears earlier in the CSS because 'base' is declared first
const text = style({
  '@layer': {
    [base]: {
      fontSize: '1rem'
    }
  }
});

// This appears later in the CSS because 'theme' is declared after 'base'
const themedHeading = style({
  '@layer': {
    [theme]: {
      color: 'rebeccapurple'
    }
  }
});

// This appears after 'themedHeading' in the source, but because it belongs to 'base',
// it is grouped with 'text' earlier in the stylesheet.
const heading = style({
  '@layer': {
    [base]: {
      fontSize: '2.4rem'
    }
  }
});

Standard createTheme usage couples the theme contract to a specific implementation, which can prevent CSS code-splitting because alternative themes must import the original theme's CSS.

To decouple them, use createThemeContract. This allows you to define the shape of your theme (the contract) without generating any CSS. You then create individual theme files that implement this contract using createTheme. This way, importing a specific theme only imports its own CSS, enabling efficient code-splitting.

// 1. Define the contract in contract.css.ts
import { createThemeContract } from '@vanilla-extract/css';

export const vars = createThemeContract({
  color: {
    brand: ''
  },
  font: {
    body: ''
  }
});

// 2. Implement specific themes in separate files
// blueTheme.css.ts
import { createTheme } from '@vanilla-extract/css';
import { vars } from './contract.css.ts';

export const blueThemeClass = createTheme(vars, {
  color: {
    brand: 'blue'
  },
  font: {
    body: 'arial'
  }
});

// redTheme.css.ts
import { createTheme } from '@vanilla-extract/css';
import { vars } from './contract.css.ts';

export const redThemeClass = createTheme(vars, {
  color: {
    brand: 'red'
  },
  font: {
    body: 'helvetica'
  }
});

To set up Sprinkles, create a sprinkles.css.ts file where you define your design tokens, properties, shorthands, and conditions. You then use createSprinkles to compose these definitions into a single sprinkles function.

Key configuration concepts:

• properties: Maps CSS properties to sets of allowed values (tokens).
• shorthands: Allows creating composite properties (e.g., mapping paddingX to paddingLeft and paddingRight).
• conditions: Defines media queries or state-based variations (e.g., mobile, darkMode).
• defaultCondition: Specifies which condition to use when none is provided.

Example configuration:

import {
  defineProperties,
  createSprinkles
} from '@vanilla-extract/sprinkles';

const space = {
  none: 0,
  small: '4px',
  medium: '8px',
  large: '16px'
};

const responsiveProperties = defineProperties({
  conditions: {
    mobile: {},
    tablet: { '@media': 'screen and (min-width: 768px)' },
    desktop: { '@media': 'screen and (min-width: 1024px)' }
  },
  defaultCondition: 'mobile',
  properties: {
    display: ['none', 'flex', 'block', 'inline'],
    flexDirection: ['row', 'column'],
    justifyContent: ['stretch', 'flex-start', 'center', 'flex-end', 'space-around', 'space-between'],
    alignItems: ['stretch', 'flex-start', 'center', 'flex-end'],
    paddingTop: space,
    paddingBottom: space,
    paddingLeft: space,
    paddingRight: space
  },
  shorthands: {
    padding: ['paddingTop', 'paddingBottom', 'paddingLeft', 'paddingRight'],
    paddingX: ['paddingLeft', 'paddingRight'],
    paddingY: ['paddingTop', 'paddingBottom'],
    placeItems: ['justifyContent', 'alignItems']
  }
});

const colors = {
  'blue-50': '#eff6ff',
  'blue-100': '#dbeafe',
  'blue-200': '#bfdbfe',
  'gray-700': '#374151',
  'gray-800': '#1f2937',
  'gray-900': '#111827'
};

const colorProperties = defineProperties({
  conditions: {
    lightMode: {},
    darkMode: { '@media': '(prefers-color-scheme: dark)' }
  },
  defaultCondition: 'lightMode',
  properties: {
    color: colors,
    background: colors
  }
});

export const sprinkles = createSprinkles(
  responsiveProperties,
  colorProperties
);

// Export the Sprinkles type for better DX
export type Sprinkles = Parameters<typeof sprinkles>[0];