Debugging CSS in Squarespace: A Systematic Approach
You've added a CSS rule to change the navigation color. You test it in the editor. It looks perfect. You publish. You check the live site. It's not there.
This is Squarespace.
Debugging CSS here is different than debugging on a regular website. Squarespace templates come with their own stylesheets. They use LESS compilation. They generate dynamic class names. Something is always overriding your custom CSS, and figuring out what requires a specific workflow.
The good news: once you know the system, debugging is actually systematic. You follow a repeatable process and you'll find the problem every time.
Why Squarespace Debugging Is Different
On a normal website you control, there's usually one or two stylesheets. You know exactly what's there. In Squarespace, you're working with layers:
The template's base styles (in LESS, compiled to CSS). The site's global styles (from Design settings). Your Custom CSS. Code Injection. Per-page styles. Mobile breakpoint overrides. And occasionally, Squarespace pushes updates that change their selectors.
This layering means specificity works differently. A rule in the template's compiled stylesheet might have higher specificity than your Custom CSS, even if both are simple selectors. That's because Squarespace's styles often nest deeper in the HTML.
Also, some styles only apply in the editor. The editor adds extra CSS classes that don't exist on the live site, so a rule that looks perfect on your screen might do nothing when the site goes live.
Understanding this is half the battle.
The Debugging Workflow
When a CSS rule isn't working, follow this process. Every time. Don't skip steps.
Step 1: Check the live site, not the editor.
This sounds obvious but people skip it. Open the live site in a browser. Navigate to the element that's not behaving. Don't rely on the editor preview. The editor and live site are genuinely different in terms of what CSS gets applied.
Step 2: Open Chrome DevTools and select the element.
Right click on the element. Select "Inspect". DevTools opens with that element highlighted. You'll see the HTML and, on the right side, a panel showing all the CSS rules affecting that element.
Step 3: Find your rule in the Styles panel.
Look at the Styles panel on the right side of DevTools. It lists every CSS rule that applies to this element, ordered by specificity (most specific at the top).
Scan through and find the rule you wrote. Did you? Good. If you didn't, your selector is wrong. Skip to the selector debugging section below.
Step 4: Check if your rule is crossed out.
If your rule appears in the Styles panel but it's crossed out (with a strikethrough), another rule is overriding it. That's actually useful information. Look above your rule. What's overriding it?
Step 5: Check the cascade.
In the Styles panel, each rule shows its source. You'll see something like "custom-css:12" (your Custom CSS on line 12) or "site.css:456" (the template stylesheet on line 456). If a template rule is overriding your rule, you need to increase your specificity.
Step 6: Test a fix in DevTools before applying it.
This is crucial. You can edit CSS directly in DevTools and see changes in real time. Click on the CSS property (the color value, the padding amount, whatever) and change it. The element updates instantly. This lets you test before you commit the change to your site.
Step 7: Once the fix works in DevTools, apply it to your Custom CSS.
Don't rely on memory. Copy the exact rule from DevTools and paste it into the Custom CSS panel. Publish. Verify it works on the live site.
Common Overriding Patterns in Squarespace
You'll see the same specificity problems over and over. Here are the culprits and how to beat them:
Template styles targeting nested selectors.
Your rule: .header-nav a { color: red; }
The template's rule: .sqs-page-header .header-nav a { color: blue; }
The template wins because it has more selectors (higher specificity). Fix this by adding the parent to your rule:
.sqs-page-header .header-nav a {
color: red;
}Now they have equal specificity, and your Custom CSS (which loads after the template) wins.
Inline styles in the editor.
If the client has used the editor's color picker to style something, that generates inline styles. Inline styles beat CSS files. You need to either remove the inline style through the editor, or use !important to override it. For client sites, !important is sometimes the pragmatic choice:
.sqs-block-image {
max-width: 100% !important;
}Is this against best practices? Yes. Does it work reliably on Squarespace? Also yes. Use it strategically, not everywhere.
Mobile breakpoint overrides.
Squarespace has built-in mobile styles. If you change something on desktop and it breaks on mobile, look for a mobile breakpoint rule in the Styles panel. It'll show @media (max-width: 640px) or similar. You need to add your own mobile rule to override it:
@media (max-width: 640px) {
.header-nav {
flex-direction: column;
gap: 0.5rem;
}
}Put all your mobile rules at the bottom of your Custom CSS, after all the desktop rules. This ensures they load last and take priority.
The Computed Styles Tab
The Styles panel shows you what rules apply. The Computed tab shows you what actually got applied. This is useful when you want to know "what is the final color of this element?" without scrolling through a hundred rules.
Open DevTools, select an element, and click the "Computed" tab. It shows you every CSS property that's actually affecting the element, and which rule is responsible. If you need to know why something is the size it is, the Computed tab answers that question faster than scanning the Styles panel.
The Selector Problem
Sometimes your rule doesn't appear in the Styles panel at all. That means your selector is wrong and your rule isn't being applied.
Debug selectors by testing them in the Console. Open the Console tab in DevTools and type:
document.querySelectorAll('.header-nav a')This returns all elements that match that selector. If you get zero results, your selector is wrong. If you get results, the selector works but something else is the problem.
Common selector mistakes in Squarespace:
You're trying to select something that only exists in the editor. Test on the live site, not the editor preview.
You're using a selector that's too generic. .sqs-block { color: red; } will try to color every block on the site, which might not be what you want.
You're targeting a class that Squarespace generates dynamically. Some classes change based on editor selections or content. Try targeting by structure instead. For example, instead of .feature-item-123, target .page-section.features .sqs-block.
You're using a pseudo-element that doesn't apply. ::before and ::after work on most elements, but not on replaced elements like images.
Styles That Work in Editor but Not Live
The editor adds several CSS classes that don't exist on the live site. If you're testing in the editor and your styles look perfect, but they disappear when you publish, this is likely the issue.
Always test on the live site. The editor is a preview tool, not a validation tool.
If you need to test before publishing, use a staging domain if your host supports it, or make the change, publish, check it, and revert if it's wrong. This takes five minutes and saves hours of "why doesn't this work" confusion.
Styles Breaking on Mobile
You set a padding that looks great on desktop. On mobile, the text gets squeezed. This is usually because you didn't include mobile breakpoint rules.
A systematic approach: design on desktop, then test on mobile. When something breaks, add a mobile rule:
/* Desktop */
.hero-section {
padding: 4rem 2rem;
}
/* Mobile */
@media (max-width: 640px) {
.hero-section {
padding: 2rem 1rem;
}
}Always test at actual mobile widths using DevTools' device emulation. Don't just resize the browser. Device emulation accounts for viewport settings that real phones use.
Squarespace Updates Breaking Your Styles
Occasionally, Squarespace updates their template stylesheets. When this happens, selectors change or new rules get added. Styles that worked perfectly suddenly don't.
You can't prevent this, but you can prepare. If you're relying on a very specific CSS selector that feels fragile, add a comment noting the Squarespace version:
/*
Navigation underline effect
Targets .header-nav-item generated by Squarespace.
If this selector breaks, check if Squarespace updated
template selectors. Last tested with template v2.3.2
*/
.header-nav-item {
border-bottom: 2px solid transparent;
}If a client reports something looking wrong after you haven't touched it, check Squarespace's release notes. If they pushed a template update, that's probably the culprit.
Testing Before Committing
The DevTools workflow is your safety net. Always test a CSS change in DevTools first. Edit the property, see if it fixes the problem, then apply the exact same change to your Custom CSS and republish.
This takes 60 seconds and prevents "oops, that broke the site" moments.
For bigger changes, use a different approach. Make the change in Custom CSS but test it on a staging environment or a duplicate collection page before pushing it to production. Don't experiment on live client sites.
Building a Debugging Habit
The fastest way to get good at debugging is to do it systematically every time. Don't guess. Don't randomly add !important to see if it sticks. Open DevTools. Find the element. Check the cascade. Test the fix. Apply it.
After you've done this a few times, you'll recognize patterns. You'll know which Squarespace selectors are stable and which ones might change. You'll understand the cascade well enough to predict what will override what.
That's when debugging becomes fast. Not because you know all the answers upfront, but because you have a process that reliably finds them.
Related Reading
If you found this useful, these might be worth your time too:
Tools That Help
Squarehead Chrome Extension can help with the workflows discussed in this article.
Want to go deeper? The Squarehead Advanced Course covers these topics and more across 11 structured modules.
