site: one design system for the four sites

Merged
RI
17h ago
+3598-1997

The approved design (19 Nov) gives the four sites one design system. This PR ports it into the generator of the three house sites, so each built page equals its approved page. The two house copies follow in openfluids/openfluids.github.io and BoringQuantSystems/boringquantsystems.github.io; the type site follows in machine-made/type.

What changes

  • src/system.css is the one stylesheet: tokens and components. build.py writes it into each page without its comments, because a linked file cost 0.3 s of render time on the phone run. site.json sets only six colours, the house face, a bar-2 label per group and the groups. The name paragraph (blurb) is removed, as the approved design says.
  • Each page: bar 1 (the four sites), bar 2 (logo and sections), the banner, the house line, Latest, the plates with live GitHub facts (language, latest release or "unreleased", last commit), the houses row, the footer. A 404 page whose addresses start at the site root, since Pages serves it at any depth.
  • fetch.py reads the facts with one GraphQL call through gh. Any failure exits 1, and the build writes no file, so a stale page cannot ship. homebrew-tap is never listed. Latest shows distinct repositories, newest first, at most three.
  • Images: AVIF and JPEG at two widths with srcset, width/height, lazy loading below the fold, a high-priority preload for the banner. og.jpg is 1200 x 630 per site. Favicon and touch icon per site; mark.svg on machine-made.
  • Fonts: Heddle 0.2.0 is added from the heddle-v0.2.0 release. fonts/SOURCES.json records version, asset and SHA-256 of every source font, and check_site.py pins the same hashes. Each page ships a subset of each font. The subset keeps every axis and every feature the style uses, and the build fails if one is lost.
  • The build runs under uv run --with fonttools==4.68.0 --with brotli==1.2.1 --with pillow==13.0.0 (README, Build; gate.sh). src/style.css and the unused Warp italic are removed.

Differences from the approved style

The approved system.css is copied. Five changes keep the existing checks passing:

  1. Colour-only :hover rules sit in @media (hover: hover).
  2. Transitions and the bar-2 scroll animation sit in @media (prefers-reduced-motion: no-preference).
  3. The Warp stack names no system font: Georgia is gone.

These three change no pixel of a still page.

  1. Tap targets on a phone (its own commit, site: 44 px tap targets on a phone, so it can be reverted alone). The approved style had bar-1 and footer links 32 px high below 720 px, the logo 28 px and Latest links 24 px. The existing check asks for 44 px at 390 px, and I did not lower it:

    • Below 720 px, bar-1 rows and footer links are 44 px high and the logo box is 44 px high. At 390 px, bar 1 is 24 px taller.
    • Below 520 px, a Latest link has 12 px of padding inside its row, so the row does not move.
    • Nothing changes at 720 px and wider.
  2. The type page on a phone narrower than 390 px (its own commit, site: the type page fits a phone narrower than 390 px). Two lines of the type home page do not wrap: the type line and the family tiles. The approved page scrolled sideways at 320 and 360 px:

    • The type line needs 317 px in a 288 px column.
    • The Heddle tile "Grotesk 1958" needs 285 px of text width, where a 320 px phone leaves 240 px and a 360 px phone leaves 280 px.

    Below 390 px the type line uses font-stretch: 70%, the narrowest width of Heddle, and a tile uses --step-3. Nothing changes at 390 px and wider. The house pages carry the rule in their style block but show no tile and no type line.

Checks: old and new

Every existing check is kept or replaced by a stronger one. Where one was replaced:

