CSS Audit Tool

Analyze CSS files for duplicates, conflicts, unused rules, and structural issues across Framework components.

Purpose

The CSS Audit tool scans CSS files to identify problems that cause styling conflicts in the Hydrowise dashboard:

Duplicate selectors with conflicting values
Unused CSS rules (selectors not in HTML)
Specificity conflicts between component CSS
!important overuse
Missing responsive breakpoints

Running the Audit

Command Line

python css_audit.py --path /path/to/css --output report.html

Options

Flag	Description
`--path`	Directory containing CSS files to scan
`--output`	Output file for report (HTML or JSON)
`--html`	Path to HTML files for unused rule detection
`--ignore`	Comma-separated list of files to skip
`--strict`	Treat warnings as errors

Audit Categories

1. Duplicate Detection

Finds selectors defined multiple times with different values:

Problem: Same selector, different values

/* In dashboard.css */
.card { background: #fff; }

/* In components.css */
.card { background: #f0f0f0; }

Solution: Consolidate into single definition or use more specific selectors

.dashboard-card { background: #fff; }
.sidebar-card { background: #f0f0f0; }

2. Specificity Analysis

Calculates specificity scores and flags conflicts:

Selector Type	Specificity	Example
Element	0,0,1	`div`
Class	0,1,0	`.card`
ID	1,0,0	`#header`
Inline	1,0,0,0	`style=""`

Warning: When lower specificity rules use !important to override higher specificity, it creates maintenance problems.

3. Unused Rule Detection

Cross-references CSS selectors against HTML to find orphaned rules:

# Output shows unused selectors
UNUSED: .legacy-button (dashboard.css:145)
UNUSED: .old-header (theme.css:89)
UNUSED: #deprecated-modal (components.css:234)

4. !important Audit

Flags overuse of !important declarations:

Count	Severity	Action
0-5	OK	Acceptable for edge cases
6-15	Warning	Review and reduce
16+	Error	Refactor CSS architecture

5. Responsive Coverage

Checks for required breakpoints in component CSS:

Required breakpoints:
  @media (max-width: 1200px)  /* Desktop */
  @media (max-width: 992px)   /* Tablet */
  @media (max-width: 768px)   /* Mobile landscape */
  @media (max-width: 576px)   /* Mobile portrait */

Report Output

Summary Section

CSS AUDIT REPORT
================
Files scanned: 12
Total rules: 847
Duplicates found: 23
Unused rules: 45
!important count: 8
Missing breakpoints: 3 files

ERRORS: 2
WARNINGS: 5

Detailed Findings

DUPLICATE: .btn-primary
  Location 1: buttons.css:45 (background: #007bff)
  Location 2: theme.css:123 (background: #0066cc)
  Recommendation: Use single source, remove duplicate

UNUSED: .legacy-modal-backdrop
  Location: modals.css:234
  Recommendation: Remove if no longer needed

IMPORTANT: 8 declarations found
  dashboard.css:89 - .sidebar { width: 250px !important }
  Consider: Use more specific selector instead

Best Practices

CSS Encapsulation Rule: Components handle ONLY their own CSS. Parents NEVER set CSS on children. This enables embedding anything in anything without style conflicts.

Run audit before each release
Keep !important count under 5 per project
Remove unused rules immediately
Use BEM or similar naming to avoid conflicts
Document any intentional duplicates