When to use this
- New component styling is being added and should follow existing design tokens/spacing scale.
- A page looks inconsistent with the rest of the site and needs a specific diagnosis.
- Not for a from-scratch design system audit -- this checks new/changed styles against an existing system, not building one.
The skill file
Copy this verbatim. It's written in the SKILL.md format (YAML frontmatter + markdown instructions) that Claude Code, and increasingly other agent tools, read directly.
--- name: css-consistency-checker description: Check new or changed CSS against the project's existing design tokens (color, spacing, typography scale) for hardcoded values that should reference an existing variable, plus responsive-width gaps. Use for new component styling in a codebase with an established design system. --- # CSS Consistency Checker ## Find the existing system first Before checking anything, identify the actual token source: CSS custom properties, a theme object, a Tailwind config, or a component library's scale. Don't invent a target -- use what already exists in this codebase. ## What to flag - **Hardcoded colors** that are the same as (or very close to) an existing token's value -- should reference the token, not repeat the hex/rgb value, so future palette changes propagate correctly. - **Hardcoded spacing** (margin/padding/gap px values) that don't align to the project's spacing scale, if one exists. - **Font sizes/weights** outside the established type scale. - **New breakpoints** introduced instead of reusing the project's existing responsive breakpoints. - **Duplicated component styles**: a new component re-implementing styling that an existing shared component/class already provides. ## Responsive check - Does new styling get checked at narrow widths (mobile), not just the viewport it was designed in? Specifically: horizontal scroll introduced by a fixed-width element, text/touch targets too small at mobile width, a layout that doesn't wrap/stack. ## Output Findings with the specific hardcoded value, the existing token/pattern it should use instead (cite it), and any responsive gap found.
Installing it elsewhere
The frontmatter/body split above is Claude Code's convention. Here's how to carry the same instructions into other tools:
Save the file below verbatim (frontmatter included) at that path, project-local or in ~/.claude/skills/ for a user-level skill. Claude Code loads the name/description pair to decide when to pull it in, or you invoke it directly as /css-consistency-checker.
Convert the YAML frontmatter to Cursor's rule format (description, globs, alwaysApply: false) and keep the markdown body as the rule content. Cursor surfaces it by description match, same idea as Claude Code's auto-load.
Codex CLI (and increasingly other agentic CLIs) read AGENTS.md at the repo root as always-on instructions. Paste the markdown body under a heading like ## {title}; for GitHub Copilot's coding agent, the equivalent file is .github/copilot-instructions.md.
Append the markdown body to .windsurfrules at the repo root. Windsurf treats the whole file as always-on context, so keep only the instructions you want applied on every request.
- Flagging a hardcoded value that's actually intentional one-off styling (e.g. a brand illustration's specific color) as if it must match a token.
- Checking only desktop width and missing a responsive/mobile-width regression.
- Suggesting a new token be created for a one-off value instead of checking whether an existing close-enough token should just be reused.