1. What are semantic colors?

Semantic color tokens describe the purpose of a color in the interface, rather than the actual color value.

For example:

gray/950 is a primitive color.

text.primary is a semantic color.

The primitive tells us what the color is.

The semantic token tells us why and where the color is used.

Primitive = color value

Semantic = meaning / role

2. Semantic Color Structure

Color
│
├── Text
│
├── Icon
│
├── Background
│
├── Action
│
├── Status
│   ├── Success
│   ├── Warning
│   └── Danger
│
└── Border

Each category represents a different UI role.

3. Text

Text semantics describe the level of emphasis or availability of text.

Token Meaning Purpose
text.primary Main text Important information, headings, primary content
text.secondary Supporting text Secondary information and supporting content
text.muted Low-emphasis text Metadata, hints, timestamps, less important information
text.disabled Unavailable text Disabled controls or unavailable content
text.inverse Text on an opposite/dark surface Text placed on dark or inverse backgrounds

Mental model

primary
   ↓
secondary
   ↓
muted
   ↓
disabled

The further down the hierarchy, the less emphasis the text receives.