Refine Primer website discovery, search, and responsive reading UX

[IEvangelist]

Description

Refine the Awesome GitHub Copilot website while preserving Primer Brand, existing resource artwork, and the green reading-progress animation. This follows an iterative desktop/mobile review of discovery, navigation, search, reading layouts, and embedded documentation.

Findings and fixes

Area	Finding	Change
Homepage discovery	Both main CTAs sent visitors to the repository, underplaying the Learning Hub.	Make Explore Learning Hub primary and View on GitHub secondary. The closing learning panel links to Watch on YouTube and Read the docs.
Artwork	Existing branded resource artwork was not reused consistently.	Share catalog icons across the six homepage cards, navigation, and search group headings. Use instance-specific SVG clipping IDs. Keep the desktop Learning Hub nav link text-only and put its icon on the primary hero CTA.
CTA contrast	Fixed gray secondary backgrounds did not follow Primer themes.	Use native Primer backgrounds and ensure the primary CTA icon follows its button foreground in both themes.
Card interactions	Reveals, wrapping labels, and text near rounded edges looked awkward.	Restore the staged outline, expansion/arrow movement, and label reveal; fade labels before collapse. Preserve the original 4px chevron-circle end inset while adding 24px start padding. Touch layouts show labels without hovering; reduced motion skips transitions.
Responsive cards	Narrow cards squeezed button labels onto multiple lines.	One column below 768px, two below 1280px, then three. Reduce nested padding at narrow breakpoints rather than shrink or truncate labels.
Page width	Homepage used a 1280px wide-screen frame while catalogs used 1296px.	Align header, hero, resource grid, and closing banner with the 1296px catalog frame at 1920px and above; preserve smaller-screen gutters.
Heading panels and footer	Heading backgrounds lacked texture; footer had only the wordmark.	Add the requested localized, theme-aware green grid/glow and subtle heading texture, disabled in forced colors. Add the official GitHub mark beside Primer's existing accessible footer wordmark/link.
Mobile navigation	Viewport-based menu width and padding did not align with the header, especially with scrollbars.	Anchor the overlay to actual header width, align its content, and retain scrolling on short screens. Reduce menu artwork to 16px.
External links	Local-looking menu routes silently redirected to GitHub.	Add outbound arrows to Hooks, Workflows, Tools, and mobile Contribute, without changing targets or forcing new tabs.
Terminology	Canvases and Extensions competed as catalog labels.	Use Extensions in navigation, discovery, breadcrumbs, metadata, and search. Retain canvas for the interactive panel concept; preserve URLs and install identifiers.
Search identity	Canonical content appeared alongside generated fallback/custom copies; resource types were ambiguous.	Enrich canonical HTML metadata, exclude duplicate generated copies, and merge by canonical identity without conflating different types, IDs, anchors, or genuine translations.
Search language	Unfiltered static English records were merged into translated results.	Scope static and Pagefind results to actual rendered document language before grouping/limits. English fallback pages search English; translated pages do not silently fall back to English without Pagefind.
Search presentation	Per-row type labels/icons added noise; headings, boundaries, and hover areas were weak.	Put branded icons beside stronger group headings, remove repeated row labels/icons, add solid group dividers and full-width hover/keyboard fills with padded text.
Search keyboard navigation	Self-review found End/arrow navigation could select a result below the visible panel.	Scroll keyboard-selected results into view with nearest alignment while retaining combobox focus; cover visible bounds and focus in every viewport/theme case.
Reading chrome	Large pinned headings consumed space; the initial compact transition bounced.	Share a compact header that reveals before the expanded hero leaves without changing document height. Keep a small right-aligned primary install action; the complete install menu remains in the expanded hero.
Reading accessibility and progress	Sticky offsets, focus, and progress completion differed between details and learning articles.	Share measured offsets, make hidden actions inert, restore heading focus on back-to-top, and disable compact pinning on narrow/short/enlarged-text layouts. Complete green progress/confetti when the article bottom becomes visible, not at a heading or after the footer.
Pagination	Previous/Next text sat above the icon/button center.	Share alignment across all six catalogs while preserving Primer current-page styling and reduced-motion-aware scroll/focus handoff to #catalog.
Embedded images	Repository-relative images and picture sources resolved against website/locale routes; some images touched surrounding prose.	Resolve images and srcset from explicit source document paths/revisions before sanitization. Apply 24px spacing to standalone documentation images only; preserve inline icons, badge rows, and component-owned galleries.

