HubSpot Content Hub Themes: How to Give Your Site Identity and Autonomy

Imagine leadership asked to change the site's main color, from blue to a new brand green. On a poorly structured site, that becomes a project: someone has to hunt the color across dozens of files, module by module, and still risks missing a corner. On a well-built site, it is one click in the theme editor, and the whole site changes at once.

The difference between those two worlds is the theme. In HubSpot Content Hub, the theme is what gives the whole site its visual identity and consistency, and it is what decides whether marketing has the autonomy to adjust the look or depends on the developer for every detail. In this guide, I will open up the anatomy of a theme: the files that define it, design tokens, breakpoints, and child themes for evolving safely.

What a theme is, in practice

A theme brings together, in a cohesive package, the site's templates, modules, styles, and global settings. It is the layer that ensures every page looks like part of the same place: the same palette, the same fonts, the same spacing, the same way of responding on mobile. Without a well-built theme, each page tends to become a visual island, and the site loses the unity that conveys professionalism.

More than aesthetics, the theme is the site's visual governance structure. It defines what can vary and what needs to be consistent, and exposes to marketing only the safe levers. It is that well-designed boundary that lets you give freedom without creating chaos, the balance every sustainable site needs to find.

The two files that define the theme

At the heart of every Content Hub theme are two files that talk to each other and deserve to be understood clearly.

• theme.json: the theme's metadata and technical configuration, like the name, the author, the responsive breakpoints, and the template used for the preview.
• fields.json: the theme's global fields, that is, the settings that appear in the theme editor for marketing to adjust, like colors, fonts, and spacing.

The division of roles is clear: theme.json handles how the theme works on the inside, and fields.json handles what marketing can change on the outside. Understanding that separation is the first step to building a theme that is both solid on the inside and flexible in just the right measure on the outside.

Design tokens: the magic of consistency

The theme's fields.json becomes, in practice, a set of design tokens: the primary color, the text color, the heading font, the body font, the base spacing. Templates and modules consume these tokens instead of fixed values. Instead of a module saying "blue", it says "the theme's primary color", and fetches that value from the token.

That is what makes it possible to change the whole site's main color in one click. When you change the primary color token in the theme editor, every place that consumes that token changes together, without you editing file by file. Tokens are the secret of a site that evolves coherently, where a brand decision propagates across the whole site automatically and reliably.

Marketer editing: autonomy with limits

The strength of a well-built theme is giving marketing real autonomy. Through the theme editor, it adjusts colors, fonts, and spacing within the limits the developer defined, and sees the result across the whole site. No need to open a ticket, no need to wait for the technical queue, no need to know how to code.

The secret is choosing well what to expose. You open the levers that make sense to vary, like the palette and the fonts, and keep fixed what needs consistency, like the layout structure and the responsive behavior. That curation is what keeps the site from becoming a patchwork, while giving marketing the freedom to adjust the brand as it evolves.

Responsive breakpoints in the theme

The theme.json declares the responsive breakpoints, like the point where the layout stops being desktop and becomes mobile. Defining this at the theme level, and not in each module, ensures the whole site responds to screens coherently. Every module comes to use the same turning point, instead of each one inventing its own. Worth setting expectations here: the theme works essentially with the mobile cut plus the default desktop, not with a free scale of breakpoints, so there is no separate custom point for tablet.

That coherence matters a lot because most traffic today comes from mobile. A site where each section becomes mobile at a different point looks misaligned and odd on small screens, exactly where most people access. Centralizing the breakpoints in the theme is what keeps the experience consistent from desktop to mobile.

Child themes: evolving without breaking production

When it is time to redesign the site or test a new visual direction, touching the production theme directly is risky. That is where the child theme comes in. It inherits the entire base of the main theme and lets you override only what changes, without touching the original. It is the safe way to build and test a new version before publishing it.

With a child theme, you experiment freely knowing the live site stays intact, running on the current theme. When the new version is ready and reviewed, you switch, with the peace of mind of someone who tested first. That safety net is what lets you evolve the site's look without the fear of breaking production on every experiment.

Why this matters for your operation

A well-built theme is what turns the site from a recurring technical-maintenance cost into an asset marketing operates on its own. When the brand evolves, the team adjusts colors and fonts on the spot, with no project and no queue. When a campaign needs a new page, it is born with the right identity, because it consumes the theme's tokens. The autonomy the theme gives translates into speed and brand consistency, two things that weigh directly on results.

Otherwise, a poorly structured theme locks the site into an expensive, slow dependency. Each visual change becomes a ticket, each brand adjustment becomes a project, and the inconsistency between pages erodes the perception of quality. Investing in a well-designed theme is investing in marketing's ability to run its own site at the pace of the business.

In practice: the rebrand that would have taken weeks

A company went through a rebrand and needed to update the whole site's palette and fonts. In the old, poorly structured theme, the colors were hardcoded across dozens of modules, and the estimate to update everything by hand was weeks of technical work, with a high risk of missing a corner and leaving the site with two faces.

After restructuring the theme with design tokens, the same rebrand became a matter of minutes: it was enough to update the color and font tokens in the theme editor, and the whole site followed at once, consistently. What was a dreaded project became a trivial task. The difference was not in the brand, it was in the theme's structure behind it.

Checklist of a well-structured theme

1. Does the theme have theme.json and fields.json with well-defined roles?
2. Do colors, fonts, and spacing live as tokens, consumed by the modules?
3. Does the theme editor expose to marketing only the safe levers to vary?
4. Are the responsive breakpoints centralized in the theme, not in the modules?
5. Is there a child theme to test big changes without touching production?
6. Is no essential visual value hardcoded straight into the modules?

Frequently asked questions

What is the difference between theme.json and the theme's fields.json?

theme.json carries the theme's metadata and technical configuration, like name, breakpoints, and preview. fields.json carries the editable global fields, like colors and fonts, that appear in the theme editor for marketing to adjust.

What are design tokens in a theme?

They are the global settings, like primary color, fonts, and spacing, that templates and modules consume instead of fixed values. Changing a token in the editor updates the whole site at once.

Can I let marketing change the look without breaking the site?

Yes, that is exactly the goal of a well-built theme. You expose the fields that make sense to vary, like palette and fonts, and keep fixed what needs consistency, like the layout structure.

What is a child theme for?

To redesign or test big changes without touching the production theme. The child theme inherits the base and overrides only what changes, working as a safety net for evolving the look.

Why centralize breakpoints in the theme?

So all modules respond to screens at the same point, keeping the experience consistent from desktop to mobile. Without it, each section becomes mobile at a different point and the site looks misaligned.

Do I need to rebuild the theme when the brand changes?

No, if the theme uses tokens. A brand change becomes updating the color and font tokens in the editor, and the whole site follows. Only rebuild when the structure, not just the look, needs to change.

Want a HubSpot theme that gives your marketing team autonomy and keeps the site consistent? At Insight Sales we build themes with tokens and real visual governance. Talk to our team and find out how we can help.