Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

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 tailwindcss

About 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, @theme options, 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/vite plugin. PostCSS: install @tailwindcss/postcss. CLI: npx @tailwindcss/cli -i input.css -o output.css
  • No tailwind.config.js in v4 — all configuration lives in CSS via @theme
  • Remove postcss-import and autoprefixer — 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

  • @theme defines design tokens that generate utility classes — not equivalent to :root. Use @theme for values needing utilities; use :root for CSS variables that only need var() access
  • @theme must be top-level (not nested under selectors or media queries)
  • All @theme values 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-500 or --color-gray-100
  • OKLCH for custom colors: oklch(0.72 0.11 178) — perceptually uniform, works with CSS color-mix()

@theme Options

  • @theme { } — Default: only emit used vars
  • @theme static { } — Always emit all vars
  • @theme inline { } — Inline var() 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:*, and max-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-*: initial removes all defaults in that namespace
  • Reset everything: --*: initial for fully custom theme
  • Disable specific colors: --color-lime-*: initial

Colors

  • 22 color families x 11 steps (50-950) plus black and white
  • Every --color-* token generates utilities across bg-*, text-*, border-*, ring-*, fill-*, stroke-*, etc.
  • Opacity modifier: bg-sky-500/50 — per-property, not whole-element
  • --alpha() for CSS opacity: compiles to color-mix(in oklab, ...)
  • Never use bg-opacity-* (removed in v4) — always bg-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-600 yes, `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-
Read the complete source ↗