Skip to content

Lyndsay's User Guide Implementation#833

Open
lynwilhelm wants to merge 54 commits into
mainfrom
user-guide
Open

Lyndsay's User Guide Implementation#833
lynwilhelm wants to merge 54 commits into
mainfrom
user-guide

Conversation

@lynwilhelm

@lynwilhelm lynwilhelm commented Jun 15, 2026 •
edited
Loading

Copy link
Copy Markdown

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. This has been a learning experience for me as a UX designer contributing code — thanks for bearing with me!

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.

Notable content

  • Overview "BFF and related tools" comparison table, refined per reviewer feedback to position BFF as a companion to (not a replacement for) other data repositories.
  • Getting started pages for creating a metadata file, nesting metadata columns, describing columns, and file/metadata provenance.
  • Real-world use cases and supplementary resources (storage options, avoiding CORS errors).

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.

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)
  • 716 core tests passing, 2 pending (npm run test:core)
  • 52 web tests passing (npm run test:web)

Known follow-ups

  • 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)

Moved from #813 (fork branch) to the BFF repo so it can deploy to staging. Review history on #813 still applies.

lynwilhelm and others added 17 commits May 20, 2026 11:55
@lynwilhelm @claude
Add user guide feature with full content and routing
c88490f 
Adds a new User Guide section to the BFF web app including sidebar navigation, multi-page doc layout, and all initial content covering app overview, specifications, real-world use cases, getting started, metadata guidance, provenance, and storage options.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@lynwilhelm
Merge branch 'AllenInstitute:main' into user-guide
5ac1f8d
@lynwilhelm @claude
Remove Learn nav link, replace with User Guide
f2c8839 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@lynwilhelm
Merge remote-tracking branch 'fork/user-guide' into user-guide
d7db3df
@lynwilhelm @claude
Remove Learn page and all references
3585da9 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@lynwilhelm @claude
User guide content and layout updates
9ffe941 
- Add Feature highlights page with 8 sections
- Merge BFF comparison table into 'What makes BFF unique' section
- Add 2x2 feature card grid with responsive stacking below 769px
- Add flag icons to all placeholder links
- Comment out unpublished links (Nature Methods, social video, ISAS publication)
- Replace AMBIOM at ISAS lorem ipsum with content coming soon
- Update all page intros to use 'BioFile Finder (BFF)' on first mention
- Remove Learn nav link and page
- Remove How BFF works section (redundant)
- Add code generation placeholder section

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@lynwilhelm @claude
User guide content, styling, and image updates
72875c5 
- Add screenshots: querying-filters, querying-results, grouping-panel,
  grouping-hierarchy, sharing-url, thumbnails
- Restructure content: move rows/columns/required/optional sections to
  'Creating a dataset'; trim 'Metadata guidance' to recommendations,
  column descriptions, and provenance
- Reinstate BFF comparison table as its own nav section
- Restructure storage options into H2/H3 hierarchy
- Remove annotations and serverless sections from Feature highlights
- Rename 'Solution using BFF' headings to 'How BFF helps'
- Fix Vol-E spelling throughout
- Update global.css H2/H3 sizes and weights
- Fix web tsconfig.json (was empty, causing TS errors)
- Table styling: restore scroll shadow, add min-width for scrollable tables,
  font size updates across User Guide CSS
