Color role

A palette answers “which colours do we have”. Roles answer “what is each colour for”. surface, on-surface, outline, primary, error: none of these names a colour, and that is the point. A card asks for surface and gets whatever the current scheme has decided a surface is, so the card can be written once and rendered into a light theme, a dark theme, and a high contrast theme without anybody editing the card. Material 3 is the best known role vocabulary, but the idea predates it and every mature system arrives at some version of it.

Roles are a division of labour with a palette, not a replacement for one. Underneath, something still says primary resolves to #3557E8, and swapping that mapping is how a theme happens. What roles buy is that the mapping lives in one place instead of in four hundred components. The practical test of whether a name is a role: could you change what it points at, on purpose, without hunting through the interface for the places that meant something else by it? brand-blue-600 fails that test. primary passes it.

The failure mode is a role vocabulary that is really a palette wearing a costume. If your roles are blue, light-blue and dark-blue, you have renamed the values, not named the jobs, and the first dark theme will expose it. The opposite failure is a vocabulary so fine grained that nobody can pick from it, which is what happens when a role is minted for every component that ever needed a slightly different grey. Keep the set small enough to hold in your head, and let genuine one-offs stay one-offs.

The word overlaps heavily with colour token, and the honest distinction is about tiers rather than about a different mechanism. A token is any named value in the chain; a role is a token whose name states a job rather than a colour, which is the tier components are supposed to read. On-colours are roles too, defined by the surface they sit on rather than by a job of their own.