> ## 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.

# Importing Tokens from DTCG, Tokens Studio, Figma and Style Dictionary

> Bring an existing token file into a Livry Theme. Four formats are detected automatically, and the import is reviewed before anything is written.

You almost certainly already have tokens somewhere. Livry imports four formats, and works out which
one it is from the content rather than asking you.

| Format | What it looks like |
| - | - |
| **W3C DTCG** | `$value` / `$type` — the native format. Round-trips exactly. |
| **Tokens Studio for Figma** | A tree of token **sets**, with `$themes` and `$metadata` manifests. |
| **Figma Variables** | The REST response or a plugin dump — a flat dictionary keyed by variable id. |
| **Style Dictionary** | A tree with `value` rather than `$value`. |

Import happens on a Theme's **Tokens** tab, in the portal.

## It is a two-step flow

<Steps>
  <Step title="Analyze">
    Upload the file. Livry detects the format, converts it, and shows you what it found — how many
    tokens, what types, what it could not map, and what it is going to ignore.

    Nothing has been written at this point.
  </Step>

  <Step title="Commit">
    You confirm, and the converted document becomes your Theme's draft.

    The commit re-derives the plan from the same bytes rather than trusting the browser's copy of
    it, so what you reviewed is what lands.
  </Step>
</Steps>

The result is a **draft**, not a published version. Review it, edit it, and publish when it is right.
See [Versioning](/theming/versioning).

## What each format costs you

<AccordionGroup>
  <Accordion title="Tokens Studio — one set is imported, the rest are reported">
    A Studio export is usually a whole design system: a base set plus a set per theme. A Livry Theme
    holds **one** token set.

    Merging them all would silently overlay light onto dark, so Livry imports one and tells you which
    sets it did not take. Pick the base set; the theme sets are usually what you want as
    [Variants](/theming/variants) anyway.

    Studio's type vocabulary predates DTCG and is finer-grained in places. `composition`, `textCase`,
    `textDecoration` and `other` have no DTCG equivalent and are reported rather than guessed at.

    Arithmetic in values (`{spacing.base} * 2`) is evaluated during conversion.
  </Accordion>

  <Accordion title="Figma Variables — one mode is taken">
    Figma holds a value **per mode**: a collection with Light and Dark modes has two values for every
    variable. A DTCG token holds one.

    The default mode is imported unless you name another, and every collection and mode found is
    reported — so a half-imported design system explains itself rather than looking broken.

    Figma's hierarchy lives inside each variable's slash-separated `name`, which becomes the DTCG
    path.
  </Accordion>

  <Accordion title="Style Dictionary — the straightforward one">
    Structurally the same tree as DTCG with `value` in place of `$value`. Types are inferred where
    they are not declared.
  </Accordion>

  <Accordion title="DTCG — exact, except for two features">
    Round-trips faithfully. The exceptions are `$extends` and `$ref`, which are preserved but never
    *applied* — a document relying on either imports with tokens missing. See
    [Tokens](/theming/tokens).
  </Accordion>
</AccordionGroup>

## What to do about modes and themes

Light/dark and per-brand are different problems, and Livry solves only one of them.

| You have | Model it as |
| - | - |
| One product, many customer brands | One Theme, one **Variant** per brand. This is what Livry is for. |
| Light and dark for the same brand | **Two Themes**, or one Theme whose tokens carry both and a `prefers-color-scheme` rule in your own CSS. Livry has no mode concept. |
| Many products, many brands each | One **Theme per product**, Variants beneath each. |

<Note>
  There is no import on the REST API. It is a two-step flow over an uploaded file, and the upload
  endpoint is portal-scoped — shipping half the pair would give you an endpoint you could not reach.
  See [what the API does not do](/api/introduction).
</Note>

## After importing

Two things are worth doing before you publish:

1. **Check the types.** Anything Livry had to infer is flagged. A colour stored as a string that
   should have been a `color` will still render, but it will not get a swatch in the editor and it
   will not convert cleanly.
2. **Add aliases.** An imported set is usually all literal values. Replacing derived colours with
   `{color.brand}` aliases is what turns a 400-token theme into one a brand can rebrand by setting
   three values.


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