Architectural Context: Palette vs Semantic vs Component Layers

Before evaluating naming and reuse, it is important to clarify structural layering.

A mature design token system separates color into three layers:

Primitive Layer

Raw color ramps such as red-500, blue-700, neutral-600.

Semantic Layer

Role-based meanings such as primary, warning, success, brand-primary.

Component Layer

Contextual assignments such as button-background, alert-border, card-surface.

This layered approach is explicitly described in Thunderbird’s recent design token work, where they distinguish primitive, semantic, and component tokens as separate architectural layers. See: https://youtu.be/rAJrAmu-lqw?si=cofi5ZeUtOYdlNAi&t=537

In that model:

• Primitives define raw color values.
• Semantics define meaning independent of specific hex values.
• Components consume semantics, not primitives.

The current Decidim color system appears strong at the primitive level and partially documented at the semantic level, but it does not formally define these as layered token tiers.

This architectural distinction is central to the rest of the audit.

1. Naming Conventions

Current System

Color families are structured as: