How palette tokens work

A colour change should not require a theme framework. For components that declare palette tokens, you can select a palette when retrieving source or override supported public CSS variables in your project. For other changes—and components without tokens—edit the source.

The simple pricing grid has two public tokens and neutral and blue palettes. Both are light appearance. Its public variables are the controls; private variables are the implementation underneath.

Layer one: variants are chosen at download time#

A component declares a set of variants, such as neutral or blue, and one default. The format can describe light and dark palettes, but each component declares the modes it actually supports.

The important detail is when a variant is applied. The catalogue exports every variant separately, so each one is its own artifact with its own digest. When you choose a variant, the colours are already in the files you receive. There is nothing to configure at runtime.

Variant values are also deliberately boring. They must be literal colours, either hex or oklch(...):

{
	"id": "blue",
	"label": "Blue",
	"overrides": {
		"light": { "accent": "#1d4ed8", "onAccent": "#ffffff" }
	}
}

A variant cannot inject a selector, a URL or arbitrary CSS into exported code, because the schema rejects anything that is not a colour.

Layer two: public variables for your overrides#

Each customizable colour is a token with a key, such as accent, and a public variable, such as --pricing-grid-accent. The public variable is the supported way to override a colour after you have copied the component.

After importing PricingGrid and defining its plans, set both colour variables on an ancestor:

<section style="--pricing-grid-accent: #1d4ed8; --pricing-grid-on-accent: #ffffff;">
	<PricingGrid title="Plans and pricing" {plans} />
</section>

Or set it once in your own stylesheet:

:root {
	--pricing-grid-accent: #1d4ed8;
	--pricing-grid-on-accent: #ffffff;
}

Because CSS custom properties inherit, the override applies to that component wherever it sits inside the element you chose, and to nothing else that does not read the variable.

Layer three: private variables inside the component#

Inside the component, each token also has a private variable, such as --_accent, declared in the entry file's scoped <style> block. The token's metadata lists the exact selectors where that declaration lives for light and dark mode.

The private variable is the component's internal name for the colour, and the selectors listed in the metadata show exactly how the public variable feeds into it in each mode. Treat private variables as implementation details: set the public one.

Where Tailwind fits#

The component's layout, spacing and typography are ordinary Tailwind utility classes in the markup. Tokens cover colours that are meant to be themed. If you want to change something that is not a token, edit the classes directly. Those local edits are yours to maintain.

Check contrast after every change#

Whatever palette you start from, a token override is a new colour combination that nobody else has checked. After changing a colour, re-check text and control contrast in every appearance mode you enable. The accessibility responsibilities page has a short checklist.

The public variable names above come from the pricing grid. Other components may declare different tokens or none at all. Each component lists its public tokens under Customization, and the customization guide covers the full picture.