Restyle the architecture docs site and animate the sidebar - #9527
Open
kube wants to merge 24 commits into
Open
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
github-actions
Bot
added
area/infra
kube
force-pushed
the
claude/petrinaut-arch-docs-styling-554323
branch
from
September 3, 2026 21:02
97106d2 to
770ac44
Compare
Restate Starlight's palette and type scale as one flat monochrome system, so the chrome reads as a single surface divided by hairlines and colour is left to the things that carry meaning. Collapsing the left panel now animates: the pane hides with visibility rather than display, the content inset derives from the pane width, and every box sized from it transitions on one curve. A drag or a held arrow key already tracks its input, so the handle marks the gesture and the transitions stand aside.
The borders framing the header, the sidebar and the on-this-page column are gone, leaving the sidebar's depth guide as the only rule drawn in the chrome, where it says how deep a row sits in the tree. The search field and the compare chips now read by fill rather than by an outline, one step off the page background in either theme.
kube
force-pushed
the
claude/petrinaut-arch-docs-styling-554323
branch
from
September 3, 2026 22:29
770ac44 to
6ca3ec5
Compare
Both rails and the collapse toggle sit at 70% until the pointer or keyboard focus reaches them, over 300ms, with the whole rail as the hover target. prefers-reduced-transparency turns the effect off. A 30px band under the header blurs and tints the content passing beneath it. backdrop-filter cannot ramp on its own, so the ramp is three stacked layers of increasing radius, each masked to a shorter band, and each filtering what the one beneath it produced. Blocks now sit 1.5rem apart with 2.25em above a section heading, and body copy is 17px: Starlight defines --sl-text-body but never applies it, so the size had to be set here.
The band ran both to 30px, which hid the blur: its strongest layers sit at the top, which is exactly where the tint is opaque. The tint keeps its 30px and the blur now runs to 60px, so below the tint there is a stretch where content is blurred and still visible. Radii go up with it, 4px to 16px.
The three layers now differ by height rather than by mask alone. All are anchored under the header and run to a different depth: 60px at 1px of blur, 40px at 2px, 20px at 4px. They overlap towards the header and thin out to one at the bottom, so the tallest and weakest is the layer that meets unblurred content. Each fades out over its own lower half, so a layer ending reads as a soft edge rather than a line across the page.
The band's construction moves to a shared class so the rail and the content column build it from one set of rules. The rail scrolls independently of the page, so its band keys off the pane's own scrollTop and appears only once rows have gone up behind the header. Shown unconditionally it would sit on the first row of an unscrolled rail and dim it for nothing.
Height and opacity both come off `--pnd-nav-progress`, which the header script writes from the rail's scrollTop, 0 to 1 over the first 60px. At rest the band has no height, so it stays off the first row of an unscrolled rail. Nothing eases it: the value already tracks the scroll frame by frame, and a transition would leave the band lagging the rows it covers. The ramp is now two layers rather than three, 60px at 1px of blur and 30px at 2px, in both places the band is used.
Both of them: the one above duplicated the header's, which is already gone, and the one below separated the bar from content scrolling beneath it, which the fade band now does by starting below the bar. The dropdown and the section name beside it also sat too close.
github-actions
Bot
added
area/deps
Starlight pulls that bar up by one to sit on the header's border, so it ends a pixel above where the two heights put it. The bar's own bottom border used to cover the difference; with that gone a sliver of unblurred content showed through.
Two authored diagrams colour a node for something other than a layer family: the device a batch runs on, and a case that falls back. Those two pairs were outside the themeable set, so in dark mode they kept a pale fill and took the inverted label colour on top of it. `d2` knocks its connections out from behind their labels with a mask built from a white rect that shows everything and black rects over each label. There white and black are not colours but show and hide, so theming them inverts the mask and every masked connection vanishes apart from the stubs behind its own labels. They are now left alone, and n7 is the page background rather than transparent, since it is also the paper those knockouts are drawn on.
`d2` draws the badge outside its palette, so it stayed a white disc with a near-black glyph whatever the host did. Matched on a pair of attributes rather than on `white` alone, and that pair is the point. The mask that knocks connections out from behind their labels is built from a white rect that shows everything and black rects over each label, where the two are not colours but show and hide. A mask holds only rects and none of them carry a stroke, so a path carrying both a fill and the badge's stroke cannot be one: across every diagram that is 623 discs and no mask element.
`cached backend + calibrations` and `release` sat on adjacent parallel edges between the same pair of nodes, and the long one ran under the short one by 44px. `d2` accepts a `near` on a connection but the elk layout ignores it, so the fix is in the text: the edge runs from the cache, which makes `cached` redundant, and `release (evict?)` now matches the wording on the node it points at.
kube
marked this pull request as ready for review
September 5, 2026 02:06
PR SummaryMedium Risk Overview Fixes diagram theming end-to-end: Reviewed by Cursor Bugbot for commit dbeef3e. Bugbot is set up for automated code reviews on this repo. Configure here. |
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved moderate issues affect accessibility, persistence behavior, content scope, and SVG processing coverage.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Restyles the Petrinaut architecture docs, animates sidebar behavior, adds Inter fonts, and enables theme-aware inline diagrams.
Changes:
- Introduces monochrome styling, updated typography, fades, and responsive animations.
- Improves sidebar resizing, persistence, and scroll effects.
- Adds themeable SVG diagrams and supporting documentation.
File summaries
| File | Description |
|---|---|
yarn.lock |
Resolves new Markdown and HAST dependencies. |
libs/@local/petrinaut-arch-docs/src/emit/d2.ts |
Adds themeable SVG processing. Moderate: Add focused tests for scoped-rule insertion and unchanged output without a D2 scope. |
libs/@local/petrinaut-arch-docs/src/cli.ts |
Supplies the font path during D2 rendering. |
libs/@local/petrinaut-arch-docs/README.md |
Documents diagram theming. Nit: Use an opaque host-background value for n7 to avoid lines crossing labels. |
libs/@local/petrinaut-arch-docs/fonts/OFL.txt |
Adds the Inter font license. |
libs/@local/petrinaut-arch-docs/content/diagrams/gpu-batch-lifecycle.d2 |
Moderate: Revert the semantic label edits or document and validate them as content changes. |
apps/petrinaut-docs/src/styles/chrome.css |
Implements the redesign and animations. Moderate: Raise idle opacity values to meet control and text contrast requirements. |
apps/petrinaut-docs/src/plugins/inline-diagrams.mjs |
Inlines generated SVG diagrams. |
apps/petrinaut-docs/src/components/SiteTitle.astro |
Adds fades and revised resize behavior. Moderate: Persist keyboard-resized width once on keyup or blur, not on every repeated keydown. |
apps/petrinaut-docs/src/components/Head.astro |
Emits and preloads Inter. |
apps/petrinaut-docs/README.md |
Documents styling, motion, diagrams, and fonts. |
apps/petrinaut-docs/package.json |
Adds Markdown-processing dependencies. |
apps/petrinaut-docs/astro.config.mjs |
Registers diagram inlining and Inter. |
Review details
- Files reviewed: 12/15 changed files
- Comments generated: 5
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 7c60f8a. Configure here.
A held arrow key repeats about thirty times a second and each repeat wrote to localStorage, which writes synchronously. The width a keyboard gesture reaches is now kept in hand and written when the gesture ends on keyup or blur, the same as a drag already did.
The rails and the header controls rest behind an opacity, so what a reader sees is their colour composited against the page, not the colour written in the stylesheet. Starlight's gray-3 arrives at 3.6:1 that way where body text owes 4.5:1, and at 50% the toggle's icon is 2.3:1 against the 3:1 a control owes. The fade is kept exactly as designed and the colour underneath it is raised instead, to the greys whose composite clears each threshold. The theme select moves to the rails' opacity: it is the one header control carrying a visible label, and at 50% over a white page no colour reaches 4.5:1, pure black included. Measured on the page rather than computed from the tokens: worst of 107 sidebar rows and 6 table-of-contents rows, both themes, 4.93:1 dark and 5.09:1 light for text, 3.68:1 and 3.19:1 for the icon.
The theming hook matches a format d2 owns: the scope class it puts on a drawing, and the colours it wrote. A change to either would stop every host override silently, with the diagrams still rendering in the palette they were drawn in. Tests cover the scoping, the drawn colour standing as each fallback, markup without a scope passing through, and the mask channels being left alone, which is the failure that erased every connection line the first time. The README offered n7 as transparent. It is the drawing's paper and also fills the rects that knock connections out from behind their labels, so a transparent one leaves every label struck through.
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.
Important
Appearance, plus the diagram renderer. No change to the architecture model or to page content, beyond two overlapping edge labels shortened on one diagram.
Summary
A new look for the architecture docs: Swiss, monochrome, and much quieter. One neutral ramp replaces Starlight's blues and greys, the chrome drops its dividers and steps back until it is pointed at, and everything that moves — the sidebar collapse, the resize, the bands under the header — now moves on one curve. Diagrams follow the page theme instead of staying white in the dark.
Before
9527-before.mp4
After
9527-after.mp4
Links
Changes
Appearance
prefers-reduced-transparencySidebar motion
visibility, so its rows travel with it and still leave the tab order at restprefers-reduced-motionResize handle
Diagrams
Test coverage
withThemeableColoursunit testslint:tscand the production buildHow to test