The Complete Production SOP: How to Deploy and Run Tailwind CSS v4 & Design Tokens in Autonomous AI Agents

Create the standardized agent skill path (`.agents/skills/cursor-tailwind-v4` or `.cursor/rules/`) so agents read the procedural directives upon workspace discovery. For universal runtime compatibility across Codex, Claude Code, Cursor, and Windsurf, place `SKILL.md` inside `.agents/skills/cursor-tailwind-v4` or reference it directly in workspace prompts.

---
name: "cursor-tailwind-v4"
description: "Adopt modern Tailwind CSS v4 CSS variables, container queries, and subgrid features."
runtimes: ["codex", "claude-code", "cursor", "windsurf"]
---

# Tailwind CSS v4 & Design Tokens SOP

1. Do NOT create `tailwind.config.js` or `postcss.config.js`.
2. Configure design tokens using `@theme` inside the primary CSS entrypoint (e.g., `src/index.css`).
3. Use native CSS variables (`var(--color-primary)`) and CSS grid `grid-template-columns: subgrid`.
4. Enforce fluid typography and container query syntax (`@container (min-width: ...)`).

Tailwind CSS v4 replaces the JavaScript configuration layer with a high-performance native engine (`@tailwindcss/vite` or standalone `tailwindcss`). The agent must clean legacy `postcss.config.js` and `tailwind.config.js` artifacts and ensure `tailwindcss@next` is installed.

@import "tailwindcss";

@theme {
  --font-display: 'Inter', sans-serif;
  --color-brand-primary: oklch(0.65 0.24 260);
  --color-brand-secondary: oklch(0.85 0.12 180);
  --text-fluid-lg: clamp(1.25rem, 1rem + 1.25vw, 2rem);
}

Invoke the agent runtime with clear parameters matching the skill. The frontmatter triggers ensure the model reads existing typography styles, inspects layout components, and applies CSS container queries instead of brittle window-based media queries.

The skill mandates running the local build runner to verify that Tailwind v4 parses the CSS entry point without syntax errors and outputs expected design token CSS variables.

#!/usr/bin/env bash
set -euo pipefail
if grep -rn 'tailwind.config' . --exclude-dir=node_modules; then
  echo 'Error: Legacy configuration detected' && exit 1
fi
echo 'Tailwind v4 architecture verified.'