Lyndsay's User Guide Implementation

[SeanDuHare]

This is a large PR. Sean will be reviewing all of the content. Everything else I am requesting review on, but only after Sean please:)...sorry this is a learning experience and work in progress!!! THX!!!

User Guide Purpose
Adds a full in-app User Guide to BioFile Finder, accessible at /user-guide. The guide covers what BFF is, feature highlights, real-world use cases, getting started instructions, and supplementary resources.

Rationale
Users — particularly those new to BFF — lacked a discoverable, structured reference for how to use the app. External documentation (READMEs, wikis) is easily missed and hard to keep in sync with the app. Embedding the guide in the app ensures it travels with every deployment and can link directly to live data views.

Architectural decisions
Data-driven content
Page content is defined as structured data (content/*.tsx) rather than as routed page components. This keeps the rendering logic (DocPage.tsx) simple and consistent — one component handles all pages — and makes it easy to add or edit content without touching any component code.

Content split by nav section
The content directory is split into one file per nav section (about.tsx, getting-started.tsx, etc.) so that editing a single page only touches a focused, manageable file. All sections are merged in content/index.ts.

CSS Module + ug- convention*
Component-level styles use CSS Modules as the rest of the app does. Content styles (images, scroll tables, icons) use :global(.ug-*) classes scoped inside .sectionBody — necessary because content files are data, not components, and cannot import CSS modules directly. This is documented in DocPage.module.css. Extracting these into small wrapper components is a noted follow-up.

Routing
The guide uses React Router's /:sectionSlug/:pageSlug pattern, matching the two-level hierarchy of the sidebar nav. Unknown routes redirect to the overview page.

Other Notes

• ug-* global classes vs CSS Modules — content-in-data-files can't import CSS modules. The current approach works and is scoped, but is inconsistent with the rest of the app. A follow-up PR will extract ScrollTable and FeatureGrid wrapper components to fully align.
• PAGE_CONTENT and NAV are parallel structures — adding a new page requires an entry in both. There is no compile-time enforcement of this. A comment in content/index.ts documents the expectation.
• Heading sizes scoped to User Guide — H2 and H3 sizes in the User Guide differ from the global design system defaults. These are scoped to .root in DocPage.module.css with a TODO to revisit when the design system heading sizes are updated globally.
• Screenshots of the filter panel, file list, grouping hierarchy, sharing URL, and thumbnail grid are included in content/assets/ and rendered inline on the Feature Highlights page.
• Passed all unit tests

Optimized for:

• readability
• scalability
• accessibility
• reviewability
• consistency with existing patterns
• low cognitive overhead for future engineers

Avoided:

• unnecessary abstraction
• cleverness
• duplicated logic
• oversized components
• tightly coupled state
• giant PRs
• one-off styling patterns

Testing performed

• Manually tested all pages and nav links at localhost:9001/user-guide
• Verified mobile nav opens, closes on backdrop click and Escape key
• Verified prev/next pagination across all pages
• Verified horizontal scroll on comparison tables
• TypeScript compiles with no errors (tsc --noEmit)
• 562 core tests passing (npm run test:core)
• 52 web tests passing (npm run test:web)
• Known follow-ups
• Replace href="#" placeholder links with real URLs (dataset examples, publication links, video links)
• Extract ScrollTable and FeatureGrid as proper CSS Module components
• Wire headings in nav.ts to an in-page anchor TOC in the sidebar (data is already structured for this)