Functional Color Token Architecture: Primitive vs. Semantic

Scalable design systems never hardcode hex values directly into components. They structure color into a two-tiered token architecture:

1. Primitive (Global) Tokens

Raw color palette definitions referencing specific values:

• blue-500: #3B82F6
• gray-100: #F3F4F6
• red-600: #DC2626

2. Semantic (Contextual) Tokens

Intent-based aliases that bind to primitives depending on application context and theme:

• surface-primary: references gray-50 in light mode and gray-900 in dark mode.
• action-primary-hover: references blue-600.
• feedback-error-text: references red-600.

Semantic tokens allow an entire product to re-theme or toggle dark mode instantly without touching component markup.