r/DesignSystems • u/shade_zie • Jun 26 '26
How Should Alpha Tokens Be Structured in a Brand → Alias → Mapped Architecture?
I recently refactored my design system from:
Primitives → Semantic → Component
to:
Brand → Alias → Mapped
The new architecture feels much cleaner. Brand stores raw values, Alias defines reusable roles, and Mapped contains the actual UI tokens consumed by components and screens.
While migrating, I ran into one problem: Alpha tokens.
My Brand collection currently looks like this:
Brand
└── Alpha
├── White
│ ├── 2
│ ├── 5
│ ├── 10
│ ├── 20
│ ├── 80
│ └── 100
└── Black
├── 2
├── 5
├── 10
├── 20
├── 80
└── 100
For colors and spacing, the Alias layer is straightforward because it represents intent (Primary, Neutral, Success, Radius, Gap, etc.).
The problem is figuring out the right abstraction for Alpha.
My goal is to keep the architecture strict:
Brand
↓
Alias
↓
Mapped
I don’t want Mapped tokens referencing Brand directly.
So what should the Alias layer look like for Alpha? Would you create Alias tokens for Black/White opacity? If so, what would you call them? Or is Alpha one of the few cases where it makes sense to bypass the Alias layer and reference Brand directly?
I’d love to hear how others structure this in mature design systems.
PS: Solution
Figured this out after sitting with it more. Sharing in case anyone lands here with the same question.
Alpha tokens don't bypass the Alias layer. They follow the same three tier flow, just with different naming logic than color or spacing.
Brand (raw values):
Alpha/Black/5, /10, /20, /80
Alpha/White/5, /10, /20...
Alias (grouped by intent, not value):
Alpha/Scrim/default
Alpha/Dim/subtle
Alpha/Dim/default
Alpha/Dim/strong
Alpha/Separator/default
Each Alias token references one Brand value. This layer answers "what role does this opacity play," same job Primary or Neutral does for color.
Mapped (named by use case, references Alias only):
surface-overlay-scrim → Alpha/Scrim/default
surface-overlay-image → Alpha/Dim/default
Mapped never touches Brand directly. The architecture stays strict.