Design system of primitives

The canonical, approved boas.dev primitive set (v3.5.0) — every component below is the live kit (boas-dev/brand/boas-kit.css + boas-vars-*.css + boas-filters.svg), not a copy. This document IS the reference; surfaces consume the kit, never reverse-engineer it. Ruled in the operator canon-curation session 2026-07-09. Flip dark/light — a mode change is paint-only.

01 Colour tokens — two poles

Everything resolves through the --c-* role cascade. The system is two poles: a blue STRUCTURE pole (frames, linework, dots-on-red) and a soft-red ATTENTION pole. The contrast rule pairs them — edge one pole, fill the opposite.

Blue — structure pole

--c-primaryazure

--c-primary-brightice / live

--c-primary-deepframe border

--c-primary-abyssaccent border

--c-accentarc / cyan

Red — attention pole (soft; danger by colour, never a louder hue)

--c-redclay

--c-red-brightrose

--c-red-deepred frame

--c-warningalert amber

Surfaces + text

--c-bgvoid

--c-bg-raisedpanel

--c-text-primarybody

--c-text-mutedmeta (chrome only)

No grey-on-dark for text (#4a4a4a banned). Body ≥ --c-text-primary; meta ≥ --c-text-muted, chrome only.

02 Type · geometry · motion

Two faces: Bricolage Grotesque (display / human voice) + JetBrains Mono (data / chrome). Radius 3px (max 5px). Motion: --t-fast 120ms · --t-med 240ms · --t-slow 480ms; the edge breathes at 5.2s.

Bricolage Grotesque

display · headings · human voice · 600 weight, tracking −.015em

JetBrains Mono 0123

data · chrome · labels · tabular numerics

Reading tiers

14px — body / lede (--fs-body)

13.5px — dense reading (--fs-read)

11px — detail / caption floor (--fs-detail)

10px — chrome label (--fs-label)

03 Edge primitive — .edge

The house signature. A scoped ::before carries the warped frame (feTurbulence → feDisplacementMap), an ::after carries the always-on halftone, content rides sharp above. Structural variants flip the contrast pole; the FRAME character is a separate axis (§04).

.edge

Default

quiet blue-structure surface

.edge--frame

Blue-pole emphasis

blue frame · red ground · blue dots

.edge--inv

Red-pole (inverse)

red frame · blue ground · red dots

.edge--quiet

Quiet / nested

softer ground, hairline

.edge--next

Upcoming / active

blue frame accent

.edge--past

De-emphasised

transparent ground, recessed, dots dimmed

04 Edge character → role

One engine, many characters. The same feTurbulence-displacement engine produces different boundary characters by baseFrequency/scale. Ruled 2026-07-09: map a character to a role — never scatter or "pick one". House #edgeLive is the default (cards/dense).

.edge--hero

Hero / dossier

deckle torn-paper edge — front page, cover, featured

.edge--live-roll

Live / now

heavy rolling audio-viz warp · hover to stabilize (still shimmers)

.edge (house)

Cards / dense

calm breathing edge — the default, everything unassigned

.edge--aged

Past / aged

particle dissolve — decay / archived

Available — role-unassigned

--edge-whisper

Whisper

near-crisp

--edge-ridge

Ridge

topographic

--edge-strong

Strong

assertive frame

05 Fills

The interior texture. Plain flat fills are banned on screen — every surface carries texture. Ruled 2026-07-09: house halftone is the default; grain, hex, coarse are kept options; dither/contour/paper disqualified; scanline/phosphor/chroma stay v3-retired.

.edge::after

Halftone

default

--grain-sprite

Grain

atmosphere

lattice

Hex

schematic

.edge--coarse

Coarse

hero

Disqualified: dither · contour · paper. Retired (v3 drift signatures): scanline retired phosphor retired chromatic-split retired.

06 Button — Corner-Bracket Console

The only button. No full border — blue corner ticks frame a red halftone fill block; mono uppercase label. Hover pushes the brackets out + energizes the fill edge. The contrast rule made literal: blue ticks ↔ red fill.

✗ Banned antipatterns — "we never do those"

solid single-fill button — flat azure/brand block, dark text (the retired plain button)
outline / bordered pill — border + transparent fill, rounded
bracketed flat pill — "[ LABEL ]" text-brackets over a plain fill (incl. email)

Email tier: the console is delivered as a pre-rendered raster of .btn (feTurbulence can't run in mail) — never a flat pill echo.

07 Controls — .field · .otp · .slot · .notice

The transactional family. Warp discipline: controls stay CRISP — the only in-control warps are the two sanctioned callouts: an .err field and a focused control (§08).

Email EmailThe only warped control — a deliberate callout.

Verification code

Check your emailA 6-digit code confirms your booking.

Code expiredRequest a new code to continue.

08 Focus — energized edge

Ruled 2026-07-09. On focus the frame ramps to #edgeHot — it breathes harder. No ring. The surface itself signals focus, reusing the hover/live grammar. Reduced-motion falls back to a visible ring (a11y). (Focus the field / tab to the button to see it energize.)

Field — click to focus

Button — tab to focus

09 Danger — colour-led

Ruled 2026-07-09. Danger reads by the red pole — red frame · warm-red ground · red halftone · red heading — on the calm house edge. The old solid double-stroke and the fragile distress warp are removed. Optional escalation is an orange "irreversible" tag in content, never a ring.

.edge.danger

Cancel this meeting?

colour-led · no solid ring · calm edge

Irreversible

Booking failedThe slot is no longer available — pick another time.

10 Medium tiers

The same identity across three delivery media. The procedural edge runs live on the web; degrades to static for print; rasterizes for email.

Web — full

Live #edgeLive breathing edge + hover energize + halftone. The reference render.

Web — degraded + print

Reduced-motion → #edgeStatic (no animation), focus → ring. Print → flatten warp + halftone, WHITE ground (PDF is print material).

Email — hybrid (inline-only tier)

feTurbulence can't run in mail. Light deliverability body + a dark pre-rendered procedural band PNG (carries edge+halftone) + a bulletproof rastered console button + the azure 4px left-tick readout (the sanctioned mail echo of the blue-structure pole) on ice body, never white. See boas-dev/reference/email-hybrid-partial.html.

11 Laws

1Contrast rule. Edge one pole, fill the opposite — blue↔red. The dots ride the edge pole; the ground rides the opposite. Plain fills banned on screen.

2Warp discipline. Edgewarp is a sparingly-used attention highlight — one per surface. A warped container does NOT warp its nested edges (no double-warp). The only in-control warps are the .err callout and focus.

3Paint-only mode flip. Everything consumes the --c-* role cascade; data-mode="light" re-resolves colour only — identical DOM, motion, geometry.

4Danger by colour, not hue-shout or gimmick. Soft red pole carries danger; no louder red, no solid ring, no fragile warp.

5One button. The Corner-Bracket Console is the only button, every tier. Banned antipatterns never appear.

6Consume, don't reverse-engineer. Surfaces import the kit; they never pattern-match tokens off a render. This document + boas-dev/brand/* are the SSOT.

boas.dev design system of primitives · v3.5.0 · canon-curation 2026-07-09
SSOT: boas-dev/brand/boas-kit.css · boas-vars-{dark,light}.css · boas-filters.svg — this doc renders them live.