> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livry.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrating Livry Into Your Stack

> Which integration approach fits your framework and component library, and the one principle that makes brand switching free.

There are three ways to consume a Livry theme, and which one you want depends on whether your
component library can accept a CSS `var()`.

<CardGroup cols={3}>
  <Card title="Stylesheet" icon="file-code" href="/guides/plain-css">
    Link `tokens.css` and reference custom properties. **Switching brand is one `href` change.**
  </Card>

  <Card title="Values in JS" icon="brackets-curly">
    Fetch `tokens.values.json` for libraries that compute on values. Switching brand means
    re-fetching.
  </Card>

  <Card title="Build time" icon="hammer" href="/guides/build-time-tokens">
    Pull the DTCG document in CI and generate. No runtime dependency on Livry at all.
  </Card>
</CardGroup>

## The principle worth internalising

<Note>
  **Your app should hold no values — only `var()` references.**

  If every colour in your theme configuration is `var(--color-brand, #5B4DE4)` rather than
  `#5B4DE4`, then swapping the stylesheet rebrands the entire application and **nothing re-renders**.
  The browser recomputes custom properties on its own.

  Every guide below is a way of getting your particular library to hold references instead of values.
</Note>

The fallback after the comma is your Theme's own value, so the app stays styled if the stylesheet
fails to load.

## Pick your guide

| Your library | Guide | Serves |
| - | - | - |
| None — you write CSS | [Plain CSS](/guides/plain-css) | `tokens.css` |
| Tailwind CSS v4 | [Tailwind](/guides/tailwind) | `tokens.css` |
| Chakra UI v3 | [Chakra UI](/guides/chakra-ui) | `tokens.css` |
| shadcn/ui, Angular Material, Skeleton | [Plain CSS](/guides/plain-css) — same mechanism | `tokens.css` |
| MUI, Vuetify, PrimeVue, PrimeNG | Values in JS — see below | `tokens.values.json` |
| Style Dictionary or any DTCG tool | [Build-time tokens](/guides/build-time-tokens) | `tokens.dtcg.json` |

<Warning>
  **Set the integration on your Theme first.** The pairs on the Theme's Integration tab decide which
  files get built. A Theme whose integration is `Build-time tokens` does not serve `tokens.css` at
  all, and the URL will answer `404`.

  You can hold several integrations at once, and the Theme builds the union.
</Warning>

## Libraries that compute on values

Some libraries derive shades, hover states or contrast ratios from a colour **in JavaScript**. Those
cannot take a `var()` — they need a real value — so they read `tokens.values.json`:

```ts theme={null}
const tokens: Record<string, string> = await fetch(
  `https://cdn.livry.dev/${env}/${themeID}/${variantID}/latest/tokens.values.json`
).then((r) => r.json());

const muiTheme = createTheme({
  palette: { primary: { main: tokens["color.brand.primary"] } },
});
```

<Warning>
  **This loses the free brand switch.** The values are baked into your JavaScript at fetch time, so
  changing Variant means re-fetching and re-rendering.

  If your library accepts `var()` anywhere it takes a colour, prefer the stylesheet approach even
  with a library listed here — and [tell us](/help/faq), because the mapping is conservative and a
  one-line change for us.
</Warning>

## Where the variable names come from

A token path becomes a custom property by hyphen-joining it, with the Theme's optional prefix in
front:

```text theme={null}
color.brand.primary                 →  --color-brand-primary
color.brand.primary  (prefix acme)  →  --acme-color-brand-primary
```

Read the prefix from the Theme rather than assuming it is empty — it is on the Theme's Settings tab,
and on the API as `assetSettings.prefix`.

## Server-rendered apps

Everything above works server-side too, and it is usually simpler: you know the tenant at render
time, so write the right `<link>` and never switch anything.

```tsx theme={null}
export default function Layout({ variantID, children }) {
  return (
    <html>
      <head>
        <link rel="stylesheet"
              href={`https://cdn.livry.dev/${ENV}/${THEME}/${variantID}/latest/tokens.css`} />
      </head>
      <body>{children}</body>
    </html>
  );
}
```

<Note>
  Put the Livry `<link>` **before** your own stylesheets, so the custom properties are defined before
  the rules referencing them are evaluated on first paint.
</Note>

## Your Theme's real URLs

Every guide here uses placeholders. Your actual URLs — with real ids, and listing only the files your
Theme builds — are on the Theme's **Integration** tab in the portal, and on the API as
`servingUrls`. The portal also generates these snippets pre-filled with your ids.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.