docs: dropdown reference

[royendo]

requested: #8450

loom.com/share/a69eb3af381a44bbb9ba028c9f3a6b3a?from_recorder=1&focus_title=1

Some changes:

• no longer underlines the tab, it looked too crowded with the carrot, dropdown
• less tall div in navbar for each icon (caused the jittery movement when hovering from icon to dropdown)
• reset on the navbar css, had Claude rewrite it.
• kind of like the default algolia search ui better, but made it wider than default

Checklist:

• Covered by tests
• Ran it and it works as intended
• Reviewed the diff before requesting a review
• Checked for unhandled edge cases
• Linked the issues it closes
• Checked if the docs need to be updated. If so, create a separate Linear DOCS issue
• Intend to cherry-pick into the release branch
• I'm proud of this work!

[royendo]

Can you move the "Reference" tab changes into its own dedicated PR? This PR is huge and we'll need to polish the aesthetics of the dropdown before merge. For example:

The dropdown is jumping when I try to hover over the menu items
Hovering a menu item should apply a background color
The dropdown arrow looks a bit heavy and misaligned
The dropdown menu should be left-aligned with its anchor element

[royendo]

can take another look if we want to bring back the "taller" text padding but not sure if really needed.. 🤔

[ericpgreen2]

Overall Summary

Good progress consolidating Reference content into a dropdown. A few content and design items to address before this is ready.

---

Content & IA

1. docs/docusaurus.config.js (dropdown items)

Missing items and label change:

• Add "Time Syntax" (/reference/rill-iso-extensions) to the dropdown—it's reference content that's currently missing
• Rename "API" to "REST API" for clarity

---

Design

2. docs/src/css/_navbar.scss (active state styling)

Layout shift issue: The current font-weight: 600 for active items causes adjacent nav items to shift when clicking between them. Options:

Option	Implementation	Trade-off
Underline only	Remove bold, keep ::after underline	No shift, but you mentioned underline + caret felt noisy
Color only	Remove bold entirely, rely on color	Minimal, but may feel too subtle
Fixed width	Set explicit width on nav items	Prevents shift, but may look awkward
Pseudo-element trick	Add invisible bold text via ::before to reserve space	Preserves current look, no shift

3. docs/src/css/_navbar.scss (navbar and dropdown styling)

Design polish:

• Top nav padding: The top navbar items have inconsistent padding/widths on hover. Audit and standardize.
• Dropdown gap: Add margin-top: 4px to .dropdown__menu for breathing room between trigger and popover.
• Dropdown size: Menu items feel oversized. Consider tightening padding from 0.5rem 0.75rem to 0.375rem 0.75rem.
• Caret: The default Docusaurus down-arrow looks dated. Consider replacing with a Rill-style chevron.

---

Code Cleanup

4. docs/src/theme/Navbar/index.js (lines 54-101)

Two MutationObservers: Both useEffect hooks watch document.body with identical options. Consider consolidating into a single observer.

5. docs/src/css/_navbar.scss (various)

Minor cleanup:

• Lines 17-19: Duplicate comment ("Active navbar item" / "Active navbar link"). Remove the first.
• Line 107: Use 0.5px instead of .5px for consistency. Consider a CSS variable for the hardcoded #e5e7eb.
• Lines 227-230: Dead selector .mobile-nav-icon-links—the JS was removed, so this targets nothing.

---

Developed in collaboration with Claude Code

[royendo]

1. docs/docusaurus.config.js (dropdown items)
   This one is moving to build/ in docs: separating developer and user docs #8450 but theres a few link stuff that is already fixed there so will leave it alone on this branch

2-5

[royendo]

I think thats everything

[ericpgreen2]

Re-Review Summary

Good progress on the previous feedback—most items have been addressed. However, there are a few UX and behavior issues to resolve before this is ready.

---

Must Fix

1. Dropdown doesn't close when clicking an item

The dropdown stays open after clicking a menu item. Standard dropdown UX is: click item → navigate → dropdown closes.

This appears to be because Docusaurus dropdowns are hover-based, and the ::before pseudo-element (hover bridge) keeps the dropdown open if the mouse is still in that area after clicking.

Fix: Add logic to close the dropdown on navigation. Options:

• Listen for route changes via useLocation in the Navbar wrapper and programmatically close dropdowns
• Swizzle DropdownNavbarItem to add an onClick handler that closes the dropdown

2. Clicking REST API causes page flicker

Steps to reproduce:

1. Navigate to Project Files
2. Refresh the page
3. Click "REST API" in the dropdown

The page flickers/jumps before navigating. This may be related to the dropdown close issue or a navigation race condition.

3. Active state and hover styling should match main

• Underline feels thin: The current text-decoration-thickness: 1px with text-underline-offset: 14px appears thinner than the original styling on main. Consider matching the previous approach.
• Hover background too tall: The hover state background extends beyond what's on main. Audit and match the existing hover styling.
• Hover background has different x-padding for the different items.

---

Code Cleanup

4. docs/src/css/_navbar.scss — Duplicate declarations

Lines 46-47 and 122-124 have duplicate text-decoration-skip-ink: none;. Remove the duplicates.

5. docs/src/theme/Navbar/index.js — Document the setTimeout workaround

The multiple setTimeout calls (100ms, 500ms, 1000ms) at lines 159-161 are a timing workaround. Add a brief comment explaining why these delays are necessary for future maintainers.

---

Developed in collaboration with Claude Code

[royendo]

as you thought, had to swizzle the component. Did so in this commit and made CSS changes as req