CSS Development Skill

Overview

Comprehensive workflow for CSS development using Tailwind + semantic component patterns. This skill automatically routes you to the appropriate specialized workflow based on context.

This skill will invoke one of three sub-skills:

• css-development:create-component

• Creating new CSS components

• css-development:validate

• Reviewing existing CSS

• css-development:refactor

• Transforming CSS to semantic patterns

When This Skill Applies

Claude Code will automatically load this skill when you:

• Create new CSS components or styles

• Review or validate existing CSS code

• Refactor inline styles or utility classes

• Work with component styling in any framework

• Need to add dark mode support

• Write CSS tests

CSS Development Patterns

All sub-skills follow these core patterns. Reference this section when working with CSS.

Core Principles

• Semantic Naming - Use descriptive class names (.button-primary , .card-header ) not utility names (.btn-blue , .card-hdr )

• Tailwind Composition - Leverage Tailwind utilities via @apply directive

• Dark Mode by Default - Include dark: variants for all colored/interactive elements

• Composition Over Creation - Reuse existing classes before creating new ones

• Test Coverage - Static CSS tests + component rendering tests

• Documentation - Usage comments above each component class

Component Class Pattern

/* Button component - Primary action button with hover states Usage: <button className="button-primary">Click me</button> */ .button-primary { @apply bg-indigo-500 hover:bg-indigo-700 dark:bg-indigo-600 dark:hover:bg-indigo-800; @apply px-6 py-3 rounded-lg font-medium text-white; @apply transition-all duration-200 hover:-translate-y-0.5; }

Key characteristics:

• Group related utilities logically (background, spacing, typography, transitions)

• Include hover/focus/active states

• Include dark mode variants using dark: prefix

• Use Tailwind's built-in scales (indigo-500, gray-800, etc.)

File Structure Convention

styles/ ├── components.css # All semantic component classes └── tests/ └── components.test.ts # CSS and component tests

Markup Integration (Framework-Agnostic)

Works with React, Vue, Svelte, or vanilla HTML:

React:

const classes = button-primary ${className}.trim(); <button className={classes}>...</button>

Vanilla HTML:

<button class="button-primary custom-class">...</button>

Vue:

<button :class="['button-primary', customClass]">...</button>

Key principle: Apply semantic class + allow additional classes for customization.

Atomic Design Levels

• Atoms: Basic building blocks (.button , .input , .badge , .spinner )

• Molecules: Composed components (.card , .form-field , .empty-state )

• Organisms: Complex components (.page-layout , .session-card , .conversation-timeline )

Testing Pattern

Static CSS Tests:

it('should have button component classes', () => { const content = readFileSync('styles/components.css', 'utf-8'); expect(content).toContain('.button-primary'); });

Component Rendering Tests:

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

Workflow: Context Detection and Routing

When this skill is invoked, follow these steps to route to the appropriate sub-skill:

Step 1: Analyze Context

Look at the user's request and recent conversation to determine intent:

Creating new components?

• Keywords: "create", "add", "new component", "build a", "make a"

• Files: Mention of components.css or new component names

• Intent: User wants to add new CSS

Validating existing CSS?

• Keywords: "review", "validate", "check", "audit", "look at"

• Files: Reference to existing CSS files or components

• Intent: User wants feedback on existing CSS

Refactoring CSS?

• Keywords: "refactor", "clean up", "extract", "improve", "convert"

• Code: Inline styles or utility classes in markup visible

• Intent: User wants to transform existing CSS patterns

Step 2: Choose Sub-Skill

Based on context analysis:

If creating: Use the Skill tool to invoke css-development:create-component

If validating: Use the Skill tool to invoke css-development:validate

If refactoring: Use the Skill tool to invoke css-development:refactor

If ambiguous: Ask the user using AskUserQuestion tool:

Question: "What would you like to do with CSS?" Options:

• "Create new component" (Guide creating new semantic CSS component classes)
• "Validate existing CSS" (Review CSS against established patterns)
• "Refactor CSS" (Transform inline/utility styles to semantic components)

Step 3: Invoke Sub-Skill

Use the Skill tool to invoke the chosen sub-skill:

Example:

I'm routing you to the create-component workflow. [Invoke Skill tool with skill: "css-development:create-component"]

Step 4: Hand Off Control

Once the sub-skill is invoked, it takes over. The main skill's job is complete.

Important Notes

• Don't skip routing: Always analyze context and choose the right sub-skill

• Don't duplicate sub-skill logic: Let sub-skills handle their workflows

• Reference pattern documentation: Sub-skills will reference the patterns documented above

• User can invoke directly: User can call sub-skills directly (e.g., "use css-development:validate")