bricks_import_variables

Phase 2IntermediateBatchComplexity: 5/10
Import variables from JSON (merge or replace)

Overview

Imports global CSS variables from JSON or CSS format into the Bricks site. Supports two modes: « merge » keeps existing variables and adds or updates new ones, while « replace » overwrites all variables with the imported set.

This tool enables design system portability between Bricks sites. Use it to transfer design tokens from staging to production, share a standard design system across projects, or restore variables from a backup.

Key Features

Merge or Replace Modes
"merge" keeps all existing variables and only adds or updates imported ones. "replace" wipes all existing variables and replaces with the imported set.
JSON and CSS Input
Accepts structured JSON arrays (from bricks_export_variables) or plain CSS strings with --name: value; pairs for maximum flexibility.
Category Restoration
When importing with the categories array, the original category organization is preserved or recreated.
CSS Parsing
The CSS input mode automatically parses --name: value; pairs separated by semicolons, making it easy to import from any CSS source.

When to Use

Migrating design tokens from one Bricks site to another
Restoring variables from a JSON backup after a failed refactor
Bootstrapping a new site with a standard design token set
Importing design tokens from a CSS file or third-party design tool
Syncing variable changes from staging to production
Prerequisites
Bricks Builder must be active. Either a variables array (from JSON export) or a CSS string with --name: value; pairs must be provided. For JSON import, categories array is optional but recommended.

When NOT to Use

When creating variables from scratch — use bricks_create_variables_batch instead
When updating a single variable — use bricks_update_global_variable
When you just need to read the current variables — use bricks_get_global_variables

Parameters

4 Total Parameters4 Optional
modestringoptional
Import mode. "merge" keeps existing variables and adds/updates imported ones. "replace" removes all existing variables and replaces with the imported set.
Default: merge Values: merge, replace
variablesarrayoptional
Array of variable objects from JSON export. Each has: name (string), value (string), category (string, optional — category ID from export).
categoriesarrayoptional
Array of category objects from JSON export. Each has: id (string) and name (string). Used to map category IDs in the variables array.
cssstringoptional
CSS string with --name: value; pairs (alternative to variables array). Parsed automatically into individual variables. Example: "--spacing-xs: 4px; --spacing-sm: 8px;"

Code Examples

Import from JSON Export (Merge)

Import variables exported from another site, keeping existing variables intact.

JSON
bricks_import_variables({
  mode: "merge",
  variables: [
    { name: "spacing-xs", value: "4px", category: "cat1" },
    { name: "spacing-sm", value: "8px", category: "cat1" },
    { name: "spacing-md", value: "16px", category: "cat1" }
  ],
  categories: [
    { id: "cat1", name: "Spacing" }
  ]
})
Response
{"success": true, "data": {"imported": 3, "skipped": 0}, "message": "Imported 3 variables (merge mode)"}

Import from CSS String

Import variables from a plain CSS custom properties string.

JSON
bricks_import_variables({
  mode: "merge",
  css: "--spacing-xs: 4px; --spacing-sm: 8px; --spacing-md: 16px; --spacing-lg: 24px; --spacing-xl: 32px;"
})
Response
{"success": true, "data": {"imported": 5, "skipped": 0}, "message": "Imported 5 variables from CSS (merge mode)"}

Replace All Variables

Replace the entire variable set with a new one from an export. WARNING: This removes all existing variables.

JSON
bricks_import_variables({
  mode: "replace",
  variables: [
    { name: "spacing-xs", value: "4px", category: "cat1" },
    { name: "spacing-sm", value: "8px", category: "cat1" }
  ],
  categories: [{ id: "cat1", name: "Spacing" }]
})
Response
{"success": true, "data": {"imported": 2, "skipped": 0}, "message": "Replaced all variables with 2 imported variables"}

Common Mistakes

Using "replace" mode accidentally, wiping out all existing variables on the site.
Always default to "merge" mode unless you intentionally want to replace everything. Export your existing variables first as a backup.
Wrong
// Oops — replaces ALL variables, not just adds new ones
bricks_import_variables({ mode: "replace", css: "--new-var: 10px;" })
Correct
// Safe: merge keeps existing variables
bricks_import_variables({ mode: "merge", css: "--new-var: 10px;" })
Importing CSS without the -- prefix on variable names.
When using the css parameter, include the double-dash prefix on each variable name, just like a standard CSS :root block.
Wrong
bricks_import_variables({ css: "spacing-xs: 4px; spacing-sm: 8px;" })
Correct
bricks_import_variables({ css: "--spacing-xs: 4px; --spacing-sm: 8px;" })

Tips & Warnings

Tips & Warnings

Always export before replacing: Use bricks_export_variables({ format: "json" }) to create a backup before using « replace » mode.

Merge is safer: « merge » mode only adds new variables or updates existing ones with matching names. It never deletes existing variables.

CSS import loses categories: When importing from CSS, variables are created without category assignments. For organized imports, use the JSON format with categories.

Pair with export: The typical workflow is: bricks_export_variables on site A, then bricks_import_variables on site B.

Return Values

FieldTypeDescription
successbooleanWhether the import completed successfully.
data.importednumberNumber of variables imported or updated.
data.skippednumberNumber of variables that were skipped (e.g., already exist in merge mode with same value).
messagestringSummary message describing the import result.

Related Tools

Technical Details

Tool ID
bricks_import_variables
API Endpoint
/bricks-mcp/v1/design-system/variables/import
HTTP Method
POST
Namespace
design-system
Source File
design-system/variables.ts
Version
1.0
Min Bricks Version
1.9
Requires Auth
Yes

Changelog

v1.0
Initial release
20250101