HubSpot Global Styles: Enforce Brand Colors in Modules

Hey there, ESHOPMAN readers! As experts deeply embedded in the world of HubSpot and e-commerce, we often see brilliant discussions unfold in the HubSpot Community. It's a goldmine for practical solutions, and today we're diving into a common challenge that many HubSpot users, especially those running storefronts or complex marketing sites, face: how to enforce brand-approved global colors within custom modules.

Maintaining a consistent brand identity is non-negotiable, especially when your HubSpot portal is the central nerve point for your marketing, sales, and even your e-commerce operations. Whether you're using HubSpot as your primary storefront or as a powerful CRM that integrates with other platforms, ensuring every button, banner, and background adheres to your brand guidelines is crucial. But sometimes, HubSpot's module fields can throw a curveball.

HubSpot CMS module settings with choice field for colors and CSS code

The Challenge: Global Colors vs. Module ColorFields

Recently, a community member posed a very relevant question: "Is it possible to pass the colors defined in fields.json to a colorfield? I want to limit the colors a user can set on a module to only the ones defined in fields.json."

The original poster was looking to restrict the color choices in a module's ColorField to a predefined set of global colors, like those typically set up in a fields.json file for theme-level control. This is a smart move for brand consistency, preventing content editors from accidentally picking off-brand hues. They shared their module field setup:

And their fields.json snippet for global colors:

[
  {
    "label": "Global colors",
    "name": "global_colors",
    "type": "group",
    "children": [
      {
        "label": "Primary",
        "name": "primary",
        "type": "color",
        "inherited_value": {
          "property_value_paths": {
            "color": "brand_settings.primaryColor"
          }
        },
        "default": { "color": "#ba1c2f" }
      },
      {
        "label": "Secondary",
        "name": "secondary",
        "type": "color",
        "inherited_value": {
          "property_value_paths": {
            "color": "brand_settings.secondaryColor"
          }
        },
        "default": { "color": "#1b1b1b" }
      },
      {
        "label": "Accent 1",
        "name": "accent1",
        "type": "color",
        "inherited_value": {
          "property_value_paths": {
            "color": "brand_settings.accentColor1"
          }
        },
        "default": { "color": "#6f645b" }
      },
      {
        "label": "Accent 2",
        "name": "accent2",
        "type": "color",
        "inherited_value": {
          "property_value_paths": {
            "color": "brand_settings.accentColor2"
          }
        },
        "default": { "color": "#d9d3cd" }
      },
      {
        "label": "Accent 3",
        "name": "accent3",
        "type": "color",
        "inherited_value": {
          "property_value_paths": {
            "color": "brand_settings.accentColor3"
          }
        },
        "default": { "color": "#7f0321" }
      },
      {
        "label": "White",
        "name": "white",
        "type": "color",
        "default": { "color": "#ffffff" }
      },
      {
        "label": "Light Gray",
        "name": "light_gray",
        "type": "color",
        "default": { "color": "#f2f2f2" }
      },
      {
        "label": "Medium Warm",
        "name": "medium_warm",
        "type": "color",
        "default": { "color": "#a89c92" }
      },
      {
        "label": "Black",
        "name": "black",
        "type": "color",
        "default": { "color": "#000000" }
      }
    ]
  }
]

The core of the problem lies in how HubSpot's ColorField's limitedOptions property works. It's designed to accept specific color values (hex codes, RGB, etc.) or references to HubSpot's built-in brand_settings (like brand_settings.primaryColor). It doesn't inherently support direct references to custom global colors defined within your theme's fields.json as dynamic variables for limiting choices.

The ESHOPMAN Solution: Leveraging Choice Fields for Global Color Control

A helpful community member provided an elegant and robust workaround, which we at ESHOPMAN wholeheartedly endorse. The solution involves using a choice field instead of a ColorField, coupled with carefully crafted CSS classes. This method gives developers precise control while offering content editors a simple, brand-compliant selection.

Step-by-Step Implementation for Enforcing Global Styles

1. Define Your Global Colors in `fields.json`

First, ensure your global colors are properly defined in your theme's fields.json. The original poster's example is perfect for this, establishing named colors like "primary," "secondary," "accent1," etc. These become accessible via HubL's theme.colors object.

2. Create CSS Classes Referencing Global Colors

Next, you'll create CSS classes that dynamically pull these global colors. You have two excellent options here:

