Primitives

Atomic building blocks composed into larger components.

Button The primary interactive affordance. Read section
Colour Clock The connection between viewer and maker. Read section
Icon SVG icon from the Phosphor Light set. Read section
Label Compact inline metadata — a token reference or a cross-link, set in mono inside a hairline outline. Read section
Mark The square image that identifies something: a headshot, a logo, an app icon. Read section
Media Presents media with grid-aligned height, or fills a caller-sized container. Read section

Button

The primary interactive affordance. Drives navigation and actions across the site. Five variants — ghost (default), action (filled), cta (circular accent disc), disc (the same circle in surface, for a secondary route standing next to a cta), toggle (ghost with the box removed, for a state control that must not read as a third button).

Show me ↗

Foundations

Typography body-mono
Colour accent ink ground surface ink-secondary border
Spacing space-within space-related cell

Behaviour

Contains Icon
Used by Nav ClockGroup
Rolebutton | link
KeyboardEnter/Space activate; focus-visible ring uses --accent
WhenAny clickable action — navigation links, form submits, CTAs. Choose variant by prominence: cta for page-level primary, disc for a secondary route that has to sit beside a cta, action for section-level, ghost for inline/back nav, toggle for a two-state control whose state is the whole message.
Not whenCard-level click targets where the entire card is interactive — use the card's own link wrapper instead.
PreferSummaryCard or SpotlightCard for case study navigation
One CTA variant per viewportMultiple accent discs compete for attention and break visual hierarchy
A disc variant needs an aria-labelIts label is one or two characters chosen to fit the circle — "DS" names nothing read aloud
Always provide href or button typeRenders as <a> or <button> — never an unsemantic element
Put visible text in the default slot; label is a cursor hint and becomes the accessible name only when the slot is emptyThe prop is interaction metadata, not a second way to render button copy

Colour Clock

The connection between viewer and maker. Time of day generates every colour on the page.

00 06 12 18

Foundations

Colour ink accent border ink-secondary surface
Spacing clock-size

Behaviour

Used by ClockGroup Colour
Roleslider
KeyboardArrow keys scrub time, drag to adjust. Specimen mode is a labelled image, not a control.
WhenNever instantiate directly — the live dial is a singleton in the Nav. On /system, mount it with the specimen prop and a unique clipId.
Not whenDon't add a second live instance anywhere.
One live instance per pageMultiple live clocks would fight over CSS custom property writes
Documentation renders use specimen mode with a unique clipIdA specimen is a static, non-interactive drawing at noon — no data-clock hook for the script to bind, no slider role, and its own clip-path id so the SVG stays valid alongside the live dial

Icon

SVG icon from the Phosphor Light set. Uses fill-based paths on a 256-unit viewBox, matching Pentameter optical weight.

Foundations

Behaviour

Used by Button ClockGroup Media Project System Section SystemTopNavBar SystemSidebarNav Iconography
Rolepresentation (aria-hidden)
KeyboardNone — decorative
WhenInline icons alongside text. Always pass a size prop.
Not whenStandalone illustrations or logos — use an img or inline SVG.
Always set size propDefault 14px may not match context
Add icons to src/lib/icons.tsRegistry is the single source — no inline SVG paths in components

Label

Compact inline metadata — a token reference or a cross-link, set in mono inside a hairline outline. Optional href. It carried an optional icon and listed status indicators as a third job until 2026-08-05: the /system status badge was the only caller that ever passed an icon, and when that badge went the prop had nothing left exercising it but its own specimen, so it went too.

space-inset accent Nav

Foundations

Typography body-mono
Colour ink-secondary border ground ink
Spacing space-within

Behaviour

Used by FoundationsBlock BehaviourBlock
RoleWhen href: link. Otherwise: static text.
KeyboardWhen href: focusable, Enter to follow.
WhenCompact metadata — token references and component cross-links.
Not whenInteractive chips, toggles, or buttons with actions.
No semantic colour variantsA label is metadata, not a state: it names a token or points at an entry, and neither of those is a thing to be green or red about. The reason used to be that the icon communicated status instead of the background — both halves of that are now gone, and the rule survives them because a coloured chip would still be the label claiming a meaning it does not have
Text and an optional link, and no third affordanceThe icon prop was that third thing. It existed for one caller — the /system status badge — and outlived it by nothing: FoundationsBlock and BehaviourBlock, the two components that actually render labels, both pass text and an href and never passed an icon. A prop kept alive by its own specimen is a prop the system is demonstrating rather than using

Mark

The square image that identifies something: a headshot, a logo, an app icon. It is one square in two sizes, and the picture either fills it or is inset on a surface tile — that is the whole model. It exists because the same square was being declared six times across Identity, SummaryCard and Byline, each with its own height, its own tile rule and its own copy of the day/night swap, and every one of those declarations drifted from the others. A mark that is 24px in one block and 48px in another is not a size decision anyone made; it is the arithmetic of three components each sizing from something local.

Tenon GSK Alan Long Expedia

Foundations

Colour surface
Spacing space-within cell

Behaviour

