Getting started

Paradox Foundational Design System

The single source of truth for Paradox design values on the web (sirius): colors, typography, spacing, radius, and the ds/ components. Every specimen on this site renders from the code tokens themselves — what you see is what ships.

How truth flows

Values are defined once in Figma and travel one way. If two links of the chain disagree, the code token file wins, and the divergence is written down as a DRIFT-nnn entry, which appears where the component sits and in the drift register.

Reading this site

Foundations

Color code truth · 2026-07-20

One warm brand scale — PX Heat — over calm neutral grounds, plus functional palettes. Warmth arrives in touches: heat is an accent system, never a background. Every swatch renders live from the code tokens; click a name for var(), a hex to copy it raw.

PX Heat — the brand scale

Seven steps, 0° → 600°. 150° is burgundy — THE accent: the primary brand moments, charts (via --ds-theme-chart-1…5, never raw heat), badge accents. The numbers are degrees Celsius, not ramp steps: each one is the colour a body glows at 0, 40, 80, 150, 250, 400 then 600 °C. That is why there is no 300 and no 500 — pick a step by the heat it tells, never by arithmetic, and never add one to fill a gap. The reason lives beside the tokens in globals.css.

Functional palettes

neutral · green · amber · red, steps 50 → 950, plus the one-offs --ds-color-black, --ds-color-white, --ds-color-blue-pxs (PXS surfaces only — never a general-purpose blue). Semantic tokens map onto these: reach for --ds-theme-* first, primitives only when no intention fits — and flag it in the PR.

Opacity scales

The board defines six scales × 13 steps (8 → 96%), token pattern {base}-{n}%. In code today only --ds-opacity-neutral-* and --ds-opacity-accent-* exist, at 8/16/24/40/56/72. ⚠️ Steps 72–96 are all bound to the /64 variable in Figma — they render at 64% (marked *).

Alias variables (opacity-*-lighter/light/main/dark/darker) exist on top of the step scales — with inconsistent mappings across groups (exact values read from the master, 2026-07-23): primary lighter = 10% but accent/success/warning/destructive lighter = 16%; light/main/dark = 24/32/40% everywhere; darker = 48% on primary/accent but 56% on success/warning/destructive. Two ladders where the code has one, and the code is the one that ships.

Gradients

Four PX Heat directional ramps + the title text gradient. In code they are @utility bg-gradient-* classes in globals.css — 13 of them with the Navbar/blur/backdrop family — and every heat stop reads a --ds-color-heat-* token, so a burgundy change reaches the gradients instead of stopping at a hard-coded hex. The only raw values left sit in bg-gradient-navbar-background and say why. Displayed large on purpose: a 7-stop ramp is unreadable as a thumbnail. Click a ramp to copy its full CSS. The Navbar/blur/backdrop ramps are still Figma styles in the parent master file — fileKey needed to extract them.

Usage

Foundations

Typography Text board · validated

Two families with a hard pairing rule, one scale from 10 to 128px. Anton is not part of the system: it's a content-only brand asset (thumbnails, video) and never touches product, web or digital surfaces — its former code usages now render Clash since sirius#913. The scale below renders from the live tokens — click a row to copy its size + line-height pair.

Two families

The scale

Traps

Foundations

Spacing 4px scale

A 4px-based scale with half-steps at the low end, plus the non-Tailwind steps 18 (72px) and 22 (88px). Click a token for var(), a value for raw px.

Foundations

Radius & borders validated · 2026-07-20

Ten radius steps, four border widths, six breakpoints — and a per-component radius mapping that is spec, not taste.

Radius

Per-component mapping (ISO-verified): buttons 8px at every size · fields 8/8/6 (sm) · checkboxes 4/6 · message textarea 16 · full is a mobile pattern — no pills on web. Details live in Button § Anatomy.

Borders

Breakpoints

Foundations

Variables Mode collection · dark ⇄ light

The semantic layer exactly as Figma defines it: the Mode collection aliases Fondations tokens per theme — Dark is the default, Light remaps every alias. This is what agents and devs consume as --ds-theme-*. Both swatches below resolve live from the code tokens; click a code token to copy its var(). Groups flagged ❌ unused in Figma (33 + 2 typography) are deliberately not imported, per governance.

Not shown here: opacity scales and their aliases live in Color § Opacity; typography size lives in Typography § Scale; the custom group (8 variables) is not inventoried yet 🚧.

