vanilla-extract

Vanilla Extract for React Components

Use this skill when implementing or refactoring React component styling with Vanilla Extract. It emphasizes zero-runtime CSS generation, strong TypeScript ergonomics, scalable variants, and safe theming patterns.

When to Apply

Use this skill when tasks include:

• Setting up Vanilla Extract with Vite + React
• Creating component styles in .css.ts files
• Building typed variant systems (styleVariants, recipes)
• Implementing design tokens and themes (createTheme, createThemeContract)
• Runtime variable updates (@vanilla-extract/dynamic)
• Global/reset styles (globalStyle, createGlobalTheme)
• Utility-first typed atoms with optional @vanilla-extract/sprinkles

Core Mental Model

Vanilla Extract generates static CSS at build time from TypeScript style definitions.

• style(...) => one scoped class
• style([ ... ]) => composed class list, but still selector-safe inside Vanilla Extract
• Theme helpers create typed CSS variable contracts, then classes/selectors assign values
• Runtime theming via @vanilla-extract/dynamic only assigns values to pre-defined vars; it does not generate new CSS rules

Setup (React + Vite)

1. Install base package:
   • @vanilla-extract/css
2. Install Vite integration:
   • @vanilla-extract/vite-plugin (dev dependency)
3. Add plugin in vite.config.ts:
   • vanillaExtractPlugin()

Vite plugin identifiers

Choose identifier strategy depending on environment:

• short: compact hashes (smaller output)
• debug: human-readable class/var names in development
• custom function: fully custom naming based on { hash, filePath, debugId, packageName }

Use debug during active development and switch to short for production when needed.

File Conventions

• Put styles in *.css.ts
• Export class names and theme contracts from style modules
• Keep component logic in *.tsx and import classes/contracts from style files
• Co-locate styles next to components when component-specific; centralize tokens/themes in shared modules