Used by Identity Summary Card Byline System Section
Roleimg
KeyboardNone — a mark is never focusable; anything interactive is the element around it
WhenAny square image identifying a person or an organisation — a headshot, a logo, an app icon.
Not whenA logo sitting inside a line of body copy — that is .inline-logo, sized in em against the text around it. Project imagery — use Media. A decorative image that is not square and does not identify anything.
PreferIdentity over Mark directly wherever the mark has a name beside it — Identity owns the size rule that follows from the label
Two sizes and no third: standard is 1.5 cells, large is 2Both are line boxes, not avatar sizes. 1.5 cells (36px) is the .t-heading-lg-mono line and a single .t-body-mono line beside a mark; 2 cells (48px) is two stacked .t-body-mono lines. A third size would have to be measured against something, and there is no third thing a mark sits beside
No per-instance sizing prop, and no way to nudge one square off the pairThe six declarations this component replaced were all per-instance exceptions that each looked reasonable alone — a one-cell chip here, a zeroed inset there, a logo_scale field in the content schema. Together they meant no two marks on the page agreed. The size is chosen by the caller from two named options and by nothing else
fill vs inset is stated by the content, never derived from the file extensionThe rule this replaces read "a raster logo takes the tile, an SVG does not", on the theory that an SVG recolours with the clock. It cannot: loaded through <img src> an SVG is an isolated document with no access to the page, so it can never inherit currentColor — and none of the logo SVGs in /public/logos use currentColor anyway; they all carry hardcoded fills. What actually needs the tile is transparency, which is orthogonal to the format. tenon-icon.svg is the proof: a solid-ground SVG that must fill, exactly the case any extension heuristic gets backwards
inset holds the mark off the tile by --space-within, and that value is the same everywhereThe inset is the tile's relationship to the thing on it, and that relationship does not change with the size of the square. A per-size inset would be two tile treatments wearing one name — which is how the old one-cell chip ended up with its padding zeroed to stay readable
A mark drawn in a single ink supplies srcDark; both are rendered and the theme picks oneGround is time-derived, so a wordmark legible at noon can be invisible at night. The swap is display rather than opacity so the hidden half takes no space in the row it sits in. This is the one copy of that swap for square marks — .inline-logo in utilities.css keeps its own because it is em-relative for a logo inside a line of body copy, deliberately off the grid
alt describes the mark once; the night half is always silentThe pair is one mark rendered twice for the clock, not two images. Announcing both says the same company's name twice with no way for a listener to tell it is a repeat, which is what the SummaryCard pair did before it came through here

Media

Presents media with grid-aligned height, or fills a caller-sized container. Surface variant pads and mounts on a backdrop; fill variant lets the image go edge-to-edge with the container snapped to the nearest grid line; card variant drops a bare, edge-to-edge image/video into the caller's own layout (e.g. a homepage card) with no figure chrome.

Foundations

Typography body-mono
Colour surface overlay-ink overlay-ink-bright overlay-scrim overlay-scrim-heavy
Spacing space-within space-related cell

Behaviour

Contains Icon
Used by Project SpotlightCard
Rolefigure (surface/fill) | none (card)
KeyboardLightbox trigger is a button (Enter/Space opens the full-screen viewer); replay/play is a button. Card and non-lightbox media are presentational.
WhenProject pages — any image or video (variant="surface"|"fill"). Fixed-size card slots — e.g. the homepage SpotlightCard — use variant="card".
Not whenInline illustrations or icons that don't need a figure wrapper — those stay on plain <img> (e.g. SummaryCard/Hero logos, Identity avatars).
Alt text is mandatory; caption is optionalEvery image needs alt text for screen readers; a visible caption is only meaningful where the layout has room for one (omit for card variant)
The caption wraps and is never truncatedIt was nowrap with an ellipsis, which cut every case-study caption mid-sentence at narrow widths — six of six on /project/google at 390px, one of six still at 1440px — leaving the full text reachable only by opening the lightbox. The grid snap models a one-line caption (CAPTION_PX), so a wrapped caption puts its figure a cell below where the snap intends; that is the accepted cost, because the snap exists to regularise the composition and a sentence the reader cannot finish is content thrown away rather than a composition being tidied
Height snaps to the cell grid only where the container is a known cell countSurface uses padding; fill uses object-fit cover with a snapped container height. Both snaps model the container as a cell count, which is exact above the composition breakpoint (.col-reading is a fixed 40) and a guess below it, where the columns run 3 / -3 and track the viewport. Fill is the variant where a guess does damage — it crops to the height it was given, so a count modelled on a 960px viewport showed 73% of the image at 1319 and 43% at 799. Below the breakpoint the fill frame takes the image ratio instead and is not snapped. Surface keeps its per-band adjustment because it pads rather than crops: being off there costs a fraction of a cell of position, never a pixel of image. Card is unsnapped everywhere and fills whatever container the caller provides.
Videos should provide a posterFallback frame when autoplay is blocked or while loading
Videos default to play-once modePlays on scroll entry, stops at end with replay button (surface/fill only); use playback="loop" for continuous
Autoplay is suppressed under prefers-reduced-motionScroll-entry autoplay is gated on matchMedia(reduce); the video stays on its poster/first frame and the replay button is shown as a manual play control
BREAKPOINTS grid constants must match the CSS gridEach entry resolves to a 24px cell (viewportPx / gridCols = 24), matching the constant --cell in src/styles/base.css. primarySpan (40) must equal .col-reading's span in utilities.css, insetOffset must equal that band's page inset in cells (two between 800 and 1319, one below 800), and the <style> media queries plus lib/cloudinary buildSizes are keyed to the same boundaries (1319 / 799) — update them together if the grid changes. They had drifted: tablet modelled a one-cell inset the columns stopped using, and the lower boundary was still 399 from before the columns split into three bands
Cloudinary image src gets a generated srcsetEvery image src is a Cloudinary delivery URL with one w_<n> transform — srcset/sizes are derived from it, never re-processed through Astro's own image pipeline