Direct HubL Variable Injection: This is straightforward for simple cases.

.primary-bg {
   background-color: {{theme.colors.global_colors.primary.css}};
}
.primary-text {
   color: {{theme.colors.global_colors.primary.css}};
}
.secondary-bg {
   background-color: {{theme.colors.global_colors.secondary.css}};
}
.secondary-text {
   color: {{theme.colors.global_colors.secondary.css}};
}
/* ... and so on for all your global colors and desired properties */

Using CSS Custom Properties (Variables): For more complex themes and better maintainability, especially if you're looking for a powerful Shopify alternative in terms of theme flexibility, CSS variables are superior. Define them once in your root and reuse them.

:root {
  --color-primary: {{theme.colors.global_colors.primary.css}};
  --color-secondary: {{theme.colors.global_colors.secondary.css}};
  --color-accent1: {{theme.colors.global_colors.accent1.css}};
  /* ... define all global colors */
}

.primary-bg {
   background-color: var(--color-primary);
}
.primary-text {
   color: var(--color-primary);
}
.secondary-bg {
   background-color: var(--color-secondary);
}
.secondary-text {
   color: var(--color-secondary);
}
/* ... and so on */

Notice the path to access the global colors: theme.colors.global_colors.primary.css. This assumes your global color group is named global_colors as in the original fields.json example.

3. Implement a `choice` Field in Your Module

Now, replace your ColorField with a choice field. The values of this choice field will be the meaningful parts of your CSS class names (e.g., "primary", "secondary").

For a richer editing experience, consider using display="radio" or even a custom UI extension if you want visual color swatches, though that's a more advanced topic.

4. Apply the Chosen Class in Your Module's HTML/HubL

Finally, in your module's HTML (module.html or similar), you'll dynamically apply the selected class:


  {{ module.buttonText }}

This snippet assumes your choice fields are nested under a field group named buttonStyles, and the choice field names are bgColorClass and textColorClass, as in the example above.

Why This Approach is Superior for Brand Consistency and RevOps

This method offers several significant advantages, especially for businesses focused on streamlined RevOps and a cohesive brand experience:

Enforced Brand Consistency: Content editors are limited to a predefined palette, eliminating off-brand color usage. This is critical for maintaining a professional image, whether you're managing a complex B2B site or an e-commerce storefront that needs to stand out from a basic wix online store.
Developer Control: Developers maintain full control over the actual color values and how they are applied, preventing accidental overrides.
Simplified Editing Experience: Editors choose from descriptive names ("Primary," "Secondary") rather than hex codes, making content creation faster and less error-prone.
Centralized Updates: If a brand color changes, you update it once in fields.json, and it propagates everywhere via your CSS classes. This is a massive time-saver for large sites.
Flexibility: You can create classes for various properties (background, text, border, hover states) using the same global color definitions.
Semantic Naming: Beyond just colors, apply this pattern to other design tokens like spacing (e.g., padding-sm, padding-md) or typography (e.g., heading-h1, body-text).
Component-Based Design: This approach aligns perfectly with component-based design systems, where modules are self-contained and draw from a central style guide.
E-commerce Impact: For ESHOPMAN users, consistent branding across product pages, checkout flows, and marketing materials directly impacts conversion rates and customer trust. A disjointed visual experience can deter customers, regardless of how compelling your product is.

At ESHOPMAN, we understand that HubSpot isn't just a CRM; it's a powerful platform for building entire digital experiences, including robust e-commerce storefronts. Our tools and expertise help businesses leverage HubSpot to its fullest, offering a truly integrated platform that can serve as a comprehensive Shopify alternative for those seeking deeper HubSpot integration and RevOps alignment. By mastering techniques like global style enforcement, you unlock HubSpot's full potential for a seamless, on-brand customer journey.

Conclusion

While HubSpot's ColorField offers convenience, achieving strict brand consistency with global colors requires a slightly more advanced approach. By combining HubSpot's choice fields with dynamic CSS classes that reference your theme's fields.json global colors, you empower your content editors with easy-to-use, brand-compliant options while maintaining developer control and ensuring a cohesive visual identity across your entire HubSpot presence. This strategy is a cornerstone of effective RevOps and a polished online storefront.

Do you have other HubSpot development challenges you'd like us to explore? Join the conversation in the HubSpot Community or reach out to the ESHOPMAN team for expert guidance!