bricks_create_global_class

Phase 2IntermediateComplexity: 5/10

Create a new global CSS class with settings and selectors

Overview

Creates a single global CSS class in the Bricks design system. Define the class name, CSS settings (typography, background, border, spacing, etc.), and optional selectors for interactive states like :hover, :focus, ::before, and ::after. Classes are the foundation of maintainable Bricks sites.

Every content element (heading, text, button, image, icon-box) must reference at least one global class. This tool creates the reusable styles that prevent inline styling across the site. For creating 3 or more classes at once, prefer bricks_create_classes_batch for better performance.

Key Features

Full CSS Settings

Supports all Bricks CSS controls: _typography, _background, _border, _padding, _margin, _display, _width, _height, _boxShadow, _cssCustom, and more.

Selector Support (V2)

Add :hover, :focus, :active, ::before, ::after, and custom child selectors (& > p, & + div) with independent settings for each.

Category Organization

Assign classes to categories (Layout, Typography, Buttons, Cards, Utilities) for organized display in the Bricks builder sidebar.

Auto-Referenced by Name

Elements reference classes by name via globalClasses: ["class-name"]. The system auto-resolves names to IDs.

When to Use

During Phase 2 (Design System Setup) to create individual utility or component classes
When you need a single new class with specific hover/focus selectors
When a "Global Class Warning" indicates missing classes on content elements
When you need to create a class with complex pseudo-element selectors (::before, ::after)
When creating 1-2 classes — for 3+ classes use bricks_create_classes_batch instead

Prerequisites

Phase 2 should be in progress. Color palette and spacing variables should ideally be created first so classes can reference them via CSS variables (e.g., var(--bricks-color-primary), var(--spacing-lg)). Call bricks_regenerate_assets after creating classes to compile CSS.

When NOT to Use

When creating 3 or more classes at once — use bricks_create_classes_batch instead (much faster)
When a suitable class already exists — use bricks_get_global_classes to check first
When you need to modify an existing class — use bricks_update_global_class instead

Parameters

4 Total Parameters2 Required2 Optional

namestringREQUIRED

CSS class name (e.g., "btn-primary", "card-shadow", "heading-section"). Will be used as .name in CSS output. Use kebab-case naming convention.

categorystringoptional

Category name to group this class under (e.g., "Buttons", "Typography", "Cards", "Layout", "Utilities"). Creates the category if it does not exist.

settingsobjectREQUIRED

CSS settings object. Keys include: _typography (font-size, color, font-weight, etc.), _background (color, image), _border (width, style, color, radius), _padding, _margin, _display, _width, _height, _boxShadow, _cssCustom (raw CSS string), _cssTransition, and all other Bricks CSS controls.

selectorsarrayoptional

Array of selector objects for interactive states. Each object has: selector (string like "&:hover", "&:focus", "& > p") and settings (CSS settings object for that state).

Code Examples

Create a section label typography class

A reusable class for section subtitle text (uppercase, accent color, letter-spacing). Applied via globalClasses: ["section-label"] on text-basic elements.

JSON

// Create a section label class (uppercase, accent color)
bricks_create_global_class({
  name: "section-label",
  category: "Typography",
  settings: {
    "_typography": {
      "font-size": "14px",
      "color": { "raw": "var(--bricks-color-accent)" },
      "letter-spacing": "0.7px",
      "text-transform": "uppercase",
      "text-align": "center",
      "font-weight": "600"
    },
    "_margin": { "bottom": "8" }
  }
})

Response

{
  "id": "a1b2c3",
  "name": "section-label",
  "message": "Global class 'section-label' created successfully."
}

Create a button class with hover effect

A primary button class with background, padding, border-radius, and a hover selector that darkens the color and adds a shadow.

JSON

