Mar 13, 2025

Articles

A Semantic Color Naming System to Align the Team

James Franklin - CTO

James Franklin

Color is a crucial part of any design system, but without a clear naming convention, managing colors across a team can quickly become chaotic. Instead of relying on abstract or arbitrary names like blue-500 or red-light, a semantic color naming system aligns designers and developers by tying colors to their intent and purpose.

In this article, we’ll explore the benefits of a semantic approach, best practices for structuring your color system, and how to implement it effectively.

1. Why Use a Semantic Color Naming System?

A well-defined naming system offers several advantages:

  • Clarity & Consistency – Everyone knows what colors to use for specific purposes.

  • Scalability – Easily adapt new colors without breaking the system.

  • Easier Handoff – Developers can match design tokens without confusion.

  • Improved Accessibility – Ensures colors are used appropriately for contrast and readability.

2. Structuring a Semantic Color System

Instead of naming colors based on hue (blue-500), use functional names that describe their role.

Primary Colors (Brand & UI Colors)

These define the brand’s core color palette:

  • primary – The main brand color (e.g., for buttons, links, accents).

  • background – The default background color.

  • foreground – The default text color.


Feedback & State Colors

Used for communicating status in UI components:

  • success – Used for confirmations, positive actions (e.g., green).

  • attention – Indicates caution (e.g., yellow or orange).

  • danger – Represents errors or destructive actions (e.g., red).

  • info – Used for informational messages (e.g., blue).

Neutral & Background Colors

Essential for structure and readability:

  • accent – Used for cards or panels.

  • border – Color for dividers and outlines.

  • text-primary – Main text color.

  • text-muted-foreground – Used for subtitles or less prominent text.


3. Implementing in Design & Code

In Figma:

  • Create color styles with semantic names.

  • Use variants for light/dark mode.

  • Group colors into categories (Brand, UI, Feedback, Neutral).

Color is a crucial part of any design system, but without a clear naming convention, managing colors across a team can quickly become chaotic. Instead of relying on abstract or arbitrary names like blue-500 or red-light, a semantic color naming system aligns designers and developers by tying colors to their intent and purpose.

In this article, we’ll explore the benefits of a semantic approach, best practices for structuring your color system, and how to implement it effectively.

1. Why Use a Semantic Color Naming System?

A well-defined naming system offers several advantages:

  • Clarity & Consistency – Everyone knows what colors to use for specific purposes.

  • Scalability – Easily adapt new colors without breaking the system.

  • Easier Handoff – Developers can match design tokens without confusion.

  • Improved Accessibility – Ensures colors are used appropriately for contrast and readability.

2. Structuring a Semantic Color System

Instead of naming colors based on hue (blue-500), use functional names that describe their role.

Primary Colors (Brand & UI Colors)

These define the brand’s core color palette:

  • primary – The main brand color (e.g., for buttons, links, accents).

  • background – The default background color.

  • foreground – The default text color.


Feedback & State Colors

Used for communicating status in UI components:

  • success – Used for confirmations, positive actions (e.g., green).

  • attention – Indicates caution (e.g., yellow or orange).

  • danger – Represents errors or destructive actions (e.g., red).

  • info – Used for informational messages (e.g., blue).

Neutral & Background Colors

Essential for structure and readability:

  • accent – Used for cards or panels.

  • border – Color for dividers and outlines.

  • text-primary – Main text color.

  • text-muted-foreground – Used for subtitles or less prominent text.


3. Implementing in Design & Code

In Figma:

  • Create color styles with semantic names.

  • Use variants for light/dark mode.

  • Group colors into categories (Brand, UI, Feedback, Neutral).

Color is a crucial part of any design system, but without a clear naming convention, managing colors across a team can quickly become chaotic. Instead of relying on abstract or arbitrary names like blue-500 or red-light, a semantic color naming system aligns designers and developers by tying colors to their intent and purpose.

In this article, we’ll explore the benefits of a semantic approach, best practices for structuring your color system, and how to implement it effectively.

1. Why Use a Semantic Color Naming System?

A well-defined naming system offers several advantages:

  • Clarity & Consistency – Everyone knows what colors to use for specific purposes.

  • Scalability – Easily adapt new colors without breaking the system.

  • Easier Handoff – Developers can match design tokens without confusion.

  • Improved Accessibility – Ensures colors are used appropriately for contrast and readability.

2. Structuring a Semantic Color System

Instead of naming colors based on hue (blue-500), use functional names that describe their role.

Primary Colors (Brand & UI Colors)

These define the brand’s core color palette:

  • primary – The main brand color (e.g., for buttons, links, accents).

  • background – The default background color.

  • foreground – The default text color.


Feedback & State Colors

Used for communicating status in UI components:

  • success – Used for confirmations, positive actions (e.g., green).

  • attention – Indicates caution (e.g., yellow or orange).

  • danger – Represents errors or destructive actions (e.g., red).

  • info – Used for informational messages (e.g., blue).

Neutral & Background Colors

Essential for structure and readability:

  • accent – Used for cards or panels.

  • border – Color for dividers and outlines.

  • text-primary – Main text color.

  • text-muted-foreground – Used for subtitles or less prominent text.


3. Implementing in Design & Code

In Figma:

  • Create color styles with semantic names.

  • Use variants for light/dark mode.

  • Group colors into categories (Brand, UI, Feedback, Neutral).

Subscribe to updates

Subscribe to updates

Subscribe to updates