feat: refine styling/navbar links and CSS in general

[arikorn]

• cleaner CSS
• make navbar links look like tabs.
• better styling for sidebar groups

Summary by CodeRabbit

• New Features

  • Icon-based navbar items for "Download Companion" and "Companion GitHub" rendered as HTML fragments with accessible titles.
  • Companion theming tokens added with dark-mode equivalents (active tab, mode toggle, group border, pulldown sidebar).

• Style

  • Navbar redesigned to a tab-like layout with refined spacing, hover/active states, glow effects, and overflow handling.
  • Improved pulldown/sidebar visuals, brand/close styles, category borders, caret/sublist indentation, and H2-related content indentation.

• Chores

  • Node.js engine requirement raised to >=22.0.

[Julusian]

Im not a fan of the boxing around the expandable sections in the sidebar.
Mt first thought was that it felt a bit noisey, then it was confusing why after going in a level only some had it, then I realised the significance.

I think the border on the right is being cut off in firefox for me, which wont be helping. And there is some shifting of text when expanding/collapsing things.

But im not sure about that part.

The header bar changes, I dont mind either way. It does appear to have lost some padding above the text, which feels off to me, it no longer feels even compared to padding beside the text.

[arikorn]

@Julusian wrote:

Im not a fan of the boxing around the expandable sections in the sidebar.

Yeah, I'm not surprised. After looking at how MS Word does things I realized that having the expand/collapse carets on the left makes a huge difference in readability (for me).

So the latest commits moves them to the left, and also does a much more subtle highlighting of the group in a way that should be both less confusing and has a cool "z-layered" effect for nested groups. (I also fixed the shifting text you mentioned.)

What do you think?

The header bar changes, I dont mind either way. It does appear to have lost some padding above the text, which feels off to me, it no longer feels even compared to padding beside the text.

OK. I think the second commit just now fixes it. It may need a bit of polish when the text wraps to two lines. I'm almost inclined to just turn off text-wrap for the edge case of the window being narrow but not so narrow that the header links disappear altogether. (Glad you're not opposed to this idea!)

[arikorn]

I wrote:

It may need a bit of polish...

OK, that should do it for the fine-tuning/polish. Let me know what you think about it all!

[Julusian]

Screencast.From.2026-02-07.22-23-34.webm

A couple of bugs I can see is:

• the hover state appears to span 1px below the bar
• the padding/vertical alignment above the text in the buttons changes at a seemily random point.

I suspect the second one is the width media-queries you have used not lining up for firefox (or linux?), I dont think using those will work reliably

I've been thinking that the threshold of when it breaks to the side nav should be adjusted because everything does crush and become a mess before that point already

And padding here is missing:

[arikorn]

Julian wrote:

A couple of bugs I can see is: (etc.)

I was afraid of that. Your system fonts are narrower than mine. Happily I finally had a brainstorm (brainwave for you?) of how to do it right, i.e. w/o media queries. Let me know what you think! (Check the commit description for details.)

I've been thinking that the threshold of when it breaks to the side nav should be adjusted because everything does crush and become a mess before that point already

Agreed. Related: I've been "irritated" by the "Download" and "GitHub" buttons which take up too much room and don't exactly look pretty. This commit replaces them with FontAwesome icons, which both looks slicker and frees up enough room that the tabs only word-wrap when User Guide is active (since it adds the version pulldown).

And padding here is missing: (version pulldown toggle button)

Funny... padding was always missing but I "revealed" it by adding hover behavior. The latest commit removes the hover behavior, so it's back to where it was.

[arikorn]

Latest screenshot:

(And of course the icons have tooltips on hover.)

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated the JSON import assertion in docusaurus.config.ts; replaced plain navbar labels with HTML/SVG fragments and metadata for Download and GitHub items; added companion-themed CSS variables, selectors and navbar/sidebar/tab rules in src/css/custom.css; bumped Node engine in package.json to >=22.0. (42 words)

Changes

Cohort / File(s)	Summary
Docusaurus config docusaurus.config.ts	Changed JSON import assertion syntax to with { type: 'json' }. Replaced navbar "Download" and "GitHub" entries with HTML fragments (inline SVG + text) and added className: 'fontawesome-container' plus title attributes.
Styling & theming src/css/custom.css	Added companion CSS custom properties (light/dark) and --ifm-navbar-height; introduced/modified navbar and sidebar selectors (.navbar, .theme-layout-navbar-left, .theme-layout-navbar-right, .navbar-sidebar, .navbar-sidebar__brand, .navbar-sidebar__close, etc.); updated hover/active rules to use new tokens; added sidebar category visuals, submenu indentation, markdown H2-adjacent indentation, and text color utilities.
Package manifest package.json	Bumped Node.js engine requirement from >=20.0 to >=22.0.

