# Tailwind Excellence Prover MCP

> Tailwind Excellence Prover runs a deep audit on your CSS structure to enforce modern design system standards. It checks for token usage, accessibility compliance (ARIA/focus states), mobile-first layouts, and semantic HTML markup. Stop building bloated styles with hardcoded values; this tool makes sure your components are clean, accessible, and scalable from day one.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** tailwindcss, design-system, accessibility, responsive, structured-reasoning, decision-pivots, css, agentic-pipeline

## Description

Look, you know how it is. You're building a component fast, and suddenly your CSS starts looking like a mess of hardcoded values. That’s where this server comes in. The `validate_tailwind_excellence` tool runs a deep audit on your entire component—both the HTML structure and the underlying CSS—to make sure you're actually adhering to modern design system standards. It doesn't just check if things *look* okay; it proves they're architecturally sound, accessible from day one, and built to scale.

You don't want bloated styles or visual bugs because some developer used a hex code instead of the defined color token. You need certainty that your markup is clean and ready for production. This server enforces five architectural pillars to keep your component library airtight.

When you run this tool, it first validates your design token usage by checking every single utility class. It confirms whether all values—for colors, spacing, and fonts—point back to defined `@theme` tokens. If a developer hardcoded `#e74c3c` or used `21px` instead of the scale token for 'small-spacing,' this tool flags it immediately. You’ll only use the official system palette, period.

The second major check is accessibility compliance. It doesn't just glance at your markup; it verifies that you've got proper semantic HTML structure in place, making sure screen readers can navigate it correctly. Crucially, it checks for appropriate ARIA labels on icons and confirms that focus states—the visible rings when a user tabs through elements—are properly defined using `focus-visible`. It also calculates color contrast ratios so you don't ship text that's too light against a background.

It then moves on to responsive audits. This tool makes sure your layout follows a true mobile-first scaling strategy. Instead of dropping in fixed desktop overrides, it enforces progressive breakpoints (`sm:`, `md:`) which means the design scales naturally as the screen size grows, rather than breaking when you change resolutions.

Separately, it controls arbitrary values. You know those utility classes like `w-[347px]`? They’re fine for one-off things, but if they spread everywhere, they defeat the whole point of a design system. This tool limits the use of these arbitrary classes to single adjustments only, forcing you to keep your core logic within the established scales.

Finally, it audits the component's overall semantic structure and class ordering. It checks that the markup is clean and follows best practices for state variants, ensuring predictable behavior across all browsers and devices. You get a clear report showing exactly where your components deviate from these five standards: token adherence, accessibility requirements, mobile-first scaling rules, arbitrary value discipline, and pure semantic integrity.

## Tools

### validate_tailwind_excellence
Audits a component's CSS and HTML against five pillars: design tokens, accessibility, mobile-first scaling, arbitrary value abuse, and semantic structure.

## Prompt Examples

**Prompt:** 
```
I'll create a pricing card with bg-[#6366f1], text-[#ffffff], w-[380px], mt-[32px], wrapped in divs, no dark mode, desktop only.
```

**Response:** 
```
Verdict: DESIGN_SYSTEM_ABSENT. Define @theme tokens: --color-primary: #6366f1 (then bg-primary), --spacing-8 for mt-8, consistent widths via max-w-sm. Add dark mode (dark:bg-gray-900). Use semantic HTML (section/article). Add responsive breakpoints.
```

**Prompt:** 
```
@theme with --color-primary (50-950), --spacing scale, --radius scale. PricingCard: <section> with <article>, focus-visible:ring on CTA, sr-only on icon, dark:bg-gray-900. grid-cols-1 md:grid-cols-2 lg:grid-cols-3. hover:bg-primary/90 transition-colors.
```

**Response:** 
```
Verdict: UI_PROVEN. Design tokens in @theme (color scale, spacing, radius). Semantic HTML (section/article). Accessible (focus-visible, sr-only, dark mode). Mobile-first responsive (grid breakpoints). Clean architecture (hover/transition states). Ship it.
```

**Prompt:** 
```
I'll build a nav with @theme tokens, proper colors, but all divs, no <nav> element, no aria-label, no focus states on links, and no responsive — desktop fixed width only.
```

**Response:** 
```
Verdict: ACCESSIBILITY_VIOLATED. Tokens and colors correct, but: use <nav> not <div>, add aria-label='Main navigation', focus-visible:ring-2 on every link, sr-only for screen readers. Semantic HTML + ARIA are non-negotiable.
```

## Capabilities

### Validate Design Token Usage
Checks if all color, spacing, and font values reference defined `@theme` tokens instead of using hardcoded literals.

### Enforce Accessibility Standards
Verifies semantic HTML structure, checks for appropriate ARIA labels on icons, confirms focus states (`focus-visible`), and calculates color contrast ratios.

### Audit Responsive Breakpoints
Ensures the layout follows a mobile-first scaling strategy using progressive breakpoints instead of fixed desktop overrides.

### Control Arbitrary Values
Restricts the use of arbitrary utility classes (e.g., `w-[347px]`) to one-off adjustments, keeping core design logic within scales.

## Use Cases

