patterns.gf.cx · the pattern library
The gf.cx specimen book — named moves that raise the floor
New here? Start with Why patterns — the frontispiece essay tracing the idea from Alexander (1977) through the Gang of Four (1994) to directing AI agents.
affordances drifting out of sync
A ↑ top affordance that appears only when a page earns it — one shared script, runtime scroll-height gate (scrollHeight ≥ max(1400px, 2.2×innerHeight)), injected once, works everywhere. Singleton-guarded, no-op if a hand-wired a.backtop exists. Two vectors: sweep for hand-authored pages, generator wiring for generated surfaces.
Small inline pills embedded mid-row that tag a data point with its origin — country, UA, or source — without a drill-down. The qualifier sits in the field with the field it qualifies.
A small mono uppercase pill that signals a record's state. Two flavours from one primitive: a fixed lifecycle vocabulary (neutral / alert / resolved / service / warning), and an urgency gradient where the band is computed from time-to-deadline — one pill walks green → amber → red as a due date nears, then flips to red OVERDUE N. The urgency flavour is emitted by the maintenance-timer, with a weeks-days data-tip countdown.
A number that drifts with time (“742 days and counting”) is computed in the browser from a fixed day-0 anchor, with the printed value as the no-JS fallback. There's no republish cron to bump it, so no missed run can leave a stale number showing green. data-unit varies the reading (days/weeks/months/years) from one anchor, and a MutationObserver picks up late-added nodes so the counter works inside cloned markup like the made-with footer. Only live totals go dynamic; fixed historical markers stay hard-coded.
The CSS-only data-tip tooltip is text-only — no HTML, no links, no interactive elements. data-tip-href upgrades a glossary term into a JS-powered card with a clickable "Learn more" link, held open by a 120ms delay so the cursor can travel from trigger to card. Its placement reads the room — above by default, flipping below when a trigger sits too high.
A <select> can't search and a long static list stops scaling past ~15 options — and hand-rolling a combobox per surface (keyboard, focus/blur races, aria, click-outside) is exactly the drift the shelf kills. The type-ahead picker turns a labelled list into a searchable combobox where the value rides the label and member names are search aliases: type 'iberia' and land on Avios, 'klm' on Flying Blue, 'AA' on AAdvantage. One behaviour, one shelf source, mounted with a markup skeleton plus one Typeahead.mount() call.
A CSS [data-tip] primitive and server-side annotator that wraps jargon terms in themed hover definitions — FCP, LCP, CrUX — inside reports and dashboards. No JS required for the base pattern; one stylesheet import.
The 'good-map' pattern for placing a facility in a location dossier: a three-beat sequence — aerial → close-up hover → street-view. Two duality axes: (A) for maps, reverse the hover so it starts on the close-up and zooms OUT to the wider context; (B) street-view either deferred (.svfacade, click-to-load) or always-on (.embed3d). An optional fourth beat dreams the Street-View still into a Studio-Ghibli twin on hover (image-to-image via fal.ai FLUX Kontext). One CDN css+js, themed off local vars. Lifted from srvc.gf.cx/transit.
A staggered wink applied to a row of sibling icons: each glyph pulses in sequence via nth-child animation-delay, turning static decoration into a quiet surface heartbeat.
A thumbnail that earns a click opens one shared enlargement modal (lightbox) — image or inline <svg> — with caption, closable by ×/backdrop/Escape. The overlay DOM injects itself on demand; mark any element data-modal and it's keyboard-native. One CDN-hosted css+js, themed off local vars. The favicon-control-plane model applied to media enlargement; lifted from the bespoke modal on srvc.gf.cx/transit.
When a section grows its own sub-pages, the parent stops being prose-with-links and becomes a visual index — a responsive grid of linked cards, each a square thumbnail, a serif title carrying a → affordance, and a one-line blurb. Shipped as the assets.gf.cx/cards .card--index variant; first used on abbeyroad.gf.cx /future/kitchen/ to index five appliance deep-dives.
A solid-green gate-hero carrying an action window paired with a UTC-anchored multi-row timeline, live now-tick, and clickable zone overlays. Flips to a shared charcoal field when the window is closed.
Turn a bare backup count into a native <details> accordion + HTML dot-timeline — one dot per point-in-time copy, placed by true date, each with a data-tip hover readout ('3 days ago · 3rd August 2026'). A count says 'backed up'; the timeline shows how deep the safety net goes and when it got regular.
A vendor-hosted HLS video player with word-by-word karaoke captions, a CC toggle, and a click-to-seek transcript — synced to true player position over the Player.js postMessage protocol, with a self-demoting wall-clock fallback for environments where the protocol can't connect.
Pick one unit and you shut out half the audience; add a °C/°F toggle button and you clutter a calm almanac with chrome nobody asked for. Let the number re-express itself instead: an odometer roll where each digit spins through the values between its old and new place and the unit letter flips with them, so the reading quietly recalibrates from 14 °C to 57 °F and back on a shared cadence. Three treatments were explored — crossfade-and-rise, mercury-tween, and the odometer — and the odometer won for reading as an instrument register that fits the Barometer skin. Falls back to a static "14 °C / 57 °F" under prefers-reduced-motion.
voice & format drift
Compose how-to and advice articles as a thesis plus 3–4 imperative micro-moves — each subhead is independently skimmable, the set rolls up into a single takeaway. The structure that lowers the bar to write and raises the value for the reader.
Superscript markers link to a numbered list at page foot — collapsed rows show one keyword each, opened bodies lead with the full title. Two type signatures (red italic + bold) carry distinct emphasis weights through the annotation.
A figure baked into a page — a restated price, a depreciation %, a score — is opaque: the reader can't see how it was derived or check it. The how-we-calculate pattern gives the calculation its own page (formula, exact inputs, worked arithmetic, why the inputs are frozen) and links the figure to it via the interactive tooltip's 'Learn more ↗'.
One block on a page — a chart, a table, a map — needs to be wider than the prose around it. Publish the container's side padding as a --page-pad custom property and let the child cancel it, instead of hard-coding a negative margin that silently desyncs the day the padding changes. Print, which zeroes the padding, collapses the bleed for free.
The dare.co.uk report masthead drifted into an oversized italic serif h1 that fought a solid, sans-bodied report. Three live header specimens on the shared page-header primitive — sans, upright serif, canonical italic — to compare and graduate. Specimen B shipped corpus-wide; page-header v0.2.0 gained the title voice + colour-chip variants.
The portfolio has one warm, editorial voice (Atkinson + Newsreader). Client-handoff and spec surfaces want a second one. type-bold distils Outfit display + Inter body on a 1.125 modular scale from two references — type and structure only — into a drop-in shelf that re-voices a whole surface by redefining the shared type tokens.
A dark-mode pitch-deck visual language — ten design tokens from near-black field to icy-blue accent, three-tier typography, five-move narrative architecture, and six reusable slide layouts. Extracted from the YouExec Hardware Innovation deck; travels wherever investor credibility is the load-bearing requirement.
A telemetry or records page that opens as a summary — the load-bearing status stays pinned up top, every section is a collapsed-by-default disclosure fold with a left bird-beak marker, an expand-all control sits under the strip, and the build-provenance stamp folds into the Built-with footer. Two shelf primitives, ledger.css and ledger.js, so no surface hand-rolls its own accordions.
The running "Session notes" lane — a JSON-driven, single-source ledger of what happened and what's owed next — codified as a portfolio standard. Append to a notes JSON, never hand-edit HTML; each note renders as a collapsed accordion with a two-line header (mono date/tag line, normal-weight title beneath); the lane is deep-linkable with the visible "#" chip purged (visibility null, use retained); an empty lane removes itself. One shelf file, session-notes.js, so no surface hand-rolls its own notes lane.
Every surface grew its own /new index with a hand-inlined sort script — happiness and growth carried one copy, brand a namespaced variant, patterns an extra sequential sort and a plate badge, home a status-pill grid. They drifted. The fix is one shelf: an inline sectional-JSON blob plus new-index.css and new-index.js, which render the list, a lines/cards view toggle, and a grid-parity sort where every key is a ▲/▼ direction toggle with per-key memory. A superset render folds every surface's varying fields (plate, upgraded, status pill, category) into the one file, so no surface hand-rolls its /new index again.
A /new index auto-generated from a JSON blob has no per-item art, and cards with an empty description render as blank real-estate. Give each card a deterministic SVG field instead: eight abstract motif families (signal, route, strata, network, lattice, ledger, frames, bloom) assigned by what the section MEANS, seeded by the slug via FNV-1a + mulberry32 so a demo always draws the same art, colour de-collided by per-family index so same-family siblings never twin, and a quiet machine-derived line where the description is empty. Delivered as one opt-in shelf asset that layers over the what's-new index without touching it, with a first-class muted mode (accent + gold only, softened) for reference surfaces that need to be easy on the eyes.
stale-green, unproven paths
A read-only page that classifies every item in a corpus on two axes — how far it got down a pipeline, and what it is or where it landed — then renders the flow as white stage cards and the outcomes as a colour-coded funnel where green-to-red carries meaning. It is a census, not a sample: it counts and names what fell out, and moves nothing. One generator emits both the data (audit.json) and the page, so the census is reproducible and can never go stale-green.
An aggregate metric — bytes stored, object count, index size — jumps, and the sparkline shows THAT it moved but not WHAT changed. The decode-the-jump pattern periodically captures a content fingerprint (a by-group manifest: count, total bytes, average size per file type), keeps a short manifest history, and diffs the two most recent captures to itemize the delta — the before/after answer to the mystery. The cheap aggregate metric is itself the trigger: a bucket is re-fingerprinted only on the runs where it actually moved.
Every gf.cx surface ships diagnostic probe endpoints — /ip, /cf, /trace — stamped in by the scaffold. The quarantine panel filters them out of reader analytics and surfaces them in a compact, collapsible instrument: status dots, measured request counts, country-of-origin chips, and scanner-UA classification, worst verdict pinned to top.
Counting physical things one at a time doesn't scale — a QR is a per-item scan, an NFC tap is one item at a centimetre. Give each item a bulk-readable identity at intake instead: a UHF RAIN tag whose EPC is an opaque id.gf.cx ref (the chip's TID as backup key, mirrored EPC↔ref↔TID in KV). Then one sweep reconciles a whole box, shelf, or room against its manifest — present / missing / misplaced / unresolved. Encode once at print (tagging is a side-effect of labelling, not a separate chore); read many forever after; and fail loud when a sweep comes back empty, because a zero-read is a reader failure, never an inventory of absence.
A failing or at-risk item on any surface should be one click away from a durable, trackable investigation. One shared script, one central endpoint, a data-flag-* contract — drop a flag anchor anywhere and it files a dedupe-aware GitHub issue plus a push, no per-surface wiring.
On a status board, a failing asset's detail page carries a collapsible panel that surfaces the attributed failure point — which audit flagged it, the signature, the restore verdict — and hands the operator a copy-ready, asset-scoped agent brief to paste into an AI coding agent. Native <details> reveal, zero JS; shown only where there's something to fix.
An R/Y/G collapsible status block that turns an operator README into a live session-log — colored-dot tier headers, count summaries per panel, done items kept with dates, and a how-to-fix sub-line per open item.
Every vendor integration gets a self-contained sandbox surface first — sandbox credential, full round-trip, proved end-to-end. Only then does the production credential wire in. Keeps secrets isolated, experimental wiring contained, and the integration's edge-cases out of the live order path.
"Looks good from here" is not deploy verification. An independent witness on a third-party network answers two questions in one shot: does it resolve from outside, and does the rendered page look right?
the same edge, the hard way
Export one BASE_URL constant from one shared module. Binding day = one-line edit + redeploy. Prevents the hand-find-replace that always misses at least one hardcoded preview URL.
A gf.cx subdomain fronted by a non-Cloudflare CA (AWS ACM → Amplify, CloudFront, ELB) can't get a cert: the apex serves Cloudflare's auto-managed CAA set, and CAA resolution walks UP to it for any subdomain lacking its own CAA — so a CA that isn't on that list is refused. The fix: give the subdomain its OWN CAA record permitting the CA. Resolution stops at the first name that has CAA records, so the walk never reaches the apex — zero blast radius on the rest of the zone.
A Cloudflare Pages project with a _worker.ts + assets binding looks like it should serve dynamic routes from the Worker and static files from the asset layer. In practice, browser navigations…
where a thing lives, moving
A path token that already appears in an ancestor segment says the same thing twice — library.gf.cx/psp-discs/psp-2026-08/ carried "psp" in both the folder and the slug. Carry each identifying fact in exactly one place along a path; a container never repeats itself in its members. Prune the echo, keep the anchor: lean in context, self-describing out of it. Bake it into the scaffold with a lint so new surfaces are born lean, not trimmed later.
An external resource whose canonical host keeps dying — takedowns, mirror rotation — should not be hard-coded on the page. Link instead to a request-time resolver that probes the mirror set and 302-redirects to the first live host. The page carries no host and self-heals as mirrors rotate; it gets stronger as you add mirrors. Remove the coupling, not the component.
Keep the taxonomy, add a memorable door. A short vanity alias 301-redirects to the deep canonical path — so crawlers and sitemaps get the structured URL while humans get the one they actually remember.
QR-encoded asset tags need to be dense (a phone camera reads /1042 faster than /sennheiser-hd-560s-headphones) and re-assignable. Both forms are first-class peers in the Worker — neither redirects to the other. Canonicalisation happens at render-time, not routing-time.
bytes moving through a distant sink
A remote object store fronted across an ocean (OneDrive's Singapore geo, pulled from NJ) costs per-request round-trips, not bytes: large files stream near line-rate but a long tail of tiny files collapses to ~100 KiB/s at ~135 ms RTT. Three moves fall out — store packed blobs not loose trees; hold concurrency low (more parallelism trips the per-drive 429 throttle); and for a big pull do the file-work on a VM in the store's own region, then ship one packed blob home. The cost is round-trips, so kill the round-trips.
surfaces shipping under-finished
Every gf.cx surface shares one warm-paper editorial base: the portfolio tokens plus the prose spec, shipped as a single stylesheet on the assets shelf. A surface links it once and re-skins with a one-line override like :root{--accent:#1f3a5f}. It never inlines a copy of the tokens, which is the drift this kills.
One script encodes the current state of what a fresh gf.cx subdomain looks like: Pages project, custom-domain binding, five-layer UX baseline, CF Access, diagnostic probes, and og:image capture — all injected at scaffold time so every surface ships finished, not minimal.
A surface built before the canonical page template drifts — wrong fonts, bespoke header CSS diverging page by page. The fix isn't to rebuild each page by hand; it's to retrieve the existing pattern (the template) and re-home the page's content onto it, preserved byte-for-byte. Reconciliation is retrieval, not reconstruction.
A page regenerated from data overwrites anything you hand-add to it — the tempting one-off paste into the rendered HTML is gone by the next build. Durable content lives in the generator: emit the section from the renderer that owns the page, gated to the one surface it belongs to (grep the siblings to prove containment), and rebuild it as native shelf markup rather than a screenshot. The render is the source of truth; edit the press, not the print.
A neutral, brand-aligned social-card image for pages whose content is known to be incomplete — archive stubs, pending-recovery placeholders. Sits in og:image so social shares stay coherent without faking an article hero.
A repeated page type — three vehicle pages, six dashboards, every product page — has a structure, but it lives only in the files themselves, kept in sync by hand. Publish it as a spec the generators read and an audit can fail on, and the copies stop drifting apart in ways only a human reading all of them could catch.
keeping the library honest
The library's frontispiece essay — what a design pattern is, traced from Christopher Alexander (1977) through the Gang of Four (1994) to directing AI agents (2026), and how the gf.cx library frames its own operating patterns against that lineage. A named move can be catalogued, searched, cited, taught — and requested precisely; the same skeleton (context, problem, forces, solution, consequences) survives the jump from code structure to shipping surfaces.
The primitive every pattern entry on patterns.gf.cx uses to show rather than tell — a sandboxed live demo beside tabbed HTML/CSS/JS source, authored as <template data-tab> fragments inside one <div class="pattern-preview">.
brand.gf.cx assembled in one session from the portfolio patterns — gfcx_subdomain_new.py scaffold, five-layer surface baseline, site.config.json, smart-404, social card, and a first piece of content ingested and footed with the built-with primitive. The clearest proof these patterns travel.
A human sitemap page — a dare.co.uk/sitemap-style 3-column ledger — whose structure AND per-family counts are GENERATED from the corpus's own meta.json files via a fail-loud taxonomy validator. Every pattern slug must be mapped into exactly one family; the generator refuses to emit until a newly-shipped pattern is categorised. So the map can never silently drift from the library: single-source, anti-drift, self-referential (this pattern counts itself into Foundation > Meta).