semantic-theming

name	semantic-theming
description	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.

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.

Related Skills

• 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