# Behavioral acceptance for Docusaurus documentation portals

Use this gate when a request includes interactive behavior such as theme switching, section navigation, or local search. A successful build and Actions run prove compilation/publication only; they do not prove the requested behavior works.

## Requirement-to-proof matrix

Write the matrix before implementation and require one direct proof per request:

| Requirement | Source/config proof | Built-artifact proof | Browser proof |
|---|---|---|---|
| Light/dark mode | `disableSwitch: false`; separate light/dark tokens | both selectors present in compiled CSS | click toggle; verify `data-theme`, persisted theme, and computed colors all change |
| Dedicated section sidebars | separate docs-plugin instances, sidebar files, and `docSidebar` navbar items | each section route renders its own sidebar labels | open every top-menu section and inspect `Docs sidebar`; ensure unrelated section labels are absent |
| Local search | local-search dependency/theme configured; no hosted provider | generated search index contains representative terms from every docs instance | type a query, wait for loading to end, confirm a visible result, and open it |

Do not report completion until every requested row has a browser proof or an explicitly stated blocker.

## Multi-section sidebars

A differently named category inside one shared sidebar is not a dedicated sidebar. For top-level menu areas that must own navigation:

1. Keep one default docs instance for overview/global theme compatibility.
2. Add one `@docusaurus/plugin-content-docs` instance per section with a unique `id`, content `path`, `routeBasePath`, and `sidebarPath`.
3. Give each sidebar an independently named root, such as `projectsSidebar`.
4. Configure each navbar entry as `type: 'docSidebar'`, with both `docsPluginId` and `sidebarId`.
5. Give each section index `slug: /` relative to its plugin route.
6. Build and inspect every top-level route, not only the source configuration.

## Static local-search verification

Use `@easyops-cn/docusaurus-search-local` as a theme and include every docs route base in `docsRouteBasePath`. Search must remain static/browser-local, with no Algolia or hosted crawler credentials.

Prefer `hashed: 'filename'` on static hosting that redirects requests carrying query strings. With `hashed: true`, the theme fetches `search-index.json?_=HASH`; a host that redirects query-string asset requests can leave the search field indefinitely loading even though `search-index.json` exists. Filename hashing emits and fetches `search-index-HASH.json` directly.

Verification:

1. Assert exactly one `search-index*.json` exists in `build/`.
2. Inspect it for representative terms from overview and every docs plugin.
3. Serve the production build under the real configured `baseUrl`.
4. Type a representative query in the navbar.
5. Confirm loading ends and a visible result appears.
6. Open the result and verify its route.
7. After deployment, fetch the exact generated hashed index from the Pages backend and repeat term checks.

## Theme debugging

If the toggle exists but the appearance does not change, inspect hard-coded colors before changing Docusaurus configuration. Typical root causes are:

- `html, body` fixed to the dark background;
- navbar/sidebar/footer colors fixed with `!important`;
- custom homepage CSS modules defining only dark values;
- light and dark Prism themes configured identically.

Move component colors behind semantic variables. Define a complete light palette in `:root, [data-theme='light']` and dark overrides in `[data-theme='dark']`. For CSS modules, use `:global([data-theme='light']) .page` to override page-level tokens. Browser verification must compare computed colors, not only the `data-theme` attribute.

## Reporting discipline

Do not substitute these for behavioral acceptance:

- local TypeScript success;
- production-build success;
- successful CI;
- a deployed HTML marker;
- presence of the toggle/search input/sidebar container.

Those are supporting checks. Report the pipeline only after matching it to the intended commit SHA, and report the feature only after exercising it.