bricks_create_classes_batch

Phase 2AdvancedBatchComplexity: 7/10

Create up to 50 global classes in a single call

Overview

Creates multiple global CSS classes in a single API call, which is significantly faster than creating them individually. Supports up to 50 classes per batch, each with full CSS settings, optional selectors (hover, focus, pseudo-elements), and category assignment.

This is the preferred tool during Phase 2 (Design System Setup) when establishing the full set of utility, typography, button, card, and layout classes. One batch call replaces dozens of individual bricks_create_global_class calls.

Key Features

Batch Efficiency

Creates up to 50 classes in one API call, dramatically reducing round-trips compared to individual creation.

Full Feature Parity

Each class supports all the same features as bricks_create_global_class: settings, selectors, and category assignment.

Per-Class Categories

Each class in the batch can specify its own category, allowing organized creation across multiple categories in one call.

Atomic Results

Returns results for each class individually, so you know exactly which classes were created and which failed.

When to Use

During Phase 2 when creating the initial design system class library (3+ classes)
When setting up typography scale classes (text-sm, text-base, text-lg, text-xl, etc.)
When creating a complete button system (btn-primary, btn-secondary, btn-ghost, btn-sm, btn-lg)
When building card utility classes (card, card-hover, card-horizontal, card-content)
Any time you need to create 3 or more classes at once

Prerequisites

Phase 2 should be in progress. Ideally create color palette (bricks_create_color) and spacing variables (bricks_create_variables_batch) first, so classes can reference CSS variables like var(--bricks-color-primary) and var(--spacing-lg). Call bricks_regenerate_assets after the batch to compile CSS.

When NOT to Use

When creating only 1-2 classes — use bricks_create_global_class instead
When updating existing classes — use bricks_update_global_class
When you need complex per-class error handling — individual calls give more granular feedback

Parameters

1 Total Parameters1 Required

classesarrayREQUIRED

Array of class objects (1-50). Each object has: name (string, required), category (string, optional), settings (object, required — CSS settings), selectors (array, optional — hover/focus/pseudo-element selectors).

Code Examples

Create typography and button classes in one batch

Sets up the core design system classes across multiple categories in a single API call. Includes responsive typography and hover selectors.

JSON

// Create a complete typography + button class set
bricks_create_classes_batch({
  classes: [
    {
      name: "text-sm",
      category: "Typography",
      settings: { "_typography": { "font-size": "13px", "line-height": "1.5" } }
    },
    {
      name: "text-base",
      category: "Typography",
      settings: { "_typography": { "font-size": "16px", "line-height": "1.6" } }
    },
    {
      name: "text-lg",
      category: "Typography",
      settings: { "_typography": { "font-size": "20px", "line-height": "1.5" } }
    },
    {
      name: "heading-section",
      category: "Typography",
      settings: {
        "_typography": {
          "font-size": "36px",
          "font-weight": "600",
          "line-height": "1.3"
        },
        "_typography:mobile_portrait": { "font-size": "28px" }
      }
    },
    {
      name: "btn-primary",
      category: "Buttons",
      settings: {
        "_background": { "color": { "raw": "var(--bricks-color-primary)" } },
        "_typography": { "color": { "hex": "#ffffff" }, "font-weight": "600" },
        "_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: { "_opacity": "0.9" } }
      ]
    },
    {
      name: "btn-secondary",
      category: "Buttons",
      settings: {
        "_background": { "color": "transparent" },
        "_typography": { "color": { "raw": "var(--bricks-color-primary)" }, "font-weight": "600" },
        "_padding": { "top": "14", "right": "28", "bottom": "14", "left": "28" },
        "_border": {
          "width": { "top": "2", "right": "2", "bottom": "2", "left": "2" },
          "style": "solid",
          "color": { "raw": "var(--bricks-color-primary)" },
          "radius": { "top": "8", "right": "8", "bottom": "8", "left": "8" }
        },
        "_cssTransition": "all 0.3s ease"
      }
    }
  ]
})

Response

{
  "created": [
    { "id": "a1b2c3", "name": "text-sm", "category": "Typography" },
    { "id": "d4e5f6", "name": "text-base", "category": "Typography" },
    { "id": "g7h8i9", "name": "text-lg", "category": "Typography" },
    { "id": "j0k1l2", "name": "heading-section", "category": "Typography" },
    { "id": "m3n4o5", "name": "btn-primary", "category": "Buttons" },
    { "id": "p6q7r8", "name": "btn-secondary", "category": "Buttons" }
  ],
  "errors": [],
  "message": "6/6 classes created successfully."
}

Common Mistakes

Using this batch tool for only 1-2 classes when bricks_create_global_class would be simpler.

Only use bricks_create_classes_batch for 3+ classes. For 1-2 classes, bricks_create_global_class is more straightforward.

Wrong

bricks_create_classes_batch({
  classes: [
    { name: "my-class", settings: { "_typography": { "font-size": "16px" } } }
  ]
})

Correct

bricks_create_global_class({
  name: "my-class",
  settings: { "_typography": { "font-size": "16px" } }
})

Creating classes without referencing design system variables, leading to hardcoded colors and spacing.

Always reference CSS variables for colors and spacing in class settings: var(--bricks-color-primary), var(--spacing-lg).

Wrong

{ name: "btn-primary", settings: {
    "_background": { "color": { "hex": "#4361ee" } },
    "_padding": { "top": "14", "right": "28", "bottom": "14", "left": "28" }
}}

Correct

{ name: "btn-primary", settings: {
    "_background": { "color": { "raw": "var(--bricks-color-primary)" } },
    "_padding": { "top": "14", "right": "28", "bottom": "14", "left": "28" }
}}

Forgetting to call bricks_regenerate_assets after creating the batch, so new CSS is not compiled.

Always call bricks_regenerate_assets after batch class creation to compile the new styles into the site stylesheet.

Wrong

// Create classes and immediately start building pages
bricks_create_classes_batch({ classes: [...] })
bricks_add_section({ ... }) // Classes may not be compiled yet!

Correct

// Create classes, regenerate, then build
bricks_create_classes_batch({ classes: [...] })
bricks_regenerate_assets()
bricks_add_section({ ... })

Tips & Warnings

Performance: One batch call with 20 classes is ~10x faster than 20 individual bricks_create_global_class calls. Always prefer batch for Phase 2 design system setup.

Limit: Maximum 50 classes per batch. For larger class libraries, split into multiple batch calls.

Error handling: The response includes both created and errors arrays, so you can see which classes succeeded and which failed (e.g., duplicate names).

Recommended batch groupings: Typography classes (6-8), Button classes (4-6), Card classes (3-5), Layout utilities (3-5), Spacing utilities (3-5).

Return Values

Field	Type	Description
`created`	array	Array of successfully created class objects with id, name, and category.
`errors`	array	Array of classes that failed to create, with error messages (e.g., duplicate name).
`message`	string	Summary message with count of created vs failed classes.

Related Tools

Technical Details

Tool ID

bricks_create_classes_batch

API Endpoint

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

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 supporting up to 50 classes per batch with full settings, selectors, and categories.

20250101