Design language v2: Steps 1-2 foundation migration - #166
Merged
AkashGoenka merged 25 commits intoSep 6, 2026
Conversation
…ss and docs.css - Create site-astro/src/styles/tokens.css with NEW design language v2 tokens from DESIGN.md §2/§12 - Includes both new design values and legacy variables for backward compatibility during migration - Import tokens.css from every page that uses landing.css or docs.css - Remove duplicate :root declarations from landing.css and docs.css - Remove --frost/--ember redeclaration from body.essay-page in docs.css (line 306) - Set --wrap to 1120px (consolidated from inconsistent 1120px/1080px) - No visual change - consolidation only Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Add field background (body::before) with frost→ember gradient to landing.css and docs.css
- Add vertical variant for <860px per DESIGN.md §12
- Remove dot-grid backdrop.css import from all pages (12 pages updated)
- Add full-bleed section separator: section + section {border-top: 1px solid var(--line)}
- Add seam CSS to landing.css (signature vertical line at column-6 gutter)
- Update section padding to 84px (from 76px)
- Both pages now render the continuous field background
Build passes successfully.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A second specimen alongside /specimen/, built from the EpicInfographics composition rules rather than from taste. Declares its composition pattern (editorial spread, 4/8) in a comment, per that repo's prime rule. Adds five signature devices where DESIGN.md 5 had one: the drafting grid, the double-rule frame + registration crosses, Fig. numbering, dimension lines with knockout labels, and the title-block footer. Breaks 12 on exactly one point - radius 0 instead of 6/10px - which is the experiment. Palette, near-white prose and the frost/ember ramp are unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A repeating background pattern is the web's most common generated-site tell, whatever it is made of. composition.md's 'the background must participate' rule is written for a 1080px print canvas, where a drafting grid is paper texture; it does not survive the move to a scrolling page. Structure is now carried entirely by drawn, non-repeating linework - the frame, the rails, the section rules, the dimension lines. The rail moves from --line-soft to --line since it is now what holds the 4:8 split visible. The frost/ember ramp is the only field left. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The first cut invented a 4/8 split from a print composition rule instead of rendering the layout already settled in 4. This uses .split (5/7, sticky argument left, artifact right) and .plain (cols 1-8) as specified. The rail replaces 5's position:fixed seam: an absolute line inside the section, measured in the same grid units as the columns, so it needs no viewport arithmetic and cannot drift. Hidden on .plain, which has no 5/7 boundary to mark. Kept from the first cut: Fig. numbering, dimension lines, title block, radius 0. Dropped: the tiled grid and the 4/8 ratio. Fixes found by rendering: Astro collapses template newlines, so the terminal's white-space:pre ran the whole transcript onto one line - now one div per line; h1 at 58px wrapped to six lines in a 5-column measure and drove ~400px of dead space; ligatures off so --match is not an en dash. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Layout only. The copy is word-for-word identical to main (verified by diffing the rendered text of both) - the ask was a layout change, and changing the words at the same time would make it impossible to judge. Two columns, one shape for every section: the argument on the left, the artifact it is talking about on the right, at 5/7. The text column keeps a single left edge down the whole page and the claim stays sticky while a tall artifact scrolls past. Nothing is centred any more. Below 900px it collapses to one column. The background is now ONE page-scale ramp - frost on the left edge, ember on the right - defined once in backdrop.css, so docs and blog get it too. It replaces the per-section colour bands (.navsec/.phil/.faq on --ink-1, .nb on a warm ground with two radial blobs) and the hero's own glow; sections are now divided by a hairline over a continuous field. The 30px dot grid that used to live in backdrop.css is gone - a repeating pattern reads as templated, and it fought the ramp for the same layer. Revert this one commit to get the current site back. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Reverts 43401f3's layout entirely. The landing page is back to the version that was live: centred hero, single-column sections, the copy and structure untouched. The reason is measurement taken after that commit shipped. A DOM probe across six dev-tool landing pages at 1440px found that nextjs.org, vercel.com and railway.com use ZERO two-column grids; where a 2-col grid exists elsewhere it is ~0.50 or an extreme sidebar ratio, and nobody repeats an asymmetric split as a page spine. 5 of 6 centre some text. The 5/7 spine applied to every section, and "nothing is ever centred", were asserted in DESIGN.md 4/5 and never measured - 11 measured type and colour only. Two things from 43401f3 are KEPT because they were not the problem: - backdrop.css still carries the single page-wide frost-to-ember ramp, so home, docs and blog share one continuous field. - The per-section colour bands are still gone: .navsec/.phil/.faq no longer sit on --ink-1, .nb has lost its warm ground and two radial blobs, and .hero::before's glow is gone. Sections are divided by a hairline over that continuous field instead of by a change of colour. Also drops the macOS traffic-light dots from every terminal on the site - 39 spans across five pages, plus the now-dead .tl rules in both landing.css and docs.css. They are decoration borrowed from a screenshot of someone else's window chrome. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
4 previously specified a 5/7 split spine, a sticky argument column and "nothing is ever centered". None of it was measured - 11 measured type and colour only, and its credibility transferred to an axis it never touched. The spine was built (43401f3), looked wrong, and the DOM probe run afterwards contradicted it. 4 is now the measurement: six dev-tool landing pages at 1440px, the probe recorded inline. Half the class - nextjs.org, vercel.com, railway.com - uses zero two-column grids. Nobody repeats an asymmetric split as a spine. 5 of 6 centre some text. So: stacked full-width sections, 500px prose measure (the measured band is 429-550px / 48-79 chars), centring allowed, a 2-col grid only as a per-section decision and only at 50/50. 5's seam is retired. It was a hairline at the column-6 gutter, a device that only exists if there is a column-6 gutter, and it was never built. The signature device is now the field that actually shipped: one page-scale frost-to-ember ramp in backdrop.css, singular rather than tiled, replacing the per-section colour bands. Also reconciles 2, which still carried the two-radial-blob field CSS that 12 rejects by name, and clears the stale seam references in 1, 6, 9 and 12. The two specimen pages go with it. Both were built on 4's retired layout, so they now demonstrate a system the spec no longer describes; neither was ever approved. The spec is the artifact. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Replaces the JS-animated recall timeline with what 7 actually asked for: two Claude Code panels, fully rendered on load. No typing effect, no scroll triggers, no opacity:0 - verified 0 hidden elements on the page (the one hit is the nav dropdown, which is meant to be closed). It is screenshot-able and works with JS off. The two panels are the same repo on two different days: 1. COLD - the recall hook searches the notebook, finds nothing, and the agent falls through to the index. One `coldstart find`, one `coldstart gs`, then the answer. The Stop hook writes the note. 2. WARM - a different session asks the same thing. The note matches, arrives with the prompt, and the answer costs zero tool calls. All command output is real and unedited from this repo, elided with `… +N lines` per 7. The question is a real one - whether "edited together" is a dependency edge - and the answer is the true one: it comes from `git log --name-status -M` in deriveCoChange, not the graph. Chrome follows 7's table exactly (panel #1f1f1f, prompt chip #2e2e2e, output box #1a1a1a on #383838, IN/OUT gutter at 34px, green dot on tool calls, ember input bar). No traffic-light dots. 7's commentary rail is dropped with 4's split: the annotations are centred captions between turn groups instead, which keeps them outside the replica - the reason the rail existed - while collapsing properly on mobile. Verified at 1440px and 390px; no horizontal page overflow at either, the output boxes scroll inside themselves. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Three fixes, all measured. TEXT CONTRAST. The field commit changed what text sits on and the greys were never moved to compensate. Measured against the composited ground: body copy at #8b9ab2 fell from 6.94:1 to 5.28:1 on the frost side, and #7a8aa3 fell to 4.30:1 - BELOW the 4.5 AA floor for normal text. Both also carry an R-B spread near 40, which DESIGN.md 11 measured as the actual cause of the washed-out look: a blue-grey on a blue-black ground has too little hue separation from its own background. New ramp, near-neutral and measured on the worst ground: --text #eef2f8 13.4:1 R-B -10 --muted #c3c8d0 9.0:1 R-B -13 --faint #a3a9b2 6.4:1 R-B -15 ONE DEFINITION. The ramp now lives in backdrop.css and nowhere else. It was hand-copied into landing.css, docs.css and how.css and had already drifted: body.essay-page carried a fixed --prose at 12.8:1 with a comment saying "was #8b9ab2 at 6.9:1", so the blog was repaired and docs and the landing page were left behind. backdrop.css is imported last by every page shell, so its :root wins; the local copies are gone. DOCS ALIGNMENT. .docs was 1200px/24px padding while .nav-in and .wrap are 1120px/28px, so the docs content edge sat at 144px against the nav's 188px - the logo read as indented against the sidebar. Now both measure 188. Also: pages/live/index.astro never imported backdrop.css, so /live/ was the one page with no background field at all - exactly the failure the notebook note on this file predicts. Fixed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The panels asked "why does gs show files edited together" against
coldstart's own repo. That only demonstrates the tool to someone who
already uses it - a visitor who has never heard of coldstart cannot
tell whether the answer was hard to get.
Now it is "how does authentication work in this codebase?" on a
fictional Node/Express API. Session one has nothing written down and
goes looking: one find locates src/auth/session.ts, one gs shows who
calls createSession and verifySession and from which line, then it
answers - sessions in Redis, not JWTs, despite the variable being
called `token`. Session two, days later, asks "are we using JWTs for
login?" - different words, same subject - and the note arrives with the
prompt for zero tool calls, carrying the warning about the misleading
name that nobody had put in a comment.
The invented-repo trade is stated on the page, not hidden. A line under
the hero says the repo and its output are invented and that only the
command shapes and output format are real, because a terminal reads as
captured output unless the page says otherwise. DESIGN.md 7 is updated
to record the trade rather than keep its "real, unedited output" rule
that this now breaks.
Format stays static HTML. A GIF would lose selectable text, indexing,
and reader control, and would be several megabytes at legible width;
the case for one is off-site (README, npm, social) where the page's own
CSS cannot render, which is what 10 already scopes.
Note for the next editor: Astro compiles the whole template as a JS
template literal, so a `${...}` inside terminal output is interpolated
and fails the build with "token is not defined". HTML-entity escaping
does NOT help - the entity is decoded before the literal is emitted.
Write the output without the construct.
Verified 1440px and 390px: no horizontal overflow, no hidden content.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Correcting a claim the product does not make. The warm panel said
"Zero tool calls. No find, no gs, no reads." That is wrong about how
agents behave: an agent handed a note still opens the file to confirm
before it answers, and one that does not is not an agent you should
trust. What the note removes is the SEARCH - working out which file -
not the verification.
The warm session now shows what actually happens: the note arrives, the
agent says it will confirm, runs one Read against the exact file the
note named, and answers from what it just saw. The tally reads "One
read instead of a search" and says plainly that the checking still
happens. The section heading moves from "It already has the answer" to
"It starts at the right file", and the closing line now says neither
session is free - what changes is how much of the work goes into
finding the file rather than answering the question.
The same overclaim was on two other pages and is fixed there too:
index.astro said the next agent "gets it for free", live/index.astro
said a question is "answered for free from a note".
This is a better demo as well as a truer one. A developer who has
watched an agent work does not believe "zero tool calls", so the claim
was costing credibility with exactly the audience the page is for.
Also moves that panel's terminal output into frontmatter. Astro parses
`{...}` in markup as an expression, so `JSON.stringify({ uid: user.id })`
fails the build the same way `${...}` did - and real source output is
full of braces. Frontmatter strings are immune to both; the file now
carries a comment saying so.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The viewer was a generic blue-and-white document reader (--accent #1f4fd8, --ground #eaeef3) — it had never been brand at all, so a note opened from coldstartmcp.dev and the same note opened from `kb view` looked like two different products. Themed at the source rather than skinning the site copy, so the local `kb view` output changes too. Three calls, recorded in the file header: - It stays LIGHT-grounded. The site is dark, but this is a long-form reading surface for note prose, and dark is worse for that. Uniformity comes from hue, not from inverting the page. - `--file` is frost and `--flow` is ember: a file note is a fixed exact address, a flow note is a path through the code. The note graph now reads as the site's own two-temperature system. - The freshness scale stays a green/amber/red traffic light — that is status, not brand. `--changed` moved redder so it doesn't collide with the new ember `--flow`. The top bar is deliberately dark against the light body, carrying the site's frost→ember hairline. That is the one place the viewer looks like the site nav, and it costs the reading surface nothing. Contrast on --ground: ink 15.3, ink-soft 8.7, muted 5.0, faint 3.9. The old muted/faint measured 4.0 and 2.1 — both were below AA. Also corrects the file header, which claimed the template was generated and must not be hand-edited. There is no generator: scripts/kb-viewer/ holds only build-site-page.mjs, which bakes this template for the site. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The footer was one row of five links, duplicated in landing.css and docs.css. Meanwhile /demo/, /live/, /notebook/, /graph/, /vs/vector-rag, three how-it-works pages and three docs pages were reachable only from the nav dropdown — so the site's own IA had no second entry point, and no internal-linking surface at all. Now four columns (See it work / Understand it / Reference / Project) beside an identity block, over a base rule carrying the tagline and a frost/ember key. Sentence-case column headings, not tracked-out uppercase. Both duplicated copies were deleted; the rules live in one new file, styles/footer.css, reached through an @import at the top of backdrop.css. Every page that renders <Footer /> already imports backdrop.css — verified, the two sets match exactly — so this adds no per-page import for a new page to silently forget, which is how /live/ shipped without its backdrop. One trap worth naming: the columns were <nav> elements at first, and the global `nav{position:sticky;border-bottom:1px solid var(--line)}` rule from landing.css applied to them, boxing and pinning each column. They are plain divs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The page had a question, then four explanatory paragraphs per panel telling you what you were about to see — roughly 110 words of narration before the first terminal line. A caption track for something that should be self-evident. Both section leads and three of the four captions are gone. The one caption kept explains `fresh`, which is a term a reader cannot infer. The hero setup is one sentence, the closing two. Nothing about the simulated session changed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Measured first. On /docs/ the DOM had 16 frost elements and zero ember; on /blog/ effectively none either. The site had a two-colour system and was spending only one of them outside the home page. The rule applied: frost marks the navigational chrome — nav, kickers, active states, links. Ember marks the artifact the sentence is about — inline code, commands, file names, note fields. So: - Inline code in prose is ember on docs and blog (docs.css `p code`, `.essay-article code`) and in the home FAQ, matching what `.keynote code` in landing.css already did. /docs/ went 0 -> 18 warm elements, /docs/notebook/ to 30. - Blog kickers are temperature-coded by topic: Memory, Codebase memory, Codebase notes and Design are ember, the rest frost. - The /live/ notebook card kicker is ember. Both brand colours clear AA on the composited grounds: frost 7.07/7.42, ember 6.45/6.77 (frost side / ember side). Two things found on the way: - Residual hardcoded greys survived the text-ramp change — #8b9ab2 and #7a8aa3 in the nav dropdown, copy buttons and terminal title bars. Those are the washed-out blue-greys the ramp was meant to kill. Now on --faint. - /live/ still advertised "2 tool calls -> 0". That is the claim already corrected in prose on this page and on /demo/: a recalled note removes the search, not the reads. It now reads "a search, then one read". Blog cards drop the reading time — at three segments the longest kicker wrapped and pushed that card's title out of alignment with its row. The reading time is still on the post itself. Verified in the browser across 12 pages: no horizontal overflow at 1440 or 390, footer grid identical under both stylesheets, no console errors. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The demo page opened with the auth question set as its headline, then repeated it inside the first panel two screens later - so the page's own title was a line of the simulated session, and a reader arriving cold had to work out that the question was the example rather than the point. The hero now says what the page is: a walkthrough of what coldstart changes inside a session. The question stays where it belongs, in the panel. The standalone .disclaim paragraph is gone; the "example repo" honesty it carried is folded into the one sub line, because a terminal still reads as captured output unless the page says otherwise. Landing: the link into this page now names it the same way. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The section was one 130-word paragraph carrying 13 inline code chips, followed by two visually identical .flags tables. Scanning the frost mono key column read as six flags, but three of them (Upgrading, Removing, Codex hook trust) were lifecycle prose wearing a flag row. - Cut the wall paragraph to two sentences (13 chips -> 2). The per-client file mapping was a table pretending to be a clause; it is now a table. - Added h3 subsection heads so the two tables are labelled and can't be read as one list. Sans, not the Newsreader display face - an h3 here is a shelf label, not another headline. - Upgrade/uninstall commands moved into a terminal block, the section's existing idiom for commands, instead of long ember chips mid-sentence. - Codex hook trust is troubleshooting, not setup; it's a callout now. Co-Authored-By: Claude Opus 5 <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
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.
Summary
Expands the design language v2 migration into the full site experience. The branch now includes the foundational token/field work plus the subsequent landing page, docs, demo, footer, notebook viewer, and measured design updates.
What changed
site-astro/src/styles/tokens.cssand removed duplicated stylesheet definitions./demo/around a clearer, static walkthrough of coldstart sessions, with responsive layouts and no hidden-content/typing dependencies.DESIGN.mdwith measured layout and contrast findings; removed superseded specimen work and stale design claims.Verification
site/design-language-v2.This PR covers the current design-language v2 scope.