Repository navigation
Put the docs contents list back in the right-hand rail - #261
Merged
Merged
Conversation
It was moved out of the rail and under the hero, and it should not have
been. The feedback that prompted the move was about the NARROW list not
collapsing into a dropdown; collapsing the narrow one was right, moving the
wide one was not, and the two got done together.
Starlight already does exactly what was wanted -- rail on desktop, collapsed
dropdown below -- so this is a revert rather than a redesign. The
MarkdownContent override existed only to render the list under the hero and
is gone; PageSidebar renders the rail again beside the dropdown it already
had; and 30-toc-under-hero.css keeps only the one unrelated rule it had
picked up, for the search dialog's offline message.
Measured at both ends. At 1790px the list sits at x=1425, right of a content
column ending at 1407, with the dropdown hidden. At 375px the dropdown is
back, collapsed, with the rail hidden. No horizontal overflow at either.
Not touched here, but found while looking: 12-docs-toc-responsive.css
contains three occurrences of a closing brace and the next selector on one
line (`}.right-sidebar {`). It is valid CSS and predates this change, but it
is why an automated pass over that file could not match its rules.
The site shipped without a walkthrough, so nothing had ever walked it. An independent acceptance pass said as much -- "a shipped public surface with no accepted UX contract... nothing to walk it against" -- and the next look at it by a person turned up fourteen defects in one sitting. That is what an unwalked surface looks like. Five journeys, each one something a person actually does: decide whether to install, get the command, learn how to use it, check what changed, and recover from a bad link. Each has a narrow-screen variant, because that is where this site has historically broken. Written by walking a served production build at 1440px and 375px. The states table covers the ones that are easy to ship broken because they are rare locally: no JavaScript, GitHub rate-limited, a changelog entry with no release behind it, the search index missing. Known gaps records what that walk found, with measurements rather than adjectives -- 29px of page margin on one side against 92px on the other, two header controls that differ in background and border while matching in size and radius. They are listed so the next pass reports what is new instead of rediscovering these. Also notes what is still missing: no design-direction.md covers this surface, so "does this look right" has no written answer for the site, which is the root of most of that list.
Contributor
|
Site preview: https://pr-261.netscli-site-preview.pages.dev Built from 296fc50 with Production is unaffected: netscli.com is served from GitHub Pages via |
fstubner
added a commit
that referenced
this pull request
Aug 28, 2026
…268) Seven of the open acceptance items, each measured before and after against a running build rather than eyeballed. Page padding was uneven. The frame is centred exactly -- 25/25 at 1280, 143/143 at 1920 -- so the asymmetry was inside the rails, not the frame: the section rail insets its text by a fluid 35-50px, the contents rail used a flat 16px. So the left text column started 84px from the viewport edge and the right one ended 40px from it. The contents rail now mirrors the section rail's insets exactly (37.86/37.86 at 1280, 50.4/50.4 at 1920) and widens from 13rem to 15rem so its text column does not pay for the padding. `--netscli-sidebar-rail-inset` moves to :root. It was declared twice on `.sidebar-content` alone, 2.1rem in 02 and 2.2rem in 14 -- the same token with drifted values, which is why the other rail could not read it. The left nav's hover highlight was inset from the active one. Only the current link was pulled onto the rail, so its box started at x=82.9 and every other link's at x=91.9, with text aligned at 107.5 throughout. The border was the intended difference; the box was not. All links share the geometry now, so only the border colour marks the current page. Headings were sized for a poster. Starlight's defaults put h1 at 42px and h2 at 35px against 16px body text -- an h2 more than twice the paragraph beside it and nearly the size of the h1 above it. A ~1.25 scale gives 34/26/21. Anchor links jumped and landed behind the header. The docs never loaded global.css, so `scroll-behavior` was `auto` and every heading had `scroll-margin-top: 0` under a 60px sticky header. Smooth now, with a reduced-motion opt-out, and headings clear the chrome by 80px. The theme selector had no focus indicator. `:focus-within` was grouped with `:hover`, so tabbing to it changed the border tint slightly and *removed* the background; the <select> has `appearance: none` and no border, so its own ring had nothing to draw. It gets a real 2px accent outline. Its dropdown rows were `rgba(17,17,17,.92)` -- the platform will not use a translucent colour for them, so they fell back to browser default white-on-black. Opaque values per theme. The search button and the menu toggle sit side by side in the narrow header and were painted differently -- one recessed, one flat. Both are `rgba(255,255,255,.035)` on the hairline token now, hover included. The breadcrumb chevrons sat low. Their line boxes are centred correctly and measured identical, but `›` is drawn mid-em-box while the words beside it sit on the baseline. A 1px optical lift. Renames 30-toc-under-hero.css, which had held nothing about the ToC since #261 reverted that experiment, to 30-scroll-and-search-offline.css and gives it the scroll rules. CSS shadowing budget 42 -> 26: the edits added five dead declarations and a prune pass removed 21. astro check 0 errors across 54 files, a11y 0 violations in both themes, no horizontal overflow at 500px or 1440px.
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.
The docs table of contents was moved out of the right-hand rail and rendered
under the page hero instead. That was a misreading of feedback about the
mobile layout: on narrow screens the contents legitimately collapse into a
dropdown, and the change applied that shape to every width. On desktop it
pushed the article down and left the rail empty.
This puts it back where it was and deletes the machinery that moved it.
MarkdownContent.astroexisted only to render the TOC under the hero. Itis removed and deregistered from
astro.config.mjs.PageSidebar.astrorenders the desktop rail again beside the existingmobile dropdown.
30-toc-under-hero.csskeeps only its unrelated search-offline rule.Measured on a served production build: at 1790px the contents rail sits at
x=1425, right of an article ending at 1407, with the dropdown hidden; at
375px the dropdown is present and the rail is not. No horizontal overflow at
either width.
astro check0 errors, 0 a11y violations, CSS budget 59.The second commit writes the site half of
ux-walkthrough.md, which did notexist. Nothing had ever walked the website, which is why a regression this
visible survived. It records five journeys (evaluate, install, learn, check
what changed, recover), their narrow-screen variants, a states table, and the
defects already measured and not yet fixed, so an acceptance pass reports
what is new rather than what is known.