bricks_create_variables_batch

Phase 2IntermediateBatchComplexity: 5/10

Create up to 50 CSS variables in one call

Overview

Creates multiple global CSS variables in a single API call, supporting up to 50 variables at once. This is the recommended tool for setting up the design system’s spacing scale, sizing tokens, and other multi-value token sets in Phase 2 of a website build.

Significantly faster and more efficient than calling bricks_create_global_variable repeatedly. Categories referenced by name are auto-created if they do not exist.

Key Features

Up to 50 Variables per Call

Create an entire design token scale in a single API request — spacing, colors, typography, sizing, and more.

Auto-Category Creation

Categories referenced by name in any variable are automatically created if they do not exist, eliminating the need for separate bricks_create_variable_category calls.

Atomic Operation

All variables are created in a single transaction. If one fails, the error is reported while others succeed.

Mixed Categories

Variables in the same batch can belong to different categories. Create spacing, color, and typography tokens all in one call.

When to Use

Setting up the mandatory spacing scale (xs=4px through 5xl=128px) during Phase 2
Creating a full set of sizing, border-radius, or shadow tokens in one operation
Bootstrapping a design system with multiple variable categories at once
Any time you need to create 3 or more variables — always prefer batch over individual calls

Prerequisites

Bricks Builder must be active. Variable names should not conflict with existing variables. Categories are auto-created as needed.

When NOT to Use

When creating only 1-2 variables — use bricks_create_global_variable for simplicity
When updating existing variables — use bricks_update_global_variable instead
When importing variables from a JSON or CSS export — use bricks_import_variables

Parameters

4 Total Parameters3 Required1 Optional

variablesarrayREQUIRED

Array of variable objects to create (1-50 items). Each object has: name (string, required), value (string, required), category (string, optional).

variables[].namestringREQUIRED

Variable name without var() or -- prefix (e.g., "spacing-xs").

variables[].valuestringREQUIRED

CSS value for the variable (e.g., "4px", "0.5rem", "#1a3a5c").

variables[].categorystringoptional

Category name. Auto-created if it does not exist.

Code Examples

Create Full Spacing Scale

Set up the mandatory spacing scale (xs through 5xl) in a single API call during Phase 2.

JSON

bricks_create_variables_batch({
  variables: [
    { name: "spacing-xs", value: "4px", category: "Spacing" },
    { name: "spacing-sm", value: "8px", category: "Spacing" },
    { name: "spacing-md", value: "16px", category: "Spacing" },
    { name: "spacing-lg", value: "24px", category: "Spacing" },
    { name: "spacing-xl", value: "32px", category: "Spacing" },
    { name: "spacing-2xl", value: "48px", category: "Spacing" },
    { name: "spacing-3xl", value: "64px", category: "Spacing" },
    { name: "spacing-4xl", value: "96px", category: "Spacing" },
    { name: "spacing-5xl", value: "128px", category: "Spacing" }
  ]
})

Response

{"success": true, "data": {"created": 9, "variables": [{"id": "v1", "name": "spacing-xs", "value": "4px"}, {"id": "v2", "name": "spacing-sm", "value": "8px"}, ...]}}

Create Mixed Design Tokens

Create variables across multiple categories in one call — spacing, borders, and shadows.

JSON

bricks_create_variables_batch({
  variables: [
    { name: "spacing-md", value: "16px", category: "Spacing" },
    { name: "spacing-lg", value: "24px", category: "Spacing" },
    { name: "radius-sm", value: "6px", category: "Borders" },
    { name: "radius-md", value: "12px", category: "Borders" },
    { name: "radius-lg", value: "20px", category: "Borders" },
    { name: "shadow-sm", value: "0 1px 3px rgba(0,0,0,0.1)", category: "Shadows" },
    { name: "shadow-md", value: "0 4px 12px rgba(0,0,0,0.08)", category: "Shadows" }
  ]
})

Response

{"success": true, "data": {"created": 7, "variables": [...]}}

Common Mistakes

Skipping spacing variables entirely during Phase 2 — agents consistently forget this step, causing inconsistent layouts.

ALWAYS create the full spacing scale (xs=4px through 5xl=128px) as the FIRST step of Phase 2. This is the most frequently skipped step and causes the most design inconsistencies. Use this exact batch call.

Wrong

// Phase 2: Only creating colors and classes, forgetting spacing
bricks_create_color({ name: "primary", value: "#4361ee" })
bricks_create_global_class({ name: "btn-primary", settings: {...} })
// No spacing variables created! All spacing will be hardcoded.

Correct

// Phase 2: Start with spacing variables FIRST
bricks_create_variables_batch({
  variables: [
    { name: "spacing-xs", value: "4px", category: "Spacing" },
    { name: "spacing-sm", value: "8px", category: "Spacing" },
    { name: "spacing-md", value: "16px", category: "Spacing" },
    { name: "spacing-lg", value: "24px", category: "Spacing" },
    { name: "spacing-xl", value: "32px", category: "Spacing" },
    { name: "spacing-2xl", value: "48px", category: "Spacing" },
    { name: "spacing-3xl", value: "64px", category: "Spacing" },
    { name: "spacing-4xl", value: "96px", category: "Spacing" },
    { name: "spacing-5xl", value: "128px", category: "Spacing" }
  ]
})
// THEN create colors and classes

Using bricks_create_global_variable in a loop for 9 spacing variables instead of one batch call.

Always use the batch tool for 3+ variables. It is 9x faster for the spacing scale and reduces API overhead.

Wrong

// 9 separate API calls (slow, wasteful)
bricks_create_global_variable({ name: "spacing-xs", value: "4px", category: "Spacing" })
bricks_create_global_variable({ name: "spacing-sm", value: "8px", category: "Spacing" })
// ... 7 more individual calls

Correct

// 1 API call for all 9 variables
bricks_create_variables_batch({ variables: [...all 9 spacing vars...] })

Exceeding the 50-variable limit per batch call.

Split into multiple batch calls of 50 or fewer variables each if you have a large token set.

Wrong

// 60 variables in one call — will fail
bricks_create_variables_batch({ variables: [/* 60 items */] })

Correct

// Split into two calls
bricks_create_variables_batch({ variables: [/* first 50 */] })
bricks_create_variables_batch({ variables: [/* remaining 10 */] })

Tips & Warnings

This is the #1 recommended tool for Phase 2. The spacing scale (xs through 5xl) is mandatory for every site. Creating it in a single batch call is the most efficient approach.

Standard spacing scale: xs=4px (tight gaps), sm=8px (small gaps), md=16px (default), lg=24px (cards), xl=32px (section inner), 2xl=48px (content blocks), 3xl=64px (section padding), 4xl=96px (large sections), 5xl=128px (hero sections).

Category auto-creation: You do not need to call bricks_create_variable_category separately. Just include the category name in each variable object and categories are created on the fly.

Max 50 variables per call. For very large design systems, split into multiple batch calls.

Return Values

Field	Type	Description
`success`	boolean	Whether the batch creation succeeded overall.
`data.created`	number	Number of variables successfully created.
`data.variables`	array	Array of created variable objects with their assigned IDs.
`data.errors`	array	Array of any errors that occurred during creation (e.g., duplicate names).

Related Tools

Technical Details

Tool ID

bricks_create_variables_batch

API Endpoint

/bricks-mcp/v1/design-system/variables/batch

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