How to build HubSpot modules your marketing team can’t break

Name fields after what they do

The person editing the page sees the field labels, not your code. “Heading”, “Short intro (one or two sentences)” and “Button text” are better labels than title_text, body_1 and cta_label. Group related fields, put them in the order they appear on the page, and hide anything technical in a group of its own.

HubSpot lets every field carry help text. Use it for anything that isn’t obvious: the recommended image size, where the text appears, what happens if a field is left empty.

Give choices, not free values

Every free color picker, font size or spacing value is a way to drift away from the brand. Where the design has rules, turn them into choices:

• Background: a choice field with Light, Dark and Brand, instead of a color picker.
• Layout: Image left or Image right, instead of order and width controls.
• Spacing: Compact, Normal and Spacious, instead of pixel values.

Colors and fonts belong in the theme settings, so they change everywhere at once. A module that hardcodes its own blue is the one that’s still the old blue after a rebrand.

Set limits the design can live with

Repeater fields in HubSpot can have a minimum and a maximum number of items. If a card row is designed for three to six cards, set those limits. A row of eleven cards is not a design choice anyone made on purpose.

The same goes for text. If a heading is designed for one line, say so in the help text, and make sure the layout still holds when someone ignores it.

Use display conditions to show fields only when they apply. If “Show a button” is off, the button text and link fields don’t need to be visible.

Make the defaults look right

When a marketer drags a module onto a page, it should already look finished, with realistic example content rather than lorem ipsum. Good defaults teach how the module is meant to be used, and they make it obvious which fields still need real content.

Build in accessibility and SEO

• Alt text: keep the alt text input on every image field, and use help text to say what makes a good one.
• Heading levels: let editors choose H2 or H3 for a module heading, so the page’s outline stays correct wherever the module is placed. Only the page’s main title should be an H1.
• Real links and buttons: a link is an <a>, an action is a <button>, and both are reachable by keyboard.
• Structured data where it fits: an FAQ module can output FAQ markup from the same fields that render the questions, so the two can’t drift apart. More in schema markup in HubSpot.

Test with the worst content, not the demo content

Before a module ships, fill it with content nobody planned for:

• A heading three times longer than the design, and one with a single word
• A long German or Finnish compound word that can’t break
• An empty optional field, and every optional field empty at once
• The maximum number of repeater items, and the minimum
• A portrait image where a landscape one was expected
• The page at phone width

If the module still looks intentional in all of these, it will survive real use. If it doesn’t, fix the layout or set a limit, rather than hoping nobody tries it.

Write it down

A one-page guide per template, showing which modules go where and what each one is for, saves more support questions than any amount of clever code. Keep it next to the theme, and update it when the modules change.