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 on discovered files:

   python3 <skill_dir>/scripts/css_specificity_analyzer.py <file_or_dir> --json
   

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 scripts/css_specificity_analyzer.py styles.css --json

Entire directory:

python3 scripts/css_specificity_analyzer.py src/ --json

Custom threshold (default 30, flag selectors scoring >= this):

python3 scripts/css_specificity_analyzer.py src/ --json --threshold 20

Human-readable output (omit --json):

python3 scripts/css_specificity_analyzer.py styles.css

Interpreting Results

The JSON report contains:

• summary: Total selectors, average/max specificity, !important count, conflict count
• selectors: Only selectors with issues (warning/error severity with suggestions)
• conflicts: Pairs of rules with large specificity gaps targeting the same property
• importants: Each !important usage with assessment of whether it's necessary

Severity levels:

• error: Score >= threshold * 2 (default 60+)
• warning: Score >= threshold (default 30+)
• ok: Below threshold (not included in output)

Presenting Suggestions

When reporting to the user:

1. Start with summary stats
2. Group issues by severity (errors first)
3. Show before/after specificity for each suggestion
4. For conflicts, show both competing rules side by side
5. For !important, explain whether it masks a real conflict or is unnecessary
6. Propose specific rewrites (e.g., "Replace #header .nav a with .nav-link")

For detailed rules on common anti-patterns and fixes, read references/specificity-rules.md.

Applying Corrections

Only apply corrections after user approval. When the user approves:

1. Apply one change at a time
2. Re-run the analyzer after each batch to verify improvement
3. Never introduce new specificity issues while fixing existing ones