astro44/css-audit

css-audit - CSS Quality Audit

Audits CSS for unused selectors, specificity issues, duplicate declarations, and design token compliance.

Input Schema

{
  "project_dir": "/path/to/project",
  "css_dir": "src/styles/",
  "html_dir": "src/",
  "checks": ["unused", "specificity", "duplicates", "tokens"],
  "design_tokens": "src/styles/tokens.css"
}

Instructions

1. Find Unused Selectors

# Extract all CSS selectors
grep -rh "^[.#a-zA-Z]" src/styles/*.css | cut -d'{' -f1

# Check if used in HTML/JS
for selector in $selectors; do
    grep -rq "$selector" src/ || echo "UNUSED: $selector"
done

2. Check Specificity Issues

// Flag high specificity selectors
// Ideal: 0,1,0 (single class)
// Warning: 0,2,0+ (multiple classes)
// Error: 1,0,0+ (ID selectors in component CSS)

const highSpecificity = selectors.filter(s =>
  s.match(/#/) || s.split('.').length > 3
);

3. Find Duplicate Rules

# Find duplicate property declarations
grep -rn "color:" src/styles/*.css | sort | uniq -d
grep -rn "font-size:" src/styles/*.css | sort | uniq -d

4. Design Token Compliance

/* Check hardcoded values vs tokens */
/* BAD: color: #3498db; */
/* GOOD: color: var(--color-primary); */

grep -rn "#[0-9a-fA-F]\{3,6\}" src/styles/*.css
grep -rn "px" src/styles/*.css | grep -v "var(--"

Output Format

{
  "skill": "css-audit",
  "status": "pass|warning|fail",
  "files_audited": 12,
  "selectors_total": 156,
  "checks": {
    "unused": {
      "passed": false,
      "count": 8,
      "selectors": [
        {
          "selector": ".legacy-header",
          "file": "src/styles/header.css",
          "line": 45
        }
      ]
    },
    "specificity": {
      "passed": true,
      "high_specificity": []
    },
    "duplicates": {
      "passed": false,
      "count": 3,
      "duplicates": [
        {
          "property": "color: #333",
          "locations": [
            "src/styles/base.css:12",
            "src/styles/components.css:89"
          ],
          "suggestion": "Extract to var(--color-text)"
        }
      ]
    },
    "tokens": {
      "passed": false,
      "violations": [
        {
          "file": "src/styles/card.css",
          "line": 23,
          "value": "#3498db",
          "suggestion": "Use var(--color-primary)"
        }
      ]
    }
  },
  "summary": {
    "unused_selectors": 8,
    "high_specificity": 0,
    "duplicate_rules": 3,
    "hardcoded_values": 5
  },
  "suggestions": [
    "Remove 8 unused selectors to reduce bundle size",
    "Extract repeated color #333 to design token"
  ],
  "errors": [],
  "next_action": "proceed|cleanup"
}

Checks Performed

| Check | What it Validates | Severity | |-------|-------------------|----------| | unused | Selectors not referenced in HTML/JS | LOW | | specificity | Selectors below threshold | MEDIUM | | duplicates | No repeated property values | LOW | | tokens | Design token compliance | MEDIUM | | important | Avoid !important | MEDIUM | | vendor_prefix | Autoprefixer handles prefixes | LOW |

Decision Logic

Any specificity violations?
    YES → status: "warning"

Token compliance below 80%?
    YES → status: "warning"

More than 20% unused selectors?
    YES → status: "warning"

All checks pass?
    YES → status: "pass", next_action: "proceed"

Usage Examples

Full CSS audit:

{
  "project_dir": "/projects/oxygen_site",
  "css_dir": "src/styles/",
  "html_dir": "src/",
  "checks": ["unused", "specificity", "duplicates", "tokens"],
  "design_tokens": "src/styles/variables.css"
}

Quick unused selector check:

{
  "project_dir": "/projects/oxygen_site",
  "css_dir": "src/styles/",
  "html_dir": "src/",
  "checks": ["unused"]
}

Token compliance only:

{
  "project_dir": "/projects/oxygen_site",
  "css_dir": "src/styles/",
  "checks": ["tokens"],
  "design_tokens": "src/styles/tokens.css"
}

Token Efficiency

• Pattern-based analysis
• No AST parsing required
• ~5-15 second execution
• Returns cleanup suggestions