Tailwind Config Conformance Validator

Overview

This skill validates and refactors code to use only Tailwind classes that are explicitly defined in your project's tailwind.config.js or tailwind.config.ts file.

The problem it solves:

Agents generate classes like text-red-650, p-7.5, w-full-minus-1 without checking if they're in your config
Developers use arbitrary values (w-[100px]) when a configured value exists
Custom theme extensions aren't being utilized, leading to inconsistent styling
Code review becomes tedious — manually checking which classes actually exist in config

The outcome:

All Tailwind classes are validated against your actual config
Invalid classes are replaced with valid alternatives from your config
A summary report shows exactly what changed and why
Your codebase stays consistent with your design system

How It Works

Step 1: Understand the Input

You provide:

Code to validate — Any file containing Tailwind classes (React, Vue, HTML, Svelte, etc.)
Optionally, the config file path — If not provided, the skill auto-discovers tailwind.config.js or tailwind.config.ts

Step 2: Parse Config

The skill reads your tailwind.config.js/ts and extracts:

Theme values: colors, spacing, typography, sizing, etc.
Extended values: anything defined under theme.extend
Corepack values: all Tailwind built-in defaults (spacings, colors, breakpoints, etc.)

Step 3: Validate Classes

For each Tailwind class in your code, the skill:

Parses the structure: text-red-600 → text (utility) + red-600 (modifier value)
Checks config: Is red-600 defined in your config theme?
Accepts valid patterns:
- Responsive prefixes: md:text-red-600, lg:p-4
- Dark mode variants: dark:bg-gray-900
- State variants: hover:text-red-600, focus:bg-blue-500
- Arbitrary values: w-[100px] (with caveat — see edge cases)
Flags violations: Classes not found in config are marked for replacement

Step 4: Suggest Replacements

When a class doesn't match config, the skill:

Finds the closest valid alternative from your config (same utility family, nearest value)
Suggest the replacement with reasoning ("used p-7.5 but config only has p-8")
Applies replacements to the code

Step 5: Generate Report

Output includes:

Refactored code — All invalid classes replaced
Change summary — List of all replacements with reasons
Config violations — Classes that were invalid and how they were fixed

Input Format

Provide your code and, optionally, the config file path.

Example 1 (auto-discover config):

Please validate this React component against our Tailwind config:

<code>
  <div className="p-7.5 text-red-650 w-[200px] md:grid-cols-12 dark:bg-navy-new">
    Content
  </div>
</code>

Example 2 (explicit config path):

Validate this with config at apps/web/tailwind.config.ts:

<code>
  <button className="px-custom-lg py-2 bg-primary hover:bg-primary-dark">
    Click me
  </button>
</code>

Output Format

ALWAYS use this exact structure:

Refactored Code

[code with all invalid classes replaced with valid ones from config]

Change Summary

Original Class	Reason	Suggested Class
`p-7.5`	Not in config. Config has `p-8` and `p-6`. Used `p-8`.	`p-8`
`text-red-650`	Not in config. Config defines `text-red-600` and `text-red-700`. Used closest.	`text-red-600`
`grid-cols-12`	Not in config. Standard Tailwind max is `grid-cols-12` but check if extended.	⚠️ Recommend extending config

Config Validation Report

Config file found: tailwind.config.ts (root)
Total classes validated: 15
Valid classes: 12
Invalid classes: 3
All violations fixed: ✅ Yes

Edge Cases Handled

1. Arbitrary Values

Arbitrary values like w-[100px] are allowed but flagged:

