Conversation
Contributor
|
| Scope | Lines Δ% | Lines Δ | Lines + | Lines - | Files Δ | Files + | Files ~ | Files ↔ | Files - |
|---|---|---|---|---|---|---|---|---|---|
| 📄 Docs | 100% | 1809 | 1273 | 536 | 31 | 3 | 25 | - | 3 |
| Total | 100% | 1809 | 1273 | 536 | 31 | 3 | 25 | - | 3 |
Legend: Files + (added), Files ~ (modified), Files ↔ (renamed), Files - (removed)
🔝 Top Files
- docs/website/styles.css (Docs): 589 lines Δ (+387 / -202)
- docs/website/index.html (Docs): 242 lines Δ (+49 / -193)
- docs/ui/src/css/toc.css (Docs): 169 lines Δ (+169 / -0)
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #1304 +/- ##
========================================
Coverage 83.12% 83.12%
========================================
Files 35 35
Lines 3662 3662
Branches 844 844
========================================
Hits 3044 3044
Misses 410 410
Partials 208 208
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
julioest
changed the title
julioest
marked this pull request as ready for review
September 16, 2026 19:53
|
An automated preview of the documentation is available at https://1304.mrdocs.prtest2.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-09-25 21:15:49 UTC |
julioest
force-pushed
the
ui/refresh-fixes
branch
from
September 17, 2026 15:35
67476be to
0407627
Compare
Collaborator
|
A few glitches or things that look off:
|
julioest
changed the title
`margin: 1.5rem 0` zeroed the inline margins, and at (0,3,1) it
outranked `.doc > * { margin-inline: auto }` at (0,1,0). The title
kept the 779 measure but anchored left, off the content band's axis
by (content width - 779) / 2: 15.5px at 1440, 255.5px at 1920, and 0
below 1169 -- so it never showed on a laptop.
.principles inherited the default 80px section padding against Figma's 164, pulling the whole block up ~82px. The hero's desktop rhythm now follows the frame's uniform gap32 stack. Landmarks land within 2px. #features derives its 237 from the unchanged bottom padding, so the band relationship holds.
The embedded contents list ran full length above the page title: generators/reference met the reader with 3303px of links and put the h1 at y3588 against a 285 baseline. From 11 entries it now shows the first five top-level rows, with a chevron to reveal everything and a per-section caret to open one. The threshold is where the list would push the title off a 402x874 screen. Six of the 3745 pages carrying a list reach it; the median page has two entries and is untouched.
The clipped list sits in normal flow at the top of the page, so seeing it means scrolling to the top, which makes the first section active again. The marking is correct but no reader can currently observe it. Kept because the invariant holds -- a clipped list must not leave the reader unmarked -- and it lights up if the list ever becomes reachable while scrolled. A floating contents nav was considered for that and deliberately not built.
Narrows 9a116d0. Two of the four strings it restored were maintainer edits, not designer ones: `niebloids` -> `algorithm function objects` (e9f847d) and the output-format line (315232b). Both are C++ terminology, where the maintainers outrank the mockup. The row 2 and row 4 panel subtitles stay on the Figma text -- there only the designer had an opinion. The mockup needs updating for these two cards instead.
Both raised in review by a maintainer. `noexcept` sat as body text beside a code-styled `[[noreturn]]` in the Attributes & Specifiers subtitle; both are C++ keywords. The Figma marks only the 12 characters of `[[noreturn]]` as code, so the mockup needs updating too. The hero panel is the is_prime snippet but its tab read "C++", while row 3 shows the same file as "is_prime.cpp" -- one file under two names. The duplication itself is in the design and is left for the designer; the inconsistent label is not.
Raised in review: the sqrt example renders two LaTeX fragments but nothing says math is a feature, so it reads as incidental. Measured, the two formulas are 71x17 and 81x16 in a 638x1194 panel -- about 0.15% of it -- and `O(log value)` renders as italic serif that passes for ordinary emphasis. Math now sits in the list of things the row claims to understand rather than being tacked on the end. The subtitle wraps to three lines where it took two, so the row is ~52px taller. Deviates from the Figma text restored in 9a116d0; the mockup needs updating to match.
"rendered exactly as you wrote them" is false, and the example in that
same row disproves it. Source:
std::enable_if_t<std::is_integral_v<T>, T> sqrt(T value);
renders as:
T sqrt(T value) requires std::is_integral_v<T>;
MrDocs re-expresses the SFINAE return type as a requires clause, which
is the opposite of reproducing it verbatim -- and a better claim than
the one being made. The row now says so.
Caught in review by a maintainer. Note 9a116d0 made this worse: the
repo said "rendered as you wrote them" and the Figma's "exactly"
strengthened an already-inaccurate claim. The mockup carries the same
error and needs correcting.
The config reference builds its previews with a standalone Asciidoctor instance, which inherits no attributes from the playbook. Without `source-highlighter` it emits bare `<pre class="highlight">`, missing the `hljs` opt-in the theme's highlight bundle selects on, so 116 of the 216 blocks on configuration/reference.html render unstyled. The hand-built blocks in the same function already hardcode those classes; this makes the converted path match.
The config reference rendered previews at `leveloffset=2`, so a symbol's `==` name became an h4 and its `===` sections h5. The sibling path in `adoc-preview-extension.js` maps those to h5 and h6, so the same source produced different levels depending on which extension rendered it, and the section titles landed on the level the theme styles as a symbol name. `+3` lines the two paths up. No h4 is emitted inside a preview now, on any page.
The card shows the same symbol panels as the landing page, which sets the symbol title gold at 36px and the section titles blue at 24px. The card had its own scale -- 1.35rem and 0.8rem -- while still inheriting the display face and its ink edge from `.doc h1-h6`. That edge is a centred stroke, so it takes a fixed bite out of each glyph however small the type is. At 14.4px a 2px stroke is 13.9% of the em and closes Bangers' counters, which is why the section labels rendered as blobs.
`.doc > *` centres its children on the 779 measure with `margin-inline: auto`. This rule sets explicit side margins at (0,1,1), which outranks it, so the bar anchored to the left edge of the content box instead -- out by (content width - 779) / 2, which is 33.5px at 1440 and 273.5px at 1920. The 1rem side padding paired with those negative margins to bleed the rule past the text; centred, it would have inset the links instead. Both go, and the bar now spans the measure exactly.
Figma 300:349 / 300:749. Tabs were slate boxes with hairline grey edges; they are gold-on-selected, blue otherwise, with the comic ink outline and hard shadow. Inactive tabs carried `opacity: .5`, which composites the whole element -- label, surface and border -- against the page and left the label at 1.93:1, under the 4.5:1 AA wants. The Figma applies its 10% blue to the background only and keeps the label at full ink; the tokens already do that, and measure 15.16:1. Both states drew their label in `--text-muted`, so selected now marks itself rather than relying on the rest being faded. The per-side weights govern: `borderStrokeWeightsIndependent` is set, so the 2.0 on each edge applies and `strokeWeight: 1.0` does not. The bottom edge is dropped -- it butted the panel's own 2px border and read as one doubled rule. Gap is 6 rather than the mock's 10, whose four equal short-labelled boxes don't match real tab text. Dark diverges deliberately: 300:749 fills inactive tabs solid `#3D8BFF`, which puts their white label at 3.32:1 and makes them louder than the panel. They take the page surface instead, as light already does. The tokens are now defined once -- the dark overrides are gone, since `--surface-tint` and `--text-strong` flip on their own. The `prefers-color-scheme` block had drifted from the `[data-theme]` one and still held the old values.
316:334241 / 316:282462. The open panel now runs full height on the page ground under its 10% blue wash, 30 padded, links 32 apart, the toggle held at 334,30. It was a 196-tall white card with rules between the items. The bar was 79 around a 47 lockup; the frame is 59 around 35.4, which also put it 22 off the docs bar on the same phone. The GitHub button had lost its padding to the link reset and sat at 131 against the frame's 157. The burger is the supplied glyph rather than three CSS bars, and the open state swaps it for the cross 316:334267 specifies -- the panel covers the viewport, so there was no way out of it. Links and Escape dismiss it too; the toggle, which lives in the panel, does not. Dark drew its edges in slate with a near-black shadow. 316:282463 strokes the bar, its buttons and their shadows in #000000. `--nav-h` is published by the toggle script: the panel's containing block is the bar, whose height is auto, so CSS can't reach it. Markup changes are applied to the generated `index.html` as well, which cannot be rebuilt without a MrDocs binary.
The mobile menu is sized in `calc(N / var(--rem-base) * 1rem)`, but the root drops 18 -> 17 under 768 -- exactly where the menu lives -- so every figure landed at 94% of 316:335019: the 38 buttons at 36, the 14 label at 13.2, the 30 padding at 28.3. These are fixed control sizes from a fixed-width frame, so they are pinned to px. The toggle also lifted itself 12 to centre on the first link's line. Both frames top-align links and toggle at y=30, and the lift put it 16 above the identical control on the landing page. The burger was three square-ended spans rotating into a cross. 316:335019 and 316:334241 place the same 24x24 "Close remove -- Iconly Pro" in both products, so both now draw that glyph. Its animation goes with it. Two things the swap exposed: `currentColor` resolves to transparent on a nested svg here, so the mark was invisible on light until the colour was set on the icon itself; and the bar's own `--navbar-font-color` is #24303F / a 92% off-white, where the frame asks for #0F172A / #FFFFFF -- which is `--text-strong`.
Tables sit on `--table-frame-background` (`--surface-tint`), which is darker than the page, and nothing here accounted for that. The link blue measures 4.96:1 on the page but 4.39:1 on the frame, and its dark counterpart 3.68:1 -- both under AA. They now take a ramp step either side: 5.66:1 light, 6.76:1 dark. Links also had no cue but hue. A link and a code span in a cell were both Menlo 400 with no decoration, so in the Type column `Attribute[]` and `string` differed only in colour -- WCAG 1.4.1. Table links carry an underline. `--table-name-color` is inherited rather than the label pink. The frame specifies that colour for the first-column names, but the selector reaches every code span in a cell, none of which are links; magenta, and on dark an outright #FF4C4C, read as dead links beside the live ones, at 3.00:1 and 3.71:1. Inheriting also handles `<code><a>` correctly, since the nested link keeps its own colour. Hover moves from the cell to the link. The cell rule washed 30% black over the whole `td`, dropping the link it advertised to 2.72:1 and putting a pointer over prose that wasn't clickable. The link's own hover steps one further in each theme's direction, so it is always the stronger state, and thickens the underline rather than adding one.
julioest
force-pushed
the
ui/refresh-fixes
branch
from
September 23, 2026 05:39
449bc59 to
41abcba
Compare
The comments added across this branch over-explained. Several narrated the investigation or recorded before and after figures that stopped mattering once the code was correct, and a few restated what the declaration below them already said. What stays is the traps that would otherwise be re-broken: specificity collisions with `.doc > *`, tokens that must be defined in all three theme blocks, `currentColor` resolving to transparent on a nested svg, per-side frame stroke weights overriding `strokeWeight`, and the rem scale changing under 768. Stripping comments from both revisions gives identical text in all 13 files.
Mermaid was initialised with `"Roboto", sans-serif`, which is the fallback at the end of the site's body stack, so every diagram rendered in the face the prose falls back to rather than the face it uses. Labels now resolve to the same stack as the text around them. The stack is written out rather than referenced: the playbook is YAML and cannot read `--ds-font-body`, so the two are kept in sync by hand.
Diagrams were light in both themes. On dark they sat as near-white slabs on the page ground with arrows at 1.45:1 against it, effectively invisible wherever they crossed it. The colours were authored in the pages as `classDef`, which Mermaid emits as inline `!important` on every shape, out of reach of any stylesheet. Dropping those declarations turns out to cost nothing: a node still carries its semantic class from `:::input` or `class A,B common`, and arrives with no inline style at all. So the roles move to `--diagram-*`, each tinting its own theme's surface, and dark gets dark nodes with light ink rather than a light drawing pasted onto the page. Light keeps the pale fills it had, at 13 to 15:1 for labels; dark runs 7.6 to 10.4:1, and arrows go to 5.29:1. `--mr-green` is new. The palette carries blue, gold, red and pink, and "output" reads green in both diagrams. No re-render and no script: once nothing is inline, CSS alone follows the theme.
Contributor
Author
|
@alandefreitas 8 of 9 fixed. Couple of question for you, on the Y and readability of typewriter font. The Y. Readability of typewriter font in long paragraphs. OPEN. Is this because of the background behind certain long paragraphs? Or does the font need to be styled a little better (line-height, spacing, etc)? The menus on mobile. FIXED ae7a01305 ebde211f1. Panel is full height at the frame's sizes, and the burger swaps to a cross so it can be closed. The docs menu was undersized too; both match now. Different headings in previews, and the heading styles in configuration/reference. FIXED 72ede9a7f 1cad1d426. Previews rendered a level too shallow, so sections took the styling meant for symbol names, and the card's own type scale collided with the display face's stroke. Both follow the landing spec now. Borders of tabs and opacity of tabs options. FIXED 871dd769c. Rebuilt to the component; the opacity had faded the label along with the surface, where the frame tints only the background. One divergence: dark inactive tabs take the page surface, not the frame's solid blue, which left the label too faint. Code blocks broken in configuration/reference. FIXED 2edc19567. The generator, not the theme: it renders previews with a standalone Asciidoctor instance that wasn't told to highlight. Same cause for the grey background and black text. Diagrams using different fonts. FIXED dfac0063b 11eb3b5ad. Mermaid was initialised with Roboto, the fallback at the end of the body stack, so diagrams rendered in the face the prose falls back to. Dark mode was worse than the font, so that went too: node colours were authored as Tables in generators/reference and extensions/library. FIXED 41abcbaaa. The inline code was the problem, not the links: every code span in a cell was painted the label colour, and none are links. The links were separately too faint and differed from adjacent code by colour alone, so they're darker and underlined now, and the cell-wide hover is gone. The prev/next bar is misaligned with the text. FIXED f445ad7d0. Explicit side margins outranked the rule centring |
Bangers ships no italic cut, so the oblique is synthesised, and WebKit does not grow the ink overflow rect to cover the skew. This span's box ends exactly at the text advance, so the last glyph was clipped: the Y of "Full-fidelity" lost 15px of its arm on iOS while Chromium drew it whole. Padding gives the glyph room and the negative margin takes the space back, so layout is unchanged. Measured in both engines at 375 through 1920: h1 geometry identical, no horizontal scroll.
Swap the hero and CTA art for the lab coat poses and refit their placement to the new aspect ratios.
The speed lines stay on mobile only.
Landing code panels take the docs palette through shared panel tokens. Fixes invisible plain text in the dark synopsis.
render.js splits highlighted snippets into per-line spans so the counter numbers each line and long lines wrap.
Panel syntax tokens and code leading now point at primitives. Value-neutral.
The 9px gutter inherited overflow-wrap: anywhere, so "10" broke into two rows. It now widens 1ch per digit.
Figma 520:84 blob, masked in the page-ground colour, so the halftone does not fight the right-rail links.
Bangers ships only 400; WebKit widens the synthetic bold and wrapped the CTA pair on iOS.
One shared mask; each mascot starts it so the fade spans the same share of the figure.
16/24/28/78px by breakpoint; the landing gutters use it in place of fixed 28 and 78.
CTA mascot scaled to 400px with the rays re-anchored to its chest.
Same padding fix as the hero h1 for the synthesised oblique.
Tighter insets and rhythm, full-width tables, content-sized hero panel below 992px.
17/1.8 on a 64ch measure, softer ink, underlined strong, and a 0.35px stroke to fill Special Elite's worn edges (PR 1304 option C).
Cap the list, not its items, so indented text ends where paragraphs do. Drop auto-hyphenation; text-wrap: pretty evens the rag in Safari.
Prose ends within the rag of the 779 column's rules and code, so it stops reading as left-aligned.
startOnLoad waited for the search index. Run once the module and label font are ready; hide the source until the SVG lands.
Labels inherited .doc's auto hyphens and split words at the 200px wrap.
Longest lines now end within a character of the heading rule, so prose matches the hr length.
Each block sizes its box from the SVG's viewBox in cqi, so the page no longer jumps when the diagram renders.
Same-colour stroke and fill made it a no-op, and Safari painted the stroke onto the start of inline code.
Collaborator
|
Merged as #1325 |
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
3 participants
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.
Follow-ups to the comic design refresh (
be06d44fb), found by measuring the built site against the frame, plus the points raised in review on this PR.Changes
Docs theme
margin: 1.5rem 0at (0,3,1) outranked.doc > * { margin-inline: auto }at (0,1,0), so the title kept the 779 measure but anchored left, off the band's axis by 15.5px at 1440 and 255.5px at 1920.pagination.css. It was out by 33.5px at 1440, 273.5px at 1920.hljsopt-in.opacity: .5faded the label along with the surface and left it at 1.93:1.Landing page
.principlesinherited 80px section padding against the frame's 164.Yand the CTAR. The Bangers buttons asked for 600, a synthetic bold that WebKit widens, which wrapped the CTA pair onto two rows on iOS.--ds-guttertoken (16/24/28/78), one inset for code and doc surfaces, even heading-to-content spacing in the doc panels, full-width tables with a usable exceptions column, and a content-sized hero code panel.Housekeeping
Testing
gulp lintclean; full Antora build clean.hljs, none missing.<header>at 402 and 768.Regression expectations live in a rig outside this repo, so they do not run in CI.
Documentation
Two pages change content:
index.adocandcommands/index.adocdrop theirclassDefcolour declarations so the theme can own diagram colours. The semantic class bindings stay, and the diagrams render the same in light.Before / after
Docs page title at 1920. The band and body copy are identical in both; the guides mark the band's centre and the title's.
Mobile contents at 402,
generators/reference.Landing hero and principles rhythm at 1440.
Open
--mr-greenis new, added for the diagram "output" role, since the palette carries no green.