WIP: Migrate pharos site to astro - #1380
Draft
brentswisher wants to merge 9 commits into
Draft
Conversation
Adds packages/pharos-site-astro, an Astro port of the Gatsby documentation site, as a candidate replacement for Gatsby. Both packages coexist for now so the two can be compared side by side; the Gatsby site is unchanged. This commit is a deliberate 1:1 copy of the Gatsby site's rendered output. It prioritizes parity over idiomatic Astro, so it does not yet follow Astro best practices — content is hand-written .astro rather than Markdown, and some Gatsby quirks are reproduced intentionally. The brand-asset zips under public/files/ are gitignored: nothing in the source or built HTML references them. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Records the follow-up work to make the Astro port idiomatic, now that the initial commit has landed as a 1:1 copy of the Gatsby output. Tiered by risk: Tier 1 is parity-safe and can start anytime, Tier 2 and 3 change rendered output and are gated on retiring pixel parity as the acceptance test. Written for an agent picking this up without prior context, so it includes the reasoning and verification commands rather than just task names. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The unanchored `lib/` rule targets compiled build output, but matches at any depth, so it also excluded packages/pharos-site-astro/src/lib/ — six hand-written source modules the site imports. They were never committed with the port. A fresh clone had no src/lib at all and could not build the package. Negate the rule for that one directory and add the missing sources. Build output under packages/*/lib/ stays ignored. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`fontSizeMap` was an array paired by index against a filtered token list, so adding, removing or reordering a line-height token would silently render every example row at the wrong font size — no error, no build failure, no visual cue. Key the map by token name and throw on an unmapped token, so the failure is loud rather than silent. Build output is byte-identical across all 63 pages. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The same Token / Value / Example <thead> was repeated in seven pages, the row loop was structurally identical in all eleven, and a near-identical `comment?: string` interface was redeclared in six. Add TokenRows.astro, which renders the shared header and row loop from a `rows` array. The example cell — the one genuine variation — is passed per row as an HTML string and emitted with set:html. Column widths are a prop because the pages disagree on them (40/30, 33/33/36, 40/40, and type-scale's four-column 25/20/25). Hoist the duplicated interfaces into tokenFormat.ts as CommentedToken, plus ScaleToken for the two pages where `comment` is required. Pages drop from 624 to 453 lines. Build output is byte-identical across all 63 pages, and all 11 token pages remain structurally identical to production (matching row counts, cell counts, and table dimensions). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
navigation.ts hardcodes the nav lists and Sidenav.astro derives hrefs from them via toSlug(), but nothing verified those slugs resolve. A typo shipped a link to a 404, and a new page left out of navigation.ts was reachable only by direct URL. Neither failed the build. Add assertNavigation.ts, which checks both directions and throws. Explicit ordering is preserved — it only compares sets, never derives order from the filesystem. Both failure modes were verified by introducing them deliberately. The page list is read with node:fs rather than import.meta.glob. A glob makes every matched page a dependency of the calling module, and since the sidenav renders on every page, that pulled each page's <style is:global> into one shared bundle and inlined all of them into all 63 pages. PAGES_DIR resolves from process.cwd() because the module is bundled into dist/.prerender before it runs. Two pre-existing orphans are listed as intentional rather than fixed: /content-style-guide/jstor-terms and /design-tokens/overview. Neither appears in the Gatsby sidenav either, so linking or deleting them is a content decision. Build output is byte-identical across all 63 pages. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Record what each item became, the verification that backs it (byte-identical build across 63 pages; 11 token pages structurally identical to production), and the import.meta.glob hazard so the next agent does not reintroduce it. Also note the .gitignore trap that left src/lib untracked, and restate that the parity gating question is still open — everything remaining is blocked on it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Astro server-renders the `<site-pharos-*>` markup, so the browser paints it before the module bundle registers those elements. Until registration an undefined custom element is an unknown tag, which computes to `display: inline` -- the page collapsed into a run of inline text (the sidenav laid out as a single ~4300px-wide line of run-together link labels) and then snapped into place when the bundle landed. The Gatsby site never showed this: it shipped an empty container div and built every element client-side, so there was no server-rendered markup to flash. The regression is a consequence of Astro's SSR output, not of the port's markup. Hide the elements with `visibility: hidden` while `:not(:defined)` matches, reserving each one's final `display` so nothing reflows when they appear. The rules clear themselves the instant `customElements.define` runs and need no JS to tear down. A CSS-animation failsafe reveals everything after 3s regardless. A JS-set flag was tried first and is wrong: it cannot fire in the case it guards against -- blocking the bundle left all 61 sidenav links hidden permanently. The animation runs off the document timeline, so it fires whether or not any script executes. Verified on the production build over throttled 3G, measuring painted frames with requestAnimationFrame rather than external polling: 401 painted-unstyled frames before, 0 after. Blocking the bundle now degrades to unstyled-but-readable instead of blank. All 63 pages remain byte-identical once asset hashes are normalised, and body height, nav width and table geometry are unchanged on six sampled routes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
20 pages stay .astro deliberately: the 11 design-token pages are data transforms whose body is a single TokenRows element, and the 6 brand-expression pages are image galleries (iconography.astro has no <p> tags and 15 <img>). Converting those would mean wrapping nearly every line in JSX. index, getting-started and 404 are bespoke. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
brentswisher
changed the title
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
1 participant
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.
🚧 This is a WIP 🚧
You can review what I've done and where it's at in MODERNIZATION.md
This change: (check at least one)
Is this a breaking change? (check one)
Is the: (complete all)
What does this change address?
Replaces the tooling used to generate pharos.jstor.org.
How does this change work?
It used astro instead
Additional context