✅ Allowed if there's a legitimate reason (truly custom, not covered by config)
⚠️ Flagged if a similar config value exists (e.g., if config has w-96, don't use w-[100px])

2. Responsive & Dark Mode Variants

All of these are validated:

md:p-4 → validates p-4, ignores md: prefix
dark:bg-gray-900 → validates bg-gray-900, ignores dark: prefix
hover:text-red-600 → validates text-red-600, ignores hover: prefix
Combinations: lg:dark:hover:text-red-600 → validates text-red-600 only

3. CSS-in-JS & Object Syntax

Handles multiple formats:

JSX className strings: className="p-4 text-red-600"
Tailwind function calls: import { cn } from '@/utils'; cn('p-4', { 'text-red-600': isActive })
CSS modules with Tailwind: @apply p-4 text-red-600;
Tailwind directives in CSS: @layer components { .btn { @apply px-4 py-2; } }

4. Plugins & Presets

If your config uses plugins (e.g., @tailwindcss/forms, daisyui), the skill:

Notes the plugin in the report
Validates core classes and plugin-provided utilities separately
Flags any conflicts between plugin utilities and core Tailwind

Important Notes

Arbitrary Values Policy

Allowed: w-[200px] if no config spacing covers this exact need
Discouraged: w-[96px] when config already has w-96
Recommendation: If frequently needed, extend tailwind.config.ts instead

Config Extensions

This skill validates against your config as-is. If you find patterns that are missing:

Note them in the report
Consider extending your tailwind.config.ts
Re-run the skill after extending config

Responsive Breakpoints

The skill uses breakpoints from your config:

Standard: sm, md, lg, xl, 2xl
Custom breakpoints: validated from your theme.screens config

Dark Mode

Validates dark: prefix if:

darkMode: 'class' is set in your config (most common)
Dark mode is enabled in your config

Walkthrough Example

Input Code:

export function Card({ isActive }) {
  return (
    <div className="p-7.5 rounded-2xl bg-gradient-blue shadow-lg">
      <h2 className="text-xl font-bold text-navy-new">Title</h2>
      <p className="text-sm text-gray-500 mt-12 md:mt-6">Description</p>
      <button className="px-custom-lg py-2 bg-primary hover:bg-primary-dark">
        Action
      </button>
    </div>
  );
}

Config (tailwind.config.ts):

export default {
  theme: {
    extend: {
      colors: {
        primary: "#007AFF",
        "primary-dark": "#0051D5"
      },
      spacing: {
        "custom-lg": "18px"
      }
    }
  }
};

Output:

Refactored Code:

export function Card({ isActive }) {
  return (
    <div className="p-8 rounded-xl bg-blue-500 shadow-lg">
      <h2 className="text-xl font-bold text-slate-900">Title</h2>
      <p className="text-sm text-gray-500 mt-10 md:mt-6">Description</p>
      <button className="px-custom-lg py-2 bg-primary hover:bg-primary-dark">
        Action
      </button>
    </div>
  );
}

Change Summary:

Original	Reason	Replacement
`p-7.5`	Not in config. Used `p-8` (closest).	`p-8`
`rounded-2xl`	Not in config. Max is `rounded-xl`.	`rounded-xl`
`bg-gradient-blue`	Not in config. No matching gradient. Used `bg-blue-500`.	`bg-blue-500`
`text-navy-new`	Not in config. Used `text-slate-900` (dark neutral).	`text-slate-900`
`mt-12`	Not in config. Max is `mt-10`.	`mt-10`
`px-custom-lg`	✅ In config (extended). Kept as-is.	`px-custom-lg`
`py-2`	✅ Valid Tailwind. Kept as-is.	`py-2`
`bg-primary`	✅ In config (extended). Kept as-is.	`bg-primary`
`hover:bg-primary-dark`	✅ Valid. Kept as-is.	`hover:bg-primary-dark`

When NOT to Use This Skill

Intentional arbitrary values: If you're deliberately using w-[calc(100%-10px)] for a specific calculation, explain that and the skill will preserve it with a note.
Not a Tailwind project: This skill is Tailwind-specific. Regular CSS projects need different validation.
No config file: If your project doesn't have a tailwind.config.js/ts, this skill can't validate. Set one up first.

Tips for Best Results

Provide the config path if it's not in the standard location (root or src/). E.g., apps/web/tailwind.config.ts
Include context if your code uses custom utilities from plugins. E.g., This project uses @tailwindcss/forms
Review the summary before applying changes — the suggestions are smart but your intent is the source of truth
Extend config strategically — if the skill frequently suggests the same replacements, consider extending your tailwind.config.ts to include those values

tailwind-config-conformance

Files1

SKILL.mdskills/tailwind-config-conformance/SKILL.md