Investigated and intentionally preserved

• /plugin/pr-artifact-explorer/ is the plugin's short installation README; /extension/pr-artifact-explorer/ contains complete extension documentation and previews. Content was not missing; the existing “What's included” link connects them. They remain distinct pages and search results.
• Locale-prefixed English fallback pages intentionally search English based on content language, not the URL prefix.
• Search still caps at eight results overall and four per group; broad-query ranking is outside scope.
• Preserve requested green grid/progress effects, original card-arrow circle positioning, Primer controls, public routes, and install identifiers.
• External catalog entries still do not fetch README bodies. Future cached external documentation must provide actual source provenance rather than infer it from a local cache filename.

Self-review and cleanup

Shared reading-header/progress behavior, pagination alignment/focus, branded SVGs, and Markdown image handling replace repeated page-specific logic. Browser regression scripts share SITE_BASE_URL with Astro's default port rather than session-specific settings. The full-diff review identified and fixed offscreen keyboard search selection. No new dependencies or screenshot binaries are committed.

Validation

• Full npm run website:build succeeds, including README/marketplace/data generation; 1155 Astro pages and a Pagefind index of 1194 canonical pages from 6934 generated HTML files. Rebuilt successfully after the self-review fix.
• Search/Markdown-image unit and integration tests: 25 passing.
• Final fresh-production search browser suite: 18 passing, including selected-row visibility, locale scoping, canonical identity, grouping, and keyboard behavior.
• Reading/catalog regression: 36 scenarios, covering six catalogs, both themes, desktop/tablet/mobile, motion, short viewports, and enlarged text.
• Compact header regression: six representative detail/article routes in both themes, covering stable handoff, primary actions, article-end completion, and mobile behavior.
• Homepage checks: theme contrast, branded artwork, actual footer-mask pixels, staged CTA motion, forced colors, and real documentation image loading/spacing.
• Mobile navigation: 48 mobile/tablet scenarios plus desktop checks.
• Card/frame layouts: 34 cases from 320px to 2560px, with matching homepage/catalog frames and complete single-line CTA labels.
• Production axe audit: 15 routes across both themes, zero violations.
• Required bash eng/fix-line-endings.sh and git diff --check pass.

One initial production search run timed out on a Learning Hub result; the complete suite passed on rerun and again after the review fix, without weakening assertions. Existing external-plugin warnings about unpinned sources and non-SPDX license names remain outside scope.

Screenshot attachment status

Seven screenshots were captured from the production preview: desktop homepage in light/dark, mobile homepage, mobile resource menu, grouped search, compact .NET reading header, and embedded extension documentation image.

Attachment upload is blocked: GitHub's user-attachment upload endpoint returned HTTP 404 with both the active OAuth credential and the verified keyring credential. No broken image URLs are included here. The captured PNGs are retained in the originating session's files/screenshots/ directory for upload through GitHub's PR editor. Screenshots still need to be attached.

Type of Contribution

• Other: website UX, accessibility, documentation rendering, and regression coverage.

No new instructions, prompts, agents, plugins, skills, workflows, or extension packages are introduced.

Pull Request Checklist

• Followed the contribution guidelines for a website-only change.
• Production build completed and generated repository outputs are current.
• Targeting main directly in github/awesome-copilot.
• Preserved public routes and install identifiers.
• Added regression coverage and website documentation.
• No new paid-service dependency or resource submission is involved.
• Attach the captured screenshots (upload endpoint currently returns 404).

By submitting this pull request, I confirm that my contribution abides by the Code of Conduct and will be licensed under the MIT License.

[Copilot]

🔵 Needs a closer look

Three unresolved moderate findings affect accessibility, search scan limits, and multi-image spacing.

Pull request overview

