On-color

The on- prefix names a surface, not a colour. on-primary means “whatever is legible on top of primary”, and its actual value is decided when primary is decided, by whoever is deciding primary. Material 3 made the convention widespread by pairing every fill in its scheme with one: primary and on-primary, surface and on-surface, error and on-error. The payoff is that a component never has to guess. A button reads primary for its background and on-primary for its label, and it stays correct through a theme swap that the button’s author never saw.

The value of an on-colour is not a constant, and this is the part teams get wrong. On a deep indigo, on-primary is white. On a mid amber, white fails contrast badly and on-primary has to be near black. A codebase that hardcodes white for text on brand colour has quietly assumed the brand will always be dark, and it breaks the first time marketing picks a yellow. Shipping the pair together is what prevents that: the fill cannot travel to a new theme without its foreground travelling with it.

Two practical notes. The pair is a contract about contrast, so it is worth checking with a ratio rather than by eye: an on-colour that is merely a lighter shade of its own fill looks fine on a good monitor and disappears on a laptop in daylight. And the prefix composes into everything else, which is why systems that use it end up with a lot of tokens: on-primary-container, on-surface-variant, and so on. That is a real cost, and it is the cost of never having to decide foreground colour at the call site. A system that prefers fewer names will express the same idea as one colour role per pair, or leave it to a colour token named for its job. The idea, not the prefix, is what matters.