Css Performance

CSS Performance Skill

Optimize CSS performance with critical CSS extraction, code splitting, purging, and bundle analysis.

Overview

This skill provides atomic, focused guidance on CSS performance optimization with measurable metrics and production-ready configurations.

Skill Metadata

Usage

Skill("css-performance")

Parameter Schema

parameters:
  optimization_type:
    type: string
    required: true
    enum: [critical-css, purging, minification, code-splitting, selectors]
    description: Type of optimization to implement

  tool:
    type: string
    required: false
    enum: [purgecss, cssnano, critical, webpack, postcss]
    description: Specific tool configuration

  metrics:
    type: boolean
    required: false
    default: true
    description: Include measurement recommendations

validation:
  - rule: optimization_type_required
    message: "optimization_type parameter is required"
  - rule: valid_optimization
    message: "optimization_type must be one of: critical-css, purging..."

Topics Covered

Critical CSS

• Above-the-fold extraction
• Inline critical, defer rest
• Tools: Critical, Penthouse

Purging (Tree-shaking)

• PurgeCSS configuration
• Safelist patterns
• Dynamic class handling

Minification

• cssnano optimization
• clean-css alternatives
• Safe vs unsafe optimizations

Code Splitting

• Route-based splitting
• Component-level CSS
• Dynamic imports

Retry Logic

retry_config:
  max_attempts: 3
  backoff_type: exponential
  initial_delay_ms: 1000
  max_delay_ms: 10000

Logging & Observability

logging:
  entry_point: skill_invoked
  exit_point: skill_completed
  metrics:
    - invocation_count
    - optimization_type_distribution
    - tool_usage

Quick Reference

Performance Targets

PurgeCSS Configuration

// postcss.config.js
module.exports = {
  plugins: [
    require('@fullhuman/postcss-purgecss')({
      content: [
        './src/**/*.{js,jsx,ts,tsx}',
        './public/index.html',
      ],
      defaultExtractor: content =>
        content.match(/[\w-/:]+(?<!:)/g) || [],
      safelist: {
        standard: [/^is-/, /^has-/, 'active', 'open'],
        deep: [/^data-/],
        greedy: [/modal$/, /tooltip$/],
      },
    }),
  ],
}

Critical CSS Setup

// critical.config.js
const critical = require('critical');

critical.generate({
  base: 'dist/',
  src: 'index.html',
  css: ['dist/styles.css'],
  width: 1300,
  height: 900,
  inline: true,
  extract: true,
});

cssnano Configuration

// postcss.config.js
module.exports = {
  plugins: {
    cssnano: {
      preset: ['default', {
        discardComments: { removeAll: true },
        normalizeWhitespace: true,
        colormin: true,
        minifyFontValues: true,
        // Unsafe optimizations (test carefully)
        reduceIdents: false,
        mergeIdents: false,
      }],
    },
  },
}

Async CSS Loading

<!-- Inline critical CSS -->
<style>/* Critical CSS here */</style>

<!-- Async load full CSS -->
<link rel="preload" href="styles.css" as="style"
      onload="this.onload=null;this.rel='stylesheet'">
<noscript>
  <link rel="stylesheet" href="styles.css">
</noscript>

Selector Performance

/* FAST */
.button { }           /* Single class */
#header { }           /* ID */

/* MODERATE */
.nav .link { }        /* Descendant */
.nav > .link { }      /* Child */

/* SLOW (avoid) */
.container * { }                    /* Universal descendant */
[class*="btn-"][class$="-lg"] { }   /* Complex attribute */

Measurement Commands

# Lighthouse CI
npx lighthouse-ci https://example.com --collect

# CSS Coverage in Chrome DevTools
# 1. Open DevTools → More Tools → Coverage
# 2. Reload page
# 3. Check CSS usage percentage

# Bundle analysis
npx webpack-bundle-analyzer stats.json

Optimization Checklist

Pre-deployment:
├─ [ ] CSS minified
├─ [ ] Unused CSS purged (< 20% unused)
├─ [ ] Critical CSS inlined
├─ [ ] Non-critical CSS async loaded
├─ [ ] Source maps excluded from production
├─ [ ] gzip/Brotli compression enabled
└─ [ ] Cache headers configured

Test Template

describe('CSS Performance Skill', () => {
  test('validates optimization_type parameter', () => {
    expect(() => skill({ optimization_type: 'invalid' }))
      .toThrow('optimization_type must be one of: critical-css...');
  });

  test('returns PurgeCSS config for purging type', () => {
    const result = skill({ optimization_type: 'purging', tool: 'purgecss' });
    expect(result).toContain('safelist');
    expect(result).toContain('content');
  });

  test('includes metrics when flag is true', () => {
    const result = skill({ optimization_type: 'critical-css', metrics: true });
    expect(result).toContain('14KB');
    expect(result).toContain('Lighthouse');
  });
});

Error Handling

Related Skills

• css-fundamentals (selector efficiency)
• css-architecture (file organization)
• css-tailwind (purge configuration)

Css Performance Guide

Overview

This guide provides comprehensive documentation for the css-performance skill in the custom-plugin-css plugin.

Category: Database

Quick Start

Prerequisites

• Familiarity with database concepts
• Development environment set up
• Plugin installed and configured

Basic Usage

# Invoke the skill
claude "css-performance - [your task description]"

# Example
claude "css-performance - analyze the current implementation"

Core Concepts

Key Principles

1. Consistency - Follow established patterns 2. Clarity - Write readable, maintainable code 3. Quality - Validate before deployment

Best Practices

• Always validate input data
• Handle edge cases explicitly
• Document your decisions
• Write tests for critical paths

Common Tasks

Task 1: Basic Implementation

# Example implementation pattern
def implement_css_performance(input_data):
    """
    Implement css-performance functionality.

    Args:
        input_data: Input to process

    Returns:
        Processed result
    """
    # Validate input
    if not input_data:
        raise ValueError("Input required")

    # Process
    result = process(input_data)

    # Return
    return result

Task 2: Advanced Usage

For advanced scenarios, consider:

• Configuration customization via assets/config.yaml
• Validation using scripts/validate.py
• Integration with other skills

Troubleshooting

Common Issues

Related Resources

• SKILL.md - Skill specification
• config.yaml - Configuration options
• validate.py - Validation script

---

Last updated: 2025-12-30

Css Performance Patterns

Design Patterns

Pattern 1: Input Validation

Always validate input before processing:

def validate_input(data):
    if data is None:
        raise ValueError("Data cannot be None")
    if not isinstance(data, dict):
        raise TypeError("Data must be a dictionary")
    return True

Pattern 2: Error Handling

Use consistent error handling:

try:
    result = risky_operation()
except SpecificError as e:
    logger.error(f"Operation failed: {e}")
    handle_error(e)
except Exception as e:
    logger.exception("Unexpected error")
    raise

Pattern 3: Configuration Loading

Load and validate configuration:

import yaml

def load_config(config_path):
    with open(config_path) as f:
        config = yaml.safe_load(f)
    validate_config(config)
    return config

Anti-Patterns to Avoid

❌ Don't: Swallow Exceptions

# BAD
try:
    do_something()
except:
    pass

✅ Do: Handle Explicitly

# GOOD
try:
    do_something()
except SpecificError as e:
    logger.warning(f"Expected error: {e}")
    return default_value

Category-Specific Patterns: Database

Recommended Approach

1. Start with the simplest implementation 2. Add complexity only when needed 3. Test each addition 4. Document decisions

Common Integration Points

• Configuration: assets/config.yaml
• Validation: scripts/validate.py
• Documentation: references/GUIDE.md

---

Pattern library for css-performance skill