css-performance

name	css-performance
description	Optimize CSS performance - critical CSS, code splitting, purging, bundle analysis
sasmp_version	1.3.0
version	2.0.0
updated	2025-12-30
bonded_agent	06-css-performance
bond_type	PRIMARY_BOND

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

Property	Value
Category	Optimization
Complexity	Advanced to Expert
Dependencies	css-fundamentals, css-architecture
Bonded Agent	06-css-performance

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

Metric	Target	Tool
CSS Size (gzip)	< 50KB	DevTools
Unused CSS	< 20%	Coverage
Critical CSS	< 14KB	Penthouse
FCP	< 1.8s	Lighthouse

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

Error Code	Cause	Recovery
INVALID_OPTIMIZATION	Unknown optimization type	Show valid options
TOOL_NOT_INSTALLED	Tool package missing	Show install command
OVER_PURGING	Styles missing in production	Expand safelist

Related Skills

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