naming-audit

Naming audit

A skill for auditing naming conventions across a design system's components, tokens, and patterns. Produces a violation report with specific examples, ambiguity flags, and rename suggestions with rationale.

Context

Naming is the primary interface between a design system and its consumers. A name is the first piece of information a designer or developer gets about what a component does, what a token means, or how a pattern behaves. Good names are predictable: consumers can guess what a name refers to before they look it up. Bad names require lookup, then clarification, then occasionally a conversation to confirm what was meant.

Naming problems accumulate. A single ambiguous component name is an inconvenience. Twenty ambiguous names spread across a library, with some following one convention and others following three others, is a system that new team members cannot navigate and experienced team members cannot trust.

This audit covers naming for components, tokens, and any documented patterns. It does not mandate a specific naming convention — it assesses whether the naming is consistent, unambiguous, and fit for its purpose.

Step 0: Identify what you're looking at

Before auditing names, determine what kind of shared UI this is. The library type changes how strict the consistency expectations should be and what recommendations are proportionate.

Classify from codebase signals:

• Design system — Full audit applies. Naming conventions should be documented, consistent, and enforced. Recommend creating a decision record for any undocumented conventions.
• Component library — Naming consistency matters, but the recommendation to "create a decision record" should be scaled down to "write down the convention you're already following, even if it's just a comment in the README." A 5-component library does not need a formal governance artefact.
• Pattern library — Naming conventions often follow the documentation tool's conventions (Fractal's folder numbering, Storybook's story hierarchy). Audit against the tool's conventions as well as internal consistency. Pattern names tend to describe what the pattern shows rather than what it does — flag this only if it creates confusion, not as a blanket violation.
• Utility collection — Naming is the primary interface. Every utility name needs to be unambiguous and predictable because there's no documentation site to fall back on. The audit should be strict on clarity and lenient on formal convention — a utility called clamp-width is better than one called u-cw even if the latter follows a prefix convention.