| name | scss-refactor-planner |
| description | Analyze SCSS folders and propose a complete refactor plan (architecture, tokens, conventions, migration steps). Read-only: no file edits. |
SCSS Refactor Planner
Usage (folder selection)
Run:
/scss-refactor-planner <path>
Examples:/scss-refactor-planner src/styles/scss-refactor-planner apps/web/src/styles/scss-refactor-planner . (not recommended if repo is huge)
If no argument is provided:
- List top-level folders (
ls -1)
- Suggest likely style folders
- Ask the user to re-run with a folder path
- Stop
0) Resolve scope
If $ARGUMENTS is empty:
- !
ls -1
- Say: "Which folder should I analyze? Re-run: /scss-refactor-planner "
- Stop.
Verify path exists:
- !
test -e "$ARGUMENTS" && echo "OK: $ARGUMENTS" || echo "ERROR: path not found: $ARGUMENTS"
If missing:
- Ask for a valid folder path (include examples)
- Stop.
Define SCOPE = $ARGUMENTS.
1) Rules
- Do not modify files.
- Provide proof for claims (file counts, grep hits, examples of patterns).
- Focus on long-term maintainability and a realistic migration plan.
- Ignore noise by default:
node_modules, dist, build, .git, coverage.
2) Inventory & map the current SCSS system
2.1 Find SCSS files
- !
find "$ARGUMENTS" -type f -name "*.scss" | wc -l
- !
find "$ARGUMENTS" -type f -name "*.scss" | head -n 80
2.2 Identify entry points and import style
Look for:
@use / @forward (modern Sass modules)@import (legacy)
Commands:
- !
rg -n "@use\\b|@forward\\b|@import\\b" "$ARGUMENTS" | head -n 200
- !
rg -n "@import\\b" "$ARGUMENTS" | head -n 200
- !
rg -n "@use\\b|@forward\\b" "$ARGUMENTS" | head -n 200
2.3 Detect “global” files and patterns
- Variables/tokens:
$color, $space, $font, $z-
- Mixins/placeholders:
@mixin, %placeholder
- Resets/base:
reset, normalize, base, typography
- Utilities:
.u-, .is-, .has-
Commands:
- !
rg -n "\\$[a-zA-Z0-9_-]+" "$ARGUMENTS" | head -n 200
- !
rg -n "@mixin\\b|@include\\b" "$ARGUMENTS" | head -n 200
- !
rg -n "^%[a-zA-Z0-9_-]+" "$ARGUMENTS" | head -n 200
- !
rg -n "\\.(u-|is-|has-)" "$ARGUMENTS" | head -n 200
3) Quality checks / anti-pattern scan
3.1 Nesting depth hotspots
Find deeply nested selectors (rough signal: many { before }).
- !
rg -n "\\{" "$ARGUMENTS" | head -n 1 (sanity)
Heuristic: search for selectors with many spaces + & or long chains:
- !
rg -n "(&\\.|\\s{2,}\\.[a-zA-Z0-9_-]+\\s+\\.[a-zA-Z0-9_-]+\\s+\\.[a-zA-Z0-9_-]+)" "$ARGUMENTS" | head -n 200
3.2 Specificity, !important, IDs, inline overrides
- !
rg -n "!important" "$ARGUMENTS" | head -n 200
- !
rg -n "#[a-zA-Z0-9_-]+" "$ARGUMENTS" | head -n 120
3.3 Duplicate raw values (token candidates)
- Colors (hex/rgb/hsl):
- !
rg -n "#[0-9a-fA-F]{3,8}\\b|rgb\\(|rgba\\(|hsl\\(|hsla\\(" "$ARGUMENTS" | head -n 200
- Spacing numbers (common duplication):
- !
rg -n "(:|\\s)([0-9]+)(px|rem|em)\\b" "$ARGUMENTS" | head -n 200
- z-index:
- !
rg -n "z-index\\s*:\\s*[0-9]+" "$ARGUMENTS" | head -n 120
3.4 Duplicated selectors/components (signal)
- !
rg -n "^\\.[a-zA-Z0-9_-]+" "$ARGUMENTS" | head -n 200
4) Produce a COMPLETE refactor plan (output requirements)
A) Current State Summary
- Total SCSS files, key folders, import style (
@import vs @use)
- Main entrypoints (global, theme, components)
- Key problems (with evidence): repeated values, deep nesting, !important, inconsistent naming, legacy imports
B) Target Architecture (choose one and justify)
Pick the best fit for the repo and explain tradeoffs:
- ITCSS (settings/tools/generic/elements/objects/components/utilities)
- 7-1 pattern (abstracts/base/components/layout/pages/themes/vendors)
- Component-first (co-located styles per component + shared tokens)
Provide a proposed folder tree and naming conventions.
C) Design Tokens & Theming Strategy
- Which tokens to extract: colors, spacing, typography, radii, shadows, z-index, breakpoints
- Recommended structure:
_tokens.scss, _mixins.scss, _functions.scss
- Theme approach: CSS variables for runtime theming + Sass tokens for compile-time
Include example token naming rules (no need to rewrite the whole codebase, just show the pattern).
D) Conventions & Rules
Define:
- Naming scheme (BEM-like, or component namespace)
- Max nesting depth recommendation
- When to use mixins vs placeholders vs utilities
- How to handle responsive rules (breakpoint mixins)
- Linting strategy (stylelint) — only as a recommendation (no installation)
E) Migration Plan (step-by-step, safe)
Must be incremental:
- Create tokens + base layer
- Convert entrypoint to
@use/@forward strategy (if needed)
- Migrate highest-duplication modules first
- Replace raw values with tokens
- Reduce nesting and remove !important where possible
- Add regression checks (visual smoke, storybook/pages, etc.)
Each step should include:
- What to change
- Expected impact
- Risk
- How to validate
F) “Top 10 Refactor Targets”
List the highest ROI targets with evidence:
- Files/folders with most duplicates / highest risk patterns
- Suggested extraction or redesign
G) Appendix
- File list summary
- Key grep hits summary (counts + representative examples)
5) Important constraint
Do NOT implement changes. Only plan, examples, and guidance.
