CSS Development: Validate

Overview

Reviews existing CSS code against established patterns and provides specific, actionable feedback:

• Semantic naming conventions
• Tailwind @apply composition
• Dark mode variant coverage
• Test coverage (static + rendering)
• Documentation quality
• Composition opportunities

This is a sub-skill of css-development - typically invoked automatically via the main skill.

When This Skill Applies

Use when:

• Reviewing existing CSS code
• Auditing component styles for consistency
• Checking if patterns are being followed
• Before merging CSS changes
• Refactoring prep (identify issues first)

Pattern Reference

This skill validates against patterns documented in the main css-development skill:

Semantic naming: .button-primary not .btn-blue Tailwind composition: Use @apply to compose utilities Dark mode: Include dark: variants Test coverage: Static CSS + component rendering tests Documentation: Usage comments above classes

Workflow

When this skill is invoked, create a TodoWrite checklist and work through validation systematically.

Announce Usage

"I'm using the css-development:validate skill to review this CSS against established patterns."

Create TodoWrite Checklist

Use the TodoWrite tool:

Validating CSS:
- [ ] Read CSS files (load components.css and related styles)
- [ ] Check semantic naming (verify descriptive class names)
- [ ] Verify @apply usage (ensure Tailwind composition)
- [ ] Check dark mode coverage (confirm dark: variants present)
- [ ] Look for composition opportunities (identify reusable patterns)
- [ ] Verify test coverage (check static and rendering tests exist)
- [ ] Check documentation (ensure usage comments present)
- [ ] Report findings (provide file:line references and suggestions)

Validation Checklist Details

Step 1: Read CSS Files

Action: Use Read tool to load CSS files for review

Files to check:

• styles/components.css (main semantic components)
• Any component-specific CSS files mentioned
• Inline styles in component files (if applicable)

What to capture:

• All class definitions
• Usage of @apply vs. inline utilities
• Presence of dark mode variants
• Documentation comments

Mark as completed when files are loaded and understood.

Step 2: Check Semantic Naming

Action: Review all class names for semantic, descriptive naming

Good patterns:

• .button-primary, .card-header, .form-field, .empty-state
• Context + component: .session-card, .marketing-hero
• Base + variant: .badge-success, .button-danger

Bad patterns (report these):

• Utility names: .btn-blue, .card-sm, .text-big
• Abbreviations: .btn, .hdr, .desc
• Generic: .component, .item, .thing
• Random: .style1, .custom, .special

For each issue:

• Note file and line number
• Show the problematic class name
• Suggest semantic alternative based on usage context

Mark as completed when all class names reviewed.

Step 3: Verify @apply Usage

Action: Check that Tailwind utilities are composed via @apply, not scattered in markup

Good patterns:

.button-primary {
  @apply bg-indigo-500 hover:bg-indigo-700 px-6 py-3 rounded-lg;
}

Bad patterns (report these):

<!-- Utilities in markup instead of semantic class -->
<button class="bg-indigo-500 hover:bg-indigo-700 px-6 py-3 rounded-lg">
  Click me
</button>

Check:

• Are utilities composed into semantic classes via @apply?
• Are there repeated utility combinations in markup that should be extracted?
• Are semantic classes actually being used in components?

For each issue:

• Show the problematic markup or CSS
• Explain why it should use @apply
• Suggest extraction to semantic class

Mark as completed when @apply usage is reviewed.

Step 4: Check Dark Mode Coverage

Action: Verify colored and interactive elements have dark: variants

What needs dark mode:

• Background colors (bg-*)
• Text colors (text-*)
• Border colors (border-*)
• Interactive states (hover, focus)
• Shadows that affect visibility

What typically doesn't need dark mode:

• Spacing utilities (p-, m-, gap-*)
• Layout utilities (flex, grid, etc.)
• Pure structural styles

Pattern to check:

/* Good - has dark mode */
.card {
  @apply bg-white dark:bg-gray-800 text-gray-900 dark:text-white;
}

/* Bad - missing dark mode */
.card {
  @apply bg-white text-gray-900;
}

For each issue:

• Note which class is missing dark mode variants
• Show the current CSS
• Suggest specific dark: utilities to add

Mark as completed when dark mode coverage is checked.

Step 5: Look for Composition Opportunities

Action: Identify repeated patterns that could use existing classes or be extracted

Look for:

• Same utility combinations repeated in multiple classes
• Similar patterns that could share a base class
• Inline utilities that could reference semantic classes

Example issue:

/* Repeated pattern */
.card-primary {
  @apply bg-white dark:bg-gray-800 rounded-lg shadow-md p-6;
}

.card-secondary {
  @apply bg-white dark:bg-gray-800 rounded-lg shadow-md p-6;
  @apply border-2 border-gray-200;
}

/* Suggestion: Extract base .card class, add variants */
.card {
  @apply bg-white dark:bg-gray-800 rounded-lg shadow-md p-6;
}

.card-secondary {
  @apply border-2 border-gray-200;
}

For each opportunity:

• Show the repeated pattern
• Suggest base class + composition
• Estimate impact (how many places benefit)

Mark as completed when composition opportunities are identified.

Step 6: Verify Test Coverage

Action: Check that CSS classes have test coverage

Static CSS tests - Check styles/__tests__/components.test.ts:

it('should have button-primary class', () => {
  expect(content).toContain('.button-primary');
});

Component rendering tests - Check component test files:

it('applies button-primary class', () => {
  render(<Button variant="primary">Click</Button>);
  expect(screen.getByRole('button')).toHaveClass('button-primary');
});

For classes without tests:

• List the class name
• Note which test is missing (static, rendering, or both)
• Provide test template to add

Mark as completed when test coverage is checked.

Step 7: Check Documentation

Action: Verify components have usage documentation

Required documentation:

• Comment above CSS class explaining purpose
• Usage example in comment

Example:

/* Button component - Primary action button with hover lift effect
   Usage: <button className="button-primary">Click me</button> */
.button-primary {
  ...
}

For classes without documentation:

• List the class name and location
• Suggest documentation to add based on class purpose

Mark as completed when documentation is checked.

Step 8: Report Findings

Action: Compile all findings into structured report

Report format:

## CSS Validation Report

### ✅ Good Patterns Found

- `.button-primary` follows semantic naming (components.css:15)
- Dark mode variants present on interactive elements (components.css:17-19)
- Tests cover className application (Button.test.tsx:23)
- Documentation comments present (components.css:14)

### ⚠️ Issues Found

#### Semantic Naming Issues

**components.css:45** - `.btn-blue` uses utility naming
- Current: `.btn-blue`
- Suggestion: Rename to `.button-secondary` for consistency with `.button-primary`
- Impact: Update 3 component files

**components.css:67** - `.card-sm` uses size in name
- Current: `.card-sm`
- Suggestion: Extract size to utility or rename to `.card-compact` for semantic meaning
- Impact: Update 5 usages

#### Missing Dark Mode Variants

**components.css:78** - `.card-header` missing dark mode
- Current: `@apply bg-gray-100 text-gray-900`
- Suggestion: Add