Migrating to Facet

Facet is designed to enter an existing codebase through generated tokens before a full authoring migration. The source explicitly calls out a compatibility tokens.css emitter for existing CSS variable conventions.

Incremental path

1. Import or author the token graph.
2. Configure the resolver to match current theme selectors such as :root and .dark.
3. Emit tokens.css in a compatible variable format.
4. Keep existing consumers on CSS variables while moving components to utilities, fx(), or recipes over time.
5. Add facet check in CI to gate contrast, mode contracts, and off-system authoring.

Import legacy tokens

The CLI includes a one-way import helper:

facet import legacy.tokens.json

The existing docs and source describe this as converting legacy or Tokens Studio-like values to the Facet graph:

• value and type become $value and $type
• bare hex colors become the object color model
• dimension strings such as 16px or 0.5rem become { value, unit }
• aliases such as {color.brand.500} are preserved

Preserve existing selectors

The resolver selector map lets a migration keep current mode hooks:

{
  "theme": {
    "values": ["light", "dark"],
    "default": "light",
    "selector": { "light": ":root", "dark": ".dark" }
  }
}

When the emitted tokens.css matches the existing variable convention, downstream styles can keep reading variables while the source of truth moves to Facet.

Move authored styles gradually

Facet can scan markup utilities:

<article class="bg-surface fg-ink radius-panel p-inset-lg shadow-card">
  ...
</article>

It can also scan static fx() calls in source files:

const cardStyle = fx({ bg: "surface", fg: "ink", radius: "panel", p: "inset.lg" });

Because both lower to the same atoms, teams can mix old markup, utilities, and fx() while a migration is underway.

Interop exports

Facet remains the source of truth for these generated outputs:

facet export tokens/app.resolver.json --out tokens.dtcg.json
facet tailwind tokens/app.resolver.json --out tailwind.css
facet styledict tokens/app.resolver.json --out tokens.styledict.json

These are documented as one-directional exporters. Do not plan a round trip from Tailwind, Style Dictionary, or Figma back into the Facet graph unless a future source explicitly adds that workflow.