WIP: Comic design refresh - #1261
Open
julioest wants to merge 20 commits into
Open
Conversation
Introduce a three-layer token vocabulary (primitives, semantic, component) in docs/shared/design-system.css as the canonical spec, implement the L0 primitives for the Antora theme (tokens.css), inline all three layers in the landing page, and rewire existing variables plus the doc-panel markup to consume them. No visual change.
Use Special Elite as the body font and Bangers for headings, wiring each surface per its convention: self-host both faces via @fontsource in the Antora theme, and load them from Google Fonts on the landing page. Point --ds-font-body and --ds-font-display at the new faces and apply the display font to all headings.
Add the comic "Main Title" token group to the shared design system (--ds-title size/leading/color/ink/outline/shadow), mapped to the nearest existing primitives. Also italicize the docs headings the fonts commit already switched to Bangers, completing that display-font rollout. The landing hero's bespoke treatment that consumes these tokens is deferred to the B1 (landing) slice.
The docs navbar logo used {{or site.url siteRootPath}}, which in local/dev builds resolved to the hardcoded production URL. Point it at "/" so it lands on the site root (the landing page) in every environment.
Also ignore the local-preview symlink docs/website/docs.
WIP checkpoint — comic navbar (white/ink bar, Special Elite links, gold GitHub button, theme toggle), the real two-tone Figma logo lockup (separate light/dark SVGs swapped per theme), correct GitHub icon, and a responsive hamburger menu below 768px. Also the in-progress hero comic-title treatment; yellow token now #facc15. Also cache-busts styles.css via render.js. Tweaks to follow in the next commit.
custom.css imported after doc.css and reset .doc h1-h6 back to the body face, so the display-face declaration never applied. Drop that reset and keep only the heading colour there. Case is deliberately left alone: reference headings are C++ symbol names, so text-transform stays off in the docs. That half of the original reasoning still holds. Bangers ships upright only, so the font-style: italic on these headings renders as a browser-synthesized oblique rather than a true italic.
Add the accent-label palette the mockups use for eyebrow pills and card titles (--ds-pink-500 on light, --ds-red-500 on dark), expose it as --ds-color-label, and add --ds-color-surface-accent for the card fill. All three theme blocks are covered, and design-system.css is kept in sync as the canonical spec. Style the feature grid off the bare divs the template already emits, so index.html needs no regeneration: filled panel, hard outline, hard offset shadow, bordered icon tiles, pink underlined titles. Tighten the desktop grid gap, which was tuned for un-boxed content and reads as adrift once the cards have visible edges. Name the component group --ds-feature-* rather than --ds-card-*: a generic soft-ambient --ds-card-* group already exists and, being declared later in the same :root, would have overridden bg, radius and shadow. That group is left in place as spec. Dark-theme values are inferred; the mockups only cover light.
Code/reference rows take the comic treatment: both halves get a hard outline and hard offset shadow, backdrop blur is dropped, and the panel labels (h2 symbol title, h3 sections) go gold, uppercase and italic per the mockups. h4 stays in the reading face, since that is only the NOTE admonition. These rules are appended last on purpose so they win over the theme-aware surface block at equal specificity. This overrides the panel-heading exemption for the landing page only. The docs site keeps it: there the headings are arbitrary template signatures, whereas here they are five short curated names. Theme toggle now follows the Figma "Secondary/Default" spec exactly: 38x38, 5px padding, 2px edge, 2px 2px 0 shadow, 22px icon, square corners (the export omits a radius). Much of this existed already in the B1 --navc-* group but targeted .nav-btn--toggle, markup that was dropped when the shipped .theme-toggle-btn was kept; those dead rules are gone and their spec now lives on the live button. Edge and icon get their own tokens rather than reusing --navc-border and --navc-shadow, which are shared with the navbar, GitHub button and hamburger and have no Figma spec of their own. Icons swap from filled glyphs to the stroked outlines the spec calls for, with stroke="currentColor" so they theme, and the CSS fill is removed because it would otherwise beat fill="none" and render them as solid shapes. Template and generated HTML are updated together.
|
| Scope | Lines Δ% | Lines Δ | Lines + | Lines - | Files Δ | Files + | Files ~ | Files ↔ | Files - |
|---|---|---|---|---|---|---|---|---|---|
| 📄 Docs | 100% | 3710 | 3153 | 557 | 19 | 9 | 10 | - | - |
| ⚙️ CI | <1% | 3 | 3 | - | 1 | - | 1 | - | - |
| Total | 100% | 3713 | 3156 | 557 | 20 | 9 | 11 | - | - |
Legend: Files + (added), Files ~ (modified), Files ↔ (renamed), Files - (removed)
🔝 Top Files
- docs/website/styles.css (Docs): 2350 lines Δ (+2081 / -269)
- docs/shared/design-system.css (Docs): 537 lines Δ (+537 / -0)
- docs/website/index.html (Docs): 362 lines Δ (+156 / -206)
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #1261 +/- ##
========================================
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
Add the magenta badges above each code/reference row and over the hero
title. Copy lives in data.json: an eyebrow at root and a label per
panel, keyed by source filename so reordering panels cannot misalign
them, stored in natural case with the uppercasing done in CSS.
Markup is {{#if}}-guarded so a panel without a label renders nothing,
and is mirrored into the generated index.html.
Styling follows the Figma spec: Bangers at 16px/16px with 0.1em
tracking, white on #EC4899, 2px #0F172A edge with a 2px 2px 0 shadow,
6px 12px padding, square corners. font-style is pinned upright since
Bangers has no italic cut and would otherwise be synthesised.
Corrects --ds-pink-500 from #e63c90, sampled off a mockup screenshot, to
the exact #EC4899. This also corrects the feature-card titles, which
route through the same --ds-color-label token.
Two labels are inferred rather than read off the design: is_prime.cpp,
which was illegible at screenshot resolution, and function_object.cpp,
which has no row in the mockup at all. Dark-mode values keep the
existing theme swap; the spec covers light only.
julioest
marked this pull request as ready for review
August 18, 2026 16:36
|
An automated preview of the documentation is available at https://1261.mrdocs.prtest2.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-08-25 23:43:10 UTC |
Tiled radial-gradient behind the hero and examples band, masked to fade down the section. Adds --ds-color-halftone and --ds-halftone-* tokens. background-repeat is explicit: Pico resets every ::before to no-repeat. Replaces the .dotted / .dotted-right image bands on the landing page.
Rebuild the hero from the Figma file: three-line headline with alternating blue/gold, refilled DOWNLOAD/GET STARTED, code panel with hatched header and line-number gutter, flying mascot, and the cityscape band on the hero's bottom edge. Desktop is a three-column grid; tracks use minmax(0,...) so the oversized mascot overflows its column instead of squeezing the panel. Values come from the .fig rather than pixel-sampling, which corrected the title to 96/62px, body copy to line-height 1.6, and the code panel -- it is per-theme, not theme-invariant as first assumed. Dark page surface becomes #272E3F per the design, which affects every section, not only the hero.
The stylesheet was what discovered the fonts, so layout ran in the fallback and reflowed ~170px when Bangers arrived. Preload the two latin faces the hero uses. The display stack fell back to Special Elite, so a comic headline briefly rendered in a typewriter face -- use heavy/condensed fallbacks instead, and give Bangers font-display: block now that it is preloaded.
The hero headline's first line is theme-dependent: character-level overrides in the Main Title node give #93C5FD on light but #3D8BFF on dark. It had been assumed to carry over unchanged.
Figma has no interaction variants, so hover and press follow the comic behaviour used elsewhere: lift 2px with the shadow grown, press 1px with it cut back, colours unchanged. Box comes from the Button Container: 101/116x38 with a 24px gap and a 1.5px shadow on mobile, 123/140x48 with 32px and 2px on desktop, labels Bangers 16/20px at 10% tracking. Heights are px because the shared 2.5rem token resolved to 50px under Pico's responsive root. The light ring is Figma's 2px page-coloured wrapper with the stroke set to OUTSIDE. Also drop six superseded B1 blocks whose :active rules had no counterpart in the new set and were still repainting on press -- gold for DOWNLOAD, translucent white for GET STARTED.
The hero overrode Pico's container cap to reach the mockup's 1284px content box but never set its own, so past 1440 the columns and the code panel grew without limit while the headline, body measure and mascot stayed fixed -- at 2560 the panel reached 881px around eight short lines of code. Cap at the design's content box plus its gutters, centred: a no-op at 1440, symmetric whitespace beyond it. The halftone and cityscape sit on the header itself, so they still span the viewport.
Rebuild the "keep the code simple" section from the .fig: a two-tone 82/52px heading with a 4/3px stroke and offset, and a card grid at 624x326 with a page-coloured 2px ring, a #1E78FF/10% inner panel, a 50/38px icon box and gold outlined titles. Icons are the four Iconly Pro glyphs applied as masks, so they take a themed colour rather than a baked-in one. The corner halftone is one repeating gradient with a radial mask, standing in for the 1019 dot vectors Figma uses per blob, and the page halftone now extends to this section -- unmasked, since only the hero fades it. Drops the starburst bust illustration, which the design does not have in this section, and the stray </div> that left index.html's tag count uneven.
Measured off the mockups: the dot grid runs on a 6.75px pitch, deltas alternating 6/7 on both axes. The 14px gap was a guess from before the design file was readable. Affects the hero as well as the feature section -- Figma has it as one page-wide pattern fill. Ink coverage in the hero's open area now reads 26.0% against the mockup's 26.5%.
Rebuild "More Code, Fewer Workarounds": centred two-tone 82px heading, a 553px subheading measure, a 20/14px label pill and 32/24px subtitle, and one bordered box with the 2px page-coloured ring splitting flush 638+638 instead of two panels with a gap. The documentation half takes Figma's split heading colours -- gold 36px for the symbol, blue 24px for Synopsis and Description, where the earlier rule gave both the same gold -- plus Special Elite body copy, pink inline code, and the declaration block on the dark code surface. The code half reuses the hero's panel chrome with the filename as its tab. Drops the per-panel decorative illustration, which the design does not have, and replaces the checklist with the subtitle paragraph.
Cloud bank and converging speed lines over the boundary into the panels section, exported flattened from Figma's Group 6 since the rays are thirteen overlapping vector shapes. Also corrects the gap between the two sections to Figma's 317px. At the default 160px the band reached up over the feature cards and washed out their copy. Desktop only: mobile puts the rays above the heading but the clouds below it, which one flattened export cannot reproduce. On dark the art is inverted -- Figma sets LINEAR_BURN, which CSS has no equivalent for, and mix-blend-mode cannot reach past this section's isolation.
`height: 100%` on .feature-card-inner resolved to auto in WebKit -- the card's height comes from grid-auto-rows: 1fr, which is not a definite height there. Grow the inner as a flex item instead.
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
2 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.
Draft — WIP on the comic design refresh (initiatives#4, Figma).
Rebased onto current
developand reconciled with the brand theme work ina51d1621b/faea11b9c. Upstream values win everywhere — the design system only supplies the indirection, so this shouldn't shift anything visually except where a slice deliberately restyles it.docs/shared/design-system.css(spec) +docs/ui/src/css/tokens.css(primitives for the Antora theme)vars.cssvars at tokens, values unchangedSecondary/Defaultspec, stroked iconscustom.cssreset, but leaves case alone so symbol names are never uppercasedNotes:
docs/website/index.htmlis hand-merged, not regenerated. No prebuilt mrdocs matches currentdevelop— the newest release is older than the one the Antora cache pulls, and that one breaks thesqrtpanel's latexmath. Generated panel interiors are untouched; only template chrome (nav, lockup, toggle) was merged in