When to use this
- Before building a new UI component, to check whether an existing one already covers the need.
- A PR introduces a component that looks like it duplicates existing functionality.
- Not for css-consistency-checker's token-level concerns -- this is about component-level duplication and API consistency.
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: design-system-consistency-checker description: Before or after a new UI component is built, check it against the existing design system/component library for duplication -- does an existing component already cover this need, and if not, does the new one follow the system's established API conventions. Use when adding new UI components. --- # Design System Consistency Checker ## Check for duplication first 1. Search the existing component library/design system for something that already does what the new component needs, including a close variant that could be extended with a new prop rather than duplicated wholesale. 2. If an existing component is close but not exact, is extending it (new prop/variant) actually simpler than a new component, given its existing usage elsewhere won't need to change? ## If a new component is genuinely needed Check it follows the system's established conventions: - **Prop naming**: consistent with how similar components name similar concepts (e.g. if every other component uses `variant`, don't introduce `type` for the same idea). - **Composition pattern**: consistent with whether the system favors children/slots vs. configuration props for similar components. - **Theming**: does it consume the same token system as other components (see css-consistency-checker), rather than hardcoding values? - **States**: does it handle the same baseline states other components in the system handle (loading, disabled, error, empty) if applicable to its kind? ## Output Either: "existing component X already covers this, here's how to use/ extend it," or "no existing match; here's where the new component deviates from the system's established conventions and should be aligned."
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 /design-system-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.
- Missing an existing component because the search only matched on name, not on what it actually does.
- Recommending reuse of an existing component that's a poor semantic fit just because it looks visually similar.
- Approving a new component with inconsistent prop naming/API shape relative to its siblings in the system.