tailwindcss
Tailwind CSS v4 utility-first discipline: CSS-first configuration, design tokens via @theme, and principled class composition. Invoke whenever task involves any interaction with Tailwind CSS — writing, reviewing, refactoring, debugging, or understanding utility classes, theme configuration, custom utilities, dark mode, or Tailwind integration with frameworks.
xobotyi · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add xobotyi/cc-foundry --skill tailwindcssAbout this skill
name: tailwindcss description: >- Tailwind CSS v4 utility-first discipline: CSS-first configuration, design tokens via @theme, and principled class composition. Invoke whenever task involves any interaction with Tailwind CSS — writing, reviewing, refactoring, debugging, or understanding utility classes, theme configuration, custom utilities, dark mode, or Tailwind integration with frameworks.
Tailwind CSS v4
Utility classes are the default. Custom CSS is the escape hatch.
Skill(frontend:css)
Skip only for trivial class additions where no CSS reasoning is needed.
Tailwind CSS uses CSS-first configuration: design tokens live in @theme, custom utilities use @utility, and there is
no JavaScript configuration file. Constrain yourself to the design system; break out only with intention.
References
- Theme — [
${CLAUDE_SKILL_DIR}/references/theme-configuration.md]: Theme tokens,@themeoptions, namespace mapping, color system - Class authoring — [
${CLAUDE_SKILL_DIR}/references/class-authoring.md]: Class composition, variants, dark mode, breakpoints - Custom utilities — [
${CLAUDE_SKILL_DIR}/references/custom-utilities-and-variants.md]:@utility,@custom-variant, directives,@source - Layout — [
${CLAUDE_SKILL_DIR}/references/layout.md]: Display, position, flexbox, grid, alignment, order utilities - Sizing — [
${CLAUDE_SKILL_DIR}/references/sizing-and-spacing.md]: Spacing scale, width/height, padding/margin, borders, box model - Typography — [
${CLAUDE_SKILL_DIR}/references/typography.md]: Font properties, text spacing, styling, decoration, layout - Backgrounds — [
${CLAUDE_SKILL_DIR}/references/backgrounds-and-effects.md]: Gradients, shadows, rings, opacity, SVG, filters - Transforms — [
${CLAUDE_SKILL_DIR}/references/transforms-and-animations.md]: Transitions, animations, 2D/3D transforms, masks - Framework — [
${CLAUDE_SKILL_DIR}/references/framework-integration.md]: Preflight, CSS Modules, class binding (React, Vue, Svelte)
Entry Point and Installation
- Single import:
@import "tailwindcss";— provides preflight reset, theme variables, and all utilities. No@tailwind base/components/utilities(v3 syntax) - Vite: install
@tailwindcss/viteplugin. PostCSS: install@tailwindcss/postcss. CLI:npx @tailwindcss/cli -i input.css -o output.css - No
tailwind.config.jsin v4 — all configuration lives in CSS via@theme - Remove
postcss-importandautoprefixer— v4 handles both internally - Do not use Sass, Less, or Stylus with Tailwind v4 — Tailwind is the preprocessor (handles
@import, nesting, variables, vendor prefixes)
Theme Configuration (@theme)
Core Rules
@themedefines design tokens that generate utility classes — not equivalent to:root. Use@themefor values needing utilities; use:rootfor CSS variables that only needvar()access@thememust be top-level (not nested under selectors or media queries)- All
@themevalues compile to:root { }CSS vars in output - Only used CSS vars are emitted by default
- Semantic token names:
--color-primary,--color-surface— not--color-blue-500or--color-gray-100 - OKLCH for custom colors:
oklch(0.72 0.11 178)— perceptually uniform, works with CSScolor-mix()
@theme Options
@theme { }— Default: only emit used vars@theme static { }— Always emit all vars@theme inline { }— Inlinevar()references into utility output
Use @theme inline when a token references another variable — prevents CSS variable resolution failures in the cascade.
Namespace → Utility Mapping
--color-*→bg-*,text-*,border-*,ring-*,fill-*,stroke-*, etc.--font-*→font-*(family)--text-*→text-*(size)--font-weight-*→font-*(weight)--tracking-*→tracking-*--leading-*→leading-*--breakpoint-*→ Responsive variants:sm:*,md:*--container-*→ Container query variants:@sm:*, andmax-w-*--spacing-*or--spacing→px-*,py-*,m-*,w-*,h-*, etc.--radius-*→rounded-*--shadow-*/--inset-shadow-*→shadow-*/inset-shadow-*--blur-*→blur-*--ease-*→ease-*--animate-*→animate-*
Breakpoints generate variants, not utilities. Colors generate multiple utility families from a single namespace.
Extending, Replacing, Resetting
- Extend: Add new tokens alongside defaults — just declare new vars in
@theme - Override: Redeclare a default var to change its value
- Reset namespace:
--color-*: initialremoves all defaults in that namespace - Reset everything:
--*: initialfor fully custom theme - Disable specific colors:
--color-lime-*: initial
Colors
- 22 color families x 11 steps (50-950) plus
blackandwhite - Every
--color-*token generates utilities acrossbg-*,text-*,border-*,ring-*,fill-*,stroke-*, etc. - Opacity modifier:
bg-sky-500/50— per-property, not whole-element --alpha()for CSS opacity: compiles tocolor-mix(in oklab, ...)- Never use
bg-opacity-*(removed in v4) — alwaysbg-color/opacity
Sharing Themes
Put @theme in a standalone CSS file and @import it after @import "tailwindcss".
Class Authoring
Fundamental Rules
- Complete class names only. Never concatenate or interpolate —
text-red-600yes,`text-${color}-600`never. Tailwind scans source files as plain text - Map dynamic values to static class string lookups
- Prettier plugin for ordering. Install
prettier-plugin-tailwindcss— do not manually sort classes - CSS variable shorthand: `bg-(--brand-