| name | tailwind |
| description | Tailwind CSS v4 (CSS-first) configuration and theming. Use when editing theme colors, light/dark or dark-only themes, @theme/@import/@plugin config, or syncing colors with a project brand skill. |
Tailwind CSS v4
Tailwind v4 is CSS-first: configuration and theme live in CSS, not a
tailwind.config.js. The entry stylesheet starts with @import "tailwindcss";
and customization happens in @theme, @plugin, @source, @utility, and
@custom-variant directives. This skill covers v4 only.
Related: for building shadcn/ui + React components, forms (React Hook Form
- Zod), accessibility, and responsive layouts, use the
ui-styling skill. This
skill focuses on the Tailwind layer itself — config, theme colors, and syncing
with a project brand skill.
Configuration essentials
The project's entry CSS is the file containing @import "tailwindcss"; (often
app.css, globals.css, styles.css, or index.css). All config lives there.
- Theme tokens:
@theme { --color-*, --font-*, --spacing-*, --radius-*, --breakpoint-* }. Each token generates utilities (e.g. --color-brand-500 → bg-brand-500, text-brand-500).
- Reference other vars: use
@theme inline { ... } when a token's value is var(--something), so utilities resolve the variable at use-time (required for light/dark).
- Content detection is automatic. Add sources with
@source "../foo", exclude with @source not "...", safelist with @source inline("bg-red-500").
- Plugins / legacy config:
@plugin "@tailwindcss/typography"; and @config "./tailwind.config.js";.
- Prefix / custom utilities / variants:
@import "tailwindcss" prefix(tw);, @utility, @custom-variant.
See references/v4-configuration.md for the full reference.
Theming workflow
Use this flow whenever changing base theme colors.
Step 0 — Detect a brand skill
Check the project for .claude/skills/brand/ (also match .claude/skills/*brand*/).
- Found → the brand skill is the source of truth. Update its canonical
color record first (Step 4), then propagate into the CSS.
- Not found → Tailwind is primary. Edit the CSS directly; skip Step 4.
ls -d .claude/skills/*brand*/ 2>/dev/null
Step 1 — Locate the color definitions
Find the entry CSS, then locate within it:
@theme / @theme inline blocks, and- any
:root { --* } and .dark { --* } (or [data-theme]) variable blocks.
grep -rl '@import "tailwindcss"' --include=*.css .
grep -n '@theme\|:root\|\.dark\|--color-' <entry.css>
Step 2 — Identify the theming pattern
- Flat — colors are literal values inside
@theme { --color-primary: ... }. No runtime switching.
- Light/dark —
@theme inline { --color-primary: var(--primary) } with the real values in :root (light) and .dark (dark).
- Dark-only — a single dark palette, no
.dark toggle.
Decision rule and full examples: references/theme-colors.md and
references/light-dark-theming.md (the dark-only section covers single-theme
projects).
Step 3 — Apply the change
Edit the value in the place that matches the pattern:
- Flat → change the literal in
@theme.
- Light/dark → change the raw value in
:root and/or .dark (not the @theme inline mapping).
- Dark-only → change the single palette source.
Keep paired values consistent — if a token exists in both :root and .dark,
decide whether the change applies to one mode or both.
Step 4 — Sync the brand skill (if present)
When a brand skill exists, record the change there so brand and CSS never drift.
Detection tiers and write-back rules are in references/brand-sync.md.
Verify
Confirm the old value is gone and the new one is present in both the CSS and
(if applicable) the brand record:
grep -rn '<old-value>\|<new-value>' <entry.css> .claude/skills/*brand*/
References
references/v4-configuration.md — CSS-first configuration referencereferences/theme-colors.md — flat @theme colors, palette overrides, semantic tokensreferences/light-dark-theming.md — light/dark and dark-only patternsreferences/brand-sync.md — brand detection, source-of-truth rule, fallback
