phy-css-dead-code

What this skill does

# CSS Dead Code Auditor

CSS only grows. Every sprint adds new rules; almost none get removed. A feature gets deleted — the styles stay. A component gets renamed — the old class selectors stay. After a year, 30-40% of your stylesheet is dead weight: downloaded by every user, parsed by every browser, doing nothing.

Point this skill at your project and get a complete inventory of dead selectors, their exact file locations, estimated byte savings, and safe-deletion commands.

**Works with any CSS methodology. No config. No build step. Zero external APIs.**

---

## Trigger Phrases

- "unused CSS", "dead CSS selectors", "CSS dead code"
- "CSS bloat", "remove unused styles", "CSS cleanup"
- "what CSS can I delete", "CSS coverage", "unused classes"
- "Tailwind purge", "Bootstrap unused", "CSS audit"
- "stylesheet cleanup", "orphaned selectors"
- "/css-dead-code"

---

## How to Provide Input

```bash
# Option 1: Audit the current directory
/css-dead-code

# Option 2: Specific CSS file or directory
/css-dead-code src/styles/
/css-dead-code assets/main.css

# Option 3: Specify content directory (where HTML/JSX lives)
/css-dead-code --content src/

# Option 4: Specific framework
/css-dead-code --framework tailwind
/css-dead-code --framework vanilla
/css-dead-code --framework bootstrap

# Option 5: Show only selectors that can be safely deleted (high confidence)
/css-dead-code --safe-only

# Option 6: Estimate size savings only (quick mode)
/css-dead-code --size-estimate

# Option 7: Check a single selector
/css-dead-code --check ".btn-legacy-primary"
```

---

## Step 1: Detect CSS Framework and Project Structure

```bash
# Detect CSS framework from project files
FRAMEWORK="unknown"

if [ -f "tailwind.config.js" ] || [ -f "tailwind.config.ts" ] || [ -f "tailwind.config.cjs" ]; then
  FRAMEWORK="tailwind"
elif grep -r "bootstrap" package.json 2>/dev/null | grep -q "\"bootstrap\""; then
  FRAMEWORK="bootstrap"
elif find . -name "*.module.css" -not -path "*/node_modules/*" 2>/dev/null | head -1 | grep -q "."; then
  FRAMEWORK="css-modules"
elif find . -name "*.scss" -o -name "*.sass" -not -path "*/node_modules/*" 2>/dev/null | head -3 | grep -q "."; then
  FRAMEWORK="sass"
else
  FRAMEWORK="vanilla"
fi

echo "Detected framework: $FRAMEWORK"

# Find all CSS/SCSS/SASS/Less files
CSS_FILES=$(find . \( -name "*.css" -o -name "*.scss" -o -name "*.sass" -o -name "*.less" \) \
  -not -path "*/node_modules/*" \
  -not -path "*/dist/*" \
  -not -path "*/.next/*" \
  -not -path "*/build/*" \
  2>/dev/null)

CSS_COUNT=$(echo "$CSS_FILES" | wc -l | tr -d ' ')
echo "Found $CSS_COUNT CSS/SCSS files"

# Find all template/component files
CONTENT_FILES=$(find . \( -name "*.html" -o -name "*.jsx" -o -name "*.tsx" \
  -o -name "*.vue" -o -name "*.svelte" -o -name "*.hbs" \
  -o -name "*.erb" -o -name "*.blade.php" -o -name "*.pug" \) \
  -not -path "*/node_modules/*" \
  -not -path "*/dist/*" \
  2>/dev/null)

CONTENT_COUNT=$(echo "$CONTENT_FILES" | wc -l | tr -d ' ')
echo "Found $CONTENT_COUNT template/component files to cross-reference"
```

---

## Step 2: Framework-Specific Analysis

### Tailwind CSS

