Repository navigation
refactor(site,docs): one home for the tokens, and a collection behind the blog - #51
Merged
Merged
Conversation
… the blog DESIGN.json's narrative rules say divergence between origins is a bug, and DESIGN.md §6 says docs and marketing consume one token set. Neither was true. The same hex values were declared twice under two naming schemes, the twelve woff2 declarations were written out twice with a third dead copy nobody linked, and the blog index was the only thing on the site that knew a post existed. packages/tokens now holds the 55 token values and the 12 @font-face rules. apps/site imports them; apps/docs maps them onto Starlight's --sl-* system instead of restating the hexes. Verified as a no-op rather than assumed: the site's resolved custom properties are unchanged, 55 for 55, and the docs HTML is byte-identical to main apart from the CSS filename hash. The hand-tuned docs light ramp stays local, because it is not a mirror of the dark one (its hairline and gray-5 steps differ, where dark collapses both onto Trace) and folding it in would either move pixels or invent tokens. Base.astro drops from 1041 lines to 345, its global block split into base/primitives/chrome. The closing CTA band had been written out four times byte for byte and is now one component; the code panel is another. Posts move to a content collection, so the index, the feed, the sitemap and llms.txt all render from one source rather than a hand-maintained list. The MDX migration was checked for faithfulness: rendered prose is byte-identical for one post and differs only by a dev comment that no longer ships for the other, and all 15 heading ids were preserved, so no deep link broke. A changelog page carries fold's own release notes, headline and bullet leads verbatim, each linking out to the full notes. The docs landing becomes a map under the three verbs the home page already uses, Federate/Govern/Operate, rather than a second hero, so the sidebar and table of contents stay visible. Its tables finally read as the ledgers the CSS comment has claimed for months: 12px muted headers, a hairline per row, no zebra. The header trades three disclosures for two, plus direct links to the docs and the repo. Three mega menus and no direct link is the generic-SaaS header PRODUCT.md lists as an anti-reference, and it had put this audience's two highest-intent destinations two interactions deep. Four dead controls turned up along the way and are fixed here: the blog's code panels rendered a copy button with no handler behind it, the share row's copy link had no handler anywhere in the repo, .chip was styled only inside .route-rail so a chip anywhere else came out unstyled, and the mobile menu's primary action collapsed to a 16px sliver whenever a panel was open, because the sheet's rows were flex-shrinkable. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018VbCAd3B4wuaifUTbH1s2T
blakebauman
added a commit
that referenced
this pull request
Aug 29, 2026
#51 moved every token value into packages/tokens, turned the blog into a content collection, and split the site's CSS into layers. CLAUDE.md still described the shape before that: a workspace of apps/* only, a site that was "plain Astro, static-only", posts as hand-written pages, and no mention of the package that now owns every colour. Records the four things a reader would otherwise have to rediscover: - packages/tokens is where a colour changes, and the docs light ramp is deliberately not in it - the site's CSS layers, and that primitives.css outranks a page's own <style is:global>, so a page-level override of a primitive loses silently - the three MDX traps this repo has already paid for: whitespace collapse in slotted children, markdown-parsing inside a multi-line JSX block, and smartypants rewriting authored quotes - changelog entries are curated verbatim from fold's CHANGELOG.md, so nobody writes release copy for the website Claude-Session: https://claude.ai/code/session_018VbCAd3B4wuaifUTbH1s2T Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
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.
Two rules the system already states and was not keeping:
The same hex values were declared twice under two naming schemes, the twelve
@font-facedeclarations were written out twice with a third dead copy nobody linked, and the blog index was the only thing on the site that knew a post existed.What changed
packages/tokensholds the 55 token values and the 12 font faces.apps/siteimports them;apps/docsmaps them onto Starlight's--sl-*system instead of restating hexes.Base.astro1041 → 345 lines, its global block split intobase/primitives/chrome. The closing CTA band had been written out four times byte for byte and is now one component; the code panel is another.Posts move to a content collection, so the index, feed, sitemap and
llms.txtall render from one source. New:/changelog/,/rss.xml,/llms.txt,sitemap-index.xml.The docs landing becomes a map under the three verbs the home page already uses (Federate / Govern / Operate) rather than a second hero, so the sidebar and TOC stay visible. Its tables finally read as the ledgers the CSS comment has claimed for months.
The header trades three disclosures for two, plus direct links to the docs and the repo. Three mega menus and no direct link is the generic-SaaS header
PRODUCT.mdlists as an anti-reference, and it had put this audience's two highest-intent destinations two interactions deep.Verified, not assumed
mainapart from the CSS filename hash. Both docs themes checked.CHANGELOG.md, each entry linking to the full release notes.Four dead controls fixed on the way
.chip.route-rail, so a chip anywhere else came out unstyledDeliberately not done
gray-5steps differ, where dark collapses both onto Trace); folding it in would either move pixels or invent tokens.public/_redirects. All 19 docs slugs are unchanged, so it would be an empty file.--sbw/.full-bleedmachinery.<main>has no width constraint here, so sections are already full-bleed by construction.docs.fold.runstill wears Starlight's header (no nav, no CTA), which diverges fromDESIGN.json's "identical on both origins". Pre-existing, and closing it means overriding Starlight'sHeader.Checks
pnpm -r build,pnpm -r typecheckandpnpm lintall pass atmain's baseline (one pre-existing warning, one info).🤖 Generated with Claude Code
https://claude.ai/code/session_018VbCAd3B4wuaifUTbH1s2T