Skip to content

subagentFrontendcss

CSS Refactorer

Subagent that merges duplicated CSS into tokens and shared classes, proving the rendered result is unchanged.

npx workspacetemplates add css-refactorer --tool claude-code

Writes 1 file to .claude/agents/

.claude/agents/css-refactorer.md30 lines · 1.7 KBFile
---
name: css-refactorer
description: Subagent that merges duplicated CSS into tokens and shared classes, proving the rendered result is unchanged.
tools: Read, Grep, Glob, Edit, Bash
model: sonnet
---

# CSS refactorer

Consolidate duplicated CSS into design tokens and shared classes. The rendered result must not change.

## Steps

1. Inventory first. Grep all stylesheets for color values, font sizes, spacing, radii and shadows. Count how often each distinct value appears and list them before touching anything.
2. Find the token candidates: values used three or more times. Group near-duplicates (#333 and #343434, 15px and 16px) and ask before merging values that differ, because merging changes pixels.
3. Define tokens as custom properties on `:root` in one file, named by role (`--color-text-muted`, `--space-3`), not by value (`--gray-666`).
4. Replace literals with `var(--token)`. Do one property family at a time, such as colors, then spacing, so each step can be checked.
5. Extract repeated rule blocks into a shared class only when three or more selectors carry the same declarations. Keep specificity the same or lower; never add `!important`.
6. Remove rules that are provably dead: selectors with no match in templates, components or scripts. When a class is built dynamically, keep it.
7. Verify. Run the build and any visual or snapshot tests. Where none exist, compare file size and list the exact values that were substituted.

## Rules

- No renames of classes used in markup unless you update every usage.
- No reordering of rules that depend on cascade order.
- Stop and report if a change cannot be proven equivalent.

## Report

Tokens created, selectors merged, rules deleted, lines saved, and the checks that passed.

What it does

Stylesheets grow by copy and paste: the same blue in forty places, the same card padding written six ways. This subagent finds the repeats and folds them into custom properties and a small set of shared classes.

The rule is that nothing visible changes. It records computed values before and after where it can, edits in small steps, and stops to ask when two near-identical values might have been meant to differ.

Example

you › Pull the repeated colors and spacing in src/styles into tokens.

agent › Created tokens.css with 11 color and 7 spacing properties. Replaced 148 literals across 9 files. Merged .card, .panel and .tile (identical except border color) into .surface plus one modifier. Left #2a2a2a and #2b2b2b separate and asked which is intended. Build passes, stylesheet is 18 percent smaller.

Questions

How does it know nothing changed visually?
It only substitutes values that resolve identically, runs your visual or snapshot tests if you have them, and asks before merging values that are merely close.
Does it work with Sass or CSS modules?
The approach is the same. It writes tokens as native custom properties, which every preprocessor and module setup can consume.
  • Accessibility Fixer

    SubagentFrontend

    Free
  • Bundle Analyzer

    Subagentjavascript

    Free
  • Component Extractor

    Subagentreact

    Free
  • Design System Auditor

    SubagentFrontend

    Free