[Repo Assist] Experiment: View Transition API for smooth cross-document page transitions (issue #1077)

[github-actions]

🤖 This PR was created by Repo Assist, an automated AI assistant. Triggered by the /repo-assist command in issue #1077 by @nojaf.

Closes #1077

Summary

This is an experiment with the [View Transition API]((developer.mozilla.org/redacted) for cross-document page transitions on fsdocs-generated documentation sites.

What it does

Adds a @view-transition { navigation: auto; } block and named element annotations to fsdocs-default.css, enabling automatic animated transitions when users navigate between documentation pages.

The animation: the main #content area gently slides in from below (12px) while the previous content slides up and fades out. The header, left sidebar (#fsdocs-main-menu), and right "On this page" sidebar (#fsdocs-page-menu) update instantly without any animation, so they don't distract from the content transition.

Accessibility: prefers-reduced-motion: reduce disables all transitions by setting animation-duration: 0s.

Browser support

Browser	Support
Chrome 126+ (June 2024)	✅ Full cross-document VT
Safari 18.2+ (Dec 2024)	✅ Full cross-document VT
Firefox (as of early 2026)	⏳ Not yet; @view-transition is gracefully ignored
Older browsers	✅ CSS rule ignored, no degradation

Key CSS changes

`@view-transition` {
    navigation: auto;
}

#content {
    view-transition-name: fsdocs-content;
}

/* … header, #fsdocs-main-menu, #fsdocs-page-menu named for instant update … */

::view-transition-new(fsdocs-content) {
    animation: fsdocs-slide-in 200ms ease both;
}
::view-transition-old(fsdocs-content) {
    animation: fsdocs-slide-out 150ms ease both;
}

Design decisions

• Slide direction: vertical (Y-axis, 12px) rather than horizontal — feels more natural for docs content and avoids layout shifts on narrow viewports.
• No JS required: purely CSS, zero JavaScript changes.
• Minimal impact: only fsdocs-default.css is changed; the template is untouched.
• Named elements: naming header/sidebars lets them update instantly rather than crossfading, which looks cleaner since their content barely changes between pages.

Open questions for maintainers

• Is the slide direction / distance right? Could also use a simple fade (opacity only) for subtlety.
• Should this be an opt-in via a new CSS custom property (e.g. --fsdocs-view-transitions: auto)?
• Do the named view-transition identifiers (fsdocs-header, fsdocs-main-menu, etc.) conflict with anything users might set in their own _template.html?

Test Status

• ✅ Build: dotnet build FSharp.Formatting.sln — 1 pre-existing warning, 0 errors
• ✅ Tests: dotnet test tests/FSharp.ApiDocs.Tests/ — 87 passed, 4 skipped
• ✅ No Fantomas changes required (CSS file, not checked by Fantomas)

Generated by Repo Assist · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@346204513ecfa08b81566450d7d599556807389f

[nojaf]

@dsyme, chef's kiss right here 🥰