css-refactor-advisor

name	css-refactor-advisor
description	Analyze a given style file or component directory, identify redundancy, inefficiency, and maintainability issues, and suggest optimizations.
when_to_use	Use this skill when you need to review CSS/SCSS code for quality issues, prepare for a style system refactor, reduce technical debt in styling, or improve performance and maintainability of a component's styles. It is particularly helpful before merging large style changes, onboarding new team members to a styling codebase, or diagnosing specific problems like specificity wars, duplicate code, or scattered responsive breakpoints.
tools	read, glob, grep
args	[{"name":"target","description":"Path to the style file or directory to analyze","required":true}]

GUIDANCE SKILL — INSTRUCTIONS ONLY CSS/SCSS architecture analysis focuses on identifying redundancy, specificity conflicts, responsive design fragmentation, maintainability gaps, and performance bottlenecks in style codebases. This skill provides patterns, conventions, and constraints. It contains no executable code — apply the guidance to your context, adapting specifics as needed per C2-B.

CRITICAL: Guidance Principles

The instructions below define the REQUIRED APPROACH — you MUST follow the prescribed patterns, conventions, and constraints.

Mandatory adherence:

• Follow all stated conventions and naming patterns
• Respect all constraints and boundaries
• Apply the recommended patterns to your implementation
• Do NOT deviate from prescribed architectural decisions
• Never modify any files; the analysis is strictly read-only
• Every complex issue MUST include a before/after code snippet demonstrating the suggested refactor

Correct Application Pattern

1. Read and absorb all guidance sections below
2. Map the prescribed patterns to your current context
3. Implement following the stated conventions — adapt specifics to fit, but preserve the intent
4. Validate against the C3 checklist at the end

Argument Details

Arg	Type	Required	Default	Description
target	string	Yes	—	Path to the style file or directory to analyze

Design Patterns & Conventions

Architectural Pattern

Multi-dimensional style audit: every analysis MUST examine the target styles through all five dimensions — Redundancy & Duplication, Specificity Issues, Responsive Design, Maintainability, and Performance. Each dimension is independently assessed, and findings are merged into a single severity-ranked report with concrete refactoring suggestions.

Naming Conventions

Findings are categorized using five standard labels that correspond to the analysis dimensions:

Category	Scope
Redundancy	Repeated style blocks, mergeable selectors, unused styles
Specificity	Overly specific selectors, !important abuse, selector wars
Responsive	Media query fragmentation, breakpoint inconsistencies, layout breakage
Maintainability	Non-semantic class names, magic numbers, missing variables, BEM violations
Performance	Expensive properties in animations, overly complex selectors, repaint/reflow risks

File / Module Organization

The output is a single structured Markdown report composed of:

1. A findings table with columns: Location (file:line), Category, Explanation, Suggestion — sorted by impact (highest first)
2. Before/after code snippets for complex issues (inline after each applicable table row or in a dedicated section)
3. An overall score (1–10) with a prioritized list of top improvements

Data Flow

Read target file(s) ({{target}} — single file or directory)
  → Parse and catalog all style rules
    → Scan for redundancy: identical blocks, mergeable selectors
      → Analyze specificity: selector depth, !important usage
        → Audit responsive design: breakpoint placement, media query nesting
          → Review maintainability: naming, variables, magic numbers
            → Check performance: animation properties, selector complexity
              → Merge findings, produce Markdown report (table + snippets + score)

Constraints & Boundaries

Hard Constraints (non-negotiable)

• Read-only: Never modify any files, styles, or configuration. The analysis is purely observational.
• Target required: The {{target}} argument is mandatory — the analysis cannot proceed without a valid file or directory path.
• All five dimensions: Every analysis MUST examine Redundancy, Specificity, Responsive Design, Maintainability, and Performance. If a dimension yields no findings, explicitly note that.
• Before/after for complex issues: Any finding that involves a structural refactor (not a simple rename or value change) MUST include a before/after code snippet.

Soft Guidelines (preferred but flexible)

• Prefer concrete before/after code snippets over prose-only explanations for all findings, even simple ones.
• When analyzing a directory, group findings by file to make the report easier to navigate.
• For BEM-related findings, reference the specific BEM rule being violated (Block, Element, or Modifier).
• Do not run build tools, linters, or dev servers — rely on static code analysis alone.
• Prioritize specificity and redundancy issues over cosmetic naming suggestions when ranking severity.

Implementation Guidance

Step-by-step Approach

1. Validate target: Confirm {{target}} points to an existing file or directory. If not, report the error and halt.
2. Read all style files: If {{target}} is a file, read it directly. If a directory, glob for *.css, *.scss, *.less and read all matches.
3. Parse and catalog: For each file, extract all rule sets, noting selectors, properties, values, and line numbers.
4. Dimension-by-dimension analysis:
   • Redundancy & Duplication: Compare rule sets across files. Flag identical blocks, mergeable selectors with shared properties, and styles with zero usage (unreferenced in markup).
   • Specificity Issues: Calculate selector specificity scores. Flag selectors exceeding a depth of 4, any use of !important, and ID selectors in reusable component styles.
   • Responsive Design: Audit media query distribution — flag breakpoints scattered across files instead of being co-located, missing min/max constraints, and conflicting breakpoint values.
   • Maintainability: Check for semantic class naming (BEM or project convention), CSS custom property / SCSS variable usage vs. magic numbers, and consistent units.
   • Performance: Identify expensive properties in animations (e.g., width, height, top, left instead of transform), deeply nested selectors causing broad DOM matching, and excessive universal selector usage.