Refines the Awesome GitHub Copilot website’s discovery, search, responsive navigation, reading UX, catalogs, and image handling while preserving existing routes and identifiers.

Changes:

• Adds locale-aware search, deduplication, keyboard navigation, and catalog pagination.
• Introduces shared reading headers, progress behavior, focus handling, and responsive visual refinements.
• Adds safe markdown image provenance, sanitization, and regression coverage.

Review findings:

• ReadingHeader.tsx — Moderate (1 vote): compact and expanded titles may both be exposed to assistive technology.
• pagefindSearch.ts — Moderate (1 vote): locale misses or deduplication can cause the full matching result set to be inspected.
• sanitize-html.ts — Moderate (1 vote): multi-image non-P containers may receive standalone-image margins.

File summaries

File	Reviewed change
website/src/styles/base.css	Shared image spacing and heading textures
website/src/pages/plugin/[id].astro	Skips README loading for external plugins
website/src/pages/extensions.astro	Updates Extensions catalog metadata
website/src/pages/extension/[id].astro	Adds repository image provenance
website/src/lib/sanitize-html.ts	Sanitizes and classifies markdown images
website/src/lib/markdown-images.ts	Resolves safe image and srcset URLs
website/src/lib/detail-page.ts	Passes image provenance to markdown rendering
website/src/integrations/pagefind-resources.ts	Builds canonical localized search records
website/src/components/brand/useCatalogPageFocus.ts	Shares catalog pagination focus behavior
website/src/components/brand/useAgentDetailScroll.ts	Shares reading pinning, progress, and scroll-spy logic
website/src/components/brand/TopNavSearch.tsx	Improves grouped localized keyboard search
website/src/components/brand/TopNav.tsx	Adds navigation icons and external arrows
website/src/components/brand/styles/TopNavSearch.module.css	Styles grouped scrollable search results
website/src/components/brand/styles/TopNav.module.css	Adjusts responsive menu sizing and alignment
website/src/components/brand/styles/styles.module.css	Refines homepage cards, CTA animation, and frames
website/src/components/brand/styles/skills.module.css	Applies shared pagination styling
website/src/components/brand/styles/reading-header.module.css	Defines compact reading header layout
website/src/components/brand/styles/plugins.module.css	Applies shared pagination styling
website/src/components/brand/styles/learning-hub-copilot-app.module.css	Updates article layout and progress visuals
website/src/components/brand/styles/instructions.module.css	Applies shared pagination styling
website/src/components/brand/styles/github-copilot-app.module.css	Updates article reading layout and progress
website/src/components/brand/styles/footer.module.css	Adds the GitHub footer mark
website/src/components/brand/styles/extensions.module.css	Applies shared pagination styling
website/src/components/brand/styles/dotnet-upgrade.module.css	Updates detail reading layout and progress
website/src/components/brand/styles/catalog-pagination.module.css	Aligns pagination controls
website/src/components/brand/styles/agents.module.css	Applies shared pagination styling
website/src/components/brand/SkillsIcon.tsx	Makes SVG clipping IDs instance-safe
website/src/components/brand/SkillsCatalog.tsx	Adds focus handling and heading texture
website/src/components/brand/SkillDetail.tsx	Adds compact install actions and image provenance
website/src/components/brand/searchIndex.ts	Adds canonical identity and locale filtering
website/src/components/brand/ReadingHeader.tsx	Adds the shared compact reading header
website/src/components/brand/PluginsCatalog.tsx	Shares catalog focus handling and texture
website/src/components/brand/PluginDetail.tsx	Adds compact install actions
website/src/components/brand/PageShell.tsx	Integrates responsive navigation positioning
website/src/components/brand/pagefindSearch.ts	Adapts localized Pagefind results
website/src/components/brand/navigation.ts	Adds navigation metadata and icons
website/src/components/brand/LearningHubIndex.tsx	Adds catalog focus handling and texture
website/src/components/brand/LearningHubIcon.tsx	Makes SVG clipping IDs instance-safe
website/src/components/brand/LearningArticleLayout.tsx	Integrates shared reading behavior
website/src/components/brand/LargeFooter.tsx	Applies footer mark styling
website/src/components/brand/InstructionsIcon.tsx	Extracts reusable instruction artwork
website/src/components/brand/InstructionsCatalog.tsx	Reuses artwork and pagination focus
website/src/components/brand/InstructionDetail.tsx	Adds compact install actions
website/src/components/brand/HomePage.tsx	Prioritizes Learning Hub and reuses artwork
website/src/components/brand/ExtensionsCatalog.tsx	Updates extension labeling and pagination focus
website/src/components/brand/ExtensionDetail.tsx	Adds compact install actions
website/src/components/brand/DetailChassis.tsx	Integrates shared reading headers and progress
website/src/components/brand/Custom.tsx	Anchors responsive navigation panels
website/src/components/brand/CookbookRecipe.tsx	Resolves images in file previews
website/src/components/brand/AgentsIcon.tsx	Extracts reusable agent artwork
website/src/components/brand/AgentsCatalog.tsx	Reuses artwork and pagination focus
website/src/components/brand/AgentDetail.tsx	Adds compact install actions
website/src/assets/github-mark.svg	Bundles the official GitHub mark
website/scripts/site-refinement-regression.mjs	Adds homepage and visual regression checks
website/scripts/search.test.mjs	Tests search indexing and locale behavior
website/scripts/search-browser.test.mjs	Tests production search interactions
website/scripts/resource-card-layout-regression.mjs	Tests responsive card layouts
website/scripts/reading-header-regression.mjs	Tests reading header behavior
website/scripts/reading-catalog-regression.mjs	Tests reading and catalog interactions
website/scripts/mobile-nav-regression.mjs	Tests responsive navigation
website/scripts/markdown-images.test.mjs	Tests image resolution and sanitization
website/README.md	Documents website conventions and checks

