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):

   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

# 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.

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.