5. Classify and rank: Assign each finding to a category. Sort by impact: Redundancy/Specificity → Performance → Responsive → Maintainability.
6. Draft before/after snippets: For complex issues, write a concise before/after code block demonstrating the suggested refactor.
7. Produce report: Build the Markdown findings table, append before/after snippets, compute the overall score (1–10), and list the top priority improvements.

Key Decisions

Decision	Rationale	Trade-offs
Target is mandatory	Style analysis without a target is meaningless; prevents accidental full-codebase scans	Less convenience for quick "review everything" requests
Five analysis dimensions	Covers the full lifecycle of style technical debt	Some overlap between Maintainability and Redundancy (e.g., duplicate variables)
Before/after required for complex issues	Concrete examples are more actionable than prose; CSS refactors are visual by nature	Increases report length; simple issues may feel under-documented
Redundancy/Specificity ranked above Maintainability	These have the highest impact on runtime behavior and developer friction	Cosmetic issues may be deprioritized even when numerous
No build or lint tools	Keeps analysis fast and self-contained; avoids toolchain dependencies	Cannot detect runtime-only issues like unused styles from dynamic class toggling

Usage Notes

Input / Output

Input: A required file path or directory path via {{target}}. When a directory is provided, all .css, .scss, and .less files within it (recursively) are analyzed. Single files of any supported extension are analyzed directly.

Output: A Markdown report containing:

1. A findings table with columns: Location (file:line), Category, Explanation, Suggestion — sorted by impact.
2. Before/after code snippets for complex findings.
3. An Overall Score (1–10).
4. Top Priority Improvements — a ranked bullet list of the highest-impact action items.

Feature Support

Feature	Input	Output
Single file analysis	CSS/SCSS/Less file path	Targeted report for one file
Directory analysis	Directory path	Multi-file aggregated report grouped by file
Cross-file redundancy detection	Directory path	Merged findings across all style files
Before/after snippets	Complex finding	Inline code block in report

Edge Cases

• Empty style file: Report "No styles found" with score N/A — do not fabricate issues.
• No style files in directory: If glob returns zero matches, report "No CSS/SCSS/Less files found in {{target}}" and halt.
• Mixed preprocessors: If a directory contains both .scss and .less files, analyze each with its own syntax rules and note the mix in the report.
• Very large files: If a file exceeds reasonable context size, analyze the first 2000 lines and note the truncation.
• Invalid target path: If {{target}} does not exist or is outside the workspace, report the error and halt immediately.
• CSS-in-JS / styled-components: These are outside the scope of this skill; note them as "skipped (CSS-in-JS)" and do not attempt to analyze.

Self-Check Before C3

Before running the formal C3 verification, confirm:

• All five dimensions have been examined (even if some yielded no findings).
• Every table row has all four columns populated (Location, Category, Explanation, Suggestion).
• Complex issues have accompanying before/after snippets.
• The overall score and top priority improvements are present.
• No files have been modified.

Common Pitfalls

Over-adaptation: "Adapt specifics to fit" does not mean rewrite the core patterns. When in doubt, preserve the prescribed approach over local convenience — the patterns exist for a reason.

Pattern drift: As implementation progresses, it's easy to gradually deviate from conventions. Regularly re-read the Design Patterns section to catch drift early.

Surface-level duplication scan: Do not limit findings to "these two blocks are identical." Examine the cascade — a repeated block may be necessary due to specificity battles elsewhere, and the real fix may be restructuring the selector hierarchy.

Ignoring the cascade: CSS is not isolated per-file. When reviewing a component's styles, always consider inherited styles, global resets, and parent-level rules that affect the component. A selector that looks clean in isolation may be compensating for a problematic upstream rule.

Vague suggestions: "Use a variable" or "Refactor this" are not actionable. Every suggestion must be concrete — propose the exact variable name, the merge target selector, or the specific BEM restructuring.

C3 Verification

Check Item	Constraint	Common Omission	Method
Pattern adherence	Prescribed patterns followed	Divergent implementation	Compare against Design Patterns section
Naming conventions	Conventions applied consistently	Inconsistent naming	Grep / code review
Hard constraints	All non-negotiable constraints met	Constraint violation	Manual checklist verification
File organization	Modules/files structured as prescribed	Misplaced or missing files	Directory structure review
All dimensions covered	Five analysis dimensions examined	Missing Performance or Responsive	Cross-reference report against Analysis Dimensions
Findings table complete	Every row has Location + Category + Explanation + Suggestion	Missing Location or Category	Table cell inspection
Before/after for complex issues	Complex findings include code snippets	Complex issue with prose-only fix	Scan for complex findings; verify snippet presence
Overall score present	Score (1–10) + prioritized improvements	Score without ranked action items	Verify both elements in output
Read-only enforced	No files modified during analysis	Accidental edit or write	Confirm no write/edit tools were invoked