bricks_get_global_variables

Phase 1BeginnerRead OnlyComplexity: 2/10

List all CSS custom properties and their categories

Overview

Retrieves all global CSS custom properties (variables) defined in Bricks Builder. Returns variable names, their CSS values, and the categories they belong to. This is the first tool to call when auditing or extending an existing design system, as it reveals the spacing scale, color tokens, and sizing tokens already in place.

Variables are stored as var(--name) references that can be used throughout element settings, global classes, and theme styles for consistent, maintainable design tokens.

Key Features

Category Filtering

Filter variables by category name or ID to retrieve only spacing, color, or typography tokens without fetching the entire set.

Full Variable Metadata

Returns the variable ID, name (CSS property name), value, and category assignment for each variable in the system.

Category List Included

The response includes both the variables array and the categories array, giving a complete picture of how variables are organized.

Design System Audit

Essential for Phase 1 of any build — reveals whether the mandatory spacing scale (xs=4px through 5xl=128px) and other design tokens are already configured.

When to Use

Auditing the existing design system before creating new variables
Checking if a spacing scale (xs through 5xl) already exists
Verifying color or typography variables before building pages
Listing all CSS custom properties to reference in global classes
Phase 1 of any website build — understanding the site context

Prerequisites

Bricks Builder must be active on the WordPress site. No variables need to exist yet — the tool returns an empty array if none are defined.

When NOT to Use

When you need to create new variables — use bricks_create_global_variable or bricks_create_variables_batch instead
When you need to list only categories without variables — use bricks_get_variable_categories

Parameters

1 Total Parameters1 Optional

categorystringoptional

Filter by category name or ID. Returns only variables belonging to the specified category. Useful for retrieving just "Spacing" or "Colors" variables.

Code Examples

Get All Variables

Retrieve every global CSS variable and its category to audit the design system.

JSON

bricks_get_global_variables({})

Response

{"variables": [{"id": "abc123", "name": "spacing-xs", "value": "4px", "category": "cat1"}, {"id": "def456", "name": "spacing-sm", "value": "8px", "category": "cat1"}], "categories": [{"id": "cat1", "name": "Spacing"}]}

Filter by Spacing Category

Retrieve only the spacing variables to verify the full scale exists.

JSON

bricks_get_global_variables({ category: "Spacing" })

Response

{"variables": [{"id": "abc123", "name": "spacing-xs", "value": "4px", "category": "cat1"}, {"id": "abc124", "name": "spacing-sm", "value": "8px", "category": "cat1"}, {"id": "abc125", "name": "spacing-md", "value": "16px", "category": "cat1"}], "categories": [{"id": "cat1", "name": "Spacing"}]}

Common Mistakes

Skipping spacing variables entirely — agents consistently forget to check whether the full spacing scale (xs through 5xl) exists before building pages.

ALWAYS call bricks_get_global_variables with category "Spacing" during Phase 1. If the scale is incomplete (missing xs=4px through 5xl=128px), create the missing variables with bricks_create_variables_batch before proceeding.

Wrong

// Jumping straight to bricks_create_page without checking variables
bricks_create_page({ title: "Home" })

Correct

// Phase 1: Check existing variables first
bricks_get_global_variables({ category: "Spacing" })
// If spacing scale is incomplete, create it in Phase 2
bricks_create_variables_batch({ variables: [
  { name: "spacing-xs", value: "4px", category: "Spacing" },
  { name: "spacing-sm", value: "8px", category: "Spacing" },
  // ... full scale xs through 5xl
] })

Not checking for existing variables before creating duplicates.

Always call bricks_get_global_variables first to see what already exists. Creating a variable with the same name as an existing one may cause conflicts.

Wrong

// Creating variables without checking
bricks_create_global_variable({ name: "spacing-sm", value: "8px" })

Correct

// Check first, then create only what is missing
const vars = bricks_get_global_variables({ category: "Spacing" })
// Review results, then create only missing variables

Tips & Warnings

Always run this tool first in Phase 1 of any website build. The response tells you whether the mandatory spacing scale, color tokens, and other design system foundations are already in place.

Spacing scale check: Look for variables named spacing-xs through spacing-5xl. If any are missing, create them in Phase 2 using bricks_create_variables_batch. The recommended scale is: xs=4px, sm=8px, md=16px, lg=24px, xl=32px, 2xl=48px, 3xl=64px, 4xl=96px, 5xl=128px.

Variable references: Use variables in element settings as var(--spacing-lg) instead of hardcoded values like "24". This ensures global consistency.

Return Values

Field	Type	Description
`variables`	array	Array of variable objects, each containing id, name (e.g., "spacing-sm"), value (e.g., "8px"), and category ID.
`categories`	array	Array of category objects, each containing id and name (e.g., "Spacing", "Colors", "Typography").

Related Tools

Technical Details

Tool ID

bricks_get_global_variables

API Endpoint

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

HTTP Method

GET

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