The first number — major
It moves when something you built on is removed or renamed: a module field, a template, a class name, a token. A major release is the one you read line by line before you apply it.
Release notes
Every release, and what it does to your files.
How a version number is read, what counts as a breaking change, and what happens to a theme file you edited when an update lands. Then the entries.
Versioning
How to read a version number.
Three numbers separated by dots. Which of them moves tells you how much attention a release needs before you apply it.
add_circle
The second number — minor
New modules, new fields, new templates. Nothing that already existed behaves differently, and nothing appears on a page you have already built until you add it.
build
The third number — patch
A fix to something that was meant to work and did not. No renames, no removals, no new fields. The only thing to check is whether you had worked around the bug yourself.
The change
Breaking
Can change a built page
Version step
Where it lands
What to look at
After you update
A module field is renamed or removed
info
check_circle
Included
Major
Every page that uses the module
A template is renamed or deleted
check_circle
Included
Major
Pages built on that template
A class name or design token is renamed
check_circle
Included
Major
Any CSS or JS you wrote against the old name
A field default changes
info
check_circle
Included
Major
Modules where you left that field alone
Markup inside a module is restructured
check_circle
Included
Major
Custom CSS and anything selecting those elements
A field or a choice is added to a module
cancel
Not included
Minor
Nothing — it arrives set to its default
A new module or template ships
cancel
Not included
Minor
Nothing until you place it on a page
A layout or browser bug is fixed
info
cancel
Not included
Patch
Whether you had patched around it yourself
Something is marked deprecated
cancel
Not included
Minor
Nothing yet — it is removed at the next major
Breaking
Can change a built page
- A module field is renamed or removed check_circle
- A template is renamed or deleted check_circle
- A class name or design token is renamed check_circle
- A field default changes check_circle
- Markup inside a module is restructured check_circle
- A field or a choice is added to a module cancel
- A new module or template ships cancel
- A layout or browser bug is fixed cancel
- Something is marked deprecated cancel
Version step
Where it lands
- A module field is renamed or removed Major
- A template is renamed or deleted Major
- A class name or design token is renamed Major
- A field default changes Major
- Markup inside a module is restructured Major
- A field or a choice is added to a module Minor
- A new module or template ships Minor
- A layout or browser bug is fixed Patch
- Something is marked deprecated Minor
What to look at
After you update
- A module field is renamed or removed Every page that uses the module
- A template is renamed or deleted Pages built on that template
- A class name or design token is renamed Any CSS or JS you wrote against the old name
- A field default changes Modules where you left that field alone
- Markup inside a module is restructured Custom CSS and anything selecting those elements
- A field or a choice is added to a module Nothing — it arrives set to its default
- A new module or template ships Nothing until you place it on a page
- A layout or browser bug is fixed Whether you had patched around it yourself
- Something is marked deprecated Nothing yet — it is removed at the next major
Before you update
An update replaces the theme files you edited.
An update is applied by overwriting the theme folder in your portal. It is not a merge. Page content is stored on the page rather than in the theme, so nothing a marketer wrote is touched — but a theme file you changed is replaced with our version of that file, and your change is gone. Keep a list of the files you have edited and treat reapplying them as part of every update.
1
List what you changed
Write down every theme file you edited before you do anything else. If you cannot remember which ones they are, that is the answer to whether you update today.
2
Read every entry in between
Everything between the version you are on and the version you are moving to applies to you. Reading only the newest entry is how a breaking change gets missed.
3
Update a sandbox portal first
Apply the release where nothing is live. Open the pages that use the modules the entries name and look at them at desktop and at phone width.
4
Reapply your edits, then go live
Put your changes back on top of the new files and keep the list. The next release overwrites them again, and the list is what makes that a task rather than an incident.
Reading an entry
What the four labels mean.
Every line in every entry below carries one of these. They are the fastest way to decide whether a release needs an afternoon or a glance.
add_circle
New
Something that did not exist before. It sits in the module list or the field panel until you choose to use it. A page you have already built does not change.
upgrade
Improved
Something that existed and now behaves better. Read these rather than skimming them: an improvement can still move a layout, and it is the label people assume is safe.
build
Fixed
Something that was meant to work and did not. If you had written a workaround for it, the workaround is now the thing to look at.
remove_circle
Deprecated
Still shipped and still working, and scheduled to be removed at the next major release. Treat it as work with a date on it rather than a warning you can leave alone.
v1.0.0
Stable release
Field group and token names settled before the theme was published, so the names in the docs are the names in the files. This is the release to read line by line.
- upgrade Improved Every module uses the same field groups in the same order: layout, then card_style, then icon_style, then its repeater. Groups that were named differently were renamed to match.
- upgrade Improved Colour now lives in one Brand Colors group. The per-module colour overrides read from it instead of holding their own copies.
- upgrade Improved Section spacing moved out of the templates and onto the seam setting, so two adjacent sections decide their own gap from the seam_bond, seam_step and seam_chapter tokens.
- upgrade Improved The per-module icon colour fields deprecated in 0.7.0 are gone. Icons read the theme icon settings.
- add_circle New Documentation template and the Docs module: sidebar, table of contents, article search and a feedback block.
- build Fixed Buttons inside the CTA band rendered at the wrong size at tablet widths.
v0.9.0
Sections people were building by hand
Three things that kept being rebuilt in a rich text field, turned into modules and partials.
- add_circle New Comparison Table module, with a sticky header row, a sticky first column and a tooltip per row.
- add_circle New Resource Card module, with search, category filters, a grid and list toggle and a detail panel.
- add_circle New Section partials under templates/sections for the CTA band, FAQ, feature grid, hero, stats, team and testimonials, so a page can be assembled from them.
- upgrade Improved Steps takes a vertical direction as well as horizontal, and the connector can be solid, dashed or dotted.
- build Fixed Accordion items stayed open when allow_multiple was switched off.
v0.8.0
The type scale and the shell
Work on the numbers underneath. Nothing was renamed here, so it is a read rather than an afternoon.
- add_circle New Type scale, font weights, line heights and letter spacing are theme settings of their own, so a size or a weight can be changed without opening a stylesheet.
- add_circle New Shell inset and shell radius added as theme settings, each with a mobile value. The hero, the CTA band and the footer all read them, so the three frames match.
- build Fixed Card padding resolved to fractional pixel values at some widths. It lands on the spacing ladder now.
- build Fixed Sticky positioning inside a module was broken by the wrapper HubSpot puts around it.
- build Fixed The tab strip overflowed the viewport at phone widths instead of scrolling inside its own track.
v0.7.0
Presets and icon libraries
The two settings that change the most on a page for the least work.
- add_circle New Theme presets: dark, light, midnight, warm, forest, and a custom slot that keeps values you set yourself.
- add_circle New Icon library setting. Material Symbols, Lucide, Phosphor, Tabler, Remix, Heroicons, Font Awesome, Bootstrap, Hugeicons and the HubSpot set, chosen once for the whole theme.
- add_circle New Material Symbols weight, fill, grade and optical size exposed as theme settings, so icon weight can be matched to the type.
- upgrade Improved Reveal animations can be switched off for the whole theme in one setting, and the stagger is a number rather than a value in the script.
- remove_circle Deprecated The per-module icon colour fields. They still work and they still win over the theme setting. They are removed at the next major release.
v0.6.0
Navigation, footer and the blog
The parts of a site that sit on every page.
- add_circle New Navigation Pro, with a mega menu, a docked variant and a language switcher.
- add_circle New Footer Pro and a slim footer, both reading the same shell radius as the hero and the CTA band.
- add_circle New Blog listing and blog post templates, with a listing hero, a post header and a recent posts module.
- add_circle New Input, checkbox and radio settings added to the theme, and the form markup reads them.
- build Fixed The mega menu dropdown ignored the container max width and ran wider than the page.
Send four things: the version you were on, the version you moved to, the URL of the page, and what you expected to see instead. That is enough to reproduce it without a call. A screenshot helps and is not required.
Send it while you are still in the file rather than after you have worked around it, because the workaround usually hides the part we need.
Usually yes, and from your own portal rather than from us. HubSpot keeps a version history for every template and module file. Open the file in the design manager, look at previous versions, and restore the one from before the update. Do that before you rewrite the change by hand.
Every entry between the version you are on and the version you are moving to, in order. If you skip two releases you have to read three entries, not one.
Yes. The update is applied from your portal, so the timing is yours. Nothing is taken out of a portal that has not updated, and a page built on an older version keeps rendering the way it did.
No. Page content lives on the page, not in the theme, so text and images a marketer set are untouched. What an update replaces is theme files. The place the two meet is a module field that was renamed, which is why a rename is a major release.
Every change you can see from a page or from the page editor. Work that produces identical markup and identical fields is not listed, because there is nothing for you to check.
Release notes
Did a release break a page?
Tell us the version you came from, the version you moved to, and where to look. We would rather have it while you are still in the file than read about it in a review.
A reply from whoever made the change not a queue
- bug_report Send both version numbers and the page URL
- history Your portal keeps a version history of every file an update replaced
- menu_book The docs carry the field and token names an entry refers to
If you are mid-update and unsure, ask before you apply it to the live portal.