CSS Variable and Theme Management

Relevant source files

• apps/v4/registry/base-colors.ts
• apps/v4/registry/themes.ts
• packages/shadcn/src/utils/add-components.ts
• packages/shadcn/src/utils/frameworks.ts
• packages/shadcn/src/utils/get-project-info.ts
• packages/shadcn/src/utils/resolve-import.ts
• packages/shadcn/src/utils/transformers/index.ts
• packages/shadcn/src/utils/transformers/transform-import.ts
• packages/shadcn/src/utils/updaters/update-css-vars.ts
• packages/shadcn/src/utils/updaters/update-files.ts
• packages/shadcn/src/utils/updaters/update-tailwind-config.ts
• packages/tests/fixtures/registry/example-at-property.json
• packages/tests/src/tests/add.test.ts

This document explains the CSS variable management system used to apply theming and styling to projects during component installation. The system handles CSS variable injection, theme system updates, and supports both Tailwind CSS v3 and v4 with distinct transformation strategies.

---

Purpose and Scope

The CSS variable management system is responsible for:

• Reading and parsing CSS variable definitions from registry items packages/shadcn/src/schema.ts4-6
• Applying CSS variables to a project's global CSS file using PostCSS transformations packages/shadcn/src/utils/updaters/update-css-vars.ts11-15
• Supporting both Tailwind CSS v3 (using @layer base) and v4 (using @theme inline) packages/shadcn/src/utils/updaters/update-css-vars.ts85-112
• Managing light/dark mode color variables and custom variants packages/shadcn/src/utils/updaters/update-css-vars.ts91-112
• Handling variable overwriting behavior for themes vs components packages/shadcn/src/utils/add-components.ts144-155
• Injecting font-specific CSS variables and @import statements for font libraries packages/shadcn/src/utils/updaters/update-fonts.ts22-30

This system does not handle:

• Runtime CSS variable updates or client-side theming.
• CSS variable usage in component files (only injection into global CSS).

Sources:
packages/shadcn/src/schema.ts4-6
packages/shadcn/src/utils/updaters/update-css-vars.ts11-15
packages/shadcn/src/utils/updaters/update-css-vars.ts85-112
packages/shadcn/src/utils/add-components.ts144-155
packages/shadcn/src/utils/updaters/update-fonts.ts22-30

---

Architecture Overview

The CSS variable and theme management system integrates deeply into the component installation pipeline. It updates the project's global CSS (commonly globals.css or another Tailwind CSS entry file) by injecting CSS variables and theme rules derived from registry components.

The CSS update is orchestrated mostly through two key function groups:

• updateCss() (in update-css.ts): the main updater called from component installation commands (addComponents), which reads the current CSS, applies CSS variable and raw CSS updates, then writes back packages/shadcn/src/utils/add-components.ts148-155
• updateCssVars() and transformCssVars() (in update-css-vars.ts): apply PostCSS transformations according to Tailwind version (v3 or v4) packages/shadcn/src/utils/updaters/update-css-vars.ts17-127

The system is aware of Tailwind CSS version differences:

• Tailwind v3 uses @layer base and scoped rules for CSS variables packages/shadcn/src/utils/updaters/update-css-vars.ts129-167
• Tailwind v4 introduces a new variant system (@custom-variant) and supports inline themes (@theme inline) with direct CSS variables packages/shadcn/src/utils/updaters/update-css-vars.ts91-112

High-level flow diagram: CSS Variable Injection Flow

Sources:
packages/shadcn/src/utils/add-components.ts34-160
packages/shadcn/src/utils/updaters/update-css-vars.ts17-127
packages/shadcn/src/utils/get-project-info.ts220-251

---

CSS Variable Schema

CSS variables are defined in registry items according to a Zod schema (registryItemCssVarsSchema) packages/shadcn/src/schema.ts4-6

Key	Type	Purpose	Tailwind Version Support
light	Record<string, string>	Light mode color variables	v3 and v4
dark	Record<string, string>	Dark mode color variables	v3 and v4
theme	Record<string, string>	Non-color theme variables such as fonts, breakpoints, shadows	v4 only

Sample snippet from a registry theme definition:

Sources:
packages/shadcn/src/schema.ts4-6
apps/v4/registry/themes.ts8-42

---

Tailwind Version Handling

Tailwind v3 Strategy

• Uses @layer base at-rule to house CSS variable declarations packages/shadcn/src/utils/updaters/update-css-vars.ts135-140
• Variables are scoped under :root for light mode and .dark class for dark mode packages/shadcn/src/utils/updaters/update-css-vars.ts159-160
• The main PostCSS plugin for this is updateCssVarsPlugin packages/shadcn/src/utils/updaters/update-css-vars.ts129-167

---

Tailwind v4 Strategy

Tailwind v4 introduces new features handled in transformCssVars packages/shadcn/src/utils/updaters/update-css-vars.ts91-112:

1. Custom variant syntax: @custom-variant dark (&:is(.dark *)); packages/shadcn/src/utils/updaters/update-css-vars.ts94
2. Inline Theme: Uses @theme inline block mapping CSS variables to Tailwind tokens packages/shadcn/src/utils/updaters/update-css-vars.ts105
3. Tailwind Config Bridge: Plugins inject @plugin, animation, and keyframe directives derived from the registry item's Tailwind configuration packages/shadcn/src/utils/updaters/update-css-vars.ts107-111

Sources:
packages/shadcn/src/utils/updaters/update-css-vars.ts91-112
packages/shadcn/src/utils/updaters/update-css-vars.ts129-167

---

Key Functions and Data Flow

updateCssVars

This is the main entry point to update CSS variables inside the project's global CSS file. It reads the file, calls the transformation, and writes it back packages/shadcn/src/utils/updaters/update-css-vars.ts17-59

transformCssVars

This function chooses the appropriate PostCSS plugin chain based on the tailwindVersion packages/shadcn/src/utils/updaters/update-css-vars.ts61-127

transformCssVars flow diagram

Sources:
packages/shadcn/src/utils/updaters/update-css-vars.ts61-127
packages/shadcn/src/utils/updaters/update-css-vars.ts17-59

---

Overwrite and Cleanup Logic

Overwrite Handling

The CLI determines whether to overwrite existing CSS variables based on user confirmation or if it's a new project. In addProjectComponents, the overwriteCssVars flag is passed to updateCss packages/shadcn/src/utils/add-components.ts144-155

Cleaning up Default Styles

For new projects, cleanupDefaultNextStylesPlugin is used to remove Next.js boilerplate styles (body color, background gradients, and default fonts) and conflicting variables like --background and --foreground packages/shadcn/src/utils/updaters/update-css-vars.ts169-237

Sources:
packages/shadcn/src/utils/add-components.ts144-155
packages/shadcn/src/utils/updaters/update-css-vars.ts169-237

---

Appendix: Relationships Between System Names and Code Entities

Sources:
packages/shadcn/src/utils/add-components.ts34-160
packages/shadcn/src/utils/updaters/update-css-vars.ts17-127
packages/shadcn/src/utils/transformers/index.ts43-72