A HubSpot theme is more than a collection of templates and styles—it's the foundation of your entire website. Build it right, and your marketing team can create beautiful, consistent pages quickly and confidently. Build it wrong, and every new page becomes a struggle against technical limitations and inconsistent design.
Modular theme development is the approach that separates professional HubSpot sites from amateur ones. It's about creating flexible, reusable components that work together seamlessly while remaining independent enough to adapt to different needs.
This guide walks through the principles, structure, and best practices of modular HubSpot theme development. Whether you're building your first custom theme or refining an existing one, these concepts will help you create themes that scale with your business.
Modular theme development means building your HubSpot theme as a system of independent, reusable components rather than a collection of one-off templates.
Think of it like LEGO blocks. Each block is self-contained and functional on its own, but blocks connect in standardized ways to build infinite variations. You're not creating custom pieces for every structure—you're creating a library of versatile pieces that combine flexibly.
In HubSpot terms, this means:
Reusable modules that work across different templates and contexts. A hero module works equally well on the homepage, landing pages, and service pages without modification.
Consistent design system with shared styles, spacing, colors, and typography. Changes to the design system propagate automatically across all modules and templates.
Flexible templates that accommodate different content needs without requiring custom development. Content editors can build diverse pages using the same template by combining modules differently.
Independent components that don't depend on each other. Removing or updating one module doesn't break others. Each module brings its own styles and functionality.
The opposite of modular development is monolithic development—building each template as a unique, self-contained entity. Monolithic themes require more initial work for each template and become increasingly difficult to maintain as the site grows.
Why invest the upfront effort in modular architecture? The benefits compound over time:
Once your module library is built, creating new pages becomes fast. Content editors drag modules into place, customize fields, and publish. What used to take days of custom development now takes hours of content work.
Every module follows the same design system. Pages automatically look cohesive because they're built from the same components. Brand consistency happens by default, not through careful manual enforcement.
When you need to update a design element—button styles, heading fonts, spacing—you change it once in the module or theme, and it updates everywhere. No hunting through dozens of templates making the same change repeatedly.
The initial investment in modular architecture pays back quickly. Future development becomes faster and cheaper because you're building on a solid foundation rather than fighting technical debt.
As your site grows, modular themes scale gracefully. Adding new templates or pages doesn't require proportional increases in development effort. The module library handles most needs without custom work.
Content editors can do more independently. They're not blocked waiting for developers to build every new page. Developers focus on building new modules and improving the system, not repetitive template work.
Successful modular themes follow several key principles:
Each module should do one thing well. A hero module displays hero content. A CTA module displays calls-to-action. A testimonial module displays testimonials. Don't create "Swiss Army knife" modules that try to do everything—they become complex, confusing, and difficult to maintain.
Each module should include everything it needs to function: its own HTML structure, CSS styles, and JavaScript (if needed). It shouldn't depend on external styles or scripts that might not be present on every page.
Use clear, predictable naming for modules, CSS classes, and files. Many developers use BEM (Block Element Modifier) methodology for CSS classes. Whatever convention you choose, apply it consistently across all modules.
Modules should use shared design tokens—colors, fonts, spacing, breakpoints—defined at the theme level. This ensures consistency and makes global design changes possible.
Make modules adaptable through well-designed fields, not through creating variations of the same module. One flexible hero module is better than five rigid hero modules with hardcoded differences.
Design and build modules for mobile first, then enhance for larger screens. This ensures good mobile experiences and prevents the common problem of desktop-focused modules that break on mobile.
A well-organized theme structure makes development and maintenance easier. Here's a recommended structure:
Theme Root: Contains theme configuration files, global styles, and documentation.
Templates Folder: Contains page templates (homepage, landing page, blog post, etc.). Templates define overall page structure and which modules are available.
Modules Folder: Contains all custom modules. Each module lives in its own folder with all its files (HTML, CSS, JS, fields, metadata).
CSS Folder: Contains global stylesheets—design system variables, typography, utilities, and base styles that apply across the theme.
JS Folder: Contains global JavaScript files that apply across multiple pages or modules.
Images/Assets Folder: Contains theme-level images, icons, and other static assets.
Within each module folder, maintain consistent file structure: module.html (HubL template), module.css (styles), module.js (JavaScript, if needed), fields.json (field definitions), and meta.json (module metadata).
Before building modules, establish your design system—the shared design language that all modules will use.
Define your brand colors as CSS custom properties (variables) in your theme's global stylesheet. Include primary colors, secondary colors, neutral grays, and semantic colors (success, warning, error). Every module references these variables rather than hardcoding color values.
Define font families, sizes, weights, and line heights. Create a type scale that provides consistent heading and body text sizes. Set these as CSS variables so they're easy to update globally.
Create a consistent spacing scale—typically based on multiples of 4 or 8 pixels. Define spacing variables for margins, padding, and gaps. Consistent spacing creates visual rhythm and makes designs feel cohesive.
Define standard breakpoints for responsive design. Common breakpoints might be 480px (mobile), 768px (tablet), 1024px (small desktop), and 1440px (large desktop). Use these consistently across all modules.
Define standard styles for common elements: buttons, links, forms, cards, etc. These become the building blocks that modules use consistently.
Your design system becomes the single source of truth. When you need to update your brand colors or adjust spacing, you change the design system variables, and all modules update automatically.
With your design system established, you can build modules that are both flexible and consistent.
Identify the content patterns your site uses repeatedly: heroes, CTAs, feature grids, testimonials, content blocks, image-text combinations, etc. These become your core module library.
For each module, think through what should be customizable. Too few options and the module is rigid. Too many options and it's overwhelming. Find the balance that provides flexibility without complexity.
Group related fields logically. Put all heading-related fields together, all button-related fields together, etc. Use clear labels and helpful descriptions. Provide smart defaults that work well without customization.
Instead of creating separate modules for minor variations, build variation into a single module. Use choice fields for style options (primary vs. secondary button), boolean fields for optional elements (show/hide subtitle), and repeater fields for variable-length content (testimonials, features, logos).
Test modules with edge cases: very long content, very short content, missing images, empty optional fields. Use conditional rendering to handle missing content gracefully. Ensure modules don't break when fields are left empty.
Every CSS class should start with the module name to prevent conflicts. If your module is called "hero-module," all its classes should be "hero-module__element." This scoping ensures modules don't interfere with each other.
Templates define page structure and determine which modules are available. Good templates are flexible enough to accommodate diverse content needs without requiring custom development.
Use HubSpot's drag-and-drop areas to let content editors add and arrange modules freely. Define which modules are available in each area based on the template's purpose.
Create templates for common page types: homepage (unique layout, specific modules), landing pages (conversion-focused, minimal navigation), content pages (flexible, blog-style), service/product pages (feature-focused), and blog posts (article layout with sidebar options).
Use partial templates for elements that appear across multiple templates: headers, footers, navigation, and sidebars. Define these once and include them in templates. Updates to partials propagate automatically.
Use HubSpot's template inheritance to create base templates that child templates extend. The base template defines overall structure (header, footer, container widths), while child templates define specific content areas and available modules.
Modular themes can become bloated if not optimized carefully. Performance should be built in from the start.
Keep module CSS focused and minimal. Only include styles the module actually needs. Avoid loading entire CSS frameworks for a few utility classes. Use CSS custom properties for values that might change rather than duplicating styles.
Only load JavaScript when modules actually need it. Use HubSpot's module-level JavaScript so scripts only load on pages where the module appears. Avoid loading large libraries (like jQuery) unless absolutely necessary.
Use HubSpot's image optimization features: responsive images with srcset, lazy loading for images below the fold, and appropriate image formats (WebP when supported). Provide guidance in field descriptions about recommended image sizes.
Inline critical CSS—styles needed for above-the-fold content—in the template head. Load non-critical CSS asynchronously. This improves perceived performance by rendering visible content faster.
Combine CSS and JavaScript files where possible. Use CSS sprites or icon fonts for small graphics. Every additional HTTP request adds latency, especially on mobile connections.
A modular theme is only as good as its documentation and ongoing maintenance.
Document each module: what it's for, where to use it, what each field does, and any special considerations. Include screenshots showing the module in use. This documentation helps content editors use modules effectively and helps future developers understand the system.
Document your design system: color palette, typography scale, spacing system, and component styles. This becomes the reference for maintaining consistency and onboarding new team members.
Maintain a changelog tracking theme updates: new modules added, existing modules updated, bug fixes, and breaking changes. Version your theme so you can track what's deployed and roll back if needed.
Periodically audit your theme: identify unused modules, find opportunities for consolidation, check for performance issues, and ensure consistency. Themes drift over time without active maintenance.
When you need to replace or remove modules, do it gracefully. Mark old modules as deprecated, provide migration paths to new modules, and communicate changes to content editors before removing anything.
Creating too many similar modules. Five slightly different hero modules is harder to maintain than one flexible hero module. Consolidate variations into single, flexible modules.
Hardcoding values. Every hardcoded value is a future maintenance burden. Use fields for content, design system variables for styles, and configuration files for theme-level settings.
Ignoring mobile. Designing for desktop first leads to poor mobile experiences. Start with mobile and enhance for larger screens.
Over-complicating modules. Modules with dozens of fields and complex conditional logic become confusing and error-prone. Keep modules focused and simple.
Neglecting performance. Loading unnecessary CSS and JavaScript on every page hurts performance. Optimize aggressively and test regularly.
Skipping documentation. Undocumented themes are difficult for others (and future you) to work with. Document as you build, not as an afterthought.
Modular themes aren't built once and forgotten—they evolve with your business needs.
Start with core modules. Build the essential modules first: header, footer, hero, CTA, content blocks, and forms. Launch with a solid foundation rather than trying to build everything upfront.
Add modules as needed. When you need new functionality, add new modules to the library. Each addition makes the theme more capable.
Refine based on usage. Pay attention to how content editors use modules. If they're constantly working around limitations, refine the modules to better match actual needs.
Consolidate when appropriate. If you find yourself with multiple similar modules, consolidate them into single, more flexible modules. Fewer, better modules are easier to maintain than many specialized ones.
Update the design system. As your brand evolves, update the design system. Because modules reference design system variables, updates propagate automatically.
Modular theme development requires more upfront investment than throwing together quick templates. But the long-term value far exceeds the initial cost.
Your marketing team becomes more self-sufficient. New pages and campaigns launch faster. Design stays consistent without constant oversight. Maintenance becomes manageable rather than overwhelming. The site scales gracefully as your business grows.