style-critic

name

style-critic

description

Use when SCSS/CSS is the subject of review or authoring in this repo. Triggers include "audit the CSS", "review the styles", "run style-critic", "is this stylesheet compliant", "check the CSS conventions", any new or edited `*.module.scss`, a diff touching `styles/`, a hardcoded color / font size / border radius, a `margin` appearing in a stylesheet, an unguarded `transition` or `animation`, a `:global()` without a comment, or before shipping any component's styles.

Style Critic

Overview

Enforces the CSS section of CLAUDE.md — the twelve conventions are the source of truth; this skill is how they get checked. gale lints SCSS syntax, but nothing in the toolchain enforces the conventions themselves: tokens over literals, gap over margins, named areas, reduced-motion guards. Convention held only by review drifts, so this skill makes every rule mechanically checkable where possible and names the judgment calls where not.

Violating the letter of the rules is violating the spirit of the rules.

Measured baseline when this skill was written (48 SCSS files):

• clean: module-only styles, aliased imports, two global stylesheets, zero positional grid placement, zero id selectors, zero hardcoded breakpoints, all 26 motion files guarded, both :global() uses commented
• debt: 136 non-token font-size, 49 non-token border-radius, 68 non-token line-height/letter-spacing, 32 hardcoded colors, 6 margins (four of them margin: 0 auto centerings)

The rules and their checks

Run every check from the repo root. A rule is clean when its check prints nothing (or the stated expected output). Read every flagged line before calling it a violation — greps find candidates, the critic renders the verdict.

R1 — component styles live in *.module.scss

find components app lib -name "*.scss" ! -name "*.module.scss"

Expected: empty.

R2 — modules imported through @/, never relatively

grep -rn "import.*module\.scss" components app --include="*.tsx" | grep -v "@/"

Expected: empty. The react-ts-css extension flagging aliased imports is a tooling bug — never "fix" it by relativizing the import.

R3 — exactly two global stylesheets

ls styles/

Expected: _breakpoints.scss and globals.scss, nothing else. New global files need a CLAUDE.md change first.

R4 — container-driven sizing (judgment)

No grep catches this. When reviewing a module, check the component's root class: it must not set its own external width to suit one parent, and must not carry outer margins. The container defines available width and height, padding, and spacing between children; children only care about their content.

R5 — gap for spacing, margins banned at all cost

grep -rnE "margin[a-z-]*:" components app styles --include="*.scss" | grep -vE ": 0;"

Expected: empty. margin: 0 resets are the only sanctioned margin. This includes prose: rendered-markdown containers are grids, element margins stay zeroed, gap sets the rhythm. margin: 0 auto centering is also a violation — center with the container (place-items, justify-self).

R6 — grid first, flex for runs (judgment)

Grid when the container defines the tracks; flex for one-dimensional, content-sized runs — toolbars, inline rows, baseline alignment. Flag flex containers doing two-dimensional layout and grids faking a single content-sized row.

R7 — named areas in fixed layouts, no positional spans

grep -rnE "grid-(area|row|column): *[0-9-]" components app styles --include="*.scss"

Expected: empty. Fixed regional layouts place children with grid-template-areas + grid-area: <name>. Auto-placed collections (repeat(auto-fill, ...), grid-auto-flow) are exempt — dynamic children can't be named. Overlays: give multiple children the same named area.

R8 — style by class, never by id

grep -rnE "^\s*#[a-zA-Z][a-zA-Z0-9_-]* *[{,]" components app styles --include="*.scss"

Expected: empty. (Hex colors also start with # but never open a block — the anchor and brace keep them out.)

R9 — tokens for color, type, radius; extend the scale when none fits

grep -rnE "#[0-9a-fA-F]{3,8}\b|rgba?\(" components app --include="*.scss" | grep -v "var(--"
grep -rn "font-size:" components app --include="*.scss" | grep -v "var(--fs"
grep -rn "border-radius:" components app --include="*.scss" | grep -v "var(--tkw-radius)"
grep -rnE "line-height: [0-9]|letter-spacing: [0-9.]" components app --include="*.scss"

Expected: empty. The token families are --tkw-*, --font-*, --fs-*, --lh-*, --ls-* in styles/globals.scss. If no token fits, extend the scale in globals.scss — never inline the value. Exempt until a spacing scale lands: gap and padding values. Judgment call to surface rather than auto-flag: #000/#fff inside mask-image gradients are alpha stops, not visual color — report them, let the human rule.

R10 — breakpoints only through _breakpoints.scss

grep -rnE "@media[^{]*[0-9]+px" components app --include="*.scss" | grep -v "bp\.\$"

Expected: empty. Desktop-first, @use "breakpoints" as bp; then @media (max-width: bp.$md).

R11 — every motion file guards prefers-reduced-motion

for f in $(grep -rlE "transition:|animation:" components app --include="*.scss"); do
  grep -q "prefers-reduced-motion" "$f" || echo "MISSING GUARD: $f"
done

Expected: empty.

R12 — :global() is a commented escape hatch

grep -rn -B2 ":global" components app --include="*.scss"

Expected: every use has a // comment directly above explaining why the scope escape is unavoidable.

Verdict discipline

• New violation in the diff under review → must fix before ship. No severity haggling; the rules have no minor tier.
• Pre-existing debt → report the count and the worst files; do not bulk-fix unrequested. Scope stays with what was asked.
• Every ❌ names file:line. A verdict without a location is a vibe, not a finding.

Report format

One line per rule, ❌ first, counts and worst offenders inline:

## style-critic — <scope audited>

- ❌ R9 tokens — 136 `font-size` off-scale; worst `app/design/page.module.scss` (43)
- ❌ R5 margins — `components/FilteredHouseList/FilteredHouseList.module.scss:187`
- ✅ R7 grid placement — 0 positional spans, 9 files on named areas
- ✅ R11 reduced motion — 26/26 motion files guarded

Close the report by separating new-in-diff violations (blocking) from pre-existing debt (counted, not fixed).

Red flags — STOP and re-read the rule

Thought	Reality
"4px is too small to deserve a token"	The scale exists to kill exactly this drift
"I'll tokenize it in a follow-up"	The follow-up never comes. Extend globals.scss now
"gap has no scale, so tokens are optional here"	gap/padding are exempt; color, type, and radius are not
"this page is a showcase, it's special"	No file is exempt until CLAUDE.md says so
"the editor says the aliased import is broken"	Tooling bug. Never relativize a module import
"a margin is easier than restructuring the parent"	Margins are banned at all cost. The container owns spacing
"margin: 0 auto is centering, not spacing"	Still a margin. Center with the container
":global is quicker than threading a class"	Escape hatch. Needs a // why-comment or it's a violation
"the grep found nothing, ship it"	R4 and R6 are judgment rules — greps can't clear them

Related skills

• component-scaffold — the four-file component structure, plus its own token-drift counter (audit-components.ts) scoped to components/
• a11y-audit — motion guards overlap; that skill owns the wider WCAG sweep