Use a design system in your product
Switch a product to Cobalt, Neutral or your organisation's design system, keep it current, and let people switch.
A product builds in one design system and can let people switch to others. Your code stays the same in each, because you write semantic tokens. Your organisation's design systems must be published first.
Switch with one command
In the product's repository, run pfdl theme (see The pfdl command line):
pfdl theme # the design systems you can use, the current one starred
pfdl theme acme # switch to acme: settings, stylesheet and code in one step
pfdl theme cobalt # back to the base
It sets "brand" in pfdl.config.json, keeps your organisation's stylesheet, fonts and logos in src/brand/, and
wires ThemeProvider in your entry file the first time. Don't edit src/brand/index.ts by hand.
Cobalt and Neutral need no sign-in. For your organisation's own, sign in first with Design Language Connect or
pfdl connect sign-in, or set PFDL_TOKEN to an access token (viewer is enough).
Keep it current
pfdl theme updatebrings in the latest published revision. Review the change and commitsrc/brand/.pfdl theme checkin CI fails when your copy is behind. Give CIPFDL_TOKENand"portal"inpfdl.config.json.
Tell AI tools which one
pfdl.config.json at the repository root tells agents and the linter which design system the product wears:
{ "brand": "acme", "portal": "https://portal.example.com" }
Agents then read its tokens and curated templates through the MCP server.
Let people switch
Offer the switch with BrandSwitcher, inside a ThemeProvider with persist so the choice is remembered:
pfdl theme acme --offer cobalt,neutral,acme # the ones BrandSwitcher offers
pfdl theme acme --only # no switch: acme only
import { BrandSwitcher } from "@purple-fabric/ui";
<BrandSwitcher />
Put it in the account menu or a settings page. It shows nothing with fewer than two on offer.
Load it from the portal instead
To load the published stylesheet at runtime rather than keep a copy, open the design system in
/brands, go to Export and use › Use it, and copy the lines it gives: an HTML <link> with
data-brand, or loadBrand() with ThemeProvider. Stylesheet link on the design system's card copies the address.
- The address with
@<revision>is pinned and never changes. The one without it follows each publish within a minute. - Fonts load only on your organisation's allowed sites (see Allowed sites). Stylesheets and logos load anywhere.
- If the design system sets a default density, pass it to
ThemeProvider density.
If something goes wrong
| What you see | What to do |
|---|---|
No design system "…" that you can use here. | Check the id with pfdl theme, or sign in with pfdl connect sign-in. |
| The product's fonts fall back to system fonts | Ask an admin to add the product's address to the allowed sites. |
| "Once it's published, the snippets … appear here." | Ask a publisher to publish it. |