Repository navigation
docs: migrate docs and blog to Primer with Squad branding, hub blog, and accessibility sweep - #2447
Open
IEvangelist wants to merge 27 commits into
Open
IEvangelist wants to merge 27 commits into
IEvangelist wants to merge 27 commits into
Conversation
Replace Tailwind and the custom pink/navy theme with @primer/css and @primer/primitives. Theme via data-color-mode, add an accessible search dialog and sidebar drawer, switch Shiki to high-contrast themes, and add axe-core WCAG A/AA, theme, keyboard and mobile e2e checks. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Layer a Squad brand skin over Primer tokens (rose/teal on navy ink, Mona Sans, framed dotted-rail layout, grid and grain texture, glows, spotlight cards, reading progress). Rebuild the landing page, add a filterable hub-style blog with featured cells and article layout, and polish docs with breadcrumbs, active TOC and pager. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Branded dialog with blurred backdrop, suggestions, section glyphs and paths, highlighted excerpts, arrow-key navigation and key hints. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Custom sort and page-size dropdowns, square checkbox filters, hub chips, and lighter 22px card titles modelled on awesome-copilot's learning hub. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…; hub pagination; remove footer gap Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
… root scrollbar contrast Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…ssibility sweep and contrast fixes Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…ktop layout Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…ma and test updates - Rewrite five docs/package-lock.json entries from an internal feed to registry.npmjs.org with sha512 integrity (release-lockfile-registry gate) - Reset search state synchronously on close/cancel so reopening quickly does not drop or keep typed text - Commit regenerated .astro collection schemas (blog hero/wave fields) - Relax docs-build table assertion for focusable scrollable tables Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
npm run screenshots captures every layout page on mobile, tablet and desktop in light and dark mode and writes an HTML gallery. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…cked files Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
IEvangelist
requested review from
bradygaster and
tamirdresher
as code owners
November 9, 2026 18:39
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Unescaped frontmatter titles in JSON-LD can allow script injection on the docs origin, alongside unresolved search, navigation, and accessibility regressions.
8 open issues
1 file not reviewed
docs/package-lock.json: Generated file
What changed in this PR
Migrates Squad’s Astro docs and blog from Tailwind to Primer, retaining Squad branding while adding richer navigation, search, and accessibility support.
Changes:
- Introduces Primer-based styling, brand tokens, Mona Sans typography, and persistent light/dark themes.
- Adds a filterable blog hub, hierarchical breadcrumbs, collapsible docs navigation, and keyboard-enabled search.
- Expands accessibility and interaction tests, adds markdown accessibility transforms, and provides a screenshot gallery CLI.
| File | Description |
|---|---|
test/docs-build.test.ts |
Allows attributes on rendered tables. |
docs/tests/sidebar.spec.mjs |
Tests section collapsing and current-page visibility. |
docs/tests/search.spec.mjs |
Updates search assertions for the redesigned dialog. |
docs/tests/search-keyboard.spec.mjs |
Covers keyboard navigation, clearing, reopening, and scroll locking. |
docs/tests/blog.spec.mjs |
Tests blog filtering, sorting, pagination, and article navigation. |
docs/tests/a11y.spec.mjs |
Adds accessibility, theme, mobile, and breadcrumb checks. |
docs/tests/a11y-sweep.spec.mjs |
Checks sampled pages and interactive states with axe. |
docs/src/styles/site.css |
Adds Primer-based site layout and content styles. |
docs/src/styles/global.css |
Removes the Tailwind theme and utilities. |
docs/src/styles/brand.css |
Adds Squad branding, visual effects, and component styling. |
docs/src/styles/blog.css |
Styles the blog hub, controls, cards, and articles. |
docs/src/plugins/rehype-a11y.mjs |
Adds markdown table, checkbox, and heading accessibility transforms. |
docs/src/pages/blog/index.astro |
Implements the searchable, filterable, paginated blog hub. |
docs/src/pages/blog/[...slug].astro |
Adds article metadata, breadcrumbs, and a table of contents. |
docs/src/pages/404.astro |
Migrates the error page to Primer styling. |
docs/src/lib/breadcrumbs.ts |
Derives docs breadcrumbs from navigation data. |
docs/src/lib/blog.ts |
Shares blog categorization and formatting helpers. |
docs/src/layouts/DocsLayout.astro |
Integrates breadcrumbs, Primer layout, and redesigned paging. |
docs/src/layouts/BaseLayout.astro |
Loads styles and fonts; updates theming and shared enhancements. |
docs/src/content.config.ts |
Adds optional blog hero and wave metadata. |
docs/src/components/ThemeToggle.astro |
Switches Primer color modes and updates accessible labels. |
docs/src/components/TableOfContents.astro |
Highlights the article section currently in view. |
docs/src/components/Sidebar.astro |
Adds collapsible sections and current-page centering. |
docs/src/components/Search.astro |
Implements native-dialog search with grouped results and keyboard controls. |
docs/src/components/Icon.astro |
Provides shared decorative Octicons. |
docs/src/components/Header.astro |
Updates responsive navigation and drawer controls. |
docs/src/components/Footer.astro |
Uses structured navigation columns and build metadata. |
docs/src/components/Breadcrumbs.astro |
Renders breadcrumb navigation and structured data. |
docs/scripts/capture-screenshots.mjs |
Captures responsive themed screenshots and generates a gallery. |
docs/README.md |
Documents Primer styling, accessibility tests, and screenshots. |
docs/package.json |
Replaces Tailwind dependencies and adds accessibility tooling. |
docs/astro.config.mjs |
Registers accessibility transforms and high-contrast code themes. |
docs/.gitignore |
Ignores screenshots and test results. |
docs/.astro/content.d.ts |
Refreshes the generated content configuration import path. |
docs/.astro/collections/blog.schema.json |
Reflects the new blog metadata fields. |
Review effort: Balanced (auto)
- Escape JSON-LD output so titles cannot close the script element - Hamburger breakpoint matches the menu it opens on non-docs pages - Search: ignore stale failures and drop stale options while typing - Dropdowns reset the previously open trigger state - Pagination keeps keyboard focus after rebuild - Result count live region stays in the accessibility tree on small screens - Only drop the blog lead blockquote when it duplicates the hero Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Collaborator
|
holy cow. thank you, @IEvangelist!!!! this is amazing. cc @tamirdresher |
bradygaster
approved these changes
Nov 9, 2026
… hover layout shift) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
🟠 Impact Analysis — PR #2447Risk tier: 🟠 HIGH 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (36 files)
tests (1 file)
|
Contributor
🏗️ Architectural Review
Automated architectural review — informational only. |
Contributor
🔒 Security Review
🔒 Security review: 1 info.
Automated security review — informational only. |
Contributor
🛫 PR Readiness Check
PR Scope: 🔧 Infrastructure
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 27 commits — consider squashing before review |
| ✅ | Not in draft | Ready for review |
| ❌ | Branch up to date | dev is 6 commit(s) ahead — rebase recommended |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | No source files changed — changeset not required |
| ✅ | Scope clean | No .squad/ or docs/proposals/ files |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | 1 active Copilot thread(s) resolved (7 outdated skipped) |
| ❌ | CI passing | 5 check(s) still running |
Files Changed (37 files, +3370 −2068)
| File | +/− |
|---|---|
docs/.astro/collections/blog.schema.json |
+9 −0 |
docs/.astro/content.d.ts |
+1 −1 |
docs/.gitignore |
+2 −0 |
docs/README.md |
+12 −2 |
docs/astro.config.mjs |
+4 −5 |
docs/package-lock.json |
+61 −777 |
docs/package.json |
+6 −3 |
docs/scripts/capture-screenshots.mjs |
+226 −0 |
docs/src/components/Breadcrumbs.astro |
+53 −0 |
docs/src/components/Footer.astro |
+66 −41 |
docs/src/components/Header.astro |
+52 −68 |
docs/src/components/Icon.astro |
+38 −0 |
docs/src/components/Search.astro |
+209 −112 |
docs/src/components/Sidebar.astro |
+43 −97 |
docs/src/components/TableOfContents.astro |
+63 −45 |
docs/src/components/ThemeToggle.astro |
+32 −14 |
docs/src/content.config.ts |
+2 −0 |
docs/src/layouts/BaseLayout.astro |
+38 −20 |
docs/src/layouts/DocsLayout.astro |
+27 −29 |
docs/src/lib/blog.ts |
+38 −0 |
docs/src/lib/breadcrumbs.ts |
+39 −0 |
docs/src/pages/404.astro |
+7 −7 |
docs/src/pages/blog/[...slug].astro |
+45 −19 |
docs/src/pages/blog/index.astro |
+373 −34 |
docs/src/pages/index.astro |
+185 −329 |
docs/src/plugins/rehype-a11y.mjs |
+59 −0 |
docs/src/styles/blog.css |
+237 −0 |
docs/src/styles/brand.css |
+597 −0 |
docs/src/styles/global.css |
+0 −389 |
docs/src/styles/site.css |
+316 −0 |
docs/tests/a11y-sweep.spec.mjs |
+87 −0 |
docs/tests/a11y.spec.mjs |
+227 −0 |
docs/tests/blog.spec.mjs |
+82 −0 |
docs/tests/search-keyboard.spec.mjs |
+79 −0 |
docs/tests/search.spec.mjs |
+15 −15 |
docs/tests/sidebar.spec.mjs |
+39 −60 |
test/docs-build.test.ts |
+1 −1 |
Total: +3370 −2068
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Migrates the docs and blog front end from Tailwind and a custom theme to Primer (
@primer/css+@primer/primitives), then layers a Squad brand skin (rose/teal on navy ink, Mona Sans, framed dotted-rail layout) on top of Primer tokens. Adds a hub-style filterable blog, a redesigned site search dialog, collapsible docs sidebar, hierarchical breadcrumbs, and a broad accessibility test sweep. Includes anpm run screenshotsCLI that captures every layout on mobile/tablet/desktop in light and dark mode.Why
The docs and blog used a fully custom Tailwind theme. Moving to Primer gives accessible components and tokens, light/dark via
data-color-mode, and a maintainable base, while keeping Squad's identity. Verified for functionality, usability and accessibility (axe WCAG 2.2 AA + best practices).How
data-color-mode(autoby default,localStorageoverride), no flash across view transitions. Brand overrides live indocs/src/styles/brand.css/site.css/blog.css, token-based only.<dialog>with blur backdrop, scroll lock, grouped results, arrow-key navigation, clear button, single-Esc close.rehype-a11yplugin).tests/a11y*.spec.mjsrun axe over a sample of built pages, interactive states and mobile.package-lock.jsonresolved entries to an internal feed (rewritten toregistry.npmjs.org+ sha512); search state reset on quick reopen; regenerateddocs/.astroschemas; relaxedtest/docs-build.test.tstable assertion for focusable tables.dev(lockfile conflict resolved by regenerating against the public registry)..changesetnot required; docs-only)PR Readiness Checklist
Branch & Commit
dev;devmerged in (merge commit, no force-push)docs/andtest/docs-build.test.ts(plus the merge ofdev)Build & Test
cd docs && npm run buildpasses (778 pages incl. generated API reference; Pagefind indexed)cd docs && npm testpasses: 13 build-output tests + 71 Playwright tests (requiresnpm run docs:apiandastro preview --port 4321)npx vitest run test/docs-build.test.ts test/docs-links.test.ts test/docs-site-location.test.ts test/release-lockfile-registry.test.tspasses (release-lockfile-registryhas a 5s timeout that can flake under CPU load when run in parallel; passes alone)npm run lint/lint:eslintnot run (no SDK/CLI changes)Changeset
packages/*/srcuntouched)Docs
docs/README.mdupdated (styling, accessibility tests, screenshot CLI)Exports
Visual review
Full gallery (76 captures: mobile 390, tablet 820, desktop 1440, light and dark) is generated locally:
cd docs && npm run build && npm run screenshotsthen opendocs/visual-review/index.html. Highlights:Landing page
Blog hub
Blog post and empty search state
Docs page (sidebar, breadcrumb, table of contents, pager)
Site search
Tablet and mobile
Review feedback addressed
Copilot review items fixed in aa54eb9: JSON-LD output is escaped (no
<can close the script element), the non-docs hamburger uses the breakpoint where its menu is visible, stale search failures and options are ignored or cleared while typing, previously open dropdown triggers reset, pagination keeps keyboard focus, the result-count live region stays in the accessibility tree on small screens, and the blog lead blockquote is only dropped when it duplicates the hero (the archive notice on the Wave 2 post is kept). Each has a regression test indocs/tests/a11y.spec.mjs.Known, pre-existing (not changed here)
#anchorsin docs content (e.g. relativefirst-sessionlink,/features/...links missing the site base). Out of scope; happy to fix in a follow-up.Breaking Changes
None. The look of the docs/blog changes intentionally; URLs, content and Pagefind selectors are unchanged.
Waivers
None.