- Add PNG module declaration to custom.d.ts

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@lynwilhelm @claude
User guide pre-review cleanup and code quality improvements
81791e1 
- Split content.tsx (2579 lines) into per-section files under content/
- Extract PageSection and PageContent into content/types.ts
- Replace React.createElement heading pattern with typed HeadingTag variable
- Move inline styles to CSS classes (ug-image, ug-icon-sm, ug-icon-md, ug-feature-grid--wide)
- Add Escape key handler to mobile menu for accessibility
- Add tabIndex and aria-label to scrollable tables for keyboard accessibility
- Add TODO comments in place of commented-out JSX blocks
- Remove leftover empty intro: '' fields now that field is optional
- Revert global.css h2/h3 changes; scope heading sizes to User Guide via DocPage.module.css
- Document ug-* global class convention in DocPage.module.css
- Document headings field intent in nav.ts
- All 562 core and 52 web tests passing

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@lynwilhelm @claude
Restore global.css to origin/main; update scoped heading TODO comment
9a78916 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@lynwilhelm @claude
Refine user guide terminology and fix typos
3bfc943 
Use "metadata file" consistently in content (dropping "dataset file"),
while keeping "Creating a dataset metadata file" as the nav and page
title. Includes minor content, styling, and spelling fixes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@lynwilhelm @claude
User guide: section anchors, link wiring, supported-viewers cleanup
4488de9 
- Add scroll-to-hash so links to section headings (#id) scroll into view.
- Wire "Dataset examples" -> creating-a-dataset#spreadsheet-examples and
  remove its pending flag icon.
- Point "See the viewer comparison table" at
  supported-viewers#viewer-table.
- Remove <strong> tags from the Supported viewers page.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@lynwilhelm @claude
Link use-case overview table rows to their detail sections
83de7cc 
Wire the 5 cases that have long-form sections (Explore screening results,
Validate metadata, Inspect image subsets, Perform QC, Manage image
inventory) as same-page jump links. The remaining 3 rows have no detail
section yet and are left as plain text.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@lynwilhelm @claude
User guide: align slugs with page titles, icon weights, table styling
85dafbe 
- Rename page slugs to match evolved titles: features ->
  feature-highlights, use-cases-overview -> use-cases, creating-a-dataset
  -> creating-a-metadata-file (nav slug + content key + all links updated).
- Rename the Provenance nav title to "File & metadata provenance".
- Bold pagination and "open in new window" icons (font-weight 600).
- Restore <strong> on the Decision guide recommendations and the viewer
  comparison table's feature column; plus content copy tweaks.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@lynwilhelm @claude
User guide content: add REMBI section, fluorophore example, copy tweaks
7fab66b 
- Add a REMBI subsection (with external link to the Nature Methods 2021
  paper and a pending template-download link) above FoundingGIDE under
  Metadata guidance > Recommendations.
- Basic example table: replace the Color column with Fluorophore
  (EGFP, Alexa Fluor 405) and update the caption.
- Rename a real-world-scenarios persona heading to "Imaging scientists".

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@lynwilhelm @claude
Refine FoundingGIDE description wording
8b3b5f0 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@lynwilhelm @claude
Let user guide sidebar scroll independently on overflow
f07da3a 
Add overflow-y: auto to the sidebar so a tall nav scrolls within the
aside instead of spilling out and scrolling the whole page. The sidebar
still fills the viewport height below the header.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@lynwilhelm @claude
Let mobile user guide menu fill viewport height and scroll
9196858 
Raise the open mobile nav from a 60vh cap to fill the space below the
header + nav bar, scrolling internally when items overflow.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@lynwilhelm lynwilhelm mentioned this pull request Jun 15, 2026
Closed
@lynwilhelm lynwilhelm marked this pull request as ready for review June 29, 2026 22:34
lynwilhelm and others added 4 commits June 29, 2026 15:34
@lynwilhelm
Merge branch 'main' into user-guide
f9636fe
@lynwilhelm @claude
Use cases: hide Validate metadata; reframe Perform QC for non-coders
aaf4b09 
- Comment out the "Validate metadata" table row and detail section
  (preserved in source for easy restore).
- Rewrite "Perform QC on datasets" for a non-programmer audience: plain
  language, no-code framing, lab-manager example (instead of the data
  engineer / Parquet / S3 framing).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@lynwilhelm @claude
Refine "Who is BFF for" persona labels
58cc3cc 
Imaging scientists; Microscopy core facility managers & PIs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@lynwilhelm
Merge branch 'user-guide' of github.com:AllenInstitute/biofile-finder…
09c1058 
… into user-guide
@SeanDuHare SeanDuHare requested a review from Copilot June 30, 2026 02:23
Copilot AI reviewed Jun 30, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new in-app, data-driven User Guide experience under /user-guide, including routing, sidebar navigation, and page rendering, while deprecating the previous /learn page.

Changes:

  • Introduces UserGuide (layout + sidebar) and DocPage (page renderer) backed by structured content data (components/UserGuide/content/*).
  • Updates routing/navigation to support /user-guide/:groupSlug/:pageSlug, redirects legacy /learn to the new guide, and adds a NotFound page.
  • Adjusts web build/config ergonomics (webpack publicPath, package-level tsconfig, improved .d.ts, ESLint tsconfigRootDir) and updates footer styling.

Reviewed changes

Copilot reviewed 25 out of 32 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
packages/web/webpack/webpack.config.js Sets publicPath: "/" to support correct asset/chunk loading on deep links.
packages/web/tsconfig.json Adds package-level TS config extending the repo base config.
packages/web/src/index.tsx Adds User Guide routes, redirects legacy /learn, and wires NotFound.
packages/web/src/components/UserGuide/UserGuide.module.css Styles the User Guide shell (sidebar/content + mobile menu).
packages/web/src/components/UserGuide/slugify.ts Adds helper for generating URL-safe heading/section slugs.
packages/web/src/components/UserGuide/Sidebar.tsx Adds collapsible sidebar navigation for guide groups/pages.
packages/web/src/components/UserGuide/Sidebar.module.css Sidebar styling for sections and active page state.
packages/web/src/components/UserGuide/nav.ts Adds prev/next page computation for pagination.
packages/web/src/components/UserGuide/index.tsx Implements User Guide page container with mobile menu + hash scrolling.
packages/web/src/components/UserGuide/DocPage.tsx Renders guide page content sections + prev/next pagination.
packages/web/src/components/UserGuide/DocPage.module.css Doc page styling, including scoped ug-* global content styles.
packages/web/src/components/UserGuide/content/types.ts Defines typed slugs and content structure types.
packages/web/src/components/UserGuide/content/index.ts Aggregates per-section content into a single CONTENT nav tree.
packages/web/src/components/UserGuide/content/about.tsx Adds “About” content pages for the guide.
packages/web/src/components/UserGuide/content/app-information.tsx Adds “App information” content pages for the guide.
packages/web/src/components/UserGuide/content/getting-started.tsx Adds “Getting started” content pages + CSV example generators.
packages/web/src/components/UserGuide/content/real-world-use-cases.tsx Adds “Real-world use cases” content pages.
packages/web/src/components/UserGuide/content/other-resources.tsx Adds “Other resources” content pages.
packages/web/src/components/NotFound/NotFound.module.css Styles the new NotFound page.
packages/web/src/components/NotFound/index.tsx Adds a NotFound page with links back to Home/User Guide.
packages/web/src/components/Learn/Learn.module.css Removes legacy Learn page styles.
packages/web/src/components/Learn/index.tsx Removes legacy Learn page component (replaced by User Guide).
packages/web/src/components/Header/Menu.tsx Updates header navigation to point to the User Guide.
packages/web/src/components/Footer/Footer.module.css Makes footer fixed at bottom with background/z-index adjustments.
packages/web/custom.d.ts Improves typings for .png and adds typings for CSS imports.
.eslintrc.js Sets tsconfigRootDir for ESLint’s TS project parsing.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread packages/web/src/components/Header/Menu.tsx
Comment thread packages/web/src/components/UserGuide/DocPage.tsx
lynwilhelm and others added 3 commits June 30, 2026 10:25
@lynwilhelm @claude
Reword use-case table intro
b08b9d9 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@SeanDuHare
Potential fix for pull request finding
3ae2944 
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
@SeanDuHare
Merge branch 'main' into user-guide
ba8e6b4
@lynwilhelm lynwilhelm marked this pull request as draft June 30, 2026 19:04
lynwilhelm and others added 9 commits June 30, 2026 13:27
@lynwilhelm @claude
Overhaul BFF comparison table on Overview page
dc6f144 
- Rename heading to "BFF and related tools" and add interoperability
  preamble linking to the Cloud storage examples section
- Remove "Type" row; simplify "Cost" to Free (note deployment cost
  for OMERO/Quilt)
- Make "Deployment" row accurate per tool (hosted URL vs self-hosted)
- Simplify "Metadata Source" (user-supplied files vs managed database)
- Add "File Source" row contrasting BFF's in-place storage (local,
  network, cloud, or public repositories) with internal data stores
- Add CloudStorage/CloudStorageExamples SectionHeading enum values for
  stable cross-page anchor links

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@lynwilhelm
Merge branch 'user-guide' of github.com:AllenInstitute/biofile-finder…
e6f06d2 
… into user-guide
@lynwilhelm @claude
Revise comparison table preamble to frame BFF as a companion
6eec02e 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@SeanDuHare
Add section on nesting metadata
c366842
@SeanDuHare
Merge branch 'main' into user-guide
5ea53b2
@lynwilhelm @claude
Rename Creating page to "metadata file" and list File Path as a column
3829d97 
- Update page title (and nav/breadcrumb/H1) to "Creating a metadata file"
- Restructure Required columns to match Optional special columns format

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@lynwilhelm
Merge branch 'user-guide' of github.com:AllenInstitute/biofile-finder…
7c31c5a 
… into user-guide
@lynwilhelm @claude
Refine metadata file page headings and advanced capabilities section
87d084c 
- Rename "Spreadsheet (dataset) examples" to "Metadata file (table)
  examples" and tidy the enum key to MetadataFileExamples
- Update link text to "Metadata file examples" to match
- Convert the advanced features section to a "BFF supports:" lead-in
  with a bulleted list using the navigation names
- Move that section to the bottom of the page and rename it
  "Advanced capabilities (optional)"

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@lynwilhelm @claude
Fix typos on metadata file and setup overview pages
0301e34 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@lynwilhelm lynwilhelm marked this pull request as ready for review June 30, 2026 22:54
This was referenced Jul 6, 2026
Open
Open
@lynwilhelm

lynwilhelm commented Jul 6, 2026

Copy link
Copy Markdown
Author

Superseded by a stacked split to keep each PR reviewable (per the request to avoid large PRs):

Both target the user-guide-final integration branch, which merges to main once both land. All files are ported verbatim from this PR, so the review history here still applies. Keeping this open for reference until #863/#864 are approved.

@BrianWhitneyAI

BrianWhitneyAI commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

should this be closed?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments
@SeanDuHare SeanDuHare SeanDuHare approved these changes
@BrianWhitneyAI BrianWhitneyAI Awaiting requested review from BrianWhitneyAI BrianWhitneyAI is a code owner
@aswallace aswallace Awaiting requested review from aswallace aswallace is a code owner

At least 2 approving reviews are required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@lynwilhelm @BrianWhitneyAI @SeanDuHare @aswallace