Sass/SCSS Optimizer

Dart Sass 1.107 is modern Sass: modules (@use/@forward), built-in modules and the modern JS API. Cost is legacy @import, global color functions, deep nesting and @extend; the migration to Dart Sass 2 is the main risk. Optimize module structure, output and deprecations.

Workflow

1. Scope (quick)

• Find the app root and detect Sass/SCSS usage: Dart Sass 1.107.x. Record the version, framework (React/Next/Vue/Svelte/Solid/Angular or HTML), styling system, and whether the library is a package, a CSS-only kit, or copied source.
• Run python <skill-dir>/scripts/audit.py <project-root> -- static scan of package.json, config/CSS files and source for version drift, @import deprecation, legacy JS API, global color functions, @extend/nesting bloat and Dart Sass 2 migration, with file:line evidence. Use --json to post-process.
• Classify the pain: bundle/import cost, runtime/re-render cost, theming/SSR style flash, accessibility/forms, large tables/lists, or migration/upgrade. Ask which hurts if unclear.
• Read references/tooling.md once: what can be measured here.
• Check the Sass entrypoints, @use/@forward structure, the compiler in Vite/PostCSS, and whether node-sass/legacy JS API remains.

2. Audit

The script finds cheap leads; you find the rest by reading. Read the install/config, the global CSS/theme file, the provider or plugin setup, and the 3-5 most-used components. Load only what applies:

Measure, never guess. Build for production and measure the real route/bundle. Inspect SSR HTML for style tags and dark-mode flash; run axe/Playwright on dialogs, menus, forms and tables. Component count, bundle bytes and a11y violations are evidence; "feels heavy" is not.

Mark each finding Confirmed (build/analyzer/axe/code evidence) or Suspected (needs measuring).

3. Report

Fill assets/report-template.md, save it as SASS_SCSS_OPTIMIZATION_REPORT.md in the project root, and show the user. Five-line summary, findings table by impact/effort, then per-finding detail (evidence, why it hurts, fix, risk, visual/behavior impact). Group near-duplicates.

4. Plan -- then stop for approval

Use plan mode: EnterPlanMode (load with ToolSearch if deferred), write the plan, present with ExitPlanMode; if unavailable show it in chat and wait for an explicit "go". Structure:

1. Quick wins -- trim imports, use path imports, add provider/plugin correctly, add missing labels/titles, move heavy components off the initial route, remove per-row overlays, align theme tokens, add SSR style/cache setup. Low risk.
2. Structural -- split component boundaries, virtualize tables, lazy-load heavy widgets, consolidate theming, migrate variants/tokens, fix form composition, deduplicate copied components. Name each behavior change.
3. Heavy -- major upgrade, primitive-base change, CSS-only to styled kit (or reverse), Tailwind 3 to 4, copy-in registry extraction, SSR architecture. Separately approved. Each step: files touched, expected effect, how to verify, how to roll back.

5. Fix

Only approved items, in small groups. After each: typecheck, lint, tests, production build, and a visual/axe check on affected components. A break must trace to one change. Do not mix a major migration with optimization edits. If a change alters a public component API, theme tokens or SSR behavior, stop and ask.

6. Verify and wrap up

Re-measure the same routes/components: route JS/CSS, SSR styles/theme, axe violations, dialog/form keyboard flow, table interaction. State plainly what could not be measured. End with deferred items and one suggested next step.

Principles

• Modules, not imports. @use/@forward.
• Modern API. Dart Sass compile/compileAsync.
• CSS output is the budget. Measure compiled bytes.

Docs

• https://sass-lang.com/documentation/