Skip to content

docs: CLAUDE.md describes the repo the token split left behind - #52

Merged
blakebauman merged 1 commit into
mainfrom
docs/claude-md-after-token-split
Aug 29, 2026
Merged

blakebauman merged 1 commit into
mainfrom
docs/claude-md-after-token-split

Conversation

@blakebauman

Copy link
Copy Markdown
Member

#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, which matters because it is the first file a new contributor (or session) reads: 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.

What it now records

Repo map

  • workspace is apps/* + packages/*
  • packages/tokens gets its own entry: change a colour there, not in an app, and the docs light ramp is deliberately not in it (hand-tuned, not a mirror of dark)
  • apps/site is described as it now is: MDX + sitemap, with blog and changelog as content collections that the index, feed, sitemap and llms.txt all render from

Conventions — four things a reader would otherwise rediscover the hard way:

  1. The CSS layers, and the cascade gotcha: primitives.css outranks a page's own <style is:global>, so a page-level override of a primitive loses silently. (This one cost a debugging round during refactor(site,docs): one home for the tokens, and a collection behind the blog #51.)
  2. Where shared things live: Closing.astro, CodePanel.astro, nav.ts (LINKS + the header tree), seo.ts.
  3. Three MDX traps already paid for: Astro collapses whitespace in slotted children and MDX markdown-parses the children of a multi-line JSX block (hence CodePanel's code prop); { starts an expression, so a literal brace needs &#123; and a pinned heading id is written \{#some-id\}; smartypants is off because it rewrote authored straight quotes and got one pair backwards.
  4. Changelog provenance: entries are curated verbatim from fold's own CHANGELOG.md. Nobody writes release copy for the website.

Docs only, no code changes.

🤖 Generated with Claude Code

https://claude.ai/code/session_018VbCAd3B4wuaifUTbH1s2T

#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

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018VbCAd3B4wuaifUTbH1s2T
@blakebauman
blakebauman merged commit 7e8705d into main Aug 29, 2026
1 check passed
@blakebauman
blakebauman deleted the docs/claude-md-after-token-split branch August 29, 2026 01:33
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