Tailwind CSS v4.1 Architect

Purpose and Scope

Establish Tailwind CSS v4.1 as a CSS-first, token-driven system backed by the Oxide engine.
Enforce v4.1-native utilities and prevent reintroduction of v3-era patterns such as JS configs, plugin-based features, and arbitrary-value abuse.

Use this skill when:

• •Authoring new Tailwind v4.1 styling for components or pages.
• •Refactoring legacy Tailwind v3 or mixed code to v4.1.
• •Setting up or reviewing the global Tailwind architecture for a project.

1. Context Discovery Protocol

Execute this sequence immediately when the skill is activated for a project.

1. •

   Audit Tailwind Version

   • •Inspect package.json for the tailwindcss dependency.
   • •If the version is < 4.0, stop and signal that the project is not yet on v4.
     • •Suggest upgrading before applying this protocol.
2. •

   Locate Tailwind Entry Point

   • •Identify the CSS file containing @import "tailwindcss";.
     • •Treat this file as the authoritative entry point for theme and engine configuration.
   • •Ignore tailwind.config.js and tailwind.config.ts by default.
     • •Only read them if the user explicitly asks for v3 → v4 migration.
3. •

   Load Migration Knowledge When Needed

   • •When the user requests help migrating legacy patterns or plugins, consult
     references/v3-to-v4-migration.md to map v3 constructs to v4.1-native architecture.

2. Core Configuration Model

Apply the Tailwind CSS v4.1 configuration model as follows.

1. •

   CSS-First Configuration

   • •Assume Tailwind runs in CSS-first mode with Oxide.
   • •Use the entry CSS file to define configuration, not JS.
2. •

   @theme as Single Source of Tokens

   • •Place all design tokens in an @theme block:
     • •Colors (prefer OKLCH),
     • •Typography,
     • •Spacing and layout scales,
     • •Animation tokens.
3. •

   Forbidden / Required Behaviour

   • •FORBIDDEN: Create, edit, or rely on tailwind.config.js or tailwind.config.ts, except when explicitly migrating data from v3.
   • •REQUIRED: Use @theme for any repeated visual decision instead of arbitrary values in markup.

Example pattern:

@import "tailwindcss";

@theme {
  /* Colors (use OKLCH for P3 support) */
  --color-brand-primary: oklch(0.6 0.18 250);
  --color-brand-surface: oklch(0.95 0.02 250);

  /* Typography */
  --font-display: "Satoshi", sans-serif;
  --font-body: "Inter", sans-serif;

  /* Spacing / layout */
  --spacing-container: 1440px;
  --spacing-sidebar: 16rem;
}

3. Reasoning Loop for Each Styling Request

Apply this loop for every styling or refactoring request.

3.1 Check Native Capability

• •Prefer native v4.1 utilities; do not suggest plugins.

3.2 Token Management

• •Use utilities for layout; add or reuse tokens for design decisions.

3.3 Syntax Validation

• •Reject plugins, hex colors, arbitrary values, and overuse of @apply.

4. Workflows

Use assets/globals-template.css for new global or update styling. Use references/v3-to-v4-migration.md for migration mapping.