Theme Builder Export and Integration

After customizing a theme in the Theme Builder, export it in the format that matches your project’s styling profile.

#JSON Export

JSON export produces a versioned ThemeDefinition compatible with the @solidiom/themes schema. This is the canonical format and can be consumed programmatically.

#Using Exported JSON

{
  "schemaVersion": 1,
  "meta": {
    "name": "My Theme",
    "slug": "my-theme",
    "version": "1.0.0"
  },
  "modes": {
    "light": {/* tokens */},
    "dark": {/* tokens */}
  }
}

Save the file as theme.json and reference it in your project. The JSON can be re-imported into the builder via a share URL (export JSON → encode as share payload manually, or use the builder’s share feature before editing).

#CSS Export

CSS export generates :root blocks with --sol-* custom properties for both light and dark modes:

/* Theme: My Theme — my-theme */
/* Generated by Solidiom Theme Builder */

:root,
:root[data-theme="light"] {
  --sol-surface: #ffffff;
  --sol-surface-raised: #f8fafc;
  --sol-foreground: #0f172a;
  /* ... */
}

:root[data-theme="dark"] {
  --sol-surface: #0f172a;
  --sol-surface-raised: #1e293b;
  --sol-foreground: #f8fafc;
  /* ... */
}

#Integration Steps

1. Import the CSS file in your project’s entry point
2. Ensure your theme toggle sets data-theme="dark" on :root
3. Solidiom recipes reference --sol-* variables and will automatically use your theme

#Tailwind v4 Export

Tailwind export generates an @theme block:

/* Theme: My Theme — my-theme */
/* Generated by Solidiom Theme Builder */
@theme {
  --color-surface: var(--sol-surface, #ffffff);
  --color-foreground: var(--sol-foreground, #0f172a);
  --radius-sm: var(--sol-radius-sm, 2px);
  --shadow-md: var(--sol-shadow-md, 0 4px 6px -1px rgb(0 0 0 / 0.1));
  /* ... */
}

#Integration Steps

1. Add the exported CSS to your Tailwind entry point
2. Ensure Tailwind scans the file (it’s @theme syntax, so Tailwind v4 picks it up automatically)
3. Solidiom’s Tailwind recipes use var(--sol-*) references and will resolve to your theme

#UnoCSS Export

UnoCSS export is identical to the CSS export. Use the same integration steps as the CSS profile.

#ref() Tokens

The builder uses ref() notation for derived tokens. For example, --sol-muted-foreground: ref("foreground"). All exports resolve references to their final computed values, so you never need to handle ref() manually in your project.

#From Share URL to Project

1. Open the share URL in the Theme Builder
2. Click Export and select your format
3. Copy or download the output
4. Integrate using the steps above

#Migration Between Versions

When the theme schema evolves, exported JSON from an older version may not be directly compatible. The builder rejects share URLs with unsupported schema versions. For programmatic migration, @solidiom/themes provides a migration chain that transforms between versions when defined.

For the full technical specification of the schema and migration mechanism, see the Theme Contract.