Old checkNew checkWhy the new one is stronger
style.css is a file; a page style block may hold no colourExactly two style blocks: the font faces and colours (built from allow.json), then src/system.css byte for byte without comments. Every CSS rule check runs on that blockA page cannot carry a style that differs from the source
Palette --bg --fg --muted --accent --edge; text and muted 4.5:1Six tokens equal allow.json; text 7:1 and muted 4.5:1 on the ground and on the surface, accent 3:1Higher floors and two more pairs
docs/fonts/* are the full 0.2.0 files (SHA-256)The source files in fonts/ are pinned twice: SOURCES in check_site.py and SOURCES.json. Each shipped subset is opened with fontTools: same family, same axes, used features kept, no glyph outside the source, every character the page sets in it presentThe old hash could not prove the page's text is covered
Preload of Weft and the text fontExactly one font preload (the house face) and, on the home page, exactly one image preload (the banner, AVIF, high priority)Tighter
Font stacks name generic families onlySame, with machine-made families allowed as fallbacks (Heddle falls back to Sans). Also, in the browser, no glyph is drawn in a system font at 390 and 1280 px on the home page and the 404 pageIt measures what the reader sees
No weight other than 400Every weight lies inside the range of the variable font that the rule uses, so no weight is faked. All text on the house pages is still checked at weight 400, normal style, in the browserSame goal; the type-site rules (Heddle 650) are now covered
--fs 16 px, --ls 24 px, --ws, body line height 1.55The step tokens equal 1.25^n rem; every font size in the style is a step token; body line height 1.5. Word spacing is gone because the approved design has noneCovers every size, not two tokens
CSS touch rules for .bar a, .ds a.b1 li and footer a 44 px, .secs a 44 px, .ds a 12 px padding. The browser check (every link at least 44 px at 390 px) is unchangedSame floor
Footer dot drawn by footer a:not(:last-child)::afterFooter dot drawn by footer li::beforeSame rule, new markup
Plate hover through outline-colorPlate hover through filter in (hover: hover)Same rule, new markup
One gradient, the banner mask, onceAn exact list of two masks (banner and bar-2 fade), each once with and once without -webkit-Same strength
No backslash in CSSNone except content: "\00b7" (the middle dot)Tightly bounded
a:focus-visible outline in the accent:focus-visible outline in the accentCovers every element
Plate grid auto-fill minmax(240px)12-column rows, a 3-column plate grid, 1 column below 520 px. In the browser, equal image heights and gaps in every gridChecks the layout itself
No nowrap anywhereIn the browser, no element past the right edge outside a scrolling or clipping box, at 320 to 1920 px. The old sideways-scroll check is keptThe design needs nowrap for hyphenated words and facts; this measures the overflow nowrap could cause
<source> forbiddenAllowed only inside <picture>, as image/avif with a srcset. Every srcset URL must resolveBounded
og:image is the banner at 1408 x 469og:image is og.jpg at 1200 x 630, size checkedCorrect social size
Line and name paragraph side by sideThe house line in the house face, exact. The build rejects a blurbThe blurb was removed by the approved design
Exact markup of bar, footer and platesExact markup of bar 1, bar 2, footer and plates. Latest, the houses row and every facts line must match the fetched dataAdds the live data
Self-test: a site renamed loom-x passesRemoved. The gate runs every check on three houses, with three names and three facesA house is now tied to its name through the houses row, so a lone rename no longer builds

New checks:

  • Spacing scale (only --sp-* tokens in margin, padding, gap and insets).
  • One h1 and heading order.
  • Banned words.
  • homebrew-tap.
  • 404 addresses from the root, and a 404 served at a nested path loads its fonts and images.
  • The build fails when the fetch fails or the facts file lacks a project.
  • Latest has no repeat.
  • No facts line wraps at 1280 px.
  • axe-core (MM_AXE).

Added after the first review:

  • Every AVIF and JPEG must decode, with Pillow, to the size it declares.
  • An empty index.html or 404.html fails.
  • Each record of the facts file is checked before use.
  • site.json and allow.json must agree on the theme.
  • A group may not take the id of a built-in section (Latest, the houses row).
  • Every style block of the 404 page must load from the root.
  • The -rs repositories of the other houses are known names.

The self-test has 338 cases.

Proof

Generator head d171410a9ca1af0c280c949c404295309057e483. Gate, with MM_CHROME and MM_AXE set:

FETCHED
DETERMINISTIC
BRAND SKIPPED: set MM_FONTS=brand-fonts to check brand/
SELF-TEST OK (338 cases)
OK
SHOTS OK (9 renders)
OK
SHOTS OK (9 renders)
OK
SHOTS OK (9 renders)
HOUSES OK
grep clean

Contrast (WCAG ratio):

Housetext / ground (7)muted / ground (4.5)text / surface (7)muted / surface (4.5)accent / ground (3)
machine-made16.585.8415.415.434.35
openfluids16.126.1114.905.659.64
BoringQuantSystems17.066.0116.155.6811.52

axe-core 4.14.1, at 1280 px: 0 violations on each home page and each 404 page (machine-made, openfluids, BoringQuantSystems).

Lighthouse 12 (performance / accessibility / best practices / SEO), served from a local folder:

PageMobileDesktop
machine-made100 / 100 / 100 / 100100 / 100 / 100 / 100
openfluids100 / 100 / 100 / 100100 / 100 / 100 / 100
BoringQuantSystems100 / 100 / 100 / 100100 / 100 / 100 / 100
machine-made 404100 / 100 / 100 / 100100 / 100 / 100 / 100
openfluids 404100 / 100 / 100 / 100100 / 100 / 100 / 100
BoringQuantSystems 404100 / 100 / 100 / 100100 / 100 / 100 / 100

Bytes loaded per page, after scrolling to the end:

PageFontsImages at 390 pxImages at 1280 px
machine-made48,828135,55586,298
openfluids74,844155,031119,712
BoringQuantSystems60,40854,73058,958

Shots, opened and checked by eye: shots.py writes home-390.png, home-1280.png, 404-390.png and 404-1280.png for each house. Each page shows bar 1, bar 2, the banner, the line, Latest, the groups, the houses row and the footer, with no overflow.

Pixel comparison of each built page against its approved page: full page at 1280 x 900, device scale 1, lazy images loaded, a pixel counted when its summed RGB difference is over 24.

PageHeight built / approvedDiffering area
machine-made2532 / 2532 px0.000 % (0 px)
openfluids2264 / 2264 px0.000 % (0 px)
BoringQuantSystems1384 / 1384 px0.0005 % (8 px, rows 68 to 72: the 28 px bar-2 avatar, scaled here from the 360 px avatar, while the approved page used GitHub's 56 px copy)

The houses built from this head are byte-identical to their copies in the two house repositories (hash lists in those PRs).