Repository navigation
Docs: draw the docs with the Vortex design system - #11207
Conversation
Copy the system's tokens and its docs and focus sections into the theme, and rewrite the layout around them: a solid header with a search form, the toctree, the page on surface, and an On this page rail that folds above narrow pages. The docs follow the OS theme, run no script outside search, and load no web font. Signed-off-by: Will Manning <will@willmanning.io>
The theme extension checks each system file's sha256 header before it minifies the CSS, names each toctree branch for screen readers, and leaves the page title out of On this page. Remove the Pygments a11y styles and the Breathe reference hook that the new theme does not use. Signed-off-by: Will Manning <will@willmanning.io>
Copy the system's CSS again. A code block with no language is labelled Text, not Python. The mono stack names each platform's monospace face, so a reader without Geist Mono does not get Courier. The footer link is underlined. The landing wordmark keeps its 400px width. Signed-off-by: Will Manning <will@willmanning.io>
Keywords are Blue, functions purple, and types teal (the new syntax-type token). Strings, numbers, and constants are pink. Pygments' type classes (.nc, .ne, .nn, .kt) take syntax-type. Signed-off-by: Will Manning <will@willmanning.io>
|
Before and after screenshots. In each image, the left side is docs.vortex.dev now, and the right side is this PR. Search has JavaScript on. The other pages have JavaScript off. Home, 1440 px, Dark Python user guide, 1440 px, Dark Python user guide, 1440 px, Light Arrays concept, 1440 px, Light Python API, 1440 px, Dark Search, 1440 px, Dark Home, 390 px, Dark Python user guide, 390 px, Light Python API, 390 px, Dark Index, 390 px, Light |
Signatures go back to 14px with teal types, field labels are white 14px semibold, and the types in field lists lose their chip. Signed-off-by: Will Manning <will@willmanning.io>
|
API entries are easier to read on small screens again (1d58870). Signatures are 14px with teal types. Field labels such as Parameters are white, 14px, and semibold. Types in field lists have no chip. The Arrays and Factory Functions entry at 390px. The live site is on the left, this PR on the right:
Full page, 390px and 1440px:
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1d58870510
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
- A paragraph's line is now about 76 characters (54ch), down from about 95 (68ch). The design system's new measure token sets it. - Reading text wraps so that a paragraph does not end on one word. - The compatibility diagram takes the same rounded corners as the other two versioning diagrams. - The landing page's hidden title does not wrap, like the system's hidden text, and the theme's header comment says which values come from the tokens. - Re-sync the copies of the system's styles. They still named the dropped display face. Signed-off-by: Will Manning <will@willmanning.io>
|
Reading length, before (left) and after (right): the Arrays page in Dark and Light at 1440, the compatibility page in Light, and Arrays in Dark at 390.
🤖 Generated with Claude Code |
The footer's policy sentence left its last word alone on a line at desktop width. The system now balances the footer's text. Signed-off-by: Will Manning <will@willmanning.io>
Docutils writes the viewport tag for each page built from a source file. The search page, the index, and the module index have none, so a phone drew them at desktop width. The theme now writes the tag when docutils has not. Signed-off-by: Will Manning <will@willmanning.io>
Headings take a blog post's mono heading ladder one level up: 28px at 500, then 22px and 18px at 600. The sidebar rows, On this page, and the pager are Geist Mono, as navigation is on the other Vortex sites. Signed-off-by: Will Manning <will@willmanning.io>
The docs loaded no web font, so headings, labels, navigation, and code fell back to each platform's mono. The theme now serves Google Fonts' Latin subset of Geist Mono (23 KB, every weight) and preloads it. Body text keeps the platform's sans. The font is OFL-1.1. Signed-off-by: Will Manning <will@willmanning.io>
|
Two changes: the headings and the navigation use Geist Mono, and the docs self-host Geist Mono.
The before shots hide a locally installed Geist, so they show what a reader without the font saw. Frame at 1440, Dark:
Python API at 390, both themes:
impeccable 4.7.0 reports no findings at 1440 or 390. |
|
👍🏼 |
A warning admonition's icon and title take the system's new warn-ink token, so a warning no longer reads as a note. Code that links (an API name in prose) takes the syntax type colour, as in signatures. Signed-off-by: Will Manning <will@willmanning.io>
A reference page is mostly links, and its reader scans for them, as the old theme's cyan links let them do. Links in the main column take accent-ink, with a 40% underline that goes solid on hover. Linked code and signatures keep the type colour. Signed-off-by: Will Manning <will@willmanning.io>
|
The docs now use colour where the old theme did. Two commits:
The sidebar stays without Blue. The current page has a raised row. Old theme (left) and new theme (right), User Guide > Vortex Python, 1440, Dark and Light:
Python API > Arrays:
🤖 Generated with Claude Code |
myrrc
added
changelog/docs
After the build, the theme extension reads every built page and the scripts that the pages load. It keeps a CSS rule only if each class, id, element, and attribute in one of its selectors is in that set, then drops the custom properties that no kept rule reads. Pseudo-classes and attribute values are not checked, so hover, focus, the phone menu, the search results, and both themes keep their rules. The system copies stay byte-for-byte, so their sha256 checks still pass. The shipped vortex.css goes from 25.8 KB to 21.9 KB, and from 5.9 KB to 5.2 KB with gzip -9. Screenshots of 9 pages and states at 1280 and 390 px, in Light and Dark, are pixel-identical before and after. Signed-off-by: Will Manning <will@willmanning.io>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Copy the design system's v115 docs CSS with tools/site-styles.mjs. v115 removes vx-stat, vx-lede, the content-max token, and the FileMap focus selector. The pruning step had already dropped all of them, so the shipped vortex.css and every built page stay byte-identical. Remove the Jinja comment above the viewport meta in layout.html. Signed-off-by: Will Manning <will@willmanning.io>
|
Additional note: this change draws GitHub as an icon but PyPi and crates.io as text, I'd suggest keeping the current state where everything is drawn as text. Text is easier to navigate than icons. |
|
And another note on my original rationale for rewrite: I wanted to make the page more dense so you'd have more information available. This design reverts this. Breadcrumbs imo are duplicating the navigation on the left. We don't (and probably shouldn't) have more than two levels of nesting, and in this case the left navigation always provides all information you need. |
Signed-off-by: Will Manning <will@willmanning.io>
- Linked code in prose has an underline at rest, 40% of its own colour and solid on hover. Before, colour was the only thing that set it apart from plain inline code (WCAG 1.4.1). - Dark --syntax-function is #f4df9a, not #c9a8f5. Under protanopia the old value was almost the same as the keyword colour. Signed-off-by: Will Manning <will@willmanning.io>
The left navigation shows where each page is, and the docs nest no more than two levels deep. Signed-off-by: Will Manning <will@willmanning.io>
…ning Copy design system v117 with site-styles.mjs --reads vortex.css and layout.html. The tokens copy keeps only the custom properties that the docs rules and these files read, and drops the type classes that the docs do not use: 3,222 bytes, down from 7,052. The theme extension no longer parses the built HTML and CSS after the build. The shipped vortex.css is 5,313 bytes with gzip -9, against 5,203 with the removed step. The rest is the breadcrumb rules, Pygments classes that no page uses, and the focus rule's selectors for other sites. Signed-off-by: Will Manning <will@willmanning.io>
Signed-off-by: Will Manning <will@willmanning.io>
Merging this PR will not alter performance2 warnings
Comparing 
Footnotes
|
Above 760px, the first column of an API summary table no longer breaks names such as open_readable one character before the end. Phones keep the wrap, so no table scrolls sideways. Signed-off-by: Will Manning <will@willmanning.io>
Body text is 16px at 1.6 line height. Flow gaps, heading margins, page padding, nav and rail rows, code blocks, and table cells are smaller. The prose measure does not change. Pages are 8 to 14 percent shorter. Signed-off-by: Will Manning <will@willmanning.io>
Summary
This draft PR changes the look of the docs to the Vortex design system that vortex.dev, bench, and the Explorer use. It is a prototype for review. It does not change the content or the URLs of any page.
Changes
docs/_theme/vortex/system/holds copies of the system's CSS (tokens, docs, and focus).vortex_theme.pystops the build if a copy has a hand edit.layout.htmlwrites the system's header, navigation, "On this page" list, and footer. The pages need no JavaScript, except for search.accessible-pygments, and the Breathe hook are removed.The build passes with warnings as errors. After gzip, each page gets 0.9 to 1.9 KB larger, and the CSS goes from 2.7 KB to 5.4 KB.
🤖 Generated with Claude Code