Poem

✨ An SVG slips into the navbar's song,
Tabs glow gentle, tidy, and strong.
Sidebars bloom with borders light,
Tokens shift from dark to bright.
Welcome tweaks — the docs feel right.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Merge Conflict Detection	⚠️ Warning	❌ Merge conflicts detected (9 files): ⚔️ .github/workflows/lint.yaml (content) ⚔️ .prettierignore (content) ⚔️ docusaurus.config.ts (content) ⚔️ for-developers/module-development/home.md (content) ⚔️ for-developers/module-development/local-modules.md (content) ⚔️ for-developers/module-development/module-config/typescript-config.md (content) ⚔️ for-developers/module-development/module-config/unit-testing.md (content) ⚔️ package.json (content) ⚔️ src/css/custom.css (content) These conflicts must be resolved before merging into main.	Resolve conflicts locally and push changes to this branch.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main changes: CSS refinements, navbar link styling improvements, and general styling adjustments across multiple files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

src/css/custom.css (2)

76-90: Impressive tab illusion technique — a couple of thoughts to consider.

The negative-margin + overflow-hidden approach for creating tab visuals is really creative! The self-referencing calc against --ifm-navbar-height means it auto-adjusts, which is great.

One small thing worth noting: this rule set has a lot of moving parts (--vertical-padding, --margin-bottom, the calc relationship between padding-bottom and margin-bottom). The comments do a great job explaining, but if you ever want to simplify further, you could consider combining the scoped custom properties into a single derived one. Totally optional — the current approach works and is well-documented.

Also, stylelint flags lines 79 and 85 for missing empty lines before declarations (declaration-empty-line-before), but those are just formatting nits — feel free to address or ignore depending on your project's lint config.

---

188-198: Small suggestion: consider removing the dead color: white declaration.

Line 192's color: white doesn't actually affect the SVG (as your comment notes!), and the real work is done by --ifm-color-emphasis-600. Having the dead declaration could confuse future readers despite the comment. Totally minor though — the comment does explain the situation well.

