Use when designing or picking values for a Tailwind CSS project: choosing spacing units, color tokens, font sizes, breakpoints, or opacity. Use also when reading existing utility classes and needing to know whether a value comes from the default theme or a custom override. Prevents hardcoded colors, ad-hoc spacing arithmetic, mismatched type scales, and the common v3 to v4 color-format mistake (rgb/hsl vs oklch). Covers the default spacing scale (single base unit in v4, 32-step scale in v3), the default 22 color families (slate / gray / zinc / neutral / stone plus 17 chromatic families), the v4 oklch P3 wide-gamut color format vs the v3 rgb/hsl format, the text-xs through text-9xl type scale, the default breakpoint scale (sm 640, md 768, lg 1024, xl 1280, 2xl 1536), the v4 CSS-variable token model (--color-*, --spacing, --font-*, --text-*, --breakpoint-*, --radius-*, --shadow-*), the v3 tailwind.config.js theme object, and opacity modifier syntax (bg-red-500/50, text-white/[0.85], bg-cyan-400/(--my-alpha)). K
Use when designing or picking values for a Tailwind CSS project: choosing spacing units, color tokens, font sizes, breakpoints, or opacity. Use also when reading existing utility classes and needing to know whether a value comes from the default theme or a custom override. Prevents hardcoded colors, ad-hoc spacing arithmetic, mismatched type scales, and the common v3 to v4 color-format mistake (rgb/hsl vs oklch). Covers the default spacing scale (single base unit in v4, 32-step scale in v3), the default 22 color families (slate / gray / zinc / neutral / stone plus 17 chromatic families), the v4 oklch P3 wide-gamut color format vs the v3 rgb/hsl format, the text-xs through text-9xl type scale, the default breakpoint scale (sm 640, md 768, lg 1024, xl 1280, 2xl 1536), the v4 CSS-variable token model (--color-*, --spacing, --font-*, --text-*, --breakpoint-*, --radius-*, --shadow-*), the v3 tailwind.config.js theme object, and opacity modifier syntax (bg-red-500/50, text-white/[0.85], bg-cyan-400/(--my-alpha)). Keywords: design tokens, theme tokens, spacing scale, color palette, oklch, P3 colors, wide gamut, type scale, font size, line height, breakpoints, sm md lg xl 2xl, opacity modifier, alpha channel, CSS variables, custom properties, theme config, tailwind config, bg-red-500, text-white, p-4, m-8, gap-2, what spacing is p-4, what color is sky-500, default theme, brand colors, custom colors, design system, token, palette, why does p-17 work, dynamic spacing, oklch vs rgb, color format changed in v4.
license
MIT
compatibility
Designed for Claude Code. Requires Tailwind CSS v3.4 or v4.0+.
metadata
{"author":"OpenAEC-Foundation","version":"1.0"}
Tailwind CSS Core: Design System
The design system is the single source of truth for every value Tailwind utilities produce. Spacing, colors, type, breakpoints, radii, shadows: all of them are tokens, and the markup expresses intent within that token system. Mastering the design system is the difference between writing fluent Tailwind and fighting it.
Both generate the same utility class names (`bg-brand-500`, `p-128`, `text-display`, `3xl:flex`). The mechanism, the file location, and the value format all differ.
### Pattern 2: Using the opacity modifier
The opacity modifier `/N` is one of the most powerful and most misunderstood features. It works on **every** color-consuming utility.
```html
<!-- Named opacity step (5% increments from 0 to 100) -->
<div class="bg-blue-600/0">...</div> <!-- fully transparent -->
<div class="bg-blue-600/10">...</div> <!-- 10% opacity -->
<div class="bg-blue-600/50">...</div> <!-- 50% opacity (the most common) -->
<div class="bg-blue-600/100">...</div> <!-- fully opaque (same as no modifier) -->
<!-- Arbitrary opacity -->
<div class="bg-pink-500/[71.37%]">...</div>
<div class="text-white/[0.85]">...</div> <!-- decimal fraction also valid -->
<!-- CSS variable opacity -->
<div class="bg-cyan-400/(--my-alpha)">...</div> <!-- v4 parens syntax -->
<div class="bg-cyan-400/[var(--my-alpha)]">...</div> <!-- v3 brackets syntax -->
<!-- Works on every color utility, not just bg -->
<div class="text-slate-900/60 border-red-500/30 ring-blue-600/50 fill-emerald-500/80">
Pattern 3: Inspecting a token at runtime
v3.4 (JavaScript)
v4.0+ (CSS variables)
```js
import resolveConfig from 'tailwindcss/resolveConfig'
In v4, this is the **only** runtime API for token lookup. The build no longer emits a JS-importable config object.
### Pattern 4: oklch P3 wide-gamut colors (v4-only)
v4 defines every default color in the `oklch()` color space, which targets the **P3 wide-gamut** display profile. On standard sRGB monitors, oklch values fall back to the nearest sRGB equivalent ; on P3 monitors (most modern phones, MacBooks since 2016, most external monitors since 2020), the colors render with measurably higher saturation, especially in the orange/red/violet/cyan ranges.
Why this matters for skills authoring custom colors:
```css
@theme {
/* GOOD : oklch produces consistent perceptual lightness across hues */
--color-brand-500: oklch(0.65 0.196 254);
--color-brand-600: oklch(0.55 0.196 254); /* perceptually one step darker */
/* TOLERATED : hex / rgb still parse fine in @theme, but lose P3 reach */
--color-legacy: #3b82f6;
/* TOLERATED : hsl maps cleanly but is not perceptually uniform */
--color-alt: hsl(217 91% 60%);
}
ALWAYS prefer oklch() in v4 ; the entire default palette uses it, and mixing formats produces inconsistent perceived contrast.
The @theme inline modifier in v4 is the escape hatch for runtime-resolved tokens (e.g. swapping a CSS variable from JS or a [data-theme] attribute).
Pattern 6: Type scale with line-height pairing
Default v4 line-heights are paired to font sizes (matching v3 theme.fontSize tuples). This means text-base automatically applies line-height: 1.5 and text-2xl automatically applies line-height: 2 / 1.5.
<!-- ALWAYS rely on the paired line-height for body text --><pclass="text-base">Body copy gets the right leading automatically.</p><!-- Override paired line-height with a separate utility when needed --><pclass="text-2xl leading-tight">Headline tightened from default.</p><!-- Set both inline via arbitrary value --><pclass="text-[14.5px]/[1.3]">Custom size with custom leading.</p>
In v4 the paired leading is set via the companion variable --text-{name}--line-height (see Pattern 1).
Pattern 7: Token-driven dark mode
The design system carries through to dark mode by changing the variable values, not by rewriting utilities. The recommended pattern in v4 :
Now bg-background and text-foreground work in both modes without dark: variants on every element.
Reference Links
references/methods.md : complete token namespace reference (every --*-* and its theme.* equivalent), full default scales for spacing / color / type / breakpoints.
references/examples.md : working code examples for v3 and v4 across spacing, colors, type, breakpoints, opacity, theme overrides.
references/anti-patterns.md : real anti-patterns mined from GitHub issues and the upgrade guide (dynamic class strings, oklch vs rgb mismatch, theme() dot-notation in v4, wrong arbitrary syntax).
Verified Sources
All content verified against the following SOURCES.md-approved URLs :
