zhaoguiyang.site/.agents/skills/tailwindcss/references/core-theme.md

name, description

name	description
core-theme	Understanding theme variables, design tokens, and customizing Tailwind's default theme

Theme Variables

Theme variables are special CSS variables defined using the @theme directive that influence which utility classes exist in your project.

Overview

Theme variables store design tokens like colors, fonts, spacing, shadows, and breakpoints. They're defined using the @theme directive:

@import "tailwindcss";

@theme {
  --color-mint-500: oklch(0.72 0.11 178);
  --font-display: "Satoshi", "sans-serif";
  --breakpoint-3xl: 120rem;
}

Now utilities like bg-mint-500, font-display, and 3xl:grid-cols-6 become available.

Why @theme Instead of :root?

Theme variables aren't just CSS variables - they also instruct Tailwind to create new utility classes. Using @theme makes this explicit and ensures variables are defined top-level.

Use @theme for design tokens that map to utilities. Use :root for regular CSS variables that shouldn't have corresponding utilities.

Theme Variable Namespaces

Theme variables are organized into namespaces that map to utility classes:

Namespace	Utility Classes
--color-*	bg-red-500, text-sky-300, border-indigo-600, etc.
--font-*	font-sans, font-serif, font-mono
--breakpoint-*	Responsive variants like md:, lg:, xl:
--spacing-*	Spacing scale for padding, margin, gap utilities
--shadow-*	shadow-sm, shadow-md, shadow-lg
--ease-*	Transition timing functions

Extending the Default Theme

Add new theme variables to extend the default theme:

@import "tailwindcss";

@theme {
  /* Add new color */
  --color-brand-500: oklch(0.65 0.2 250);
  
  /* Add new breakpoint */
  --breakpoint-3xl: 120rem;
  
  /* Add new font */
  --font-display: "Satoshi", "sans-serif";
}

Using Theme Variables

Tailwind generates CSS variables for your theme variables, so you can reference them:

<!-- Use utility classes -->
<div class="bg-brand-500 text-display">Content</div>

<!-- Reference CSS variables directly -->
<div style="background-color: var(--color-brand-500)">
  Content
</div>

Default Theme

When you import tailwindcss, it includes default theme variables:

@layer theme, base, components, utilities;

@import "./theme.css" layer(theme);
@import "./preflight.css" layer(base);
@import "./utilities.css" layer(utilities);

The default theme includes:

• Color palette (red, blue, green, etc. with 50-950 shades)
• Font families (sans, serif, mono)
• Spacing scale
• Shadows
• Breakpoints (sm, md, lg, xl, 2xl)

Key Points

• Theme variables define which utilities exist in your project
• Use @theme directive to define design tokens
• Variables must be defined top-level, not nested
• Tailwind generates both utilities and CSS variables
• Default theme provides a solid starting point