Review details

Suppressed comments (3)

website/src/components/brand/ReadingHeader.tsx:21

• When the handoff makes this slot visible, useAgentDetailHeroPin changes its aria-hidden to false, but the expanded hero's <h1> remains in the accessibility tree. Screen readers therefore encounter the same title twice (the compact div followed by the original heading), even though the compact copy is only a visual reading header. Keep one title exposed to assistive technology—e.g. synchronize the compact header as a visual duplicate and preserve the expanded heading as the sole accessible heading, while keeping the compact install action accessible.

    <div className={styles.slot} data-reading-header inert aria-hidden="true">
      <div className={clsx(styles.surface, className)}>
        <div className={styles.row}>
          <div className={styles.title} title={title}>{title}</div>

website/src/components/brand/pagefindSearch.ts:120

• The limit only bounds the returned items, not the Pagefind records inspected: when the current locale has no matching hits (or many results collapse during dedupe), this loop calls data() for every result in the response. A common query on a translated/fallback page can therefore load the entire index's matching records and defeat the MAX_PAGEFIND_HITS bound. Add a separate maximum scan budget (or use a provider-side language filter) and stop once that budget is exhausted, while retaining the result limit.
  website/src/lib/sanitize-html.ts:40
• For non-P containers the image-count check is skipped, so a raw HTML badge/gallery row such as <div><img ...><img ...></div> has no text nodes and marks every image as a block. The global rule then adds 24px margins between inline images, contrary to the image-only-block behavior; apply the same single-image/standalone-container check to these supported parent types or explicitly exclude multi-image rows.

• Files reviewed: 61/62 changed files
• Comments generated: 0
• Review effort level: Lite (auto)

Note

Copilot is running an experiment and ran this review at Lite.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[IEvangelist]

Live design-team preview

https://ievangelist.github.io/awesome-copilot/

The reviewed branch is deployed on the author's fork so the design team can explore the changes without running the site locally.

• Based on this PR's reviewed commit 0a7502c9.
• Fork-only deployment branch design-review-pages adds project-URL compatibility for Learning Hub links and social-preview images; the PR branch is unchanged.
• Verified live in desktop/light and mobile/dark layouts: homepage, catalogs, resource details, Learning Hub articles, cookbook, embedded images, social image, and grouped search.
• Successful Pages deployment.

This is a public design preview, not the production site. Search-engine crawling is discouraged with robots.txt.