Skip to content

refactor(site,docs): one home for the tokens, and a collection behind the blog - #51

Merged
blakebauman merged 1 commit into
mainfrom
refactor/shared-tokens-and-blog-collection
Aug 29, 2026
Merged

blakebauman merged 1 commit into
mainfrom
refactor/shared-tokens-and-blog-collection

Conversation

@blakebauman

Copy link
Copy Markdown
Member

Two rules the system already states and was not keeping:

Divergence between origins is a bug. — DESIGN.json, narrative
No per-origin theming; docs and marketing consume these tokens only. — DESIGN.md §6

The same hex values were declared twice under two naming schemes, the twelve @font-face 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.

What changed

packages/tokens holds the 55 token values and the 12 font faces. apps/site imports them; apps/docs maps them onto Starlight's --sl-* system instead of restating hexes.

Base.astro 1041 → 345 lines, 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, feed, sitemap and llms.txt all 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.md lists as an anti-reference, and it had put this audience's two highest-intent destinations two interactions deep.

Verified, not assumed

  • Token move is a no-op. Site resolved custom properties unchanged, 55 for 55. Docs HTML byte-identical to main apart from the CSS filename hash. Both docs themes checked.
  • MDX migration is faithful. Rendered prose byte-identical for one post; the other differs only by a dev comment that no longer ships. All 15 heading ids preserved, so no deep link broke, and post URLs are unchanged.
  • Changelog content is sourced, not written. Headline and bullet leads come verbatim from fold's own CHANGELOG.md, each entry linking to the full release notes.

Four dead controls fixed on the way

Blog code panels rendered a copy button with no handler behind it
Share row "Copy link" had no handler anywhere in the repo
.chip styled only inside .route-rail, so a chip anywhere else came out unstyled
Mobile menu CTA collapsed to a 16px sliver whenever a panel was open (shrinkable sheet rows)

Deliberately not done

  • The docs light ramp stays local. It is not a mirror of the dark one (its hairline and gray-5 steps differ, where dark collapses both onto Trace); folding it in would either move pixels or invent tokens.
  • No public/_redirects. All 19 docs slugs are unchanged, so it would be an empty file.
  • No --sbw / .full-bleed machinery. <main> has no width constraint here, so sections are already full-bleed by construction.
  • docs.fold.run still wears Starlight's header (no nav, no CTA), which diverges from DESIGN.json's "identical on both origins". Pre-existing, and closing it means overriding Starlight's Header.

Checks

pnpm -r build, pnpm -r typecheck and pnpm lint all pass at main's baseline (one pre-existing warning, one info).

🤖 Generated with Claude Code

https://claude.ai/code/session_018VbCAd3B4wuaifUTbH1s2T

… 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
blakebauman merged commit 482057f into main Aug 29, 2026
1 check passed
@blakebauman
blakebauman deleted the refactor/shared-tokens-and-blog-collection branch August 29, 2026 01:15
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant