If you’ve been working with HubSpot CMS for a while, you probably remember the dark days of rigid templates. Marketers had to submit a support ticket just to change the layout of a landing page or add a new section.
Today, things are different. HubSpot’s drag-and-drop (dnd) areas and theme framework have completely changed the game. But just because you can build flexible themes doesn’t mean every developer does.
In this guide, I’ll walk you through the architecture of a modern, highly scalable HubSpot theme that keeps both developers happy (with clean code) and marketers happy (with ultimate flexibility).
1. Stop Hardcoding, Start using dnd_area
The biggest mistake I see developers make is treating HubSpot like a traditional WordPress PHP template. They hardcode sections and only leave tiny text modules editable.
Instead, your base templates should act as empty canvases. Use the dnd_area tag to let marketers build their own layouts.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>{{ page_meta.html_title }}</title>
{{ standard_header_includes }}
</head>
<body>
{% global_partial path="../partials/header.html" %}
<main class="main-content">
{% dnd_area "main_content_area" class="dnd-wrapper" %} {% end_dnd_area %}
</main>
{% global_partial path="../partials/footer.html" %} {{
standard_footer_includes }}
</body>
</html>By keeping the wrapper minimal, you give the marketing team the power to construct their own pages using your custom modules.
2. Granular Custom Modules
If your theme has a module called “Home Page Hero”, you’re doing it wrong. Modules should be agnostic and reusable across multiple pages.
Instead of building page-specific modules, build layout-specific modules:
- Hero Section (Can be used on Home, About, or Service pages)
- Feature Grid (Can be used for features, services, or team members)
- Rich Text with Image (The bread and butter of any layout)
- Call to Action Banner
Pro Tip: Keep your module fields organized. Use groups and tabs in your
fields.jsonso marketers don’t have to scroll through 50 fields to find the button color setting.
3. Integrating Tailwind CSS with HubSpot
HubSpot’s default CSS handling is okay, but if you want to build fast in 2026, Tailwind CSS is the way to go. You can set up a modern build process using the HubSpot CLI.
Here is a quick look at how you structure your package.json to compile Tailwind directly into your HubSpot theme’s CSS folder:
{
"name": "hubspot-modern-theme",
"version": "1.0.0",
"scripts": {
"start": "hs watch src/theme DestTheme & tailwindcss -i ./src/css/input.css -o ./src/theme/css/styles.css --watch",
"build": "tailwindcss -i ./src/css/input.css -o ./src/theme/css/styles.css --minify && hs upload src/theme DestTheme"
}
}This setup allows you to use Tailwind utility classes directly in your HubL templates and custom modules. When you hit save, the HubSpot CLI syncs it instantly.
4. Master the theme.json File
Your theme.json is the control center for your client’s brand. It prevents them from going rogue and using neon green text on a yellow background.
Define your exact brand colors, typography, and spacing variables here:
{
"name": "Neo Brutalist Theme",
"author": "Pratik Chauhan",
"colors": {
"primary": "#FFA000",
"secondary": "#111317",
"background": "#F8F8F6"
},
"spacing": {
"padding_small": "1rem",
"padding_large": "4rem"
}
}You can then reference these dynamically in your CSS using theme.colors.primary or output them as CSS variables in your base.html so Tailwind can pick them up.
Final Thoughts
Building a scalable HubSpot theme is about striking the perfect balance between structure and freedom. You want to give marketers the tools to build landing pages at 3 AM without calling you, while ensuring the site remains blazing fast and visually consistent.
If you architect your themes with reusable modules, global partials, and a modern CSS workflow, you’ll drastically cut down maintenance time and deliver a far superior product to your clients.
