[Enhancement]: Add targeted visual regression testing

Page or section

Site-wide presentation, shared components, and navigation on https://docs.stacklok.com.

What could be better?

Changes to shared theme styles, custom components, navigation, or responsive layouts can affect many pages. The current checks do not render a representative set of pages and detect unintended visual changes before they are merged.

We need targeted visual regression coverage that gives us confidence in the site's main layouts and custom components without trying to test every page.

Proposed improvement

Add an automated visual regression check for a small, documented set of representative pages and interactions. The initial coverage should include:

• The home page.
• The hidden /theme-preview page, which exercises common theme elements, styles, and custom enterprise constructs.
• One MCP server guide, such as /toolhive/guides-mcp/context7, including the expanded metadata details panel. The check should confirm that real metadata is rendered instead of a loading, missing-data, or error state.
• One navigation or index page from each major site section to exercise the applicable sidebar configuration and confirm that navigation loads correctly.
• Representative mobile viewports, including opening and using the mobile navigation and checking that the page remains usable without unintended overflow or obscured content.

Capture the representative pages in both light and dark mode. Exercise relevant interactive states, such as the MCP metadata details panel, sidebar navigation, and mobile menu, before comparing the rendered result with an approved baseline.

The check should run automatically when a pull request can affect the rendered site and provide an actionable visual diff when a comparison fails. Keep the page and viewport matrix small, stable, and documented so that contributors can understand and intentionally update approved baselines.

Acceptance criteria

• A documented representative page and viewport matrix covers the home page, theme preview, an MCP guide with loaded metadata, major navigation layouts, and mobile behavior.
• The representative pages are checked in both light and dark mode.
• Relevant interactive states are exercised before capture, including loaded and expanded MCP metadata and mobile navigation.
• The check detects unintended visual differences and makes the expected and actual results easy to review.
• Contributors can intentionally update the approved baseline through a documented workflow.
• The check runs automatically for relevant pull requests and is reliable enough to serve as a merge signal.

Additional context

This issue intentionally does not select a visual testing tool, baseline storage mechanism, browser matrix, or CI implementation. Those choices should be made during implementation based on maintainability, cost, and compatibility with the existing Docusaurus and Vercel workflows.

Exhaustive coverage of every documentation page is out of scope. This should remain a focused regression suite for shared layouts, components, themes, and responsive behavior.

Start by reviewing the documentation site's existing Docusaurus and Vercel workflows, then map the requested representative URLs: the home page, /theme-preview, /toolhive/guides-mcp/context7, and major section indexes. Define a small light/dark and mobile matrix with interactive states before choosing the implementation. Done means reliable pull-request checks, actionable diffs, and documented baseline updates.