```bash
# Check tailwind.config.js content paths
echo "=== Tailwind Config Check ==="
python3 -c "
import re, json

try:
    with open('tailwind.config.js') as f:
        content = f.read()
    # Extract content array
    content_match = re.search(r'content\s*:\s*\[(.*?)\]', content, re.DOTALL)
    if content_match:
        print('Content paths configured:')
        for line in content_match.group(1).split(','):
            line = line.strip().strip('\"\'')
            if line:
                print(f'  {line}')
    else:
        print('⚠️  No content array found in tailwind.config.js — all classes may be purged!')
except FileNotFoundError:
    print('tailwind.config.js not found')
"

# Find classes actually used in content files
echo ""
echo "=== Tailwind Classes In Use ==="
# Extract all class="" values from content files
grep -rh "class[Name]*=\"[^\"]*\"\|class[Name]*={[^}]*}" . \
  --include="*.jsx" --include="*.tsx" --include="*.html" --include="*.vue" \
  --exclude-dir="node_modules" --exclude-dir="dist" 2>/dev/null | \
  grep -oE '[a-z][a-z0-9:-]+' | sort -u | head -50

# Run Tailwind CLI to see what would be purged
if command -v npx &>/dev/null; then
  echo ""
  echo "Running Tailwind dry-run to check purged classes..."
  npx --yes tailwindcss -i ./input.css -o /tmp/tw-output.css --minify 2>/dev/null
  echo "Output size: $(du -h /tmp/tw-output.css 2>/dev/null | cut -f1)"
fi
```

### Vanilla CSS / SCSS

```python
# Extract all selectors from CSS files and cross-reference with content
import re, os, sys
from pathlib import Path
from collections import defaultdict

def extract_selectors(css_content):
    """Extract all CSS selectors from a stylesheet."""
    # Remove comments
    css = re.sub(r'/\*.*?\*/', '', css_content, flags=re.DOTALL)
    # Remove @-rules (media queries, keyframes) content for now
    css = re.sub(r'@[^{]+\{[^}]+\}', '', css)
    # Extract selectors (before the { block)
    selectors = re.findall(r'([^{}@][^{}]*)\s*\{', css)
    result = []
    for sel_group in selectors:
        # Split on commas for multi-selector rules
        for sel in sel_group.split(','):
            sel = sel.strip()
            if sel and not sel.startswith('@'):
                result.append(sel)
    return result

def extract_class_refs(content):
    """Extract all class and ID references from template/component files."""
    classes = set()
    ids = set()
    # class="foo bar baz"
    for match in re.finditer(r'class(?:Name)?\s*=\s*["\']([^"\']+)["\']', content):
        classes.update(match.group(1).split())
    # className={`...`} dynamic classes
    for match in re.finditer(r'["\']([a-z][a-z0-9-_]+)["\']', content):
        classes.add(match.group(1))
    # id="foo"
    for match in re.finditer(r'\bid\s*=\s*["\']([^"\']+)["\']', content):
        ids.add(match.group(1))
    return classes, ids

# Collect all selectors from CSS files
all_selectors = defaultdict(list)  # selector -> [(file, line_num)]

css_dirs = ['.']
for css_dir in css_dirs:
    for fpath in Path(css_dir).rglob('*.css'):
        if 'node_modules' in str(fpath) or 'dist' in str(fpath):
            continue
        content = fpath.read_text(errors='ignore')
        for sel in extract_selectors(content):
            all_selectors[sel].append(str(fpath))

print(f"Total unique selectors found: {len(all_selectors)}")

# Collect all class/id references from content files
all_classes = set()
all_ids = set()
content_exts = ['.html', '.jsx', '.tsx', '.vue', '.svelte', '.erb', '.hbs']
for root, dirs, files in os.walk('.'):
    dirs[:] = [d for d in dirs if d not in {'node_modules', 'dist', '.next', 'build', '.git'}]
    for fname in files:
        if any(fname.endswith(ext) for ext in content_exts):
            fpath = Path(root) / fname
            content = fpath.read_text(errors='ignore')
            c, i = extract_class_refs(content)
            all_classes.update(c)
            all_ids.update(i)

print(f"Unique class references found in templates: {len(all_classes)}")

# Find unused selectors
unused = []
for selector, locations in all_selectors.items():
    # Extract the class name from the selector
    class_matches = re.findall(r'\.([a-zA-Z][a-zA-Z0-9_-]*)', selector)
    id_matches = re.findall(r'#([a-zA-Z][a-zA-Z0-9_-]*)', selector)

    is_used = False
    for cls in class_matches:
        if cls in all_classes:
            is_used = True
            break
    for id_name in id_matches:
        if id_name in all_ids:
            is_used = True
            break

    # Skip element-only selectors (body, h1, p, etc.) — too risky to flag
    if not class_matches and not id_matches:
        continue  # element selector, skip

    if not is_used:
        unused.append((selector, locations))

print(f"\nUnused selectors: {len(unused)}")
for sel, locs in sorted(unused, key=lambda x: len(x[1]), reverse=True)[: