Tailwind CSS Skill

Canonical Sources

This skill references the following globals — read them BEFORE starting work:

• system/globals/colors.md — OKLCH palette, token table, color semantics
• system/globals/effects.md — Border radius, shadows, card pattern

Domain

Tailwind v4 Expertise, @theme Directive, OKLCH, Utilities, Dark Mode

KPIs

Metric	Target	Measurement
Hardcoded Colors	0	npm run check:kpis
Inline Styles	0	npm run check:kpis
tailwind.config.mjs	must not exist	npm run check:kpis

npm run check:kpis (.claude/scripts/check-kpis.mjs) is the single source of truth for these checks — do not re-implement them with ad-hoc greps. The convention guard hook additionally warns when a change introduces hardcoded colors or inline styles.

Rules

Tailwind v4 Setup

AstroDeck uses Tailwind CSS v4 via @tailwindcss/vite (NOT @astrojs/tailwind).

• No tailwind.config.mjs — config lives in CSS
• @theme directive for token registration
• .dark class for dark mode overrides

@theme vs .dark

/* Token registration (Tailwind recognizes these as utilities) */
@theme {
  --color-primary: oklch(11.2% 0.0079 286.75);
  --color-primary-foreground: oklch(100% 0 0);
}

/* Dark mode overrides (only change values, no new tokens) */
.dark {
  --color-primary: oklch(100% 0 0);
  --color-primary-foreground: oklch(11.41% 0.0079 286.75);
}

Dark Mode Pattern

Do NOT control colors with dark: prefix. Use CSS variables that automatically override in .dark:

<!-- Wrong -->
<div class="bg-white dark:bg-gray-900 text-black dark:text-white">

<!-- Correct -->
<div class="bg-background text-foreground">

Utility Patterns

/* Responsive (mobile-first) */
text-base md:text-lg lg:text-xl

/* Hover/Focus states */
hover:bg-primary/90 focus:ring-2 focus:ring-ring

/* Transitions */
transition-colors duration-200

/* Dark mode (automatic via CSS variables) */
bg-background text-foreground  /* works in both modes */

Non-Negotiable

These rules always apply — even under time pressure, even for "just a quick fix":

• No hardcoded colors. bg-blue-500 is never "just temporary" — it gets forgotten and breaks on the next theme change.
• No inline styles. Not even "just for this special case." Tailwind utilities cover everything.
• OKLCH only. "HSL is more readable" is not an argument — the entire design system is based on OKLCH. Mixing destroys color consistency.
• No tailwind.config.mjs. Not even "because a package expects it." Config lives in CSS via @theme.
• No @astrojs/tailwind. AstroDeck uses @tailwindcss/vite. The old integration is incompatible with Tailwind v4.

Before Applying

Read LEARNINGS.md in this directory to avoid known anti-patterns.