20 palettes ship with the library, in two families. Each one defines both colour schemes, so a theme and dark mode are independent choices rather than a grid you have to maintain.

1@import "tailwindcss";2@import "xiod-ui/styles";34/* One line. Every token from the Colors page is redefined, light and dark. */5@import "xiod-ui/themes/cobalt";

Order matters: the import has to come after xiod-ui/styles, or the base tokens win. You can still override individual tokens below the import — the palette is a starting point, not a lock.

1@import "tailwindcss";2@import "xiod-ui/styles";34/* Scoped: each palette applies only under its own data-palette attribute,5   so importing several is safe — none of them touch the base tokens. */6@import "xiod-ui/themes/cobalt/scoped";7@import "xiod-ui/themes/lagoon/scoped";8@import "xiod-ui/themes/riso/scoped";

Then write the attribute with setPalette from useTheme. It remembers the choice in localStorage and suppresses transitions during the swap, the same way the light/dark toggle does. This needs ThemeProvider in your root layout — see the Dark Mode page for that setup.

1"use client";23import { useTheme } from "xiod-ui/theme-provider";45export function PaletteSwitcher() {6  const { palette, setPalette } = useTheme();78  return (9    <div className="flex gap-2">10      <button onClick={() => setPalette("cobalt")}>Cobalt</button>11      <button onClick={() => setPalette("lagoon")}>Lagoon</button>1213      {/* undefined clears the attribute and falls back to the base tokens */}14      <button onClick={() => setPalette(undefined)}>Neutral</button>15    </div>16  );17}

Import only the palettes you actually offer. Each scoped stylesheet is a few hundred bytes gzipped, but they all ship on every page.

• Readable text. Every *-foreground token clears 4.5:1 against the surface it actually sits on — including the state foregrounds, which are checked against their own colour tinted over the background at the opacity components really use.
• Usable controls. White text clears 4.5:1 on the solid destructive fill, and that fill clears 3:1 against the background, so a destructive button is legible as a control and not only as text.
• Distinct from each other. No two palettes' primaries sit closer than 0.055 in OKLab, a shade above the range where two colours read as one. Palettes may share a hue; none should be mistakable for another at a glance.

All three are enforced by a check that runs on every build, so a palette that fails any of them cannot ship.

1@import "xiod-ui/styles";2@import "xiod-ui/themes/cobalt";34/* Cobalt, but squarer and with a deeper blue. */5:root {6  --radius: 0.25rem;7  --primary: #1d4ed8;8}

The Customization page covers this properly — the full token set as a starter template, how to scope an override to one part of the app, and the mistakes that make an override silently do nothing.