Primitives

Button validated · 2026-07-20

Buttons carry the actions of forms, dialogs, and screens. The web family is a rounded rectangle — 8px radius at every size — with a state system driven by opacity, not by color swaps. Eight variants, no more: there is no outline, no link, and no burgundy button. (Glass taxonomy reworked by Maxime, 2026-07-22: glass renamed glass dark, glass light and glass destructive introduced.)

Variants — the eight families

Anatomy — sizes & content slots

Every button (not icon buttons) can carry a left icon, a right icon, a badge, or a combo — hidden by default behind the Figma properties Left Icon / Right Icon / Show Badge, so they're easy to miss. Slots exist on every variant and every state; geometry is state-invariant (verified on the master — states only modulate opacity). Icons are Lucide, 16px at every size; the badge is the “Glass Badge”: dark 56% pill (opacity/neutral-inverted/56), padding 8/2, radius full, XS 12/16 Medium uppercase, white.

States — an opacity system

States don't swap colors; they modulate the whole button's opacity. Ghost variants add an interaction background on top.

Rest is 1, not .88 (arbitration of 2026-08-26). The board's ladder ran .88 → .80 → 1: the button sat slightly back, dimmed on hover, and came fully forward when pressed. Rest at .88 makes every button's label translucent on every screen, which costs contrast for a nuance nobody reads. Rebased on a rest of 1, the press cannot go above, so it goes below — 1 → .80 → .88. The direction is mirrored; the distinction between enabled and pressed is kept. Checkbox, Radio and Toggle already worked this way.

Glass — the liquid material

