bricks_create_global_variable
Overview
Creates a new global CSS custom property (variable) in the Bricks design system. The variable is stored as var(--name) and becomes available throughout the entire site for use in element settings, global classes, and theme styles.
If the specified category does not exist, it is automatically created. This is the single-variable creation tool — for creating multiple variables at once (e.g., a full spacing scale), use bricks_create_variables_batch instead.
Key Features
When to Use
Creating a variable during a quick design tweak or one-off addition
Phase 2 of a website build — setting up the design system one variable at a time
When you need to create a variable and auto-create its category simultaneously
When NOT to Use
When you need to update an existing variable — use bricks_update_global_variable instead
When you just need to read existing variables — use bricks_get_global_variables
Parameters
namestringREQUIREDvaluestringREQUIREDcategorystringoptionalCode Examples
Create a Spacing Variable
Add a single spacing token to the design system.
bricks_create_global_variable({
name: "spacing-lg",
value: "24px",
category: "Spacing"
}){"success": true, "data": {"id": "v1a2b3", "name": "spacing-lg", "value": "24px", "category": "cat_spacing"}}Create a Color Variable
Add a custom color token for reuse across the site.
bricks_create_global_variable({
name: "color-accent-light",
value: "#e8d4a0",
category: "Colors"
}){"success": true, "data": {"id": "v4d5e6", "name": "color-accent-light", "value": "#e8d4a0", "category": "cat_colors"}}Create a Border Radius Variable
Define a reusable border-radius value for cards and buttons.
bricks_create_global_variable({
name: "radius-md",
value: "12px",
category: "Borders"
}){"success": true, "data": {"id": "v7f8g9", "name": "radius-md", "value": "12px", "category": "cat_borders"}}Use the Variable in an Element
After creating a spacing variable, reference it in element settings instead of hardcoding values.
// In element settings, reference the variable:
{
"_padding": { "top": "var(--spacing-lg)", "bottom": "var(--spacing-lg)" },
"_gap": "var(--spacing-md)"
}// Renders as padding: 24px (top/bottom) and gap: 16pxCommon Mistakes
bricks_create_global_variable({
name: "var(--spacing-sm)",
value: "8px"
})bricks_create_global_variable({
name: "spacing-sm",
value: "8px"
})// 9 separate API calls for the spacing scale
bricks_create_global_variable({ name: "spacing-xs", value: "4px", category: "Spacing" })
bricks_create_global_variable({ name: "spacing-sm", value: "8px", category: "Spacing" })
bricks_create_global_variable({ name: "spacing-md", value: "16px", category: "Spacing" })
// ... 6 more calls// 1 API call for the entire spacing scale
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" },
// ... all 9 values
] })// Hardcoded spacing everywhere
{ "_padding": { "top": "24", "bottom": "24" }, "_gap": "16" }// Reference spacing variables for consistency
{ "_padding": { "top": "var(--spacing-lg)", "bottom": "var(--spacing-lg)" }, "_gap": "var(--spacing-md)" }Tips & Warnings
Naming convention: Use kebab-case with a category prefix: spacing-sm, color-primary-light, radius-lg, shadow-card. This makes variables easy to discover in the Bricks UI.
Mandatory spacing scale: Every site MUST have the full spacing scale: xs=4px, sm=8px, md=16px, lg=24px, xl=32px, 2xl=48px, 3xl=64px, 4xl=96px, 5xl=128px. Without this, layouts become inconsistent. Use bricks_create_variables_batch for the full scale.
Prefer batch for multiple variables: This tool is ideal for 1-2 variables. For 3+, always use bricks_create_variables_batch.