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 belongs 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 gaps in the scale (no 300/500) are the scale — never interpolate missing steps.

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. Pick one ladder (DRIFT-010).

Gradients

Four PX Heat directional ramps + the title text gradient — all Figma color styles, zero code tokens yet. Displayed large on purpose: a 7-stop ramp is unreadable as a thumbnail. Click a ramp to copy its full CSS. Seven more library gradients (Navbar/blur/backdrop) live in the parent master file — fileKey still needed.

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 (see DRIFT-022). 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 🚧. Three Mode variables have no code token (DRIFT-023): popover foreground-paragraph, success-bg-transparent, warning-bg-transparent.

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.

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 */

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 .88 · hover .80 · active 1 · 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 · 1:1

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.

Optional slots (Figma props, all 12px): dot · left icon · avatar · closable ×. The px-heat glow recipe: px-heat inset glow — click to copy.

Primitives

Tag no ds/ · DRIFT-007

Versatile labels for categorization, filtering and metadata. Five color variants × three types (fill, dash, emphasis) × three sizes — square-ish radii, unlike the Badge's pill. Closest existing code (pxlab Tag.tsx, shadcn ui/badge.tsx) matches neither: this page is the spec.

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 — DRIFT-029). 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

⚠️ Board inconsistency (flagged): textarea border is white 8% where inputs use 16% — part of DRIFT-010. The dropdown/leading/payment types and every textarea variant have no ds/ component (DRIFT-007).

Primitives

Progress no ds/ · DRIFT-007

Task progress or passing time. Two variants — Primary (white fill) and PX Heat (the 270° heat ramp) — four track heights, radius full. The Slider derives from this recipe. shadcn's ui/progress.tsx 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. No Figma board yet (DRIFT-021) — the ds/Slider component is staged on the sirius branch design/selection-controls; click a size label to copy its JSX.

Primitives

Rich text code off-spec · DRIFT-008

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, token --ds-font-mono to add). The off-spec flag is about the code: ui/markdown.tsx still renders teal h3s and a gray-* palette — this board is its restyle spec.

À 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, board to backfill (DRIFT-028)

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.

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.