Customization

There are three levels of customization, from lightest to most involved: choose a variant, override palette tokens with CSS variables, and edit the source. Palette overrides exist only for components that declare tokens; every other component is customised by editing its utility classes.

Content comes first #

Where a component accepts text, links or images as props, replace the preview fixture content with your own through those props before changing anything else. Props, their defaults and which ones are required are listed on each component page.

Choose a palette #

The palette selector uses a technical variant ID to identify the exported colour choice. Every release has at least one variant. Each has an id (such as neutral or blue) and a label, and one is marked as the defaultVariant. A variant is a set of palette overrides for the light mode, the dark mode, or both. A component without tokens normally has a single default variant that leaves the source unchanged.

Variants are applied when the catalogue builds its artifacts, so each variant is a separate download with its own artifactDigest. Choosing a variant does not add runtime configuration; the chosen colours are already in the exported source.

Palette values are restricted to literal colours, either hex (#rgb, #rrggbb, #rrggbbaa) or oklch(...). A variant can never inject selectors, URLs or arbitrary CSS.

Palette tokens and CSS variables #

Palette tokens apply only to components that declare them. Such a component keeps each value in its scoped <style> block as --_local: var(--public, fallback). A component with no tokens has no public variables to set; change its colours by editing the Tailwind utility classes in its source.

Each customizable colour is a token with three names:

Each token also lists the selectors in the entry file's <style> block where its value is declared, per mode (targets.light, targets.dark). Those selectors are where to look if you want to see exactly how the public variable is consumed.

If you author tokens, two constraints apply. A target selector must appear exactly once, compared after normalising whitespace, among the rules of the entry file's <style> block, nested rules included. The declaration under that selector must be exactly <localVariable>: var(<publicVariable>, <fallback>), because the build rewrites only the fallback when it materialises a variant.

The names in the table are illustrative. A component's public token keys and variables are listed under Customization on its page and in its public metadata; the bundle receipt points to the customization documentation through customizationPath. The private variable and target selectors are authoring details, visible in the entry file's source.

For the pricing grid, set its two public variables on a wrapper (after importing PricingGrid and defining plans):

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

To override it site-wide, set it in your global stylesheet on a selector that contains the component:

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

The private --_ variable is an implementation detail. Set the public variable, not the private one.

Editing the source #

Everything you download is plain Svelte and Tailwind. When props and tokens are not enough, edit the files: change the markup, swap utility classes, remove parts you do not need. The component's customization.guide lists specific suggestions where the author provided them.

Once you edit the source, future releases will not merge automatically. Keep the receipt so you know which version your copy started from.