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.

1. 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.

1. 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.

1. @theme as Single Source of Tokens

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

1. 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.