Best practices for design system naming conventions

A foundational part of your design system is how you choose to name styles and components. Giving your components reasonable—dare I say, consistent—names isn’t just about developers. It’s for your teammates who will be collaborating with you, and future designers who will need to work with these components without reading your mind. 

Solid naming conventions make your designs easier to implement, your design systems easier to understand, and you a more collaborative designer. Inconsistent, context-specific names turn design systems into temporary solutions instead of a consistent, non-context-dependent design management tool.

(Want to make collaborating with developers even easier? Check out our Design System Manager.)

Let’s get into the best practices for naming conventions.

File naming convention best practices for styles and components

🗂 Tips for categories

Design systems have two categories: perceptual patterns and functional patterns. Every design system component fits into one of the above two major categories, and many incorporate elements from multiple categories.

We’ll be discussing perceptual patterns:

• Color
• Typography
• Sizing/spacing
• Imagery

While naming, try to focus on the element’s category and role, but not its form.

A blue primary button in your system, for example, should be named button/primary/default—without any mention of its color. This naming structure ensures that your element evolves along with your system, so if the color of that primary button changes, you won’t have to update its name throughout your system and codebase components.

(Want to read more about design systems? Start with our comprehensive guide.)

Best practices 101

The non-negotiable important factors in naming a component are:

• Consistency
• Clarity
• Meaning

The goal of implementing conventions is to make the element’s role in the design system obvious just from the name—meaning that, though iconsmallblue might make sense to you, it’s a disaster according to those three rules. 

Good practices:

• Separating words with hyphens or forward slashes 
• Following an “order of operations” type structure. 
• Using lowercase letters only

Practices to avoid:

• Using numbers and symbols
• Describing colors or using font types
• Focusing on component role

When these are practices, component names will be understandable without context and readable without needing to be sounded out.

Some factors to keep in mind are:

• Category: mobile, inverse, ui
• Type: header, hero, title, subtitle, paragraph, button, input, caption
• Size: large, medium, small, default
• Alignment: left, center, right

(Put your naming convention knowledge to work in InVision’s Design System Manager.)

Let’s get into category-specific guidelines:

🌈 Colors

• Structure: use/variation
• Examples:primary/default; tertiary/light

Usage examples:

• Good: brand/primary
• Bad: brand/green1

By describing colors using their role in the color hierarchy plus their differentiator, and not the color name, the color is clear without relying upon terms that could be misunderstood by someone unfamiliar with the style guide, or a colorblind collaborator.

✏️ Text Styles

• Structure:category/type/size/style/alignment
• Examples:para/primary/left; mobile/para/large/bold/right; para/primary/italic/left; inverse; para/small/center

Usage examples:

• Good: para/primary/left
• Bad: para/caption/timesnewroman

Having a specific text style for a caption might be too limiting if it’s not one-of-a-kind in the system. Additionally, it’s best to not use the actual name of the text, as that is an element that might change with a rebrand and would then have to be updated across the board

🎨 Layer Styles

• Structure:category/use/variation
• Examples:ui/input/default; fill/primary/hover; shadow/high

These names are based on clear and obvious layer styling elements and leave no guesswork for collaborators.

🛠Components

• Structure:category/type/element/variation, or organism/molecule/atom/variation
• Examples:btn/primary/hover; nav/header/mobile/dark; cards/media-block/complex/web

Usage examples:

• Good: menu/dropdown/default
• Bad: menu_dropdown_1

By explaining the component’s structure and functionality, these names provide context for the component without describing its appearance.

Thank you from your teammates

These simplified, streamlined, and standardized naming conventions might be less imaginative than what you had been doing to date, but they’re much easier to work with. As your team and system evolve, you’ll be grateful for the clarity in your naming conventions—and the role they play in your design system.