💡 Optional cleanup

 .navbar-sidebar__close {
 	padding: 0.5em;
 	border-radius: 0.5em;
-	color: white; /* doesn't do anything currently, because the SVG is hardcoded to: */
+	/* The SVG icon doesn't respond to `color`; it uses the variable below instead: */
 	--ifm-color-emphasis-600: white;

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (3)

src/css/custom.css (3)

78-99: Heads-up: the border-bottom color on the active tab is silently overridden by specificity.

The selector .theme-layout-navbar-left .navbar__link (specificity 0,2,0) on line 78 sets border-bottom: 2em solid transparent. The .navbar__link--active selector (specificity 0,1,0) on line 91 tries to override it with border-bottom: 2em solid var(--companion-active-tab-bg) — but it loses the specificity battle.

It happens to look correct because background-clip: border-box (the default) lets the background-color shine through the transparent border. So the visual result is fine today, but it's fragile — if someone later adds background-clip: padding-box or changes the background, the tab will break in a confusing way.

Consider bumping the active selector's specificity to make the intent explicit:

Suggested tweak

-.navbar__link--active {
+.theme-layout-navbar-left .navbar__link--active {
 	/* Make active link look a like a page-tab ... */
 	color: var(--companion-active-tab-color);
 	background-color: var(--companion-active-tab-bg);

---

215-218: Bold styling choice — the h2 ~ general sibling combinator indents broadly.

.markdown h2 ~ :not(h1, h2) will indent every sibling element after any h2 (including h3–h6, tables, blockquotes, details, etc.) with a 2rem left margin. This creates a nice visual hierarchy, but a couple of things to keep in mind:

• Tables and wide elements may look cramped with the extra left margin on narrower viewports.
• h3–h6 headings also get indented, which is presumably intentional for the hierarchical effect but might surprise future content authors.

If this is the desired behavior for the docs, looks good! Just wanted to make sure it's a deliberate choice rather than an overshoot. 🙂

---

207-213: These utility classes appear to be completely unused — safe to remove.

Verified across the entire codebase: .text-gray-50 and .text-gray-500 are defined only in this file and aren't referenced anywhere else (no HTML, JS, or MDX files use them). Your instinct to clean them up is spot on! Feel free to remove them along with the comment if you'd like to keep the stylesheet lean.

[arikorn]

for CodeRabbit: some of these items have been discussed previously in bitfocus/companion#3943 which is a copy of this code (but before CodeRabbit was enabled here). Summarized here.

Bold styling choice — the h2 ~ general sibling combinator indents broadly.

The styling is intentional and works fine.

These utility classes appear to be completely unused — safe to remove.

For @Julusian to confirm.

[arikorn]

Note for Julian: the vertical offset of the tab labels is "intentional" but if you don't like it, I can change it. Here's my commit comment:

The Rabbit's insight made me realize that the bottom-border wasn't necessary for the tab-look. The current version vertically shifts the tab-labels down, which makes them less tall and also visually separates them from the non-tab links in the navbar.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

src/css/custom.css (2)

108-120: Consider merging the duplicate .theme-layout-navbar-right .clean-btn:not(:hover) blocks

The selector .theme-layout-navbar-right .clean-btn:not(:hover) appears in two separate rule blocks (lines 111 and 118). I understand the split — the first block shares background-color with .navbar-sidebar__brand .clean-btn:not(:hover), while the second adds margin only for the right container. It works correctly, but two blocks with the same selector can be a maintenance pitfall since someone might later add a property to one block unaware of the other.

One option: keep the shared background-color rule as-is and fold the margin into it with a comment, or add a small note like /* see also rule at line N */ to cross-reference them.

Totally up to you — just a thought to help future readers! 🙂

---

167-204: Excellent DOM-structure documentation in the comments! 📝

The block comment at lines 168–176 explaining the DOM nesting and why the "not collapsed" selector is needed is really valuable. This kind of documentation makes CSS much more approachable for the next person.

Tiny nit on line 188: padding-right: 0em — the unit on zero values is unnecessary (0 is the same in all units). Completely cosmetic though!

Proposed nit

-	padding-right: 0em;
+	padding-right: 0;

[arikorn]

As noted in the latest commit message, I added a "tab" for the homepage so that one tab is always active. This makes the tab section look more distinct from the outset but at the expense of taking up a bit of space. (An alternative would be to move "Bitfocus Companion" from the logo to the tab label, but I'm not sure it's a good idea. I wonder though if it might be OK to remove the "Bitfocus" and put that on the homepage instead, or remove completely?)

---

(On home page; mouse hovering over "User Guide", window made as narrow as possible without word-wrap)

---

Narrow-mode sidebar:

---

Note on the CodeRabbit nitpick:

Caret scale at 0.6 — consider using transform: scale(0.6) for broader compatibility

transform: scale(0.6) is an error because it overrides the Docusaurus transform that rotates the caret. The scale: parameter, OTOH, correctly adds to the transform.

[Julusian]

I prefer the text vertically centered, I think it looks odd being lower, and especially as it doesnt align with the 'bitfocus companion' text.

I'm not sure that there is a benefit to having that home tab though

And there is hover behaviour on the 'bitfocus companion' text that I dont remember seeing, that I'm not sure I like. Again partly becuase of the vertical differeence, but also it doesnt surround the logo. Im not sure its necessary though

[arikorn]

I prefer the text vertically centered, I think it looks odd being lower, and especially as it doesnt align with the 'bitfocus companion' text.

I'm not sure that there is a benefit to having that home tab though

Well to some extent, these two go together: the home tab makes it visually clear that the vertical offset is a "property" of the tab group (i.e. by always having an active tab no matter what page you're on).

The vertical offset also makes the tabs shorter -- more like browser tabs in height, for example.

The home tab makes the tab-behavior more consistent by showing an active tab for each page. It could be named something other than home, of course.

If you're still against, just say the word and I'll recenter them vertically (and remove the home tab). So options:

1. Keep it as it is now (tabs look more tab like, consistent behavior when on home page)
2. Recenter tabs vertically for consistent vertical alignment; keep home page tab for tab/page consistency.
3. Recenter tabs vertically, remove home page tab.
4. (options 1 or 2 but rename "Home" -- either as I suggested in my previous comment or otherwise)

So just let me know your final choice. Thanks!

And there is hover behaviour on the 'bitfocus companion' text that I dont remember seeing, that I'm not sure I like. Again partly becuase of the vertical differeence, but also it doesnt surround the logo. Im not sure its necessary though

It surrounds the logo but is hard to see, probably because it lacks additional vertical padding. I added it for consistency with all other links on the navbar but can easily remove it. Especially if we keep the home tab. 😀.

[arikorn]

I may have found a good compromise: keep everything vertically aligned but make the navbar shorter so that tabs aren't so tall. Ideally it would be reduced to 3rem from 3.75 rem, but I'm pretty sure you'll consider it too narrow so, the commit uses 3.25 rem.

For this commit I renamed "Home" to "About" and put it at the end of the left-menu. This is just a suggestion: it can go away if you still don't like it. (And I removed the hover highlight on the logo/brand -- it's easy enough to reinstate too.)

Note that I also discovered that the buttons do fine with word-wrap disabled, but this is totally optional.

So the new options (not mutually exclusive) are:

1. This looks great. Keep it.
2. The tabs looks even better with --ifm-navbar-height: 3rem, go for it.
3. Leave the *&!% navbar height alone. Live with tall tabs...
4. Get rid of the "About" tab.
5. Rename the "About" tab to ___.
6. Move the "About" tab to the left, where it was.
7. Replace "About" with "[Bitfocus] Companion" and remove that text from the brand.
8. Restore hover-highlighting of the brand.
9. Restore word-wrap in buttons as the screen gets narrow.

My preference is probably 2 and I don't feel strongly about any of the rest -- I've already presented my reasons in favor of keeping the "About" (aka "Home") tab in my previous comment, but honestly, it's a small thing.

Current look (sidebar is unchanged from the previous commit):

---

(Hover over What's New)

[arikorn]

(oops, forgot an obvious option: 3. Leave the *&!% navbar height alone. Live with tall tabs... added in previous comment. but don't forget there are additional options unrelated to navbar height there... )

[Julusian]

Im happy with shorter nav. I think it was only that height because either thats the default, or the logo pushed it to that for some reason.

I prefer without a home or about tab

I suppose it did go around, but not all the way around, which makes that look odd to me.
But I do feel that it needs some hover style, but that could be simpler and just change the text color/opacity a bit?

[arikorn]

@coderabbitai resume

[coderabbitai]

✅ Actions performed

Reviews resumed.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docusaurus.config.ts (1)

9-9: ⚠️ Potential issue | 🟠 Major

Update import syntax to with — assert has been removed in Node.js v22 and Chrome 126+.

The assert keyword for import attributes has been deprecated and is now removed in modern environments. Node.js v22 and Chrome 126+ no longer support it and will throw a SyntaxError. Update the import to use the standardized with syntax:

import versions from './versions.json' with { type: 'json' }

This ensures compatibility with current and future runtimes.

🧹 Nitpick comments (4)

src/css/custom.css (4)

17-31: Nice theming setup! 👍

The custom properties for light/dark companion theming are well-organized and easy to follow. One small note: Stylelint is flagging unexpected empty lines before custom properties on lines 19, 25 (and similarly lines 43, 47 in the dark block). If you'd like a clean lint run, you could either remove those blank lines or adjust the Stylelint config to allow them — totally up to you and how strict you want to be with the linter.

---

63-88: Clever tab effect — one tiny readability nit on the calc expression.

The negative-margin trick to create faux-tabs is really neat! On line 76, calc(0rem - var(--ifm-navbar-height) / 2) works fine but 0rem as a way to negate is a bit unusual. A more conventional form would read slightly clearer:

💅 Optional cleanup

-	--margin-bottom: calc(0rem - var(--ifm-navbar-height) / 2); /* move the button down to create the tab-like effect */
+	--margin-bottom: calc(-1 * var(--ifm-navbar-height) / 2); /* move the button down to create the tab-like effect */

---

134-141: Nested CSS selectors — worth a quick browser-support sanity check.

CSS nesting (.fontawesome nested inside .theme-layout-navbar-right .navbar__link) is used here and in several other places (lines 147–161, 192–194, 221–223). This is native CSS nesting, which is well-supported in modern browsers but not in older ones. Since this is a documentation site likely targeting modern browsers, it's probably fine — just mentioning it in case you need to support older browsers.

---

236-242: These utility classes aren't referenced anywhere—safe to remove.

Good catch adding that comment! A quick check confirms that .text-gray-50 and .text-gray-500 aren't used anywhere in the codebase, so they can be safely pruned. Feel free to remove them to keep the stylesheet clean, unless you're planning to add them for future use (in which case a quick TODO comment would be helpful for the next person).

[arikorn]

@coderabbitai: Regarding the first nitpick, please apply @Julusian 's instructions to this repo. Quoted here:

@coderabbitai we don't care about issues from styelint, biome, or any other linters you might consider using. we have an explicit linter workflow already covering everything we care about, anything else is fighting the configuration we have explicitly defined

@coderabbitai: Regarding the third nitpick, please note that your "Nested CSS selectors — worth a quick browser-support sanity check." advice is incorrect as explained in the linked PR -- here is a link to my specific comment: Docusaurus processes nested CSS.

@coderabbitai: in general please crosslink all learnings from the companion repo with this repo and vice-versa

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@arikorn, thank you for these clarifications! I've noted all three points:

1. Linter issues: I'll skip flagging issues from stylelint, biome, or similar linters since you have an explicit linter workflow already configured.

2. Nested CSS: You're absolutely right—Docusaurus processes nested CSS during build, so browser support concerns don't apply here.

3. Cross-linking learnings: I'll ensure learnings from the bitfocus/companion repo are also applied to this bitfocus/website repo and vice versa going forward.

These have been added to my knowledge base for future reviews on both repositories!

---

✏️ Learnings added

Learnt from: arikorn
URL: https://github.com/bitfocus/website/pull/31

Timestamp: 2026-02-13T04:37:12.521Z
Learning: For the bitfocus/website repository: Do not flag issues from stylelint, biome, or any other linters. The repository has an explicit linter workflow already covering everything the maintainers care about.

---

Learnt from: arikorn
URL: https://github.com/bitfocus/website/pull/31

Timestamp: 2026-02-13T04:37:12.521Z
Learning: For the bitfocus/website repository: Nested CSS selectors do not require browser support warnings because Docusaurus processes and compiles nested CSS during the build process.

---

Learnt from: arikorn
URL: https://github.com/bitfocus/website/pull/31

Timestamp: 2026-02-13T04:37:12.521Z
Learning: Cross-link all learnings between the bitfocus/companion repository and the bitfocus/website repository. Learnings applicable to one repository should be applied to the other as well.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

src/css/custom.css (1)

55-67: Tab clipping approach is clever! One small a11y note.

The overflow: hidden on .theme-layout-navbar-left is a neat trick to avoid precise padding calculations. Just something to keep in mind: focus outlines (keyboard navigation rings) on tab links may get partially clipped at the container edges. If you ever notice truncated focus indicators during keyboard testing, overflow: clip with overflow-clip-margin could be a more targeted alternative — but honestly this is unlikely to be a problem in practice given how the tabs are positioned.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Search for usage of text-gray-50 and text-gray-500 in the codebase (excluding custom.css)
echo "=== Searching for text-gray-50 ==="
rg 'text-gray-50' --type-list | grep -q html && rg -n 'text-gray-50' --type html || echo "No matches found in HTML files"
echo ""
echo "=== Searching for text-gray-500 ==="
rg 'text-gray-500' --type-list | grep -q html && rg -n 'text-gray-500' --type html || echo "No matches found in HTML files"
echo ""
echo "=== Broader search across all file types except CSS ==="
rg -n 'text-gray-50|text-gray-500' --type-not css

Repository: bitfocus/website

Length of output: 1047

---

🏁 Script executed:

#!/bin/bash
# Simple direct search for these class names
echo "=== Searching for text-gray-50 usage ==="
rg 'text-gray-50' --type-not css 2>/dev/null | head -20 || echo "No matches found"

echo ""
echo "=== Searching for text-gray-500 usage ==="
rg 'text-gray-500' --type-not css 2>/dev/null | head -20 || echo "No matches found"

echo ""
echo "=== List key files in repository to understand structure ==="
git ls-files | grep -E '\.(html|jsx?|tsx?)$' | head -20

Repository: bitfocus/website

Length of output: 447

---

These utility classes aren't used anywhere in the codebase — safe to remove!

Great instinct questioning these! Our search confirms that .text-gray-50 and .text-gray-500 aren't referenced anywhere in the project, so removing them would be a nice lightweight cleanup of the stylesheet.

[arikorn]

This is @Julusian 's call; it's not my code.

[coderabbitai]

Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!

[arikorn]

Well... if you look closely, it does wrap completely around, but there's no padding around the circle-logo, so it's very hard to see. All of which suggests that a little padding will do the trick. But WAIT HOLD THE PRESSES! I just figured out how to make the logo+text (navbar__brand) act like a tab when nothing else is selected. I even prevent the behavior on the app-bundled docs (i.e. CSS remains compatible with companion)... So check it out, I hope you'll like it, but if not, I'll remove it and either add a bit of padding with the current-style link-highlighting, or just change opacity on hover.

And, of course, the "About" tab is gone now.

---

(hover over "for developers")

---

(hover over logo)

[Julusian]

I'm not keen on the tab styling for that.
I think either the hover box with some padding or some opacity on the text is best

[arikorn]

@coderabbitai resume

[coderabbitai]

✅ Actions performed

Reviews resumed.

[arikorn]

OK. I went with opacity change, mostly to differentiate it from the tabs.
I tested the CSS both here and in companion.
I think we've converged now!