bricks_update_theme_styles

Phase 2AdvancedComplexity: 8/10

Update typography scale, heading margins, contextual spacing

Overview

Updates a theme style’s settings in Bricks Builder using deep merge — only the provided sections are changed, leaving all other settings intact. This is the primary tool for configuring site-wide typography, heading scale, heading margins, link styles, contextual spacing, and element defaults.

This tool is critical in Phase 2 (Design System Setup) and must configure the complete typography scale (H1-H6), heading margins, body typography, link styles, contextual spacing, and element defaults for sections, containers, and buttons.

Settings are organized into sections: typography, colors, general, links, contextualSpacing, css, and element-specific sections (section, container, button, heading, etc.).

Key Features

Deep Merge

Only the provided sections are changed. Existing settings in other sections remain untouched. You can safely update just typography without affecting button defaults.

Full Typography Scale

Configure typographyHeadingH1 through typographyHeadingH6 with per-level font-size, font-weight, and line-height. Also set the shared typographyHeadings for font-family.

Heading Margins

Set h1Margin through h6Margin with top and bottom spacing values to create consistent vertical rhythm without per-element overrides.

Contextual Spacing

Remove default browser margins on specific tags and set custom paragraph/heading spacing site-wide using contextualSpacingRemoveDefaultMargins, contextualSpacingParagraph, and contextualSpacingHeading.

Element Defaults

Set default styling for 20+ element types (section padding, container max-width, button padding/border-radius, accordion, tabs, slider, etc.) so every new instance inherits consistent base styles.

Condition Updates

Optionally update display conditions to change where the theme style is active. Conditions are fully replaced (not merged) when provided.

When to Use

Setting up the full typography scale (H1-H6 font sizes, weights, line-heights) during Phase 2
Configuring heading margins (h1Margin through h6Margin) for vertical rhythm
Setting body typography (font-family, font-size, color, line-height)
Configuring link styles (color, text-decoration, transition)
Setting contextual spacing to remove default margins and add consistent paragraph/heading spacing
Setting element defaults for sections (padding), containers (max-width), and buttons (padding, border-radius)

Prerequisites

At least one theme style must exist (use bricks_get_theme_styles to find available style IDs)
Color palette should be set up first so variables like var(--bricks-color-primary) resolve correctly
Spacing variables should be created before referencing them in theme style settings

When NOT to Use

When creating a brand new theme style (use bricks_create_theme_style instead)
When changing colors (use bricks_create_color or bricks_create_color_palette instead)
When setting per-element styles on a specific page (use global classes or inline settings)

Parameters

4 Total Parameters2 Required2 Optional

style_idstringREQUIRED

Theme style ID to update. Use bricks_get_theme_styles to find available IDs (e.g., "default", "bricks-mcp-dark").

labelstringoptional

Rename the theme style display label.

settingsobjectREQUIRED

Settings sections to update. Each key is a section name, value is the section settings. Deep merged with existing. Available sections: typography (typographyBody, typographyHeadings, typographyHeadingH1-H6, h1Margin-h6Margin, typographyHtml, focusOutline, blockquoteTypography), colors (colorPrimary, colorSecondary, etc.), general (siteLayout, siteBackground), links (typography, transition), contextualSpacing (contextualSpacingRemoveDefaultMargins, contextualSpacingParagraph, contextualSpacingHeading), css, section, container, block, div, button, heading, text, image, form, nav-menu, accordion, alert, carousel, slider, tabs, etc.

conditionsarrayoptional

Update display conditions. Replaces existing conditions entirely. Each condition: { main, postType?, archiveType?, ids?, exclude? }.

Code Examples

Complete Phase 2 theme style setup

Comprehensive example from CLAUDE.md Phase 2 step 5 showing body typography, full H1-H6 scale, heading margins, link styles, contextual spacing, and element defaults. This is the recommended starting configuration for every new site.

JSON

