semantic-theming

Enforce semantic CSS variable theming in Tailwind projects. Prevents raw colors (hex, rgb) and non-theme Tailwind classes. Use when project has semantic tokens, CSS vars, or custom ESLint theming rules.

⭐3stars🔀2forks📁View on GitHub🕐Updated Dec 20, 2025⬇️1downloads

When & Why to Use This Skill

This Claude skill automates the enforcement of semantic CSS variable theming within Tailwind CSS projects. By prioritizing design tokens over raw color literals (hex, RGB) and standard Tailwind color classes, it ensures that generated code is maintainable, theme-aware, and compliant with custom ESLint rules. It is essential for projects requiring strict adherence to design systems and scalable UI architectures.

Use Cases

  • Refactoring legacy React components to replace hardcoded Tailwind colors (e.g., 'bg-blue-500') with project-specific semantic tokens (e.g., 'bg-primary').
  • Generating new UI components using 'cva' or 'clsx' that automatically adhere to the project's internal theming documentation and CSS variables.
  • Preventing ESLint 'no-raw-colors' violations during the code generation phase to reduce CI/CD fix cycles.
  • Ensuring consistent dark mode and multi-theme support by strictly using CSS custom properties instead of static utility classes.
namesemantic-theming
descriptionEnforce semantic CSS variable theming in Tailwind projects. Prevents raw colors (hex, rgb) and non-theme Tailwind classes. Use when project has semantic tokens, CSS vars, or custom ESLint theming rules.

Semantic Theming Skill

Use semantic design tokens instead of raw colors. This skill teaches Claude to write theme-compliant code from the start.

Detection Criteria

This skill applies when the project has ANY of:

  • docs/THEMING.md exists
  • eslint-rules/no-raw-colors.js exists
  • ESLint config includes wescobar/no-raw-colors or similar theming rule
  • src/index.css defines CSS custom properties (e.g., --color-primary)

Quick check: Look for these indicators before applying this skill.

When to Use

  • Writing or editing React components with className
  • Using Tailwind utility classes for colors/backgrounds/borders
  • Working with cn(), clsx(), or cva() class composition
  • Styling any UI element with colors

Forbidden Patterns

Raw Color Literals

// FORBIDDEN - Will fail ESLint
style={{ color: '#ff0000' }}
style={{ backgroundColor: 'rgb(255, 0, 0)' }}
style={{ borderColor: 'hsl(0, 100%, 50%)' }}

Non-Semantic Tailwind Classes

// FORBIDDEN - Will fail ESLint
className="bg-red-500"
className="text-white"
className="border-blue-300"
className="bg-slate-900 text-gray-100"
className="from-purple-500 via-pink-500 to-red-500"

Correct Patterns

Semantic Token Classes

// CORRECT - Use semantic tokens
className="bg-surface text-primary"
className="bg-surface-secondary border-primary"
className="bg-error text-error"
className="bg-success text-success"
className="text-secondary bg-primary"

Common Semantic Tokens

Category Tokens
Background bg-surface, bg-surface-secondary, bg-primary, bg-error, bg-success
Text text-primary, text-secondary, text-accent, text-error, text-success
Border border-primary, border-error, border-surface

With Class Composition

// CORRECT - Semantic tokens in cn/clsx/cva
import { cn } from '@/lib/utils';

className={cn(
  "bg-surface text-primary",
  isActive && "bg-primary text-surface",
  hasError && "border-error text-error"
)}

CVA Variants

// CORRECT - Semantic tokens in cva
const buttonVariants = cva(
  "bg-surface text-primary border-primary", // Base
  {
    variants: {
      variant: {
        primary: "bg-primary text-surface",
        error: "bg-error text-surface",
        success: "bg-success text-surface",
      }
    }
  }
);

Escape Hatches

When absolutely necessary (rare):

// Line-level disable
// eslint-disable-next-line wescobar/no-raw-colors
className="bg-red-500" // Legacy code migration

// File-level disable (very rare)
/* eslint-disable wescobar/no-raw-colors */

Use sparingly - prefer fixing to disabling.

Migration Examples

Old (Forbidden) New (Semantic)
bg-white bg-surface
bg-gray-900 bg-surface-secondary
text-white text-surface (on dark bg)
text-gray-900 text-primary
text-gray-500 text-secondary
border-gray-300 border-primary
bg-red-500 bg-error
bg-green-500 bg-success
text-blue-500 text-accent

Project-Specific Tokens

Check docs/THEMING.md or src/index.css for the full list of available semantic tokens in this project. Token names may vary between projects.

Integration with ESLint

The no-raw-colors ESLint rule enforces this at:

  • Pre-commit hooks (blocks commit)
  • IDE integration (inline errors)
  • CI/CD pipeline

Generate correct code from the start to avoid fix cycles.

  • validate-lint - Run linting validation
  • quality-gate - Complete quality checks including lint

Validation

After writing styled code:

  1. Check for any raw colors or non-semantic Tailwind classes
  2. Replace with semantic tokens from the project's theme
  3. If unsure, check docs/THEMING.md for available tokens