// Create a button class with hover selector
bricks_create_global_class({
  name: "btn-primary",
  category: "Buttons",
  settings: {
    "_background": { "color": { "raw": "var(--bricks-color-primary)" } },
    "_typography": { "color": { "hex": "#ffffff" }, "font-weight": "600", "font-size": "16px" },
    "_padding": { "top": "14", "right": "28", "bottom": "14", "left": "28" },
    "_border": { "radius": { "top": "8", "right": "8", "bottom": "8", "left": "8" } },
    "_cssTransition": "all 0.3s ease"
  },
  selectors: [
    {
      selector: "&:hover",
      settings: {
        "_background": { "color": { "raw": "var(--bricks-color-primary-dark)" } },
        "_transform": "translateY(-2px)",
        "_boxShadow": [{ "x": "0", "y": "4", "blur": "12", "spread": "0", "color": { "hex": "#00000020" } }]
      }
    }
  ]
})

Response

{
  "id": "d4e5f6",
  "name": "btn-primary",
  "message": "Global class 'btn-primary' created successfully."
}

Common Mistakes

Using inline _typography styles on every heading instead of creating a global class first.

Create heading-section, heading-card, text-body classes in Phase 2, then reference them via globalClasses on every content element. Zero inline styles on content elements.

Wrong

// WRONG: Inline styles duplicated on every heading
{ "type": "heading", "settings": {
    "text": "Our Services", "tag": "h2",
    "_typography": { "font-size": "36px", "font-weight": "600", "color": { "hex": "#1a1a2e" } }
}}
// Repeated 10 times across the page — impossible to update globally

Correct

// RIGHT: Create class ONCE, use everywhere
bricks_create_global_class({
  name: "heading-section",
  category: "Typography",
  settings: {
    "_typography": { "font-size": "36px", "font-weight": "600", "color": { "hex": "#1a1a2e" } }
  }
})
// Then on every section heading:
{ "type": "heading", "settings": { "text": "Our Services", "tag": "h2" },
  "globalClasses": ["heading-section"] }

Using _gap with units like "20px" in class settings. The Style Mapper adds units automatically.

Use plain numbers without px for _gap, _padding, and _margin values.

Wrong

settings: { "_gap": "20px", "_padding": { "top": "32px" } }

Correct

settings: { "_gap": "20", "_padding": { "top": "32" } }

Creating classes one at a time when setting up the design system with many classes.

Use bricks_create_classes_batch for 3+ classes. Only use this single-class tool for 1-2 classes or when you need complex selectors.

Wrong

// 10 separate API calls to create 10 utility classes
bricks_create_global_class({ name: "text-sm", ... })
bricks_create_global_class({ name: "text-base", ... })
bricks_create_global_class({ name: "text-lg", ... })
// ... 7 more calls

Correct

// One batch call for all 10 classes
bricks_create_classes_batch({
  classes: [
    { name: "text-sm", settings: { "_typography": { "font-size": "13px" } } },
    { name: "text-base", settings: { "_typography": { "font-size": "16px" } } },
    { name: "text-lg", settings: { "_typography": { "font-size": "20px" } } },
    // ... all classes in one call
  ]
})

Tips & Warnings

Critical rule: Every content element (heading, text-basic, button, icon-box, image) MUST reference at least one global class via globalClasses: ["class-name"]. The element settings should contain only content (text, image URL, link), NOT styling.

Recommended classes to create: section-label, heading-section, heading-card, text-body, text-small, btn-primary, btn-secondary, card, card-content, badge, icon-circle. These cover 90%+ of content elements.

Remember: Call bricks_regenerate_assets after creating classes to compile the new CSS into the site stylesheet.

Return Values

Field	Type	Description
`id`	string	Unique hex ID of the created class (e.g., "abc123").
`name`	string	The class name as created.
`message`	string	Success confirmation message.

Related Tools

Technical Details

Tool ID

bricks_create_global_class

API Endpoint

/bricks-mcp/v1/design-system/classes

HTTP Method

POST

Namespace

design-system

Source File

design-system/classes.ts

Version

1.0

Min Bricks Version

1.9

Requires Auth

Yes

Changelog

v1.0

Initial release with full CSS settings, V2 selector support, and category assignment.

20250101