### Refactoring a Legacy Component
A developer takes an old pricing card built with hardcoded colors and fixed widths. They run `validate_tailwind_excellence`. The tool immediately flags the missing design tokens, forcing them to update the component using `--color-primary` and consistent max-widths.

### Building a Complex Navigation Bar
When building a new global navigation bar, an engineer needs to ensure it works everywhere. They run `validate_tailwind_excellence`, which forces them to use `<nav>` instead of `<div>` and adds the necessary `aria-label` for screen readers.

### Fixing Poorly Responsive Grids
A team builds a product listing page that looks great on desktop but breaks on mobile. Running `validate_tailwind_excellence` forces them to rethink the layout, implementing progressive breakpoints (`grid-cols-1 md:grid-cols-3`) and fluid typography.

### Auditing Component Library PRs
Before merging a new button component, an architect runs `validate_tailwind_excellence`. This ensures every interactive element has a defined focus state (`focus-visible:ring-2`) and meets the required contrast ratio before it hits production.

## Benefits

- Stops hardcoded values. The tool forces all colors and spacing to reference custom `@theme` tokens, eliminating random hex codes or arbitrary pixel sizes from your markup.
- Guarantees accessibility compliance. It checks focus rings (`focus-visible:ring-2`), requires ARIA labels on icon buttons, and verifies the 4.5:1 color contrast ratio automatically.
- Enforces mobile-first scaling. Instead of designing for desktop and overriding down, it mandates a base-mobile approach using progressive screen breakpoints (e.g., `grid-cols-1 md:grid-cols-2`).
- Cleans up structure. It pushes you toward semantic HTML (`<main>`, `<nav>`) instead of leaving you with messy, non-descriptive div soup.
- Prevents bloat. By controlling arbitrary values (like `w-[347px]`), it keeps your component architecture clean and highly maintainable.

## How It Works

The bottom line is that you get an instant structural report showing exactly where your CSS violates modern design system rules.

1. Input your component's CSS and HTML structure into the tool.
2. The agent runs `validate_tailwind_excellence`, executing five decision pivots (token checks, accessibility audit, etc.) against the provided code.
3. You receive a detailed verdict: 'UI_PROVEN' if it passes all tests, or a specific list of violations and suggested fixes.

## Frequently Asked Questions

**How does Tailwind Excellence Prover fix hardcoded colors?**
It doesn't 'fix' it, but it identifies it. The `validate_tailwind_excellence` tool flags any hex color or pixel size that isn't defined in your custom `@theme` tokens, forcing you to use the correct token variable.

**Can I use Tailwind Excellence Prover for React components?**
Yes, it processes the resulting CSS and HTML structure. You pass the compiled code snippets through `validate_tailwind_excellence` to check the output layer, regardless of the framework.

**Does validate_tailwind_excellence handle JavaScript state changes?**
No. The tool focuses solely on the static CSS and HTML structure. It checks for structural compliance (like adding focus rings) but doesn't run dynamic JS logic.

**What is 'Design Token Detachment' in Tailwind Excellence Prover?**
It means using raw values instead of theme tokens. The tool catches this when it sees a hardcoded color or size, suggesting you reference your defined `--color-primary` token instead.

**How do I initialize and connect to the Tailwind Excellence Prover MCP Server?**
You connect via your preferred AI client using standard MCP protocols. Since it's a hosted server, you don't need local dependencies for basic operation. Your agent simply calls the exposed tool endpoint (validate_tailwind_excellence) once you have set up the connection.

**When validate_tailwind_excellence detects a violation, what is the format of its feedback?**
The output provides a clear 'Verdict' followed by actionable remediation steps. The report doesn't just say something is wrong; it tells you exactly which design principle failed (e.g., ACCESSIBILITY_VIOLATED) and how to fix it using specific semantic tags or tokens.

**Are there constraints on the amount of CSS or component code I can provide to validate_tailwind_excellence?**
The tool is designed for single-component or page-level validation. While we recommend providing focused sections, extremely large files might exceed the context window limit of your AI client. Break complex pages into smaller units before running the check.

**Does using the Tailwind Excellence Prover MCP Server impact my project's security profile?**
The server only analyzes the provided CSS structure and class declarations; it doesn't execute any code or modify your repository. It acts as a static linter, making its use safe from a direct security standpoint.

**Does it generate Tailwind code?**
No. The agent writes the UI. The tool VALIDATES that it follows design system principles — @theme tokens instead of arbitrary values, semantic HTML for accessibility, mobile-first responsive strategy, and clean component architecture with proper state variants.

**Does it support Tailwind v4?**
Yes. Tailwind v4 awareness is built in: @theme for design tokens (not tailwind.config.js), @import 'tailwindcss' (not @tailwind directives), @utility for custom utilities, @variant for custom variants, built-in container queries, and automatic content detection. It catches v3 anti-patterns in v4 projects.

**Why is accessibility a dedicated pillar?**
Because AI agents consistently generate div soup with no semantic HTML, no focus states, and no ARIA. Tailwind makes styling effortless but semantic structure and accessibility still require deliberate choices. This tool forces: semantic elements, focus-visible:ring, sr-only text, contrast ratios, and motion-safe variants.