Repository navigation
README and docs site: content-first rework on the Canton Infrastructure Design System - #216
Merged
Merged
Conversation
Rework the README and the docs-site home page per review feedback on readability and presentation. README (497 → ~160 lines): plain title, one badge row, what-it-is in two sentences, real terminal output, install, a compact command table, short sections for the Web UI, observability, and internals, with links out to the docs for everything long-form. The release download charts and their data links are kept. Removes the decorative header block, emoji section headers, and marketing-style layout tables in favor of plain prose. Docs home: drop the splash template — the home page is now a regular documentation page (sidebar, table of contents) leading with the terminal session and a guide map instead of hero actions and icon cards. Hero and card CSS removed; fonts, accent scale, and code-block typography stay. Verified against the rendered site in light and dark; production build green (16 pages).
Fact-check fixes from review: Token standard: the CLI supports both generations, routed per instrument — reads and transfers work against CIP-0056 (Final) instruments such as Canton Coin on stable Splice, while creating new instruments uses Token Standard V2 (CIP-0112, approved but not yet final) and requires the alpha Splice build with the tokens-v2 profile. The README, tokens guide, FAQ, and the token-flow skill previously described the tooling as CIP-0112-only, which both hid the working CIP-0056 support and implied a finalized standard. All five places now carry the same per-generation wording, with links to the CIP documents. Service list: name what the default profile actually runs — Canton synchronizer and participant, the Splice validator and super-validator apps, and the three party wallets. The Scan explorer is not exposed as an endpoint in the default profile and is no longer claimed. Resource figures: attribute the requirements to the devkit's own preflight — at least 8 GB Docker memory (12 GB recommended) and 10 GB free disk — instead of unsourced figures (the previous 20 GB disk number did not match the enforced threshold). Skills lint passes; site rebuilt from the corrected docs (16 pages).
Restyle the site on a measured design system in the style of leading API documentation: white surfaces with hairline borders (#EEF1F5) and a near-black dark theme (#0E1013 / #25292D), a single blue accent (#0F7FFF) with 10%-alpha pill actives at 12px radius for sidebar and TOC current items, 30px/700/-0.75px page titles, 24px/600 section headings, 18px/28 article body, 14px UI text in an 18rem sidebar, and bordered 12px-radius code frames. Both themes are derived from the same token sheet; headings size from Starlight's --sl-text tokens so the scale applies everywhere, and the page-title override targets Starlight's actual h1#_top element. Fonts remain the self-hosted Inter Variable and JetBrains Mono Variable. Verified against the rendered site in light and dark; production build green (16 pages).
Replace the Inter/JetBrains Mono stand-ins with the exact faces from the reference design system, both freely licensed: - Switzer (Indian Type Foundry) for body and UI — distributed via Fontshare under the Fontshare Free Font License; variable normal + italic files vendored with FFL.txt. - Paper Mono (Paper Design) for code — SIL Open Font License; variable file vendored with OFL.txt from the upstream repository. Fonts are bundled by the build (hashed assets, no CDN), the Fontsource packages are removed, and Expressive Code's build-time font settings point at the new families. Verified in the rendered site: body and headings compute to Switzer, code frames to Paper Mono, and Switzer's glyph metrics match the reference measurement exactly.
Add the measured hover, press, and focus layer: - Sidebar and TOC items: 5% neutral hover wash with the text stepping toward heading color (rgba(80,83,87,.05)/#171A1E light, rgba(222,226,230,.05)/#CED1D5 dark — measured values), 150ms background/color transitions. - Press feedback: the accent pill (10% blue, 12px radius) appears under the pointer on :active — the same treatment the item keeps once it is the current page, so the click previews its result. - Search button: same hover wash and press pill. - Keyboard focus: 2px accent outline with 2px offset on links, buttons, and summaries. - Content links transition their hover darken; the mobile tap highlight is replaced by the pill treatment.
The dashboard-customization panels table overflowed its container: the unbreakable PromQL tokens forced the query column to 782px inside a 686px table, which pushed the table past the prose measure and starved the last column down to 113px — wrapping its text into ~10-line rows. overflow-wrap: anywhere on table code lowers the tokens' min-content width, so auto table layout balances the columns again: the table fits the container exactly, queries wrap inside their chips, and row heights drop from 227px to content height. Verified on the dashboard and telemetry reference tables in the rendered site.
Restyle the site on the in-house design system (token sheet, effects, and docs UI kit from the Bitdynamics design package) in place of the previous externally-referenced look: - Cool ink neutrals (navy-cast gray ramp) with one decisive cobalt accent (#2946CE light / blue-400 dark); links cobalt with darker hover; sidebar current item is a cobalt-subtle rectangle at 2px radius; the TOC uses a 2px left rule with the cobalt rule on the current item. - Archivo (variable width and weight) replaces Switzer: body at 100% width, headings quietly extended at 104% with 600 maximum weight, and the brand's structural wide caps (118% width, letterspaced uppercase) for the wordmark and sidebar group labels. JetBrains Mono replaces Paper Mono for code and data. Both faces are vendored with their OFL license texts; the previous font files are removed. - Code blocks render on dark ink (#0B0F1A) in both themes with 4px radius and dark frame headers, via a single dark Expressive Code theme and matching frame overrides. - Radius language 2/4/8, hairline borders instead of shadows, 120ms damped motion, 2px cobalt focus outline in both themes. Verified against the rendered site in light and dark; production build green (16 pages, all four font files bundled). Note for dev: changing the Expressive Code theme requires clearing .astro caches, or stale pages reference the previous ec.*.css hash.
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.
Reworks the two entry points a new user hits first — the README and the docs site — for content and for look, based on team review that both needed a more distinctive, engineer-voice presentation.
Content
README rewritten in plain engineer voice: what the tool does, the command surface, and how to install — no marketing framing. Factual corrections along the way:
--profile tokens-v2). Both CIP links verified.Docs home (
website/src/content/docs/index.mdx) becomes a regular content-first page — terminal-first, no hero/splash/card grid. The same corrections applied todocs/tokens.md,docs/faq.md, and the token-flow skill doc.Design
The docs site adopts our design system (same package the Web UI now uses, see #215):
overflow-wrap: anywhereso reference tables keep balanced columnsNote: the branch history includes two interim design commits that the final design-system commit supersedes — squash-merge recommended, or review commit-by-commit starting from the last three.
Verification