Scan and fix Tailwind anti-patterns across the movemental codebase, enforcing DESIGN.md token-first design.
Target: $ARGUMENTS
If no target is provided, scan src/components/ and src/app/(site)/.
Before Starting
- Read
src/app/globals.css — load the token inventory (@theme inline + :root).
- Read
docs/design/DESIGN.md — the authoritative design spec.
- Read
docs/build/prompts/stitch-to-react-migration.md §7 — the Stitch→DESIGN.md translation table.
Scan Checklist
1. HARDCODED COLORS (Critical)
Search for Tailwind color utilities that bypass semantic tokens:
Banned patterns:
bg-white, bg-black → bg-card / bg-inverse-surface
text-white → text-inverse-foreground (only in midnight sections) or text-primary-foreground
text-black → text-foreground
bg-blue-*, text-blue-* → bg-primary / text-primary
bg-gray-*, text-gray-*, bg-slate-*, text-slate-* → semantic tokens
- Arbitrary hex:
bg-[#...], text-[#...], border-[#...]
- Inline rgb/hsl in className or style props
Movemental translation table (from migration prompt §7):
| Anti-pattern |
Replace with |
bg-white, bg-[#ffffff] |
bg-card (on cards) or bg-popover |
bg-[#f7f9fb] |
bg-background |
bg-[#f0f4f7] |
bg-section or bg-muted |
bg-[#e1e9ee] |
bg-elevated or bg-secondary |
bg-[#0053db], bg-blue-600 |
bg-primary |
bg-[#101820], bg-black |
bg-inverse-surface |
text-[#2a3439] |
text-foreground |
text-[#566166], text-gray-500 |
text-muted-foreground |
text-white (on dark sections) |
text-inverse-foreground |
Allowed exceptions:
src/components/ui/* (shadcn primitives — do not touch)
src/app/globals.css (token definitions)
- SVG
fill/stroke using currentColor
- Opacity modifiers on semantic tokens:
bg-primary/10, text-inverse-foreground/55
2. BORDER VIOLATIONS (Critical — DESIGN.md §3.1)
Search for decorative borders used for section separation:
border-b, border-t, divide-y, divide-x between sections → remove and use tonal stacking
- Allowed:
border-border on form inputs, border-primary for accent on quotes/callouts
3. SHADOW VIOLATIONS (High)
shadow-sm, shadow-md, shadow-lg, shadow-xl, shadow-2xl → remove or replace with shadow-ambient
- Only
shadow-ambient (defined in globals.css) or tonal stacking (Ghost Lift)
4. ARBITRARY VALUES (High)
w-[, h-[, p-[, m-[, gap-[ with pixel/rem values → use Tailwind spacing scale
rounded-[ → use rounded-md (matches --radius: 0.375rem)
text-[ with size values → use standard Tailwind scale or Display/Eyebrow primitives
shadow-[ → use shadow-ambient token
Allowed: clamp() for responsive type, calc() for layout math, values in globals.css.
5. RAW HTML INSTEAD OF PRIMITIVES (Medium)
Search for patterns that should use movemental primitives:
<section with manual bg/padding → <Section variant="..."> primitive
<div with max-w-* + mx-auto + px-* → <Container> primitive
- Large bold headings with manual tracking →
<Display size="..."> primitive
- Uppercase small labels →
<Eyebrow> primitive
- Long-form text blocks →
<Prose> primitive
- Cards with shadow + rounded →
<SurfaceCard tone="..."> primitive
- Raw
<button → <Button> from shadcn
6. DARK MODE VIOLATIONS (Medium)
- No
dark: prefixes should exist — movemental is light-primary only
class="dark" on any element → remove (midnight is via Section variant, not class toggle)
text-white outside a variant="midnight" context → text-inverse-foreground inside midnight, or text-primary-foreground on primary backgrounds
7. TAILWIND V4 BEST PRACTICES (Low)
aspect-[4/5] → aspect-4/5 (canonical Tailwind v4)
bg-gradient-to-* → bg-linear-to-* (Tailwind v4)
- Duplicate utility classes
- Conflicting utilities (
p-4 p-6, flex block)
className concatenation without cn() utility
Fixing Protocol
- Fix at the source layer — If a needed token doesn't exist, add it to
globals.css @theme inline first.
- Never modify
src/components/ui/* — These are shadcn primitives.
- Batch similar fixes — If the same anti-pattern appears in multiple files, fix all instances.
- Verify after fixing — Run
pnpm typecheck after changes.
Output Format
## Tailwind Cleanup Report
### Summary
- Files scanned: X
- Violations found: X (Critical: X, High: X, Medium: X, Low: X)
- Auto-fixed: X
- Manual review needed: X
### Violations by Category
#### 1. HARDCODED COLORS — X violations
| File | Line | Violation | Fix |
|------|------|-----------|-----|
#### 2. BORDER VIOLATIONS — X violations
...
[Continue for all categories]
### Files Modified
- path/to/file.tsx — X fixes applied
Rules
- Always scan before fixing. Present the full report first, then apply fixes.
- Group fixes by file to minimize edits.
- Do not touch
src/components/ui/*, globals.css definitions, or Stitch source files in docs/build/stitch/.
- This is a light-primary site. There is NO global dark mode. Midnight is regional via
<Section variant="midnight">.
1---2name: tailwind-cleanup3description: Scan and fix Tailwind anti-patterns for movemental — hardcoded colors, arbitrary values, raw HTML bypassing shadcn/primitives, border violations, and non-semantic tokens. Enforces DESIGN.md token-first design.4user-invocable: true5allowed-tools: Read, Grep, Glob, Edit6metadata:7 source: https://skillmd.com/skills/joshuashepherd/tailwind-cleanup8---910Scan and fix Tailwind anti-patterns across the movemental codebase, enforcing DESIGN.md token-first design.1112Target: $ARGUMENTS1314If no target is provided, scan `src/components/` and `src/app/(site)/`.1516## Before Starting17181. Read `src/app/globals.css` — load the token inventory (`@theme inline` + `:root`).192. Read `docs/design/DESIGN.md` — the authoritative design spec.203. Read `docs/build/prompts/stitch-to-react-migration.md` §7 — the Stitch→DESIGN.md translation table.2122## Scan Checklist2324### 1. HARDCODED COLORS (Critical)2526Search for Tailwind color utilities that bypass semantic tokens:2728**Banned patterns:**29- `bg-white`, `bg-black` → `bg-card` / `bg-inverse-surface`30- `text-white` → `text-inverse-foreground` (only in midnight sections) or `text-primary-foreground`31- `text-black` → `text-foreground`32- `bg-blue-*`, `text-blue-*` → `bg-primary` / `text-primary`33- `bg-gray-*`, `text-gray-*`, `bg-slate-*`, `text-slate-*` → semantic tokens34- Arbitrary hex: `bg-[#...]`, `text-[#...]`, `border-[#...]`35- Inline rgb/hsl in className or style props3637**Movemental translation table (from migration prompt §7):**3839| Anti-pattern | Replace with |40|---|---|41| `bg-white`, `bg-[#ffffff]` | `bg-card` (on cards) or `bg-popover` |42| `bg-[#f7f9fb]` | `bg-background` |43| `bg-[#f0f4f7]` | `bg-section` or `bg-muted` |44| `bg-[#e1e9ee]` | `bg-elevated` or `bg-secondary` |45| `bg-[#0053db]`, `bg-blue-600` | `bg-primary` |46| `bg-[#101820]`, `bg-black` | `bg-inverse-surface` |47| `text-[#2a3439]` | `text-foreground` |48| `text-[#566166]`, `text-gray-500` | `text-muted-foreground` |49| `text-white` (on dark sections) | `text-inverse-foreground` |5051**Allowed exceptions:**52- `src/components/ui/*` (shadcn primitives — do not touch)53- `src/app/globals.css` (token definitions)54- SVG `fill`/`stroke` using `currentColor`55- Opacity modifiers on semantic tokens: `bg-primary/10`, `text-inverse-foreground/55`5657### 2. BORDER VIOLATIONS (Critical — DESIGN.md §3.1)5859Search for decorative borders used for section separation:60- `border-b`, `border-t`, `divide-y`, `divide-x` between sections → **remove** and use tonal stacking61- Allowed: `border-border` on form inputs, `border-primary` for accent on quotes/callouts6263### 3. SHADOW VIOLATIONS (High)6465- `shadow-sm`, `shadow-md`, `shadow-lg`, `shadow-xl`, `shadow-2xl` → **remove** or replace with `shadow-ambient`66- Only `shadow-ambient` (defined in globals.css) or tonal stacking (Ghost Lift)6768### 4. ARBITRARY VALUES (High)6970- `w-[`, `h-[`, `p-[`, `m-[`, `gap-[` with pixel/rem values → use Tailwind spacing scale71- `rounded-[` → use `rounded-md` (matches `--radius: 0.375rem`)72- `text-[` with size values → use standard Tailwind scale or Display/Eyebrow primitives73- `shadow-[` → use `shadow-ambient` token7475**Allowed:** `clamp()` for responsive type, `calc()` for layout math, values in `globals.css`.7677### 5. RAW HTML INSTEAD OF PRIMITIVES (Medium)7879Search for patterns that should use movemental primitives:80- `<section` with manual bg/padding → `<Section variant="...">` primitive81- `<div` with `max-w-*` + `mx-auto` + `px-*` → `<Container>` primitive82- Large bold headings with manual tracking → `<Display size="...">` primitive83- Uppercase small labels → `<Eyebrow>` primitive84- Long-form text blocks → `<Prose>` primitive85- Cards with shadow + rounded → `<SurfaceCard tone="...">` primitive86- Raw `<button` → `<Button>` from shadcn8788### 6. DARK MODE VIOLATIONS (Medium)8990- No `dark:` prefixes should exist — movemental is light-primary only91- `class="dark"` on any element → remove (midnight is via Section variant, not class toggle)92- `text-white` outside a `variant="midnight"` context → `text-inverse-foreground` inside midnight, or `text-primary-foreground` on primary backgrounds9394### 7. TAILWIND V4 BEST PRACTICES (Low)9596- `aspect-[4/5]` → `aspect-4/5` (canonical Tailwind v4)97- `bg-gradient-to-*` → `bg-linear-to-*` (Tailwind v4)98- Duplicate utility classes99- Conflicting utilities (`p-4 p-6`, `flex block`)100- `className` concatenation without `cn()` utility101102## Fixing Protocol1031041. **Fix at the source layer** — If a needed token doesn't exist, add it to `globals.css` `@theme inline` first.1052. **Never modify `src/components/ui/*`** — These are shadcn primitives.1063. **Batch similar fixes** — If the same anti-pattern appears in multiple files, fix all instances.1074. **Verify after fixing** — Run `pnpm typecheck` after changes.108109## Output Format110111```112## Tailwind Cleanup Report113114### Summary115- Files scanned: X116- Violations found: X (Critical: X, High: X, Medium: X, Low: X)117- Auto-fixed: X118- Manual review needed: X119120### Violations by Category121122#### 1. HARDCODED COLORS — X violations123| File | Line | Violation | Fix |124|------|------|-----------|-----|125126#### 2. BORDER VIOLATIONS — X violations127...128129[Continue for all categories]130131### Files Modified132- path/to/file.tsx — X fixes applied133```134135## Rules136137- Always scan before fixing. Present the full report first, then apply fixes.138- Group fixes by file to minimize edits.139- Do not touch `src/components/ui/*`, `globals.css` definitions, or Stitch source files in `docs/build/stitch/`.140- This is a light-primary site. There is NO global dark mode. Midnight is regional via `<Section variant="midnight">`.