تسمية الرموز وبنية الرموز متعددة المستويات

A flat list of color tokens works at first, then collapses as the system grows. A tiered token architecture keeps tokens scalable and meaningful.

This lesson builds on implementing tokens by structuring and naming them well.

Primitive (or global) tokens are raw values: blue-500 = #3b82f6, space-4 = 16px.

They are the full palette of available values, named by what they are, with no opinion about where they are used.

Semantic (or alias) tokens describe intent: color-action-primary, color-text-danger.

They reference primitives but add meaning. Components use semantic tokens, so re-theming means repointing aliases, not editing every component.

Component tokens scope values to a specific component: button-background-color, card-padding.

They reference semantic tokens. The chain below shows the three tiers resolving down to a raw value.

Why three tiers? Indirection. Change color-action-primary from blue to green once, and every button, link, and focus ring updates.

Without semantic tokens you would hunt down every hardcoded blue. Tiers turn sweeping changes into one edit.

Name semantic tokens by role, never by value. color-success survives a palette change; color-green becomes a lie.

The same rule applies to primitives - prefer blue-500 over brand-blue if the brand might shift.

Adopt a predictable pattern: category-property-variant-state, e.g. color-text-link-hover.

When every token follows the same grammar, developers can guess token names instead of searching docs. Consistency is the goal.

Not everything needs a token. Tokenizing every one-off value creates noise and maintenance burden.

Tokenize values that repeat or carry meaning. A truly unique magic number can stay inline with a comment.

Light, dark, and brand themes differ at the semantic layer. Primitives stay constant; semantic aliases repoint per theme.

This is why the tier structure makes multi-theme support nearly free - you swap one mapping table.

Show the token chain in your docs: which primitive a semantic token points to, and which components consume it.

This transparency helps contributors choose the right tier and understand the ripple effect of a change.

A tiered, well-named token system scales from one product to dozens of themed, white-labeled apps without rework.

The structure is the difference between tokens that empower and tokens that become technical debt.

You structured design tokens into a scalable architecture:

• Primitive tokens hold raw values.
• Semantic tokens add intent; components reference these.
• Component tokens scope values per component.
• Name by role, follow a consistent schema, and avoid over-tokenizing.

Tiered tokens make sweeping design changes a single edit.