Glass exists for actions that float over imagery — the material is the point, and it only reads on a complex surface. Three variants (master's Buttons board, 2026-07-22): glass dark = the “Dark Glass” example of @ybouane/liquidglass, verbatim, radius adapted to 8; glass light = same with brightness +0.3 and a neutral 10% tint layer; glass destructive = light with the destructive-red 16% tint and label. Each variant runs through its five states below, over the WIP artboard’s photo (Paradox App, node 8209:117190). In Figma the variants carry effect style Glass/sm; without WebGL they fall back to the flat recipes below.

/* glass dark — the official "Dark Glass" example, verbatim
   (only cornerRadius adapted: 50 → 8, radius-rounded-field) */
element.dataset.config = JSON.stringify({
  brightness: -0.3,
  blurAmount: 0.25,
  cornerRadius: 8
});

/* glass light — brightness flips to +0.3, plus a tint layer under the
   label: opacity/primary/lighter = rgba(250,250,250,0.10) */

/* glass destructive — light, with tint and label in destructive red:
   opacity/destructive/16% = color-mix(red-600 16%, transparent) · label red-600 */

/* flat fallbacks (no WebGL):
   dark  → radial-gradient(296.68% 50% at 50.25% 50%, white 0→4%)
           + rgba(23,23,23,.64) + blur(4px)
   light → rgba(250,250,250,.10) + blur(4px)
   destr → red-600 @ 16% + blur(4px) · label red-600
   all   → radius 8 · opacity .88 enabled */

PX Heat — the brand effect

An opt-in effect for brand moments — a beta invitation, a launch announcement — and for nothing else. It is not a variant: it is two layers laid over a button, a blurred PX Heat glow behind it and the same ramp travelling around its border. Both turn on one 9-second drift, so they move together instead of beating against each other.

Two things decide whether it is used correctly. The ring paints the interior with the page ground, so the effect replaces the variant's surface — pick the variant for its label and its states, not its fill. And the wrapper is inline-flex, so a heat button does not stretch; give it its width.

The ramp is a palindrome, 600 → 0 → 600. A loop has to close without a seam, and the full ramp jumped from coral to near-black on every turn. It has been animated since 2026-08-24; before that the code asked for a class that exists nowhere in the project, so it rendered as a fixed blur.

Action group

The master's composition pattern for a set of actions: tertiary (ghost) + secondary + principal, optionally paired with 40px secondary icon buttons. The group is modular — 2 or 3 text actions (always exactly one principal), plus 0, 1 or 2 icon buttons. Click a combo to preview it:

Implementation — semantic tokens

The actionable group of the semantic layer backs buttons and inputs. Reach for these before any primitive — a semantic token is an intention. Values below resolve live; toggle the theme to see both renditions.

Primitives

Icon Button validated · 2026-07-20

The compact sibling of Button: a square carrying a single Lucide glyph. Same eight families, same opacity state system, same 8px radius — squares 24/32/36/40 with a 16px glyph (20px on lg). One nuance of its own: ghost focus is a 2px border, not a shadow ring.

Variants — the eight families

Identical taxonomy, identical use cases — see the Button variants table. One square per family.

Anatomy — sizes

States — the same opacity system

Same scale as Button — enabled 1 · hover .80 · active .88 · focus 1 + ring · disabled .48 — with one nuance of its own: ghost focus is a 2px border (--ds-color-neutral-500), not a shadow ring.

Glass — the liquid material

The same three materials as Button — the spec, the playground and the engine recipe live in Button § Glass. Judged over the same artboard photo:

Implementation

src/components/ds/common/IconButton.tsx — same semantic actionable tokens as Button (table here). API: Icon (a Lucide component), variant, size, href. Click any specimen above for ready JSX. Glass variants staged on the sirius branch design/glass-button-variants.

Primitives

Badge Badge.tsx · status dot added 2026-08-17

Badges inform on the status of a piece of data. Seven variants — including the burgundy accent and the px-heat glow, which live here and NOT in buttons — four sizes, two states (default / hover at 80%). Backgrounds are 56% transparent theme mixes with the Glass frost. Click any badge for its JSX.

Liquid glass — over imagery

Badges are Glass Badges: over imagery they carry the exact same liquid material as the glass buttons — engine refraction under their 56% tint layer, pill-radius lens. px-heat is the exception (glow, no glass). Same engine, same playground parameters as Button § Glass.

The px-heat glow recipe: px-heat inset glow — click to copy.

Slots — status dot, icon, close

Three optional slots in Badge.tsx, on top of the label: a status dot, a left icon and a closable ×. The dot is an 8px pellet in one of four semantic values — neutral · success · warning · destructive — and it colours the dot, never the pill: the variant stays whatever the surface calls for. It is the DS's small status mark, not the 14px Status indicator, which carries a glyph inside a ground-coloured ring. The Figma board's avatar slot has no code prop.

Primitives

Marker Marker.tsx · shipped 2026-08-20

A marker names a position: today in a calendar, the third course in a list, the step you are on. It is Badge's circular sibling and deliberately not a Badge with a rounded corner: one unit of content, a fixed diameter, no room for a label. Three surfaces only, primary, secondary and accent, plus px-heat on the step marker where the glow means progress. No success, warning or destructive: those report the status of a process, and a marker never does.

The four places it replaces a hand-drawn circle

Each of these is a burgundy fill Maxime kept on 2026-08-17, on the condition that it enters the DS with Badge's own variants and scale rather than as a local circle.

Primitives

Tag Tag.tsx · aligned

Versatile labels for categorization, filtering and metadata. Four surfaces — primary (the default), neutral, brand, px-heat — × three types (fill, dash, emphasis) × three sizes, square-ish radii unlike the Badge's pill, plus an optional 8px status dot. Shipped as ds/common/Tag.tsx. Decision Maxime 2026-08-17: danger, warning and success left the surface axis — painting a whole pill green to say “active” says something false, because those three colours report the status of a process and never a selected state. They became a dot the tag carries. primary and px-heat came in from Badge, so the two components say the same word for the same thing. The board has not caught up: it carries neither new surface and still draws the three semantic ones, so the board is a Figma backlog item rather than a divergence to arbitrate.

Status indicator

A 14px dot embedded in tags or labels to reflect a page/update/action status — 2px ground-colored ring, 24% tinted fill, 8px glyph.

Primitives

Text input partial ds/ coverage

Five field types (default, leading dropdown, trailing dropdown, leading text, payment) × three sizes × six states (placeholder, filled, focus, destructive, success, disabled) — plus three textarea variants (text, tag, message) with their own state set, and two web-designed extensions (search, password), shipped in code, board still to backfill. Heights 48/40/32, radius 8/8/6 (sm drops one step). Click a field for its JSX (default type) or its CSS recipe — and try the live one.

Five types

States — with label & hint

Textarea — three variants

The board draws the textarea border at white 8% where inputs use 16%. The code uses 16% and the code is what ships. The dropdown/leading/payment types and every textarea variant have no ds/ component (DRIFT-007).

Primitives

Progress Progress.tsx

Task progress or passing time. Two variants — Primary (white fill) and PX Heat (the 270° heat ramp) — four track heights (sm 4 · md 6 · lg 8 · xl 12), radius full. The Slider derives from this recipe. Shipped as ds/common/Progress.tsx; shadcn's ui/progress.tsx is a different component and does not implement this spec.

Primitives

Slider derived · no board

Born on the web (Maxime, 2026-07-23): the Progress bar anatomy — radius-full track + fill — plus a handle, in two fill variants (decision 2026-07-24, the same pair as Toggle ON): px glow, the official PX Heat ramp compressed into the fill, and neutral, a neutral-50 fill on a 16% track. Same four sizes as Progress. The ds/Slider component ships on staging; the Figma board is a backlog item, not a divergence. Click a size label to copy its JSX.

Primitives

List item derived · no board

An entry that designates an object in a list, where a Button triggers an action. Born on the web for the Athena conversation drawer (Maxime, 2026-09-10: « ce n'est pas un bouton »): a title, a quieter detail line under it, aligned left on two lines rather than one. Three states from the actionable family (rest, current, disabled) and two slots added 2026-09-18 for archiving: a leading mark that says a state, and a trailing action. The element stays a native button for the keyboard and screen readers; only the visual recipe changes. No Figma board, and that is a backlog item, not a divergence.

Leading and trailing slots

Added 2026-09-18 for archiving a conversation. The trailing action is rendered outside the button, and that is the whole point of the prop: a button inside a button is not valid HTML, the keyboard never reaches it, and the click bubbles to the entry. A render test in sirius holds that rule.

States

Implementation

Primitives

Menu derived · no board

A short panel opened from a button: one line per choice, a group label above them, and a check on the one that is active. Born on the web for the conversation drawer (Maxime, 2026-09-14: the history sort behind a filter icon), then reused for the per-row archive action. Radix owns the mechanics — focus, escape, outside click, keyboard — and the DS only places tokens. ui/dropdown-menu stays where it is already used; this is not a migration.

Anatomy

Two rules the panel earned the hard way, both dated and both from measurement rather than reading a name.

Implementation

Composites

Athena widget anatomy derived · state lives in the gallery

An Athena widget is the card the assistant shows inside a conversation turn: a calendar to pick a slot, a picker to choose between proposals, an uploader, a ring, a player. There is one card per turn. This section documents only what every one of them shares — the shell, the rise, the three elevation steps, and the rule that lets a widget into the catalogue at all. It deliberately does not inventory them: the state of each widget, its contract and its open defects live in the sirius gallery, which stays the single register, and the review rules live in ds/rules.json. Duplicating either here would create a second truth.

The shared shell

Three decisions travel together on every widget: the radius says what the surface IS, the lift says whether it is read or touched, and the elevation is carried by the card rather than written by each child. The two specimens are the real components, served live by sirius staging (/dev/athena-widgets?embed=): the site never redraws a widget, a copy drawn by hand is a fake (Maxime, 2026-09-18).

Admission

A widget that renders is not a widget that exists. The bar below is what lets one into the catalogue, and it is the reason four visuals stayed invisible from birth.

Implementation

Composites

Athena widgets catalogue · 37 widgets

Every widget Athena can show inside a conversation turn, all 37, as they exist on sirius staging on 2026-09-18. Each card gives the widget's name, its key, what it is for, what triggers it, the file that renders it, and the widget itself, live: the real component served by sirius staging in an iframe (/dev/athena-widgets?embed=<id>), in the mode this page is in, never a capture or a redrawn copy. Nothing more, on purpose: the state of each widget — its detailed contract, its open defects, its design changes — lives in the sirius gallery at /dev/athena-widgets, which stays the single register, and every card here links to its entry there. Click a widget: it answers, exactly as it does in the chat. The shell they all share is Athena widget anatomy; the rules a review runs against are ds/rules.json. Two widgets are application states rather than tool-triggered cards and say so. The two application-state widgets were captured after design/widget-parity-2 landed on staging.

Answers and choices 6

Commitment 3

Media and navigation 3

Agenda 5

Visualisations 8

Protocol cards 6

Content 4

Application states 2

Primitives

Rich text markdown.tsx · aligned 2026-07-31

How every element of an article renders — the full stack from the master's Text component board: title label, H1 (default + visual block), H2, H3, body, lists, quote, small, inline code and code paragraphs, picture and video with legends, and three spacers. Quote/code use JetBrains Mono italic — official as an ultra-rare option strictly for code / transcript-style content (decision 2026-07-24). The token --ds-font-mono now ships in globals.css over a system mono fallback that holds on its own until the face is loaded; ui/markdown.tsx still reaches for Tailwind's font-mono, which is not bound to it. The renderer is on spec since 2026-07-31 (sirius#778): it sets H1 --ds-font-size-2xl, H2 xl and H3 lg in --ds-theme-ground-fg-title, and the invented burgundy H1, teal #17BEC9 H3 and gray-* palette are gone. Two values stay hard-coded and say why in the file: the mono face and the #dbbdc8 chip label, both sitting on a burgundy tint rather than a theme surface.

À propos de cette Loop

Ceci est un titre H1

Étape 1 sur 4

Ceci est un titre H1 (visual block)

Ceci est un titre H2

Ceci est un titre H3

Un paradoxe est une affirmation qui semble se contredire, mais qui peut néanmoins être vraie. C'est une idée qui défie la logique et le bon sens, et qui nous oblige à remettre en question nos hypothèses et nos croyances.

1. Apprendre les contradictions.
2. Les paradoxes temporels.
3. Réussir à jongler l'impossible.

• Navigue dans les complexités du paradoxe avec assurance.
• Découvre comment les paradoxes stimulent la pensée créative.

Ton chemin vers la liberté financière commence ici.

Par exemple, après qu'il ait dit : "ça me tue intérieurement" tu aurais pu dire : "ça me tue intérieurement"

Par exemple, après qu'il ait dit : "ça me tue intérieurement" tu aurais pu dire : "ça me tue intérieurement"

The moral of the story is: never underestimate the power of a good laugh and always be careful of bad ideas.

02:08 -06:18

Un lien vers la méthode complète au fil du texte, du gras qui passe en Medium titre et de l'italique simple.

---

Principe	Effet
Clarté d'esprit	Moins de bruit, plus de décisions nettes
Paradoxe assumé	Deux vérités peuvent coexister

• Écrire la première itération.
• Confronter la version à un vrai lecteur.

The full board stack · title label 12/16 SemiBold uppercase over a 16% rule · H1 2xl / H2 xl / H3 lg (Clash Medium) · body & lists SM 14/20 · quote + code chips = JetBrains Mono italic 12/16 #dbbdc8 on burgundy 10% · small 12/16 neutral-200 · media: radius 16, black-8% border, Shadow-dark/sm, legend indented 8 · the video bar's hover timestamp-preview (thumbnail + times) is specced on the board, omitted from this static demo · the closing run — link, emphasis, table, task list (Circle Checkbox at sm) — is web-designed, with the board as a Figma backlog item

Primitives

Icons Lucide

The icon system is Lucide — the full official library, vendored (… icons): 24px grid, stroke 2, round caps. The Figma board mirrors this set; when an icon is missing there, it exists here first. Sizes in use: 16px in buttons and inputs (20px in lg icon buttons), 12px in badges and tags. Click any icon to copy its lucide-react import.

Primitives

Athena Orb LiquidOrb · v3 validated 2026-09-16

Athena's presence, and the only orb the product draws. A WebGPU shader coloured by the PX Heat ramp: the one place in the system where the brand scale appears as a material instead of a fill. The version in force is V3, a Voice Wave (upstream style 19) dressed in PX Heat: a wave that beats from the centre, drawn upstream for a voice, exposed, with a quiet halo. The parameters are a versioned design: ORB_PARAMS_V1, _V2, _V3 in src/lib/ds/LiquidOrb.tsx, and ORB_PARAMS names the one the product wears. This page is the reference for it: a shader has no frame to extract from, so the values below are the source, rendered live rather than described, by the same WGSL sirius serves. Every specimen copies its JSX on click.

Material

One sphere, four fluid colours, a glass shell over them. In V3 the fluid is a membrane: a wave that beats out from the centre, whose height the shell refracts and splits at the limb. Nothing is a bitmap: at 280 or at 24, it is the same WGSL evaluated per pixel.

Versions — v1, v2, v3

Three decisions, each kept under its name so the product can go back. A version is one object in LiquidOrb.tsx; moving ORB_PARAMS to it is the whole release. The style is a parameter like any other: v1 is upstream's refractive blob (23), v2 its iridescent opal (13), v3 its voice wave (19). Every other style of the upstream bank can be tried in PX Heat on the sirius bench, which is where a v4 would be looked at first.

Sizes — where it is worn

Two sizes ship today, and both are the same place: the identity block of the Athena chat header (AthenaIdent, geometry in ORB_IDENT_V3). 24 at rest, with an 8 px gap to the name; 32 while a voice session is open. The box a caller passes must be the ball's diameter; the component draws its own overscan around it, so a size is never a crop. Under 64 px the shader renders at 2× and the browser reduces it: an exact 2×2 average, so the fluid's ridges stop shimmering and the limb stays a line rather than a threshold.

Voice — the wave is the spectrum

When Athena speaks, the orb is not an animation timed to her voice: the ball's x axis is the frequency axis and the wave's height is the band's amplitude, 32 bands from 80 Hz to 8 kHz on a log scale, smoothed in time and across neighbours so the membrane reads as a wave and not as a comb. The analyser is bound in voice mode only. The flow speed rises from the preset's 1 toward ORB_VOICE_V1.speakingSpeed = 1.5 with the voice level, and the phase is integrated frame by frame (phase += dt × speed, uniform speed pinned at 1), so a change of speed never rewinds the wave at the exact moment she starts talking.

Fallback & motion

No WebGPU (Firefox, Safari under 26) or a shader that fails to load: the CSS sphere OrbCss renders instead, a radial gradient down the heat scale with its inset rim, so an orb never degrades to an empty circle. On this page, an orb scrolled out of view stops rendering and a reduced-motion visitor gets one held frame; LiquidOrb itself keeps one shared device and pipeline for the page and one buffer per instance.

Panel — tune it live

The tuner's own controls, on DS primitives, driving every orb on this page at once. Pick a version, then one group at a time: the upstream tool stacks all five, which is thirty controls of scroll, and a panel that tall cannot sit beside what it tunes. Labels and ranges are the sirius bench's exactly, so a value read here can be typed there and back. Copy the preset hands you the OrbParams literal in sirius' shape (scalars in struct order, then the twelve colours): pasting it into LiquidOrb.tsx as ORB_PARAMS_V4 and having it reviewed is how a tweak becomes the product's orb.

Implementation — v3

The scalars and colours the shader reads, as validated, with v1 and v2 beside them. Copy a row for its value; copy the recipe above for the whole object. The uniform ORDER in buildUniforms mirrors the shader's struct Uniforms field for field and is ported from upstream: reordering it to read better lands every value in the wrong field. The eighteen metal and particle values are identical across the three versions and only read by styles none of them uses; they exist so the layout stays upstream's.

Registers

Exemplars canon · validated 2026-07-28

Screen-level canon: the reference screens to imitate when you build a screen. Components are specced above; this register answers the next question up — how screens are composed. Source: Maxime's Figma frames (file uZfZ4lr4eJeDb4q5KeWDiz), 41 screens extracted and measured. Imitate the logic (hierarchy, rhythm, density, tone), never the pixels. The measured facts per screen — annotations verbatim, every value mapped to its token, layout, type, density — live one file per screen in exemplars/analysis/ — e.g. exemplars/analysis/home-desktop-large.md with its export in exemplars/captures/, same slug on both sides. Read the analysis file to build; look at the capture to compare.

The responsive doctrine, seen on one screen

Home at six widths — the visual proof of Bible hard rule 8. From 1280 up the content column is capped and the margins absorb the extra width; at 1024 and below the cards keep their pixel size and the rows become peeking carousels. Responsiveness is how much of the next card shows, never a resize.

The five exemplars

E1 — Home

Why it's canon

The member dashboard reference: mixed card families (course, action, tutorial, event, identity) stacked in labelled sections, each a Ground Header over a horizontal card row. Uniform 20px radius across ~20 card instances of five types. The Paradox Score / streak block is the single focal point.

Figma constraint → rule

The tablet frame zeroes the course section and pastes an overlay carousel; desktop-small uses override frames with mask-cropped cards. Same intent both times: at ≤1024px card rows become peeking horizontal carousels at fixed card size. One carousel component for the whole compact family — never per-screen overlays, never a reflow that shrinks cards.

Also inside

The richest annotations of the corpus (19 verbatim) — the scroll-linked card animation spec and the streak-chart opacity rules, the only written motion intent we have. The mobile Identity/stats block is annotated 🚧 WIP, do not integrate; the logo 🚧 Wrong logo.

analysis/home-{desktop-large,desktop-xl,desktop,desktop-small,tablet,mobile}.md

E2 — Catalog

Why it's canon

Browsing density and section rhythm. Course cards are a fixed size (244×344 standard, 624×344 featured) — wider screens add margin, never columns. Section vertical rhythm is a constant 488px step (440 section + 48 gap), holding through the 11-section multi-topic frame. Exactly one accent badge per visible card, never more, never a fill.

Figma constraint → rule

Tablet instances the mobile component at 768px, and every instance is internally named "@ Desktop large" whatever its width. Read as: tablet belongs to the compact family and follows the mobile composition — there is no third tablet grid to build. The naming carries no design meaning.

Also inside

Empty states exist but are annotated 🚧 EMPTY STATE ILLUSTRATION MISSING — the intent is there, the illustrations aren't. Hover, search and filters-open variants are captured.

analysis/catalog-*.md · 7 files incl. the multi-topic frame

E3 — Course detail

Why it's canon

A long content page with a sidebar. Desktop runs a genuine two-column split (modules flex-1 ≈848px + fixed 392px progress sidebar, 40px gap) that stacks full-width on mobile. Spacing is 100% on the DS scale with zero drift — the cleanest screen of the corpus on that axis. Title and description each drop one type tier from desktop to mobile; body copy stays 16px.

Figma constraint → rule

On mobile the hero title/meta block exists twice (one live over the image, one hidden below) — the hidden copy is the component's default content, kept rather than detached. Read as: on mobile the hero title overlays the image, exactly one title in the DOM. Render the overlay, drop the duplicate.

analysis/course-detail-{desktop-large,mobile}.md

E4 — Loop

Why it's canon

The broadest reference of the corpus — list shells, overlays, modals, chat and a long report page in one coherent family. Fixes the desktop list shell (Ground Header 64, pagination 64, footer 224) and the overlay vocabulary: 528px side panel, 480px modal, both over a 72%-black + 2px-blur scrim. Accent discipline at its strictest — burgundy is absent from three of four desktop screens and, on chat, marks only the member's own bubbles.

Figma constraint → rule

The share modal shows off-grid values (7 / 7.5px offsets, 0.714px borders) — artefacts of scaling a component in the frame. Read as: the close button sits at the standard 8px inset, borders are 1px. The JetBrains Mono Italic quote callout is the real validated exception for transcript content — not a licence for a third UI font.

Also inside

A hidden "Section compact" variant (82px cards) on both session lists — an unreleased density system.

analysis/loop-*.md · 16 files (preview, focus mode, share modal, analysis, sessions, chat, transcript, filters)

E5 — Loop creation

Why it's canon

The multi-step wizard reference. The whole New Loop flow is ONE master component whose steps are revealed by layer visibility, not a component per step — and the type hierarchy is deliberately flat: a single Clash headline over an otherwise uniform field of DM Sans 14px. Its State matrix sections inventory the empty, filled, error and recap states — currently the only state documentation in the corpus.

Figma constraint → rule

The disabled CTA is a raw 48% opacity class. That value is the DS disabled opacity — the intent is right, only the binding is raw. Read as: disabled = the DS .48 state, via its token.

Confetti is dead

The Success modal ships a full-frame confetti raster. Confetti is banned (Maxime, 2026-07-28) — gamified, childish, dated. The celebration primitive is the fire-crackle border effect, and the code already agrees: LoopCreateSuccessModal.tsx renders <BorderFireEffect>. Its palette is PX Heat extended into incandescence and it emits from the card border — it frames the artifact instead of covering the screen. The modal is canon for its layout only.

analysis/loop-creation-*.md · 7 families incl. dispatch, verbatim, thematique, success, detail drawer

How canon gets minted

Two routes, and nobody but Maxime mints. An agent may propose a candidate in a PR; only his explicit promotion counts. An exemplar without a WHY is a screenshot.

Registers

Drift register

Every documented divergence between the Figma master, the code tokens, and the ds/ implementations — found during the ISO reproduction pass of 2026-07-20. Each entry carries what was expected, what was observed, and where it stands. Resolved entries stay: they're the history of the system.