Color

PDS ships color in two layers. 119 core steps are the palette. 153 alias tokens are the decisions already made with it — color.Text.Primary, color.Background.Button.Primary Hover — and each one resolves to a core step. Nothing prevents you from typing a core step directly, so the only thing separating the palette from the system is which layer you reach for.

69 of the 119 core steps are referenced by an alias. The other 50 have no decision attached, and they are not scattered. 30 of them are the half-steps — 50, 150, 250, 350, and purple’s 450 — and another seven are step 1100, the darkest, in every hue. Slate’s 1100 is the exception, because it is color.Text.Primary.

So the alias layer was built on the round steps and left the ones between them alone. The half-steps still render in the matrix above and have never been the answer to a question. Reach for one and you are making the decision rather than applying it, and the package has nowhere to record what you decided.

The alias layer is lopsided: Background has 85 tokens, Border 45, Text 14, and Primary 9. The reason is how it grew. Background names a surface per component per state, so color.Background.Label.Purple Disabled and color.Background.Button.Outline Hover are separate tokens rather than one rule applied twice. A background you need probably already has a token. A text color for a state nobody has built probably does not — fourteen names cover every piece of text in the product.

In dist/css, 147 of the 153 alias properties are a var() pointing at another property, and the chain is intact: --color-background-button-primary is var(--color-primary-purple), which is var(--color-core-purple-600). Change one step and everything downstream of it moves.

In dist/js, the same token is a flat string. Color.BackgroundButtonPrimary is #3F48FD, and nothing in the value records that it came from purple 600. So a search for every consumer of a core step finds them in stylesheets and misses them in JavaScript, and the only complete map of alias to core is the 189 references in the Figma token file.

Six alias tokens have no core step behind them: color.Primary.Black and color.Primary.White are literal hex, and the four transparent button backgrounds are transparent — spelled rgba(0, 0, 0, 0) in CSS and transparent in JavaScript.

The tokens define one color per name. color.Background.Primary is white, in every theme, because the package has no concept of a theme.

Dark mode in the React library is therefore a second map, written by hand in @persona/design-system, and it reaches past the alias layer to core steps: its dark background is Color.CoreSlate1000 and its dark secondary text is Color.CoreSlate500. Neither is an alias, so neither appears in the alias layer as a dark value, and the two maps can disagree without anything detecting it.

Every step above is labeled in whichever of black or white meets WCAG AA against it, computed from the token at build time, and where neither reaches 4.5:1 the swatch says so. That is contrast for the swatch against black or white, and nothing else. It does not tell you the contrast of two tokens you are about to put together, and it is not a conformance claim — see Accessibility for what PDS does and does not verify.