Purpose

This document defines the semantic color system used across the design system.

It explains:

• What each semantic token means
• When to use each token
• How semantic tokens map to primitive colors
• How to choose the correct semantic token
• When a new semantic token is justified

The semantic system is designed to be used first in Notion documentation and later represented in the design-system token registry.

1. Token Architecture

The color system follows a two-tier structure:

PRIMITIVE
    ↓
SEMANTIC
    ↓
COMPONENT

Primitive

Primitive tokens represent the raw design value.

Examples:

gray/950
gray/700
gray/600
gray/400

blue/900
blue/500
blue/200

sky/600

Semantic

Semantic tokens represent the purpose, role, meaning, context, or state of that value.

Examples: