The new navigation is almost here, and as many of you have noticed, it can break custom CSS. Here's how we handled it, in case it saves someone the month I spent going the long way.
I was tasked with rebuilding our custom CSS so the new nav would match production. Last year a developer rebuilt our homepage and sub-pages, and we didn't want to lose that look. My first approach was to rebuild it section by section in the new format, using AI tools to help. After about a month I'd nearly finished just the homepage.
Then it clicked: there had to be a simpler way. I used AI to compare our production CSS against the new-nav structure, and there was the answer. Much of our code scopes styling to the #doc-layout element Docebo uses today. In the new nav, that top-level element is replaced by app-layout — so every rule anchored to #doc-layout was matching nothing, which is why the layout fell apart.
The fix for the bulk of our code was to broaden those selectors to match both elements instead of rewriting them:
css
/* Before */
#doc-layout:has(.your-page-scope) .some-element { ... }
/* After */
:is(#doc-layout, app-layout):has(.your-page-scope) .some-element { ... }The :is(#doc-layout, app-layout) wrapper matches the old element and the new one, so the same rule works in both navs at the same specificity. Applying that across our top-level selectors solved about 99% of the breakage in one pass. From there it was just a few one-offs — the nav bar, some restyled titles — and within two days we had a near-exact replica.
Worth noting: this worked so cleanly because our CSS was already structured around that #doc-layout anchor. If yours is scoped differently — tied to widget IDs, or elements the new nav renames — you'll have more one-off work. But the takeaway holds: before rebuilding anything, use a diff (AI or otherwise) to compare your production CSS to the new-nav structure and see how the top-level elements differ. A small, targeted bridge may do most of the work.
Happy to answer questions if anyone's tackling the same migration — glad to share what worked (and what didn't).
