bricks_update_global_variable

Phase 2IntermediateComplexity: 4/10

Update a variable value with auto-rename of references

Overview

Updates an existing global CSS variable by ID. You can change the variable’s name, value, or category assignment. When renaming a variable, all references across the entire site are automatically updated — including pages, global classes, theme styles, and components.

This automatic global rename is one of the most powerful features of the variables system, as it ensures no references break when you refactor your design tokens.

Key Features

Global Auto-Rename

When you rename a variable, every reference across all pages, global classes, theme styles, and components is automatically updated to use the new name.

Partial Updates

You only need to provide the fields you want to change. Omitted fields retain their current values.

Category Reassignment

Move a variable to a different category by specifying a new category name. The category is created if it does not exist.

Value Hot-Swap

Changing a variable value instantly affects every element that references it, making site-wide design adjustments a single operation.

When to Use

Changing the value of a spacing or color token (e.g., adjusting spacing-lg from 24px to 28px)
Renaming a variable for better naming consistency (e.g., "gap-lg" to "spacing-lg")
Moving a variable to a different category for better organization
Refactoring design tokens across an established site

Prerequisites

The variable must exist. You need the variable_id which can be obtained from bricks_get_global_variables. At least one of name, value, or category must be provided.

When NOT to Use

When you need to create a new variable — use bricks_create_global_variable instead
When you want to delete a variable — use bricks_delete_global_variable
When you need to update multiple variables — consider calling this tool once per variable

Parameters

4 Total Parameters1 Required3 Optional

variable_idstringREQUIRED

The unique ID of the variable to update. Obtain this from the bricks_get_global_variables response.

namestringoptional

New variable name (without var() or -- prefix). Triggers a global rename of all references across the site when changed.

valuestringoptional

New CSS value for the variable. Takes effect immediately wherever the variable is referenced.

categorystringoptional

New category name to reassign the variable to. Created automatically if it does not exist.

Code Examples

Update a Spacing Value

Adjust the large spacing token from 24px to 28px across the entire site.

JSON

bricks_update_global_variable({
  variable_id: "v1a2b3",
  value: "28px"
})

Response

{"success": true, "data": {"id": "v1a2b3", "name": "spacing-lg", "value": "28px"}}

Rename a Variable (Global Rename)

Rename a poorly-named variable. All references across pages, classes, and theme styles are updated automatically.

JSON

bricks_update_global_variable({
  variable_id: "v1a2b3",
  name: "spacing-lg"
})
// Previously named "gap-large" — all var(--gap-large) references become var(--spacing-lg)

Response

{"success": true, "data": {"id": "v1a2b3", "name": "spacing-lg", "value": "24px", "references_updated": 47}}

Move Variable to Different Category

Reorganize a variable from one category to another.

JSON

bricks_update_global_variable({
  variable_id: "v4d5e6",
  category: "Design Tokens"
})

Response

{"success": true, "data": {"id": "v4d5e6", "name": "color-accent", "value": "#c5a347", "category": "cat_design_tokens"}}

Common Mistakes

Using the variable name instead of the variable_id in the first parameter.

The variable_id is the unique identifier returned by bricks_get_global_variables, not the CSS name. Call bricks_get_global_variables first to get the ID.

Wrong

bricks_update_global_variable({
  variable_id: "spacing-lg",
  value: "28px"
})

Correct

// First get the ID
const vars = bricks_get_global_variables({})
// Find spacing-lg in the results, note its id: "v1a2b3"
bricks_update_global_variable({
  variable_id: "v1a2b3",
  value: "28px"
})

Creating a new variable instead of updating an existing one, resulting in duplicates.

Always check if the variable exists first with bricks_get_global_variables. If it exists, use update; if not, use create.

Wrong

// Creates a duplicate "spacing-lg"
bricks_create_global_variable({ name: "spacing-lg", value: "28px" })

Correct

// Update the existing one
bricks_update_global_variable({ variable_id: "v1a2b3", value: "28px" })

Tips & Warnings

Rename is powerful: When you rename a variable, the tool searches all pages, templates, global classes, theme styles, and components for var(--old-name) references and updates them to var(--new-name). This is a site-wide find-and-replace operation.

Value changes are instant: Since CSS variables cascade, changing a value here affects every element that references it. Test on a staging site first if making large-scale value changes.

No undo: Variable updates cannot be reverted automatically. Note the current value before changing it in case you need to roll back.

Return Values

Field	Type	Description
`success`	boolean	Whether the update was applied successfully.
`data.id`	string	The variable ID (unchanged).
`data.name`	string	The updated variable name.
`data.value`	string	The updated CSS value.
`data.references_updated`	number	Number of references across the site that were updated during a rename operation.

Related Tools

Technical Details

Tool ID

bricks_update_global_variable

API Endpoint

/bricks-mcp/v1/design-system/variables/{variable_id}

HTTP Method

PUT

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