{
  "style_id": "default",
  "settings": {
    "typography": {
      "typographyBody": {
        "font-family": "Inter",
        "font-size": "16px",
        "line-height": "1.6",
        "color": { "hex": "#333333" }
      },
      "typographyHeadings": {
        "font-family": "Inter"
      },
      "typographyHeadingH1": {
        "font-size": "52px",
        "font-weight": "700",
        "line-height": "1.15"
      },
      "typographyHeadingH2": {
        "font-size": "40px",
        "font-weight": "600",
        "line-height": "1.2"
      },
      "typographyHeadingH3": {
        "font-size": "30px",
        "font-weight": "600",
        "line-height": "1.3"
      },
      "typographyHeadingH4": {
        "font-size": "24px",
        "font-weight": "600",
        "line-height": "1.35"
      },
      "typographyHeadingH5": {
        "font-size": "20px",
        "font-weight": "600",
        "line-height": "1.4"
      },
      "typographyHeadingH6": {
        "font-size": "16px",
        "font-weight": "600",
        "line-height": "1.5"
      },
      "h1Margin": { "bottom": "24" },
      "h2Margin": { "top": "48", "bottom": "20" },
      "h3Margin": { "top": "32", "bottom": "16" },
      "h4Margin": { "top": "24", "bottom": "12" },
      "h5Margin": { "top": "20", "bottom": "8" },
      "h6Margin": { "top": "16", "bottom": "8" }
    },
    "links": {
      "typography": {
        "color": { "raw": "var(--bricks-color-primary)" },
        "text-decoration": "none"
      },
      "transition": "all 0.3s ease"
    },
    "contextualSpacing": {
      "contextualSpacingRemoveDefaultMargins": [
        "h1", "h2", "h3", "h4", "h5", "h6", "p", "ul", "ol"
      ],
      "contextualSpacingParagraph": { "bottom": "16" },
      "contextualSpacingHeading": { "top": "32", "bottom": "12" }
    },
    "section": {
      "_padding": { "top": "80", "bottom": "80" }
    },
    "container": {
      "_width": "1200px"
    },
    "button": {
      "_padding": {
        "top": "12",
        "right": "24",
        "bottom": "12",
        "left": "24"
      },
      "_border": {
        "radius": { "top": "8", "right": "8", "bottom": "8", "left": "8" }
      },
      "_typography": { "font-weight": "600" }
    }
  }
}

Response

{
  "success": true,
  "style_id": "default",
  "message": "Theme style updated. Sections modified: typography, links, contextualSpacing, section, container, button."
}

Update only link styles

Deep merge means you can update a single section without affecting everything else.

JSON

{
  "style_id": "default",
  "settings": {
    "links": {
      "typography": {
        "color": { "hex": "#4361ee" },
        "text-decoration": "underline"
      },
      "transition": "color 0.2s ease"
    }
  }
}

Response

{
  "success": true,
  "style_id": "default",
  "message": "Theme style updated. Sections modified: links."
}

Common Mistakes

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

Agents consistently forget to set typographyHeadingH1 through typographyHeadingH6 with decreasing font sizes. Without this, all headings look the same size. Always define all 6 levels with appropriate font-size, font-weight, and line-height.

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

Set h1Margin through h6Margin with consistent bottom margins (and top margins for h2-h6) so headings have consistent vertical rhythm site-wide without per-element overrides.

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

Configure contextualSpacingRemoveDefaultMargins to remove browser defaults on tags like h1-h6, p, ul, ol. Then set contextualSpacingParagraph and contextualSpacingHeading for consistent spacing.

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

Always check with bricks_get_theme_styles first to find the correct style_id. Common values: "default", or custom slugs like "bricks-mcp-dark".

Warning: Undefined array key "fix_description" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 47

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-includes/kses.php on line 2018

Warning: Undefined array key "wrong_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 48

Warning: Undefined array key "right_code" in /var/www/vhosts/mcpbricksbuilder.wecode.swiss/httpdocs/wp-content/themes/bricks/includes/elements/code.php(236) : eval()'d code on line 49

Margin and padding values in theme styles should be plain numbers without units (e.g., "80" not "80px"). The Style Mapper adds units automatically.

Tips & Warnings

Critical: This is the most important design system tool. A well-configured theme style eliminates the need for inline typography and spacing on individual elements. Always set the complete H1-H6 scale, heading margins, and contextual spacing.

Tip: Deep merge means you can call this tool multiple times to build up settings incrementally. Each call only modifies the sections you provide.

Tip: Typography settings use CSS property names with hyphens: font-size, font-weight, line-height. Colors use the object format: { "hex": "#333" } or { "raw": "var(--bricks-color-primary)" }.

Warning: Conditions are fully replaced (not merged) when the conditions parameter is provided. If you only want to update settings without changing conditions, omit the conditions parameter entirely.

Return Values

Field	Type	Description
`success`	boolean	Whether the theme style was updated successfully.
`style_id`	string	The ID of the updated theme style.
`message`	string	Confirmation message describing what was updated.

Related Tools

Technical Details

Tool ID

bricks_update_theme_styles

API Endpoint

/design-system/theme-styles/{style_id}

HTTP Method

PUT

Namespace

design-system

Source File

design-system/theme-styles.ts

Version

1.0

Min Bricks Version

1.9

Requires Auth

Yes

Changelog

v1.0

Initial release with deep merge, conditions update, and full settings support.

20250101