css-specificity

Analyze CSS specificity in a project, detect conflicts, flag unnecessary !important usage, and suggest corrections. Use when reviewing CSS code quality, debugging style overrides, auditing stylesheets, or when a user asks to check their CSS specificity, find CSS conflicts, simplify selectors, or clean up !important usage. Triggers on tasks involving .css files where specificity or selector quality is relevant.

SKILL.md

---
name: css-specificity
description: Analyze CSS specificity in a project, detect conflicts, flag unnecessary !important usage, and suggest corrections. Use when reviewing CSS code quality, debugging style overrides, auditing stylesheets, or when a user asks to check their CSS specificity, find CSS conflicts, simplify selectors, or clean up !important usage. Triggers on tasks involving .css files where specificity or selector quality is relevant.
---

# CSS Specificity Analyzer

Analyze CSS files for specificity issues, detect conflicts between rules, and suggest concrete improvements. Conservative approach: report and suggest, never auto-apply changes.

## Workflow

1. Locate `.css` files in the project using Glob (`**/*.css`)
2. Run the analyzer script (path relative to this skill's directory):
   ```bash
   python3 PATH_TO_SKILL/scripts/css_specificity_analyzer.py <file_or_dir> --json
   ```
   Replace `PATH_TO_SKILL` with the absolute path to the directory containing this SKILL.md.
3. Parse the JSON output
4. Present findings grouped by severity (errors first, then warnings)
5. For each issue, show the selector, line number, current specificity, and a concrete suggestion
6. Wait for user approval before applying any changes

## Running the Analyzer

```bash
# Single file
python3 PATH_TO_SKILL/scripts/css_specificity_analyzer.py styles.css --json

# Entire directory
python3 PATH_TO_SKILL/scripts/css_specificity_analyzer.py src/ --json

# Custom threshold (default 30, flag selectors scoring >= this)
python3 PATH_TO_SKILL/scripts/css_specificity_analyzer.py src/ --json --threshold 20
```

## Interpreting Results

The JSON report contains four sections:

- **summary**: Total selectors, average/max specificity, !important count, conflict count, warning/error counts
- **selectors**: Only selectors with issues (includes specificity, score, severity, and suggestion)
- **conflicts**: Pairs of rules with large specificity gaps targeting the same CSS property
- **importants**: Each `!important` usage with assessment of whether it masks a conflict or is unnecessary

## Presenting Suggestions

Propose specific rewrites with before/after specificity (e.g., "Replace `#header .nav a` with `.nav-link`").

For common anti-patterns and concrete fix examples, read [references/specificity-rules.md](references/specificity-rules.md).

## Applying Corrections

Only apply corrections after user approval. Apply one change at a time, re-run the analyzer after each batch, and never introduce new specificity issues while fixing existing ones.