Skip to content
Agentic Experience Design Language Help Go to the portal

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.

For developers2 min read

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 update brings in the latest published revision. Review the change and commit src/brand/.
  • pfdl theme check in CI fails when your copy is behind. Give CI PFDL_TOKEN and "portal" in pfdl.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

If something goes wrong
What you seeWhat 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 fontsAsk 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.