fix(fumadocs-ui): prevent sidebar focus ring clipping with overflow-clip

[yamcodes]

Summary

Fixes an issue where keyboard focus-visible rings on drill-in sidebar items were being truncated along their left and right edges.

Root Cause

[data-docs-sidebar-slide] used overflow: hidden, clipping the 4px outer box-shadow focus ring of full-width sidebar items along the left and right boundaries, despite having 23px of column gutter padding available outside the container.

Changes

• Changed overflow: hidden to overflow: clip; overflow-clip-margin: 0.5rem; on [data-docs-sidebar-slide] in packages/fumadocs-ui/css/theme.css and apps/www/app/docs/docs-chrome.css.
• Replaced overflow-hidden with overflow-clip in packages/fumadocs-ui/src/components/drill-in-sidebar.tsx.
• Audited other focusable surfaces across the site (mobile drawer, TOC links and footers, AI actions and popovers, code block tabs and copy buttons, homepage tabs) and verified they do not suffer from clipping.
• Added patch changeset for @arkenv/fumadocs-ui.

Verification

• Tested with Playwright visual inspection on desktop and mobile viewports. Focus rings now render with complete, uncut rounded corners on all 4 sides.
• Verified drill-in animations and slide transitions operate cleanly without leaking parked panels.
• pnpm check and pnpm typecheck pass with zero errors.

[changeset-bot]

🦋 Changeset detected

Latest commit: 195e2d6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@arkenv/fumadocs-ui	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@arkenv/agent-plugin

npm i https://pkg.pr.new/@arkenv/agent-plugin@1743

arkenv

npm i https://pkg.pr.new/arkenv@1743

@arkenv/build

npm i https://pkg.pr.new/@arkenv/build@1743

@arkenv/bun-plugin

npm i https://pkg.pr.new/@arkenv/bun-plugin@1743

@arkenv/core

npm i https://pkg.pr.new/@arkenv/core@1743

@arkenv/fumadocs-ui

npm i https://pkg.pr.new/@arkenv/fumadocs-ui@1743

@arkenv/nextjs

npm i https://pkg.pr.new/@arkenv/nextjs@1743

@arkenv/nuxt

npm i https://pkg.pr.new/@arkenv/nuxt@1743

@arkenv/standard

npm i https://pkg.pr.new/@arkenv/standard@1743

@arkenv/vite-plugin

npm i https://pkg.pr.new/@arkenv/vite-plugin@1743

commit: 195e2d6

[pullfrog]

Important

overflow-clip-margin is not supported in Safari/WebKit, so the focus-ring fix silently no-ops there — WebKit still clips the ring exactly as it did before.

Reviewed changes

• Drill-in pane overflow — the slide pane's overflow: hidden became overflow: clip plus overflow-clip-margin: 0.5rem in both packages/fumadocs-ui/css/theme.css and apps/www/app/docs/docs-chrome.css, and the inline Tailwind class in drill-in-sidebar.tsx flipped from overflow-hidden to overflow-clip, letting the 4px focus ring and 0.25rem pill radius paint into the column gutter without moving the rail insets.
• Changeset — adds a patch changeset for @arkenv/fumadocs-ui.

The mechanism is sound and matches the design intent already documented in the code comments (theme.css:440-459). The overflow: hidden → clip transition is also safe for the drill-in behavior: the pane's height is always set to the visible panel's scrollHeight, and the parked panel is translated ±120%, far beyond the 8px clip margin, so no leak regression. One concern is anchored inline below.

ℹ️ Nitpicks

• packages/fumadocs-ui/css/theme.css:419 still describes the pane as "the drill-in overflow-hidden pane" — that comment predates this change and is now stale.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

Important

The WebKit fallback fixes the ring clipping but misaligns the resting top-level Sections panel on Safari: the left/inset-inline offsets that restore the absolute drill panels act as a 4px translation on the position: relative root nav, so items jump sideways when drilling — contradicting the "exact 24px active-pill rail alignment" the fallback's own comment claims to preserve.

The prior Safari concern and the stale-comment nitpick from the last review are addressed by this commit — the @supports not (overflow-clip-margin: 0.5rem) fallback is the right mechanism, and the theme.css:419 comment now reads accurately. The geometry of the fallback itself has one flaw, anchored inline.

Reviewed changes

• WebKit overflow-clip-margin fallback — added @supports not (overflow-clip-margin: 0.5rem) blocks in both packages/fumadocs-ui/css/theme.css and apps/www/app/docs/docs-chrome.css that extend the slide pane's border box via margin-inline: -0.25rem, compensate with padding-inline: 0.25rem, and inset child navs, so the 4px ring paints inside the clip region when clip-margin is unavailable.
• Stale comment cleanup — the theme.css comment describing the drill-in pane as overflow-hidden now refers to the "slide pane" generically.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ Prior feedback fully addressed. The incremental change scopes the WebKit fallback's inset-inline compensation to [data-docs-sidebar-slide] > nav.absolute in both CSS files, so the resting position: relative root nav no longer absorbs the offset as a 4px translation — resting and drilled panels keep identical 24px rail alignment, which I re-verified against the current markup (drill-in-sidebar.tsx toggles the root nav between relative and absolute inset-x-0 top-0). No new issues found.

Reviewed changes

• Scoped fallback inset to absolute panels — the @supports not (overflow-clip-margin: 0.5rem) block in both packages/fumadocs-ui/css/theme.css and apps/www/app/docs/docs-chrome.css now matches > nav.absolute (dropping the physical left/right in favor of logical inset-inline), so only the absolutely-positioned drill panels are pulled back to the content box while the resting root nav stays untouched.
• Comment refresh — the fallback comment now describes the absolute-panel scoping, matching the "exact 24px active-pill rail alignment" claim.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}