Design Foundations

/* Reference brand tokens directly. Never hard-code hex. */
background: var(--lifi-sapphire);     /* primary action surfaces */
color: var(--lifi-ink);          /* highlight / accent runs */
border-color: var(--lifi-pink);   /* legacy LI.FI-pink hue */

/* Or use semantic accents that flip with the palette: */
background: var(--accent-primary);
color: var(--accent-secondary);

• Lean on neutrals. A screen at 65% neutral reads as calm and professional. The accent carries more weight when the room is quiet.
• One accent per decision. The primary CTA is --accent-primary. Everything else defers. One blue button per page, not four.
• Compose via color-mix — tinted surfaces (e.g. color-mix(in oklch, var(--accent-primary) 12%, transparent)) keep the palette small while giving you 100+ practical values.
• Reserve semantics. --success means "something went well", --danger means "this is destructive or broken". If neither is true, don't reach for a semantic color.
• Respect the 5% tertiary ceiling. Tertiary is the loudest color — a little goes a long way. One tag, one chart series, one slide.
• Never hardcode hex values in stylesheets. #6366f1 is a bug waiting to break the next palette swap. Reach for a token.
• Don't override accents locally. If you're writing color: #8b5cf6 to force a specific purple, the design system has already lost.
• Don't use green for "friendly". Green is "yes" or "live", not "positive vibes". Use primary or neutral for mood.

• Reach for --text-* from prose, labels, numerals. Anything where the consumer is a text node — <h*>, <p>, <span>, <label>, table cells, list-item titles.
• Reach for --icon-* from icon-only chrome. Borderless icon buttons, dropdown carets, list-row affordances, navbar utility icons, status dots that aren't text-adjacent. Don't use --text-* in an icon-only component — if the icon family ever diverges from text, every icon consumer would need a rule update.
• Both families are theme-aware. The :root block paints them for dark mode; [data-theme="light"] overrides for light. One token, two contextual values — consumers never branch on theme.
• To diverge icons from text, override the alias in :root / [data-theme="light"], not in the consumer rule. Example: --icon-primary: color-mix(in oklch, var(--text-primary) 88%, var(--accent-primary)); tints every borderless icon button with a hint of brand. The consumers automatically pick it up.
• Never hardcode an icon colour like color: var(--text-primary) in an icon component. Always go through --icon-*. The whole point of splitting the families is that a future divergence is a one-line change.

• CSS — styles.css · search for --text-primary: (canonical definition in :root, mirrored in [data-theme="light"]). The icon family sits immediately after the text family in both blocks.
• Canonical consumers — Borderless icon button reads --icon-primary and --icon-muted for rest / muted variants. Any component with icon-only chrome should follow.
• History — May 2026 split. Previously .btn-icon.btn-borderless consumed --text-muted directly. The default flipped to --text-primary + an opt-in .btn-muted variant; on the same pass both colours moved behind --icon-* aliases so future divergence is a token-layer edit.

Numeric form — for chart libraries, JS loops, programmatic indexing.

/* Bar chart with 6 categorical series */
.bar[data-series="1"] { background: var(--spectral-9); }
.bar[data-series="2"] { background: var(--spectral-2); }
.bar[data-series="3"] { background: var(--spectral-5); }
/* … or use the series tokens directly, which derive from spectrum */
.line[data-series="3"] { stroke: var(--series-3); }

Named form — for prose-readable references where the index isn't meaningful.

/* Decorative block / illustration fill */
.callout--amber {
  background: color-mix(in oklch, var(--spectral-amber) 12%, transparent);
  border-left: 3px solid var(--spectral-amber);
}
.badge--violet {
  color: var(--spectral-violet);
  background: color-mix(in oklch, var(--spectral-violet) 14%, transparent);
}

Dark mode (default)

Light mode overrides — L drops 0.16–0.26 for contrast against light surfaces; chroma holds or eases slightly (lower L gives chroma headroom before sRGB clipping). Hue identities preserved — coral is coral, blue is blue — and --spectral-9 (blue) anchors to exact LI.FI Blue in light mode (0.44 · 0.23 · 268).

Token shapes — every spectral color exposes both forms simultaneously.

Hue lookup — number ↔ name ↔ hue angle

Series mapping — --series-N tokens derive from spectrum so chart colors stay stable across brand-preset switches.

• Two layers within Brand Colors — pick by intent. The 3 identity accents (--accent-primary / -secondary / -tertiary) carry brand identity and shift with the Theme Composer. The 12 extended hues (--spectral-1…--spectral-12) extend the palette for content where the color carries no semantic meaning — categorical data, illustration fills, decorative blocks — and stay put across preset switches. Reach for the layer that matches the intent.
• Don't use the extended palette for UI chrome. Buttons, borders, focus rings, hover states all bind to the identity accents + neutrals so they restyle when the user picks Across or Uniswap. The extended hues are stable on purpose; that's exactly the wrong behavior for chrome.
• Semantic state stays separate from spectral hues. --spectral-5 is in the green family but --success (semantic green) lives in the Semantic tier. Don't substitute one for the other — a designer changing the success token won't update charts; a designer changing spectral-5 won't update success states.
• Don't hand-pick chart colors outside the curated subsets. The 4 / 6 / 8-series subsets above are pre-tuned for max categorical distance. Picking --spectral-9 + --spectral-8 for two series puts deep blue next to sky blue — the eye reads them as one variable, not two.
• For 2-series charts, use --series-1 + --series-2 (blue + orange). Earlier iterations had series-1 = brand primary, which restyled chart data on every preset switch. Blue + orange is the universally-distinct pair regardless of active brand.
• For more than 8 categories, group instead of stacking colors. 12 colors is the extended palette's ceiling — beyond that, even the eye can't keep distinct identities straight. Either group categories ("rest" bucket) or use a sequential palette instead of a categorical one.
• Light/dark adjustments are automatic. Each --spectral-N remaps to a darker, slightly more chromatic value in [data-theme="light"] — consumers don't need to handle theme branches manually.

• CSS — styles.css · search Spectrum Palette for the dark-mode definitions in :root; light-mode overrides live in the [data-theme="light"] block further down. Sits next to the brand identity tokens (--accent-primary et al.) — same palette, two layers.
• Spec — design.md §02 → Color → Spectrum (extended brand palette). Per-hue OKLCH choices + light/dark mode philosophy.
• Sibling tokens within Brand Colors — --accent-primary / --accent-secondary / --accent-tertiary (the 3 identity accents, palette-switchable). The Spectrum 12 + the identity 3 together make up the full brand palette.
• Adjacent tiers — --success / --warn / --error / --info (semantic), --series-1…--series-8 (chart-curated subset of Spectrum), --ink-* / --surface-* (neutrals).
• Used by — Series Palette card (#series-palette) for charts; available for any decorative or illustration use elsewhere via var(--spectral-N).
• Stability contract — the extended palette stays put across brand-preset switches (Option A in the design proposal). Switching to the Across or Uniswap preset changes the 3 identity accents but the 12 spectral hues do NOT shift — chart data should read the same regardless of brand. The one sanctioned exception is the Theme Composer’s Charts axis: a theme may opt its series tier (--series-1..12) into a brand-derived ramp — the spectral primitives themselves never move.

<!-- One device figure. --dw/--dh = rendered px (logical × 0.12 scale);
     data-logical-w = the logical CSS width the ruler reads. -->
<div class="ds-doc-device ds-doc-device--laptop ds-doc-device--notch"
     data-logical-w="1280" style="--dw:154;--dh:96">
  <div class="ds-doc-device__frame"></div>
  <div class="ds-doc-device__label">
    <span class="ds-doc-device__name">MacBook Air 13"</span>
    <span class="ds-doc-device__res">1280 × 800</span>
  </div>
</div>

<!-- Chrome modifiers: --monitor (stand) · --laptop (deck) +
     --notch · --tablet (camera) · --phone (island) +
     --home (SE) / --punch (Android). -->

Laptops & desktops

Tablets

Phones

Breakpoint anchors — industry reference (Tailwind), not LI.FI tokens

• Logical viewport is the layout number. Media queries and layout widths read CSS px (logical), not the hardware pixels. Design to the logical column; the native + DPR columns are for asset export (@2x / @3x).
• 1280 is the practical floor. Treat “laptop and wider” as ≥ 1280 px (MacBook Air 13"). Floating surfaces fit inside it with room to spare — the --w-* ladder (Surface widths) tops out at 640.
• The Advanced Limit widget is sized to this floor. Footprint = 1168 px (view-rail 64 + form 416 + receive 640 + two 24-px gaps), leaving ≈ 56 px margin each side on a 1280 screen and scaling generously on 1440+. Closes the loop with swap.css → “Advanced widget tier” and Widget.
• Breakpoints are an industry reference, not our tokens. The sm / md / lg / xl / 2xl anchors are Tailwind's, shown for cross-team shorthand. LI.FI's own width vocabulary is --w-* (Spacing → Surface widths).
• One shared scale (≈0.12×). Every frame is drawn at the same ratio, so relative footprints read true across the whole set — a phone really is a fraction of a monitor. The ruler dims devices narrower than your target width rather than hiding them.
• Grouped by class, divided by zone. Laptops & desktops / Tablets / Phones each get a .ds-doc-eyebrow label and sit in their own .ds-doc-device-stage, separated by a .ds-doc-divider--loose — the same group-by-axis, divide-between-zones pattern the catalog uses elsewhere.
• The frames are width presets. Clicking (or Enter / Space on) any device snaps the ruler to that device's logical width — the ruler and the stage drive each other. The control itself is the .slider primitive, so it inherits the system track / thumb / fill and focus chrome; the live breakpoint is a .chip-accent1 and the fit count a .muted line.
• Reserve safe areas on notched / Island phones. The logical viewport spans the inset zones; pad interactive content with env(safe-area-inset-*) so it clears the notch, Dynamic Island, and home indicator.

CSS: styles.css — search Device frame — screen-size reference (the .ds-doc-device-* + .ds-doc-device-ruler + .ds-doc-bp-track blocks).
Composed primitives: .slider (the ruler control) · .chip-accent1 (breakpoint badge) · .muted (fit count) · .ds-doc-divider--loose (zone separators).
Ruler JS: the inline IIFE next to this section (reads [data-device-ruler], drives [data-fits] + the active .ds-doc-bp-seg, and JS-enhances every .ds-doc-device[data-logical-w] into a width preset). Track fill via window.lifiSliderFill.
Tokens: --surface-sunk / --surface-raised, --text-faint, --accent-primary / --accent-primary-mid, --space-*, --text-caption / --text-micro, --font-mono.
Spec: design.md → Foundations → Device resolutions & breakpoints.
System tie-in: swap.css → “Advanced widget tier” · Widget · Spacing → Surface widths (--w-*).

/* Resting card */
.card {
  background: var(--surface-card);
  box-shadow: var(--elev-1);
  border-radius: var(--space-16);
}

/* State choreography — bump the tier on interaction */
.card:hover         { box-shadow: var(--elev-2); }
.modal, .popover { box-shadow: var(--elev-3); }

Three tiers — pick by state, not by aesthetic. Light/dark recipes auto-flip via the [data-theme] override.

The dark-mode trick — a 1px inset 0 1px 0 rgba(255,255,255, 0.04–0.06) rim highlight is what sells the lift on dark surfaces, where standard drop shadows barely register. Light-mode tokens drop the rim and lean on classic Material-style drop shadows instead.

Companion filter-form tokens for masked elements. Each --elev-N ships with a --elev-N-filter sibling that approximates the same visual lift in filter: drop-shadow(…) form. Use when an element has mask-image applied (which clips box-shadow) and the elevation lift must still be visible. The inset rim-highlight layer doesn't translate to drop-shadow and is omitted from the filter form — only the outset lift layers are preserved.

Author single-layer, not chained. Chained filter: drop-shadow() calls compound — the second filter takes the first filter's output as input, blurring the already-blurred result. The visual is a smeared soft-glow that reads weaker than a multi-layer box-shadow with the same numbers (which paints each layer independently and sums cleanly). So a filter token authored as a 1:1 port of a multi-layer --elev-N recipe will self-cancel and render near-invisible. Always collapse the chain to a single drop-shadow() whose opacity sums the box-shadow layers' opacities, at the larger blur radius.

Two patterns, pick by topology. The CSS spec applies filters BEFORE masks, and mask-clip defaults to border-box — which trims the drop-shadow() output back to the masked element's box. Two ways to handle it:

Pattern A — group of masked elements (preferred). Host the filter: var(--elev-N-filter) on the unmasked PARENT; the masked children drop their own shadow. The parent's drop-shadow paints around the children's combined silhouette — cutouts at shared edges read as true holes with shadow rims, and the children keep full perimeter shadows. Canonical example: .ui-amount-pair hosts the filter, the two .ui-amount-card children carry the FAB cutouts. No mask-clip override needed.

Pattern B — standalone masked element (fallback). When the masked element stands alone with no parent to host the filter, apply filter: var(--elev-N-filter) on the element itself AND set -webkit-mask-clip: no-clip; mask-clip: no-clip; so the drop-shadow output isn't trimmed. Diagnostic if shadow still looks invisible: stress-test with filter: drop-shadow(0 4px 12px rgba(255,0,0,0.9)); no red around the card = mask-clip is still trimming.

/* Pattern A — masked group, filter on the unmasked parent (preferred) */
.masked-group {
  filter: var(--elev-1-filter);   /* paints around combined silhouette */
}
.masked-group > .masked-child {
  mask-image: radial-gradient(…);
  box-shadow: none;                /* mask-clip would clip outset paint */
}

/* Pattern B — standalone masked element (fallback) */
.masked-element {
  mask-image: radial-gradient(…);
  -webkit-mask-clip: no-clip;       /* don't trim drop-shadow to border-box */
  mask-clip: no-clip;
  box-shadow: none;
  filter: var(--elev-1-filter);
}

• Reach for the tier, not the recipe. Don’t hand-author box-shadow: 0 4px 16px ... on a card. The tier is the contract; the recipe is implementation detail that evolves once across the system.
• State choreography is built-in. Rest = --elev-1, hover = --elev-2, floating = --elev-3. Don’t signal interactivity by darkening a border — bump the tier instead.
• Don’t skip a tier. A resting card going straight to --elev-3 on hover overshoots; the user reads it as “floating away,” not “focused.” Use --elev-2 for hover.
• Pair with a fill. Elevation is a shadow recipe, not a fill recipe — cards still need background: var(--surface-card) (or another --surface-* token). The shadow alone doesn’t lift; fill + shadow does.
• Materials bundle elevation. When a card uses a Material (data-material="paper"), the tier is baked into the material’s shadow token (--material-paper-shadow: var(--elev-1)). Use --elev-N directly only when authoring outside the Materials API. See Materials.
• Use --elev-N-filter when the element is masked — and prefer hosting it on an unmasked parent. mask-image clips box-shadow because per spec, filters paint BEFORE masks, and mask-clip defaults to border-box — trimming outset paint to the element's box. box-shadow is the canonical elevation method; the filter form is its value-matched twin, for masked elements ONLY — never put a filter elevation on an unmasked element (that was the .ui-destination-wallet-card mistake: reverted to box-shadow, the filter token value-matched instead). The companion --elev-1-filter / --elev-2-filter / --elev-3-filter tokens value-match their --elev-N box-shadow twins via filter: drop-shadow(…), and WHERE you put the filter matters: (Pattern A, preferred) when the masked element is one of a group, host the filter on the unmasked PARENT — its drop-shadow paints around the children's combined silhouette and cutouts at shared edges read as true holes with shadow rims; the masked children just drop their own box-shadow. (Pattern B, fallback) when the masked element stands alone, apply the filter on the element AND set -webkit-mask-clip: no-clip; mask-clip: no-clip; so the drop-shadow output isn't trimmed. The inset rim-highlight layer (dark mode) doesn't have a drop-shadow equivalent and is omitted from the filter form; the outset lift layers carry the visual weight. Canonical use: .ui-amount-pair hosts the filter, the two .ui-amount-card children carry the FAB cutouts (see .ui-swap-arrow).
• Author each filter token to value-match its box-shadow twin — mirror the outset layers, chained. Chain one drop-shadow() per outset layer at the same offset / blur / opacity (e.g. drop-shadow(0 1px 2px rgba(0,0,0,0.06)) drop-shadow(0 1px 1px rgba(0,0,0,0.04)) for --elev-1 light). Chained drop-shadow() does NOT self-cancel at small (1–2 px) blurs — both layers render (verified June 2026 by an isolated A/B test at 6%/4% AND amplified 40%/30%: the chained square rendered a full shadow matching box-shadow). A prior rule claimed chaining renders "near-invisible" and mandated a single summed drop-shadow() — that was wrong; the single-summed form reads SOFTER (no tight inner layer) and was caught as a visible mismatch against box-shadow cards. The only real caveat is at very large blur radii (--elev-3's 56 px), where the shadow-of-a-shadow can faintly smear. The inset rim-highlight layer has no drop-shadow equivalent and is dropped (dark mode only; imperceptible). Diagnostic when a masked card looks off: compare its computed filter against the same --elev-N in box-shadow form on an unmasked sibling.

Definitions: styles.css · search --elev-1: in :root (dark) and [data-theme="light"] (light overrides).
Spec: design/components/foundations.md → Elevation over hard borders.
Cross-reference: Elevation over hard borders below for the system-wide discipline.

/* Recessed track inside a card — alpha-subtle on the card’s fill */
.track { background: var(--alpha-subtle); }

/* Hover state — alpha-dim on the row’s fill */
.row:hover { background: var(--alpha-dim); }

/* Active pill — alpha-raised */
.pill.is-active { background: var(--alpha-raised); }

/* Active & hovered — alpha-overlay (the strongest tier) */
.pill.is-active:hover { background: var(--alpha-overlay); }

/* Text on alpha surfaces — use the on-alpha scale, not --text-primary
   directly. The on-alpha tokens are tuned for legibility against
   the resolved color of an alpha layer over the page bg.            */
.pill-label { color: var(--on-alpha-default); }

• Use alpha tokens, not raw rgba(). The alpha scale flips correctly between light and dark themes; raw rgba doesn’t. A handcoded rgba(255,255,255,0.18) looks fine in dark mode and disappears in light mode — the tokens solve that.
• Layer alphas on top of fills, don’t replace them. An alpha overlay is a state on top of an underlying surface; the surface fill (--surface-*) is what defines the base. Set background: var(--alpha-raised) on a child element of the card, not on the card itself.
• Use the on-alpha text scale on alpha surfaces. Default text on a translucent surface depends on what’s underneath. Use --on-alpha-default / --on-alpha-muted for that case.
• Tier semantics: subtle < dim < raised < overlay. Don’t skip tiers (a hover going straight from subtle to overlay reads as “flashing”) and don’t reverse them (active should always be brighter than inactive).

Definitions: styles.css · search --alpha-subtle.
Spec: design.md §02 → Alpha state layers.

/* PREFERRED — Paper material bundles this recipe. */
.my-card { background: var(--mat-bg); box-shadow: var(--mat-shadow); border: var(--mat-border); }
/* On the element: data-material="paper" (or rely on a :where() default).
   See #material-paper for the full Materials API. */

/* MANUAL — use only when authoring outside the Materials API. */
.card {
  /* 1. Fill one step above the parent surface */
  background: var(--surface-card);

  /* 2. Shadow at one of three elevation tiers */
  box-shadow: var(--elev-1);

  /* 3. Optional 3-6% hairline — just enough to crisp the corner */
  border: 1px solid color-mix(in oklch, currentColor 6%, transparent);
}

Three coordinated mechanics. Cards read as “lifted off the page” through these working together — not through one opaque outline.

• Default to Paper material. The Materials API (data-material="paper" + --mat-*) bundles this recipe correctly — fill, shadow, border, hover-shadow choreography all flow together. Manual authoring is for the rare case Materials don’t fit (a one-off prototype, a non-component primitive, or a deliberate departure from the system).
• Why the rule. Borders force a hard luminance step at the edge, which reads as utilitarian — form-control, spreadsheet-cell. Elevation reads as physical (cards have shadows in real life) and survives both modes equally well.
• Borders fail in dark mode. A 10% white-on-near-black hairline is barely visible. Shadows + raised fills carry the lift in both modes by construction.
• State choreography uses the tier, not the border. Rest = --elev-1, hover = --elev-2, sticky-active = --elev-2 + accent halo, modal/popover = --elev-3. The shadow rises with the user’s intent. Materials carry hover via --mat-shadow-hover; manual authoring writes the tier into :hover directly.
• When to opt out entirely. .input, .select, .textarea keep their explicit borders — the form-control convention is universal and users expect a border-as-input-edge mental model. Segmented controls keep their pill track. Badges and chips keep their tinted fills without elevation. The rule is for container surfaces (cards, rows, tiles, modals), not inline form chrome.

Recommended path: reach for the Paper material — data-material="paper" + --mat-* consumption.
Manual recipe: the three-mechanic version above. Use only outside the Materials API.
Spec: design/components/foundations.md → Elevation over hard borders — the canonical rule, with bug history.
Tokens: --surface-* in Surfaces; --elev-1 / 2 / 3 in Elevation tiers above.

/* Materials are values; components read them through --mat-*.
   Apply by setting `data-material` on the element.            */

<!-- Default (paper) — no attribute needed -->
<div class="card">…</div>

<!-- Switch to glass for a floating panel -->
<div class="card" data-material="glass">…</div>

<!-- Halo — soft accent wash + radial glow; pick accent via --accent-tint -->
<div class="card" data-material="halo"
     style="--accent-tint: var(--lifi-sapphire);">…</div>

Components consume the resolved API:

/* In the component CSS — reference --mat-*, never --material-*-* */
.card {
  background: var(--mat-bg);
  border: var(--mat-border);
  box-shadow: var(--mat-shadow), var(--mat-highlight);
  backdrop-filter: var(--mat-backdrop);
  -webkit-backdrop-filter: var(--mat-backdrop);
  border-radius: var(--space-16);     /* shape — owned by the component */
}

The resolved API — five tokens. Components consume these; never reference --material-*-* directly inside a component rule.

The four named materials. Each material's full character is defined as a bundle of --material-<name>-{bg,border,shadow,backdrop,highlight} tokens in :root. May 2026 — raised, sunk, tinted, and frosted retired; frosted's role merged into glass.

Three layers — top to bottom. Each layer is authored once; the layer below references the layer above.

Why three layers and not one. Without the resolved layer, components would reference material definitions directly (background: var(--material-paper-bg)) — and there'd be no override path. With the resolved layer, the component is material-agnostic; the active material is set via data-material on the element, and the component re-reads --mat-* through CSS variable cascade. Same component renders as paper, glass, or tinted depending on one attribute.

• Components read --mat-*, never --material-*-*. The point of the resolved layer is that components stay agnostic. A rule like .stat-card { background: var(--material-paper-bg); } skips the override mechanism and bakes paper in — that's drift.
• OKLCH at the definition site only. Material tokens compose --surface-*, --lifi-*, --accent-*, --elev-* — never bake an oklch() / hex / rgba literal inside a --material-*-* token. The LI.FI 1.0 FOUC bug pattern repeats at this layer if a contributor copies a literal in.
• One default per element, swap via attribute. A component that always wears one material declares it with a :where(<class>) { --mat-bg: …; } block (specificity 0 — data-material overrides). A component that picks per-instance leaves --mat-* at the :root default and sets data-material in the markup.
• No [data-theme="light"] override for the resolved layer. Light/dark flows through the upstream tokens already (--surface-*, --elev-*, --shadow-panel-glass, --lifi-*). If a material reads wrong in one theme, fix it at the definition site or the upstream token.
• Adding a new material extends the family. Both the definition block in :root and the matching [data-material="<name>"] selector get added in the same edit, plus a row in the matrix in design.md §02 → Materials, plus a new .ds-doc-card in this section.

A glass card declaration in CSS. Each property maps to one of the four numbered layers in the diagram — the comments below line up with the badges on the iso plane.

<div class="card" data-material="glass">…</div>

.card {
  /* 01 · Drop shadow — Elevation owns this; the material just picks the tier */
  box-shadow: var(--mat-shadow), var(--mat-highlight);   /* glass → var(--elev-2) */

  /* 02 · Surface fill — from Surfaces; Material picks the character */
  background: var(--mat-bg);            /* glass → var(--surface-panel-glass) */
  backdrop-filter: var(--mat-backdrop);   /* glass → blur + saturate */

  /* 03 · Edge — hairline + inset rim, owned by Material */
  border: var(--mat-border);

  /* Shape — owned by the component, not by the layer stack */
  border-radius: var(--space-16);
  padding: var(--space-20);            /* 04 · Content gets a frame */
}

Swap data-material="glass" for "paper" to get an opaque card — same four layers, same numbered ownership, just a different Material recipe picking the surface character. The diagram’s gradient viewport is what makes the glass effect legible: with nothing to refract, glass would look identical to paper.

Four layers, four foundations. Each layer is owned by exactly one foundation — the diagram exists to make the ownership visible. Material owns the edge styling and the surface character (opaque, translucent, gradient, or accent-tinted), but never the shadow — that always belongs to Elevation.

The fifth layer — backdrop, only on glass. When a card sets data-material="glass", a backdrop-filter: blur(...) sits between layer 02 (surface fill) and the page bg behind the card, pulling the page color through the translucent surface. The diagram drops the page-bg plate and the backdrop layer to keep the paper baseline clean — the glass-specific stack is described in the Glass material card at #material-glass.

What each plate is rendered with. Every plate that has a real DS counterpart pulls from a token — the fill plate is --surface-card, the edge plate uses the same hairline + rim recipe a real card carries. A palette switch propagates through the diagram on the next paint.

Plate geometry. Each plate is 280×180 px and spaced 100 px apart on the Z axis. The iconic isometric pose is rotateX(58deg) rotateZ(-32deg), applied once on the parent stack with transform-style: preserve-3d. Number badges are children of the same stack so they inherit the iso transform automatically — their digit text is counter-rotated (rotateZ(32deg) rotateX(-58deg)) so it stays upright while the chip body sits on the plate plane.

• One layer, one foundation. Page bg comes from Surfaces, fill comes from Surfaces, shadow comes from Elevation, edge comes from Materials. Don’t reach across — .card { background: var(--elev-1); } is nonsense; an elevation tier is a shadow recipe, not a fill.
• Material owns surface character + edge, not shadow. A material name (paper / glass / gradient / halo) defines how the surface fill renders — opaque, translucent, gradient, or accent-tinted — plus the edge styling and (for glass) backdrop filter. The drop shadow itself is owned by Elevation; the Material recipe just picks which --elev-* tier composes with it. Components consume the resolved --mat-* tokens. See Materials system.
• The shadow plate in the diagram is synthetic. Real --elev-1 / --elev-2 / --elev-3 are tuned to be quiet against the card — they’d be invisible as a stand-alone floating plate at this distance. The diagram exaggerates the shadow into a discrete plate to teach the layer; production cards use the real --elev-* tokens.
• Don’t add a sixth layer. If a component needs a tinted overlay (active state, hover, recessed track), reach for an --alpha-* token painted on a CHILD inside layer 05 — not a new sibling layer to the card. State layers stack inside content; they don’t insert between fill and edge. See Alpha state layers.
• The diagram is a teaching device, not a primitive. Use .ds-doc-iso-card only inside the catalog when documenting a related concept (a new material’s anatomy, a tile-vs-card comparison, the swap-widget’s stack). Never on a product or marketing surface.

Primitive: styles.css · search .ds-doc-iso-card.
Cross-references: Surfaces (layers 01 + 03) · Elevation (layer 02) · Materials (layer 04 + the bundle) · Typography (layer 05).
Spec: design.md §02 → Materials — the layer-ownership rule lives in the Materials section because Materials is the bundling concept that ties the other foundations together.

<!-- paper is the default; the attribute is optional -->
<div class="card" data-material="paper">
  <div class="mono">24h volume</div>
  <div>$1.24B</div>
</div>

• Use for content surfaces — stat-cards, feature-cards, action-cards, action containers. Anything with prose, metrics, or interactive controls inside a non-recessed container.
• Don't use for floating panels. Paper has a small drop shadow, not a deep one — a floating panel needs raised (deeper drop) or glass (translucent + blur). Paper sits AT the page level; floating sits ABOVE.
• Don't use for recessed wells or demo containers. Paper reads as elevated; if you want recessed, use sunk.

Definitions: styles.css · search --material-paper-bg.
Selector: [data-material="paper"] in styles.css after the [data-theme="light"] block.
Spec: design.md §02 → Materials.

<!-- glass — for floating panels, rails, dropdowns -->
<div class="ds-doc-menu-panel" data-material="glass">
  <div>Network</div>
  <div>Polygon</div>
</div>

• Glass needs something behind it. A glass panel against a flat surface looks like slightly tinted paper — the blur effect requires page content behind to be visible. Floating panels are the natural use case.
• Don't accent-tint the shadow. Pre-Apr-2026 the FAB popover used color-mix(--accent-primary 18%) in its light-mode shadow and read as a different surface from the playground rail. Neutral black-only is the contract — the glass fill carries any palette connection on its own.
• Use sparingly. backdrop-filter is GPU-expensive — twenty glass cards on a page hitch. Keep glass for floating chrome, not as a card surface.

Definitions: styles.css · search --material-glass-bg.
Underlying recipe (3 tokens): --surface-panel-glass, --shadow-panel-glass, --backdrop-panel-glass — defined in styles.css :root, exposed only through this material.
Consumers: .ds-doc-menu-panel, .cmd-palette__panel, .navbar::before. (.dropdown__panel moved to Paper material in May 2026.)
Spec: design.md §02 → Materials + §02 → Panel Surfaces.

<!-- gradient — for hero KPIs and one-off accent surfaces -->
<div class="card" data-material="gradient">
  <div>Cross-chain TVL</div>
  <div>$8.42B</div>
</div>

• Once per surface. Two gradient cards adjacent to each other compete; use gradient on a single hero surface and reach for tinted (much quieter) for secondary highlights.
• White text only. The brand gradient is too saturated for primary-text contrast; the demo primitive flips text to white automatically. Don't override back to --text-primary.
• Don't use for content cards. Gradient surfaces are a marketing / hero pattern. Inside a product UI (dashboards, the swap widget, signed-in app), reach for paper or tinted instead.

Definitions: styles.css · search --material-gradient-bg.
Brand gradient tokens: --lifi-sapphire, --lifi-ink in :root.
Spec: design.md §02 → Materials.

<!-- Default tint (--lifi-ink) -->
<div class="card" data-material="halo">…</div>

<!-- Override tint per element -->
<div class="card" data-material="halo"
     style="--accent-tint: var(--lifi-sapphire);">…</div>

<!-- The .brand-card class wears halo by default via :where() -->
<article class="tile brand-card"
         style="--accent-tint: var(--lifi-sapphire);">…</article>

Composer-tunable. Material Composer exposes the tint slider (default 12 %) for the gradient peak and the shadow tier slider. Opacity / blur / highlight are not applicable for halo.

• Use for brand-identity moments. A LI.FI brand showcase, a competitor card, a premium feature highlight, an “about this protocol” card. Halo signals “this card is the brand” without going as loud as gradient.
• One halo per region. Two halo cards adjacent to each other compete for the eye. If a row holds three brand cards, halo on each is fine — the directional gradient gives each card its own corner-anchored highlight. But within a single content block, reach for halo on one card and let neighbours sit on paper.
• Tint must be a brand token. Use --lifi-sapphire / --lifi-ink / --lifi-pink / --accent-primary, not raw hex. The LI.FI 1.0 default rule applies — never bake a literal palette value.
• The halo is anchored top-right. Don’t hand-author a different anchor (top-left, center, etc.) for one-off variants — either accept the system anchor or propose a new material. Anchor consistency is what makes a row of halo cards read as a family.

Definitions: styles.css · search --material-halo-bg.
Composer integration: shared.js → initMaterialComposer() — halo is in MATERIALS, DEFAULTS, APPLICABLE, and applyMaterialTokens.
Default consumer: .brand-card via :where(.brand-card) in styles.css. Spec: design.md §02 → Materials.

Single value across both themes — simplest form. Set --tile-accent directly when the same colour reads well in light and dark.

<article class="tile" data-material="halo"
         style="--tile-accent: var(--lifi-sapphire);">
  <div class="eyebrow-word">Partner</div>
  <h3 class="tile-title">Acme Wallet</h3>
  <p class="tile-body">…</p>
</article>

Dual-mode — recommended for branded tiles where the partner / integration / brand has tuned values per theme. Light values stay readable on a near-white surface; dark values gain the lift needed for a dark canvas.

<article class="tile" data-material="halo"
         style="--tile-accent-light: oklch(50% 0.18 250);
                --tile-accent-dark:  oklch(72% 0.16 250);">
  …
</article>

Active state — the standard sticky-selected affordance. Toggle .is-active on the article (typically via JS click handler) and the tile lights up in its own accent: bg shifts to an 8 % accent wash, border becomes the full accent, and a soft 18 px glow drops below.

<article class="tile is-active" data-material="halo"
         style="--tile-accent: var(--lifi-sapphire);">…</article>

• Reach for halo when the tile carries identity, not data. Partner showcases, integration directories, ecosystem spotlights, theme cards, premium feature tiles. The halo wash signals "this card has a personality." Don't use halo for KPI tiles, settings rows, form sections — those want paper.
• Pick single-value when light/dark contrast is fine, dual-mode when it's not. A medium-saturation hue often reads adequately on both surfaces — one --tile-accent is enough. A deep brand value that disappears on dark, or a vivid value that blares on light, needs dual-mode tuning.
• Active state is sticky. .is-active is a class you toggle via JS to mark a sustained selection (selected theme, active filter, currently-applied preset). Distinct from :active (the mouse-down momentary state). Don't use .is-active for hover.
• One active per group. When several tiles share a "pick one" relationship (theme picker, preset gallery, filter chips), enforce single-active in the click handler — remove .is-active from siblings before adding it to the click target.
• Don't override --mat-bg directly. The material recipe is parametric via --accent-tint — the .tile rule already wires that to --tile-accent. Setting --mat-bg by hand bypasses the system and breaks the composer.
• Contrast-aware text on filled buttons. If a tile carries an accent-filled button inside (like .brand-card's preview button), pair the --tile-accent-* colours with a --text-on-accent-* companion (near-black for bright accents, white for deep ones). The brand-card's --brand-c-on is the canonical pattern.

Token wiring: styles.css · search --tile-accent-light for the dual-mode contract on .tile; :where(.brand-card) for halo as default on brand cards.
Active state: .tile.is-active rule in styles.css (search .tile.is-active,).
Live consumer: design-system/competitors.html#brands — the brand-card grid composed from this recipe (the .brand-card wrapper provides the markup contract + chip / source / active-button details).
Halo material itself: documented at #material-halo above.

/* Reach for --space-N tokens; never use raw px outside the tokens themselves. */
padding: var(--space-24);       /* 24 px — comfortable card padding */
gap: var(--space-16);            /* 16 px — flex/grid item gap */
margin-bottom: var(--space-32);  /* 32 px — section break */

/* Cluster tokens for closer-grouped items: */
gap: var(--cluster-sm);           /* 6 px */
gap: var(--cluster-md);           /* 10 px */

• Geometry on grid — every dimension is a token. Width, height, padding, margin, gap, border-radius. If the value you'd write isn't on the 4px grid (i.e. not a multiple of 4), it's a bug — pick the nearest token instead. The 4n+2 values like 26 / 34 / 42 / 54 from older button tunings are exactly what we're moving away from.
• The two allowed exceptions are 1px and 2px — only inside border: / border-*: / outline: declarations (hairlines, focus rings). Everywhere else, use a --space-* token.
• If you can't find a token that fits, audit the size before adding one. Most "I need 38px" cases are really "I should snap to 36 or 40." Only add a new --space-* if the size is intentional, recurring, and on the 4px grid (e.g. a real WCAG 44px touch target). Ad-hoc literals are not the answer.
• Pick by intent. 4–8px for inline gaps; 12–24px for component-internal padding; 24–48px for compact control heights and chip widths; 32–64px for section padding; 96–160px for full-page hero spacing.
• Don't mix scales within a row. If buttons in a toolbar use 8px gap, the modifier control next to them does too. Mismatched scales side-by-side make the row feel arbitrary even when each value is individually on grid.
• Component sizes compose vertically. An icon button next to a text input must share a height (40 / 40, not 42 / 38). The grid is what makes "lining up" automatic instead of pixel-pushing.

/* Reach for the nearest tier; never write a literal width
   for a panel / modal / menu / palette. */
.modal--sm          { max-width: var(--w-6);  } /* 384px */
.modal              { max-width: var(--w-9);  } /* 480px */
.modal--lg          { max-width: var(--w-12); } /* 576px */

.cmd-palette__panel { max-width: var(--w-10); } /* 512px */
.ui-card            { max-width: var(--w-7);  } /* 416px */
.ds-doc-menu-panel  { width:     var(--w-3);  } /* 288px */

/* Width tokens compose with --space-* tokens for chrome — the
   width-token sets the surface contract, --space-* sets internals. */
.modal              { padding: var(--space-24); border-radius: var(--space-16); }

• Reach for the nearest tier; never write a literal width. A 410-pixel panel becomes var(--w-7), not 410px. The token reads as the surface's tier and a future tweak happens in one place. Same rule as the --space-* family — the literal value is implementation detail.
• Step semantics: --w-N+1 is the next tier up, always. No skips, no exceptions. The +32px step is uniform across the ladder, so "give me one bigger" is a pure increment without checking a table.
• Names are deliberately abstract — a surface type doesn't own a tier. --w-7 is the swap canvas today; tomorrow it's also a wallet-picker drawer or a quote-detail sheet. Don't rename a tier when a new surface lands on it; just use it.
• If a real component needs a width outside the ladder, inline it and document it. The chart playground modal sits at 1080px; the palette export modal at 720px. Both inline their max-width on the element with a code-comment explaining why. The --w-* ladder is for shared, repeating surfaces — workspace-class one-offs intentionally live outside it.
• If your component doesn't fit any tier, stop and ask. Most "I need 600px" cases are really "I should use --w-12 (576px) and shorten the body" or "this is a bespoke workspace, not a modal." The seventeen tokens are load-bearing; ad-hoc additions dilute the contract. Ask before adding a new --w-* token.
• Width tokens compose with --space-*. The width-token sets the container; --space-* sets internal padding, gap, and radius. Both must be tokenized — mixing a tokenized width with a literal padding (or vice versa) re-creates the drift the system is designed to prevent.
• Always pair with width: 100% + max-width: var(--w-*). Lets the surface shrink on narrow viewports without a media query, while still capping at the canonical width on desktop.
• Mobile behavior is the surface's responsibility, not the token's. The token gives you the desktop max; if a surface needs to go full-screen on mobile (cmd-palette does this at ≤640px), handle it with a media query that overrides the max-width — don't fork the token.

/* Every multi-size component should expose the same 4-tier modifier set */
.btn-sm     /* sm — 32px row */
.btn        /* default — 40px row */
.btn-lg     /* lg — 48px row */
.btn-xl     /* xl — 56px row */

/* Match neighbours in a row — same tier across siblings */
<div class="row">
  <input class="input--lg">
  <button class="btn-primary btn-lg">Submit</button>
</div>

Tier vocabulary. Four named tiers; semantic role per tier.

Lockstep ladders. Five token ladders that scale together per tier. Buttons demonstrate; other components map their own padX / padY when joining.

Math contract. A pill-style component lands on its target tier height when:

/* Pill components with line-height: 1 + 1px transparent border */
height = padY × 2 + line-box + 2px border

/* If the label is bigger than padY math allows, widen the line-box
   via calc-based line-height. Buttons use this trick on lg / xl. */
.btn-lg { font-size: 16px; line-height: calc(22 / 16); /* line-box → 22 */ }

Application matrix. Where the ladder is implemented today.

Radius token-binding — the playground per-theme corner channel. Beyond the height ladder above, every multi-size primitive should derive its radius via calc() off a customization token so the playground per-theme Corner sliders scale it in lockstep. Button-shaped primitives bind to --button-radius: .btn-*, .seg-* (wrapper + item + the .seg-menu split picker), .search-trigger, .btn-icon. Card-shaped primitives bind to --card-radius: .alert / .notification / .setting-row and the card family. Still literal — pending: .input--* and .field-inline--* use literal --space-* radii and don't yet track the sliders — they're value-drifting (--sm / --lg sit off the 8 / 12 / 16 / 20 ladder), so they need a value-normalization pass (snap to ladder, add --xl) before binding. The trap to watch: a literal that happens to match the ladder by value (e.g. var(--space-16)) reads correct at the 16px default but silently ignores the slider — .seg-menu and .search-trigger were both rebound from exactly that drift (June 2026).

• Same-tier siblings always align. An .input--lg sits next to a .btn-lg. Mixing tiers inside a single row breaks visual rhythm — the row reads as "the small one is wrong" rather than "two sizes."
• Heights derive from tokens, not arbitrary px. Every padding and radius is a --space-* token (4n only). The four heights — 32 / 40 / 48 / 56 — emerge from padY × 2 + line-box + 2px border. If the math doesn't land cleanly, widen the line-box via calc-based line-height rather than inventing a non-token value.
• Don't fork the ladder. If a new component needs size variants, map onto sm / default / lg / xl using values from the existing token grid. Never invent new tier names ("md-tight", "lg-loose"). If only two tiers fit the use case, ship just sm + default — don't create a parallel ladder.
• Skip the ladder for inherently single-size components. Some primitives don't earn variants — .fab, .callout, .modal, .search, the auto-TOC chip strip. They live at one canonical size only.
• Promote a missing tier to the system, not as a one-off. If a layout needs an xl input + xl seg, the fix is to extend those families to xl using the token map above — not to author one-off CSS rules. Update the application matrix when a new tier lands.

/* Component CSS — publishes a local --card-gap that defaults to a tier. */
.ui-quote-list {
  --card-gap: var(--gap-card-md);    /* 12 px default */
  display: flex;
  flex-direction: column;
  gap: var(--card-gap);
}

/* Per-instance override — no need to touch the component CSS. */
<div class="ui-quote-list" style="--card-gap: var(--gap-card-lg);">
  …
</div>

/* Context-scoped override: */
.compact-area .ui-quote-list {
  --card-gap: var(--gap-card-sm);
}

/* Swappable ladder — install a preset by overriding the 5 tier
   tokens at :root. Every consumer flips via cascade automatically;
   no component re-authoring needed. Same mechanism as the Palette
   Composer. */
:root[data-card-gap-preset="compact"] {
  --gap-card-xs: var(--space-2);
  --gap-card-sm: var(--space-4);
  --gap-card-md: var(--space-8);
  --gap-card-lg: var(--space-12);
  --gap-card-xl: var(--space-16);
}

Application matrix. Where each tier is wired today. Use cases are guidance, not contracts — if a new card list reads better at a different tier, that's a designer call.

Swapping the mapping. The ladder is a 5-token bundle; a future "card gap composer" installs a preset by overriding the 5 tokens at :root. Default mapping ships in styles.css; preset overrides go on :root[data-card-gap-preset="…"]. Component CSS stays untouched. See the Markup pane for the preset shape.

• One family per spacing concern. --stack-* is for vertical content rhythm (form fields, page sections); --cluster-* is for inline-flex gaps (icon + label pairs, chip clusters); --gap-card-* is for card-to-card spacing. Don't cross the streams — if a quote list reaches for --cluster-md, that's drift to fix at the call site.
• The md tier IS the default. When in doubt about which tier a new card list should use, start at --gap-card-md (12 px). The other tiers (xs, sm, lg, xl) exist for specific contexts: a tight pair with a FAB at the seam, a compact rail list, a marketing-tier hero grid. Don't reach for --gap-card-lg just because it "looks roomier" without a contextual reason.
• Reach for named tiers, never the raw --space-* underneath. If the value happens to match (e.g., --space-12), reach for --gap-card-md instead so the semantic intent is in the source. The grep grep "gap:.*--space-" *.css on card lists / grids should return nothing. Bypassing the tier to the raw value defeats the swappability — a future preset swap won't reach values authored as --space-12.
• Components publish a local --card-gap. Pattern: .foo-list { --card-gap: var(--gap-card-sm); gap: var(--card-gap); }. The local var gives consumers a per-instance override path without re-authoring the component (just set --card-gap in an inline style or context selector).
• Custom values via --card-gap, not new tier names. If a card list genuinely needs a non-system gap (rare), override --card-gap with any --space-* token at the call site. Don't invent --gap-card-medium-tight — the five-tier ladder is the ceiling. If the same custom value shows up in 3+ call sites, that's the signal to either remap the ladder via a preset or reconsider which tier the consumers should use.
• To install a different ladder mapping, override the 5 tier tokens at :root. A future "card gap composer" UI works this way: it sets :root[data-card-gap-preset="compact"] (or similar) with five new --gap-card-* values, and every consumer flips automatically via cascade. Component CSS is the contract; consumers always read named tiers via --card-gap; the mapping is the variable layer underneath.
• Adjacent families: --stack-* for vertical content gaps (sections, form fields). --cluster-* for horizontal inline gaps (icons + labels). --gap-card-* for card-to-card. Sub-card internal spacing (e.g., padding inside .ui-amount-card) lives in the per-card --amount-card-* tokens, not here.
• Nested rhythm — wrap a sub-group to tighten without touching the outer container. When a container's gap is correct for separating top-level zones (header → group → footer) but a subset of children wants to read as one coherent set, don't change the container's gap. Drop a stack wrapper around the subset that publishes its own tighter --card-gap. The outer rhythm survives; the inner group feels denser. Canonical example: the swap form's state-content keeps 16 px between header → stack → action footer, while the inner .ui-form-stack (limit-price card + amount pair + expires-in row + alerts) runs at 8 px. The wrapper class is per-page composition — the reusable thing is the wrap-and-publish---card-gap technique, not the wrapper name.

/* :root defaults (styles.css) — mode-independent, no [data-theme] variant. */
:root {
  --grid-gap-x: var(--space-16);   /* horizontal gutter — grid column-gap */
  --grid-gap-y: var(--space-24);   /* vertical rhythm — margin / row-gap */
}

/* A canvas grid consumes BOTH axes. */
.portal-kpi-grid {
  display: grid;
  column-gap: var(--grid-gap-x);
  row-gap: var(--grid-gap-y);
  margin-bottom: var(--grid-gap-y);   /* section rhythm below */
}

/* A canvas with a non-default gutter pins its own; the composer paints
   over it inline. */
.playground-canvas {
  --grid-gap-x: var(--space-24);   /* historical widget gutter */
}

/* The composer paints to the active canvas via the shared helper. */
// shared.js
window.ThemeComposer.applyGapsToScope({ x: 24, y: 32 }, canvasEl);

Preset trios + slider ladder. The Custom sliders step the ladder 8 / 12 / 16 / 20 / 24 / 32 / 40 (starts at 8 — cards never touch).

Consumers today. Two canvases. The Portal inherits the 16/24 defaults; the Playground pins --grid-gap-x: 24.

• Two axes, not one. Between-cards gutter (--grid-gap-x → column-gap) and between-sections rhythm (--grid-gap-y → margin-bottom / row-gap) serve different jobs and differ by default (16 vs 24). Don't collapse them to one symmetric gap.
• Distinct from the card-gap ladder. --gap-card-* is the universal card-LIST gap family any list opts into; --grid-gap-x/y is the composer-controlled CANVAS rhythm. Portal/Playground canvas grids consume --grid-gap-x/y; everything else uses the card-gap ladder. Don't cross them.
• Reach for the token, not the underlying --space-* when wiring a canvas grid/section — a bare --space-24 on a canvas section defeats the composer knob. Intra-component cluster gaps (icon + label, inline pairs) stay --space-*; only the canvas grid + section rhythm tokenize to --grid-gap-*.
• The FAB composer surfaces Spacing only when a canvas is present. DEFAULT_FEATURES.gaps = false (the bare default stays off); it’s enabled in the Portal + Playground rail mounts (features.gaps: true) and in the FAB gated on a canvas (features.gaps: !!canvas). Gaps are a per-canvas concern: on chrome-only pages (marketing / catalog / launchpad) the FAB has no canvas to scope to, so it omits Spacing (painting --grid-gap-* to :root would be a no-op there anyway). Unlike corners + surface, whose tokens are universal consumers and stay in the FAB unconditionally.
• Adding a 3rd canvas consumer: wire its grids/sections to the tokens, enable features.gaps in its rail composer mount, and — if its default differs from 16/24 — pin a per-canvas default + seed the editor from the canvas's effective gaps (the Playground pattern, so the readout stays honest). Don't add gaps to the FAB without surfacing first.
• Source of truth: tokens in styles.css :root; helpers ThemeComposer.readGaps / ThemeComposer.applyGapsToScope / ThemeComposer.clearGapsFromScope in shared.js; composer theme-editor.js → features.gaps. The durable contract is CLAUDE.md → Canvas grid-spacing system; this card is the rendering.

/* Concentric corners — a child's radius derives from the parent's
   radius and the padding (the gap) between them. One equation: */
/*   outer radius = inner radius + padding  */
/*   inner radius = outer radius − padding  */

/* The usual case — choosing a NEW nested element's radius.
   --space-16 here is the parent's padding; clamp the floor at 0. */
.child {
  border-radius: max(var(--card-radius) - var(--space-16), 0px);
}

/* Worked:
     parent 24 + pad 8   → child 16   (concentric)
     parent 16 + pad 24  → child 0    (sharp: inset exceeds the radius) */

The relationship. One equation, read from either end.

Worked examples. Inner radius derived as max(outer − padding, 0). Every value a --space-* token.

Outward — the over-round ceiling. Framing a card around content, the outer radius is min(inner + padding, 32). Below the cap it tracks the content concentrically; past it the card stays calm instead of ballooning. .destination-card is the reference consumer.

• Concentric means a constant gap. The two corner curves stay parallel only when outer = inner + padding. Matching the radii (ignoring the padding) makes the gap pinch around the diagonal — the inner corner reads as crowded. It's the most common rounded-corner mistake.
• Two directions, each clamped. Designing a frame around known content → outer = min(inner + padding, 32) (ceiling). Choosing a new nested element's radius → inner = max(outer − padding, 0) (floor). Same equation, solved for different unknowns, each clamped at its limit.
• Clamp the floor at 0 — never negative. Use max(var(--card-radius) - var(--space-N), 0px). When padding ≥ the parent's radius, the child's corners go sharp: the parent's straight edges start before the child's corner, so any rounding crowds the bend.
• Cap the ceiling at 32 — never over-round. Use min(calc(var(--inner-radius) + var(--space-N)), var(--space-32)). Once inner + padding exceeds 32, the encompassing card stops tracking the child and reads as a calm rounded card rather than an over-bubbled one — strict concentricity balloons the corner at large padding, and the curves are far apart at that scale anyway, so the cap is barely perceptible. .destination-card (seed 16 + pad 32 = 48 → 32) is the reference. The outward twin of the 0px floor.
• It's a calc, not a token. There's no --nest-radius — the value depends on two per-context inputs (the parent's radius + the gap to it), so the calc() is the API. Pull the parent radius from --card-radius / --panel-radius and the padding from the parent's own --space-*.
• Derive, don't retrofit. Card / panel / button radius all default to a flat 16 px for top-level surfaces (see Sizing ladders + the Radius system) — that flat default is deliberate. Reach for the concentric calc on new nested work where the parallel-curve look matters; retrofitting existing nested cards to step their radii is a separate, visible design decision.
• Source of truth: CLAUDE.md → Nested radius — concentric corners (the durable contract). Spec in design.md → Nested radius; the calc pattern is documented next to the radius tokens in styles.css.

<!-- Theme is set on <html>. shared.js writes data-theme from the toggle. -->
<html data-theme="light">…</html>
<html data-theme="dark">…</html>

/* Surface fills consume tokens that flip per theme. */
.page      { background: var(--surface-page); }
.well      { background: var(--surface-sunk); }
.section   { background: var(--surface-raised); }
.card      { background: var(--surface-card); }

/* For composed character (paper, glass, gradient, halo) reach for
   a Material instead of stacking surface + shadow + border by hand.
   See #materials. */

The fill family. Five solid + one glass. Light/dark values auto-flip via [data-theme="light"].

Light mode caps at --surface-page. The dark surface ladder steps 5 → 8 → 16 → 24% lightness (rebalanced May 2026 v2 — pre-rebalance was 5 → 8 → 10 → 15 with a too-tight 2% page→raised step; v1 went 8 → 14 → 19; v2 settled on uniform 8% steps); in light mode the canvas is already 100% white, so there’s no value “above” it for a card to step up to. --surface-card pivots to var(--surface-page) in light and cards lift via shadow alone (Material Design approach). The pivot lives in one token; component CSS never branches per theme.

• Theme is set via [data-theme="dark"] or [data-theme="light"] on <html>. Pre-paint init in shared.js reads localStorage to avoid FOUC.
• Dark = default. Light is opt-in via the toggle.
• Surface tokens layer correctly. --surface-raised on top of --surface-page; --surface-card on top of either. Don’t skip tiers.
• For state — reach for the alpha layers, not raw rgba. Hovers, active pills, recessed tracks all live in Elevation → Alpha state layers. The alpha tokens flip correctly across themes; raw rgba doesn’t.
• For lift — reach for the --elev-* tier, not a hand-authored shadow. See Elevation → Elevation tiers.
• For composed character — reach for a Material. Paper / raised / sunk / glass / tinted / gradient bundle fill + border + shadow + backdrop + highlight. See Materials.
• Theme-flip via the Theme Composer — every derived token recomputes from seeds, so palette changes apply instantly.

/* Two family tokens — set once on `html`, never override per-component. */
--font-sans: 'Geist', system-ui, -apple-system, 'Segoe UI', sans-serif;
--font-mono: 'Geist Mono', ui-monospace, 'SF Mono', Menlo, Consolas, monospace;

/* Default everything to sans — single declaration on the document root. */
html { font-family: var(--font-sans); }

/* Opt into mono only when the content is technical. */
code,
.mono,
.eyebrow-code,
.ds-doc-codeblock { font-family: var(--font-mono); }

/* Inline token reference inside prose — small surface, mono font, faint
   tinted bg so it reads as "reference" without becoming a chip. */
code {
  font-family: var(--font-mono);
  font-size: 0.92em;
  background: color-mix(in oklch, var(--text-primary) 6%, transparent);
  padding: 1px 6px;
  border-radius: var(--space-4);
}

Family tokens

Loaded weights

Where each is used

• Both families are per-theme — the Theme Composer's typography axis. --font-sans (Geist by default) and --font-mono (Geist Mono by default) are each driven by the active theme's font / mono field, painted on apply (e.g. LI.FI 2.0 → Inter + IBM Plex Mono). The scale, weights, and tracking below stay SHARED across brands — only the two families swap. See CLAUDE.md → "Typography axis".
• Mono is institutional, not decorative. Use it when the content is genuinely technical — code, addresses, numeric values, token names, eyebrow markers. Don't reach for mono to make body copy look "engineered" or "data-flavored." That drift makes the system read as caricature; mono loses its meaning when it's used everywhere.
• Body copy is always Geist 400 / 16px / 1.6. Never compress for "data density" — the system fits at 16px.
• Inline <code> in prose is a token reference. When you mention a token name, surface name, or class in copy (--accent-primary, .ds-doc-card, oklch(68% 0.220 268)), wrap it in <code>. The mono font + tinted background makes the difference between "the accent token" (prose) and --accent-primary (reference) visible without parentheses.
• Mono headings are rare. Use sans for hierarchy. The exception: an eyebrow/kicker ABOVE a heading (.eyebrow-code, .ds-doc-eyebrow) — that's mono uppercase 500–700, deliberately quiet, anchoring the heading below it. A full mono <h1> reads as a code-snippet headline, not a section title.
• Don't load weights you don't ship. Geist 300/800/900 are loaded for deck-tier compositions and brand extremes; Geist Mono stops at 700 because mono past 700 reads as graphic, not code. If you find yourself needing a weight that isn't loaded, the answer is usually "use the next loaded weight," not "add another."
• Pair with the right line-height. Mono inherits the same --lh-* token rules as sans. Geist Mono's loose default line-height fights tables and code blocks — pair with --lh-sm (20px) for caption-tier mono, --lh-body (24px) for body-tier mono, and the matched display tokens above that.
• The .mono / .mono-sm utilities exist for table columns. Token-name columns and small numeric columns use them so the column reads as a list of identifiers, not prose. Don't apply .mono to a whole table row or paragraph — it's a per-cell utility.

/* The Jumper sans token — defined once in styles.css :root, next to
   --font-sans. Same system fallback stack. */
--font-jumper: 'Urbanist', system-ui, -apple-system, 'Segoe UI', Arial, sans-serif;

/* Consume at the BRAND-SURFACE level — a Jumper page/region sets the
   family once on its root, never per-component. */
.jumper-surface { font-family: var(--font-jumper); }

/* Current consumer — the lockup sub-product label: */
.brand-lockup--jumper .brand-lockup__label { font-family: var(--font-jumper); }

<!-- Pages that render Jumper chrome load Urbanist alongside Geist: -->
&family=Urbanist:wght@300;400;500;600;700;800;900

Family token

Shared vs differentiated — the brand-overlap contract

Loaded weights

• The swap happens at the brand-surface level, never per-component. A Jumper page or region sets font-family: var(--font-jumper) once on its root; components inherit. Mixing Geist and Urbanist inside one surface is the drift this token exists to prevent.
• Everything except the family is shared. Sizes, line-heights, weights, tracking, and the mono family all come from the existing ladders. Don't author Jumper-specific type sizes or weight roles — if a value feels wrong in Urbanist, surface it as a system question, not a per-brand fork.
• Load Urbanist on pages that consume the token. The token's fallback stack means an unloaded page silently renders system sans — fine for resilience, wrong as a steady state. Add family=Urbanist:wght@300..900 to the page's Google Fonts link when its chrome goes Jumper.
• Mono stays Geist Mono on both brands. Addresses, code, numerics, and eyebrows are institutional, not brand voice.
• This is the interim integration. Jumper lives inside the LI.FI design system (shared components, shared dev + design resources) until the formal brand split. When that lands, this card is the seed of the extraction checklist — the Differentiated rows in the Anatomy contract are exactly what moves.

<!-- 1. Section header — .content-tile with mono eyebrow + sans h3 + sans body -->
<div class="content-tile content-tile--sm">
  <p class="content-tile-eyebrow">// 03 — Foundations</p>
  <h3>Color tokens describe intent</h3>
  <p>Pages reference <code>var(--accent-primary)</code> …</p>
</div>

<!-- 2. KPI — real .stat-card primitive: eyebrow + value + delta chip -->
<div class="stat-card">
  <div class="stat-card-eyebrow">Volume routed · Q1 2026</div>
  <div class="stat-card-value">$1.24<span class="stat-card-unit">B</span></div>
  <div class="stat-card-footer">
    <span class="stat-card-label">vs. Q4</span>
    <span class="chip chip-delta-pos">↑ 38.4%</span>
  </div>
</div>

<!-- 3. Inline references — wrap token names / addresses / events in <code> -->
<div class="card">
  <p>Quotes route through the <code>0xb1739…ee01</code> aggregator…</p>
</div>

<!-- 4. Detail list — sans dt term, sans dd value; wrap hex / tx hash in <code> -->
<dl class="detail-list">
  <div class="detail-list__row">
    <dt class="detail-list__term">Recipient</dt>
    <dd class="detail-list__desc"><code>0x742d35…f8e3</code></dd>
  </div>
  <div class="detail-list__row">
    <dt class="detail-list__term">Amount</dt>
    <dd class="detail-list__desc">1,250.00 USDC</dd>
  </div>
</dl>

<!-- 5. Tab nav — .ds-doc-tab-nav above .card content -->
<div class="ds-doc-tab-nav" role="tablist">
  <button class="ds-doc-tab-nav-item is-active">Overview</button>
  <button class="ds-doc-tab-nav-item">Routes</button>
</div>
<div class="card">
  <h4>Bridge volume across 28 chains</h4>
  <p>Routes are scored by execution time, slippage, and fee.</p>
</div>

• Mono is the technical anchor; sans is the editorial voice. Reach for mono when content is genuinely a reference (a token, an address, a token name, a code symbol). Reach for sans for everything that's prose or UI label. The two together give a composition technical credibility without making the whole surface feel like a code snippet.
• One mono cluster per region. An eyebrow + heading + body with inline code works because mono lives in two intentional spots (the eyebrow, the references). A surface with mono labels, mono headings, mono buttons, and mono captions reads as a debug console — mono loses its meaning when it's the default voice.
• KPI / stat numerics use mono. Numbers across rows align column-to-column at fixed-width. Don't sans-ify a stat block thinking it'll look "softer" — the readability cost is real when readers compare values down a column.
• Inline code is the default for token references in copy. Wrap token names, class selectors, file paths, hex strings, and OKLCH literals in <code>. The mono font + tinted background makes "the accent token" (prose) different from --accent-primary (reference) without parenthetical asides.
• Tab nav, eyebrows, and small uppercase markers all share the same recipe — mono 500 or 600, uppercase, --tracking-wider. They're "section signs" that tell the reader "you're crossing an architectural boundary." Don't decorate; the recipe IS the signal.
• Mono headings are the rare exception. A full mono <h1> reads as a code-snippet headline, not a section title. Use sans for hierarchy; pair an uppercase mono eyebrow above the heading if you need the technical signal.

/* Type scale tokens — match the catalog's scale, never roll your own px. */
font-size: var(--text-display);   /* 56 px display heading */
font-size: var(--text-h1);        /* 40 px page title */
font-size: var(--text-h2);        /* 32 px section title */
font-size: var(--text-h3);        /* 24 px sub-section */
font-size: var(--text-body-xl);   /* 20 px oversized lede */
font-size: var(--text-body-lg);   /* 18 px large body / xl button labels */
font-size: var(--text-body);      /* 16 px prose */
font-size: var(--text-sm);        /* 14 px dense reference */
font-size: var(--text-caption);   /* 12 px caption / label */
font-size: var(--text-micro);     /* 10 px ticks / badges / superscripts */

/* Pair with the right line-height + tracking tokens from --lh-* and --tracking-*. */

Families. --font-sans = Geist (everything except code). --font-mono = Geist Mono (code, addresses, numeric values, eyebrows). Mono is institutional; never decorative.

Deck-tier weight override. Hero / Display / H1 sit at 700 — the brand's heaviest editorial weight. The deck tier (.text-poster · .text-statement · .text-keynote · .text-colossal) is the only exception in the scale: it overrides to 800. Reason — at canvas-fill scale (≥112px) the letterforms read as outlines at 700; the +100 weight bump restores the visual presence the composition expects. Authored as a single shared rule on the four utilities + their --fluid siblings; don't fork per-class. Source: styles.css → search .text-poster, .text-poster--fluid,; spec: design.md §03 → Mega Display weight override.

Deck-tier fluid clamps. Every deck-scale utility ships a --fluid sibling — .text-poster--fluid = clamp(48px, 9vw, 112px); .text-statement--fluid = clamp(56px, 12vw, 144px); .text-keynote--fluid = clamp(56px, 16vw, 192px); .text-colossal--fluid = clamp(48px, 22vw, 256px). Use the fluid form on responsive surfaces; reserve the static form for known-fit contexts (a 1920×1080 deck slide, a desktop-only landing hero).

Gradient mega. Pair deck-scale type (≥112px) with .text-gradient-mega — a 110° gradient at 180% horizontal span tuned so the shimmer reads across a single word. The standard .text-gradient compresses badly at this scale.

• Pair every font-size with its tier's line-height. Caption-tier text (--text-caption 12px, --text-sm 14px) takes --lh-caption (16px) or --lh-sm (20px). Body text takes --lh-body. Display text takes the matched --lh-display/--lh-hero/etc. Mismatching tiers — e.g. --lh-body (24px line-box) under --text-caption (12px font) — reads at ~1.92 ratio, not 1.5, because the line-box was tuned for a 16px font. Bug history: May 2026, .tooltip--multi shipped line-height: var(--lh-body) on caption-size text; result read as airy and off-tier. Fix removed the override; multi-line variant inherits --lh-sm from the base. Validator E015 now flags this pattern.
• Static font → static --lh-* token. When font-size is a fixed token (e.g. .text-keynote, .text-h1), pair with the matching pixel --lh-* (e.g. --lh-keynote: 180px). The pixel line-heights are designed at the right ratio for the static font size.
• Clamped/fluid font → unitless literal line-height. When font-size uses clamp(), NEVER use a pixel --lh-* token — the line-height stays fixed while the font shrinks below its static size, dropping the ratio under 1.0 and overlapping lines. Use line-height: 1.18 (display/hero) or 0.95 (≥112px) instead. The bug pattern that lit this rule: --lh-display on responsive heroes.
• Deck scale = one line, one phrase. The 112–256px tier carries sub-1.0 line-heights for canvas-fill — no wrapping, no multi-line. If a phrase doesn't fit, drop a tier (keynote → poster → hero) or shorten it. Colossal (256px) is reserved for single-word reveals — LI.FI, CONNECT., YES.; anything more belongs at keynote (192px) or below.
• Gradient .grad spans inside display type need the descender-escape block — display: inline-block; padding: 0.04em 0.08em 0.04em 0; line-height: inherit. Without it, -webkit-background-clip: text slices descenders on g/y/p (most visibly on words like typography, liquidity).
• Deck scale (≥112px) uses .text-gradient-mega, not .text-gradient. The standard gradient compresses at this scale; the mega variant has a wider hue path and a 180% horizontal span tuned for the canvas-fill case.
• Tracking is part of the contract. --tracking-tighter (−4%) for h1/display/hero/poster/statement; --tracking-crunch (−5%) for keynote + colossal; normal for body; --tracking-wide / --tracking-wider for caption / eyebrow uppercase. Don't override per-instance.
• Mono is for code, addresses, numeric values, eyebrows. Never for body copy.
• Body copy stays at 16px / 1.6 line-height. Don't compress for "data density" — the system fits at 16px.

<!-- Inline tuner — picker chips and slider rows are rendered from
     MATERIAL_REGISTRY in shared.js. Markup is just the empty
     containers; JS populates them at init (and re-renders the
     slider column when the active material changes). -->
<div class="material-composer">
  <div class="material-composer-tray" data-mc-preview>
    <div class="material-composer-surface"
         data-material="paper"
         data-mc-preview-surface
         data-mc-role="Card">…</div>
    <!-- 3 more surfaces (tile, small, panel) -->
  </div>
  <div class="material-composer-controls">
    <!-- Empty — JS renders one chip per registry entry -->
    <div class="material-composer-picker" data-mc-picker></div>

    <!-- Empty — JS renders only the active material's controls.
         data-mc-slider-class adds a class to each <input type="range">
         (use slider-range--panel for the inline card; omit for modal). -->
    <div class="material-composer-sliders"
         data-mc-sliders
         data-mc-slider-class="slider-range--panel"></div>

    <button data-mc-open-modal>Open full composer</button>
    <button data-mc-reset>Reset material</button>
  </div>
</div>

<!-- Modal workspace lives at the bottom of the page (id="material-composer-modal").
     Same hooks; JS auto-syncs sliders between inline ↔ modal. -->

Registry-driven. Picker chips and slider rows are rendered from a single MATERIAL_REGISTRY array in shared.js → initMaterialComposer(). Each entry declares id + label + defaults + controls (the dials it exposes) + writeTokens(state, root) (how dial values translate into --material-<id>-* token writes). Adding a material is two adjacent edits: add the entry here, add the matching tokens + [data-material="…"] block in styles.css. The init driftCheck() compares the two and console.warns on mismatch.

Markup hooks

Material registry — current shape

• Sliders mutate --material-<name>-* at :root. Every consumer (cards, panels, the FAB popover, dropdowns, etc.) reads var(--mat-*) via the [data-material] attribute selectors and repaints automatically. No per-component wiring.
• The registry is the single source of truth for the composer. Picker chips and slider rows are rendered from MATERIAL_REGISTRY; nothing about the material set is hand-coded in HTML. To add a material: append one entry to the registry AND add tokens + a [data-material="…"] block in styles.css. The drift check at init flags forgotten halves.
• Each material exposes only the dials that affect it. Halo shows tint + shadow; glass shows opacity + blur + highlight; paper / gradient show opacity + shadow + highlight. No greyed-out theatre — switching materials re-renders the slider column to honest controls.
• LI.FI 1.0 default rule. Saved variants live in localStorage but the composer NEVER auto-loads them on page init. The user has to click a saved variant to apply it. This is the same brand-protection rule that governs the Theme Composer.
• Composer state isn't a Material. Tuning opacity from 100 to 80 isn't authoring a new material — it's previewing what the existing one would look like at that value. Promote a tuning to a real material by exporting JSON, hand-promoting the values into styles.css --material-*-* definitions, and adding a card in #materials.
• Don't author "saved variant = material". Variants are temporary explorations. The system Materials are the named, hand-curated set in styles.css.
• Export is the only path back into the system. The Composer never writes to styles.css, never opens a PR. Export JSON, paste into a commit, run the validator.

• CSS — styles.css · search MATERIAL COMPOSER for the inline workspace + modal styles. The Materials layer itself is documented in #materials (Foundations).
• JS — shared.js · initMaterialComposer(). Auto-mounted from DOMContentLoaded.
• Spec — design.md §02 → Materials → Material Composer.
• localStorage key — lifi-mc-variants · array of {name, material, values, createdAt}.
• Related — #theme-composer (sibling tool — the Theme Composer), #materials (the layer this Composer edits).

/* styles.css — formula-driven semantic tokens (excerpt). The four
   anchors are LIVE FUNCTIONS of --brand-anchor, not hand-typed
   oklch literals. Swap --lifi-sapphire → everything rebalances. */
:root {
  /* Brand anchor — feeds the semantic formula */
  --brand-anchor: var(--lifi-sapphire);

  /* Per-role coefficients — dark-mode defaults */
  --sem-success-L-offset: 0.040;
  --sem-success-C-mult:   0.770;
  --sem-success-H:         165;
  /* … danger · warn · info … */

  /* Derived semantic anchors — OKLCH relative-color formulas */
  --success: oklch(from var(--brand-anchor)
                   calc(l + var(--sem-success-L-offset))
                   calc(max(c, 0.12) * var(--sem-success-C-mult))
                   var(--sem-success-H));

  /* Companion bg / border tint from the role token itself */
  --success-bg:     color-mix(in oklch, var(--success) 14%, transparent);
  --success-border: color-mix(in oklch, var(--success) 30%, transparent);
  --success-fg:     var(--success);
}

[data-theme="light"] {
  /* Light mode — same formula, different coefficients */
  --sem-success-L-offset: 0.095;
  --sem-success-C-mult:   1.000;
}

A theme customizes the coefficients via the optional semantics field on its record — per-mode lo / cm plus role-locked hues. Absent → the formula defaults above.

// theme record (theme-presets) — optional semantics override
semantics: {
  hues:  { success: 165, danger: 24, warn: 98, info: 264 },
  dark:  { warn: { lo: 0.100, cm: 1.40 } },  // partial OK — merges over defaults
  light: { warn: { lo: 0.280, cm: 1.60 } }
}

Formula-driven, tuned per theme. The semantics live in styles.css as OKLCH relative-color expressions — not hand-typed values. Each role anchor reads the L and C of --brand-anchor, applies a per-role offset (L) and multiplier (C), and locks the hue to a canonical position. The Theme Composer’s Semantic states section edits the coefficients per theme: at :root it writes the --sem-* coefficient vars (the formulas recompute via cascade); on a scoped canvas (Playground widget, Portal brand surface) it re-derives the tokens as resolved literals, since the :root formula can’t re-resolve against a canvas seed.

The doctrine — three channels, three owners

Guardrails — slider ranges

Each slider in the Theme Composer’s Semantic-states section is bounded so the formula can’t drift a role outside its legible territory. lo and cm are per-mode; the hue is role-locked and shared by both modes.

Where the values live

Browser support

OKLCH relative-color syntax (oklch(from <color> L C H)): Chrome 119+, Safari 16.4+, Firefox 128+. Evergreen-safe by 2026. Older browsers fall back to whatever the cascade can compute — typically the inherited default. If you need older-browser support, ship a @supports not (color: oklch(from red l c h)) fallback block with the hand-typed legacy values.

Do

• Tune per theme — Theme Composer → Semantic states (the floating composer, the Playground rail, or Portal Settings → Theme). Pick the role in the seg, drag L offset / Chroma × / Hue; the swatch + preview chips show the resolved tone.
• Reach for this when a theme wrecks a state — the canonical case is a light or low-chroma brand anchor washing --warn out so a warning no longer reads as one. Fix it on that theme; the correction saves to the theme record and travels with it.
• Test in both modes — lo / cm are per-mode (the section re-syncs on every mode flip); the hue is shared.
• When the brand palette merely changes hue or shifts a little, do nothing — the cascade rebalances every semantic from the new --brand-anchor automatically.
• Export CSS carries the customization — the --sem-* coefficient vars land in :root (dark + hues) and the light block (light lo/cm), exactly the shape styles.css uses.

Don’t

• Don’t hand-type --success: oklch(…) literals into styles.css. The formula is the source of truth; direct overrides break the cascade and bypass the brand-link.
• Don’t expect an edit to apply outside its theme — coefficients persist on the theme record and apply when that theme is picked. Nothing auto-applies on cold load (the LI.FI 1.0 default rule).
• Don’t add a new role without extending both sides: the styles.css formula block (coefficients + oklch(from …) + companions) and theme-composer-core.js (SEM_ROLES / SEM_DEFAULTS) + the editor’s role list.
• Don’t substitute spectral hues for semantic state — the semantic tier is status-only (see the colour-usage card above).

The editor is one layout-agnostic primitive mounted into any host. The list is compact .theme-card--row cards, one per preset via window.ThemeComposer.renderCardRow(preset, mode, isActive). The edit view is window.ThemeComposer.mount(opts) — the host passes the axis seeds + a scope and owns persistence through onChange (the primitive is storage-agnostic).

// Mount the editor into any host (theme-editor.js). scope decides WHERE
// it paints: null → :root sitewide · element/array → that canvas only.
const controller = window.ThemeComposer.mount({
  host:     editHost,
  palette:  { dark, light },                         // OKLCH seeds per mode
  meta:     { name, description },
  radii:    window.ThemeComposer.readRadii(preset),    // {card,panel,button,pill}
  gaps:     window.ThemeComposer.readGaps(preset),     // {x,y}
  surface:  window.ThemeComposer.readSurface(preset),  // {dark,light} L recess
  panels:   window.ThemeComposer.readPanels(preset),   // 'elevated' | 'flat'
  scope:    [playgroundCanvas],   // rail → canvas · FAB → canvas|null · Portal → chrome|brand
  features: { gaps: true, surface: true, panels: true },  // palette/corners/meta default on
  onChange: (next) => persist(next)   // host owns storage; editor is storage-agnostic
});
// controller: setPalette · setRadii · setGaps · setSurface · setPanels · setSemantics · setCharts · setMode · refresh · destroy

<!-- List card — emitted per preset by window.ThemeComposer.renderCardRow() -->
<div class="theme-card theme-card--row" data-theme-card="lifi-1">
  <button class="theme-card-select" data-theme-card-select></button>
  <span class="swatch-strip"><!-- N accent + surface .swatch--strip --></span>
  <div class="theme-card-body">
    <span class="theme-card-name">LI.FI 1.0</span>
    <span class="theme-card-meta">Legacy Pink · LI.FI Blue</span>
  </div>
  <button class="theme-card-edit" data-theme-card-edit>…</button>
</div>

This catalog Preview is hydrated by the catalog-only ds-theme-composer.js — it mounts the real editor with scope:[host] + onChange as a no-op, so the doc demo paints only itself and never persists.

The engine stores seeds, never derived tokens. Each saved theme is a flat set of OKLCH seeds per mode; deriveTokens recomputes the full token map on every apply, so derivation logic stays the single source of truth. The non-palette axes (radii / gaps / surface / panels / semantics / charts) are optional — absent means the baseline default.

// Preset record — theme-presets[]
{
  id: 'lifi-1', revision: 6,
  name: 'LI.FI 1.0',
  description: 'Legacy Pink · LI.FI Blue',
  // display-only (competitors page / brand cards):
  category: 'Cross-chain', website: 'https://li.fi',
  source: { name, url }, palette: [ { hex, label }, … ],
  // engine inputs — OKLCH seeds per mode (hue-parity: each accent's h matches across modes):
  dark:  { primary:{l,c,h}, secondary:{l,c,h}, tertiary:{l,c,h}, surface:{l,c,h} },
  light: { /* same shape */ },
  // non-palette axes (all optional; absent → baseline default):
  radii:   { card, panel, button, pill },   // button = RENDERED px (paint adds +4 anchor)
  gaps:    { x, y },
  surface: { dark, light },                 // per-mode L recess below the page seed
  panels:  'elevated' | 'flat',
  semantics: { hues, dark, light },           // per-role state-token coefficients (optional)
  charts:  'spectral' | 'brand'              // categorical series tier (optional; default spectral)
}

// localStorage keys (brand-neutral; pre-rename lifi-* migrated on read)
theme-presets   // the preset list (cold)
active-theme    // id of the active preset
brand-palette   // the hot active seeds

Bundled merge. presets.js ships window.BUNDLED_THEME_PRESETS; store.load() installs them on first visit and appends any new bundled id on later visits — user-created themes are never overwritten. The seed default is DEFAULT_PALETTE (LI.FI 1.0). Nothing auto-applies on cold load (per the LI.FI 1.0 default rule); the composer paints in-session only.

Two views, one stage. The composer toggles data-tc-view="list" | "edit" on the .tc-stage element. The list manages saved themes (compact .theme-card--row cards); the pencil drills into the edit view, which mounts the shared editor pre-filled with the theme's seeds + axis values.

The customization axes

Four mounts · same primitive, different scope

Interaction behaviours

• The composer themes the content canvas, never the chrome. A canvas-scoped edit must not mutate the sitewide closure palette — the mode-toggle observer would re-broadcast it to :root one flip later (the "overrides the whole page" leak). Canvas mounts build a local palette; the closure write is guarded if (!canvas).
• Edits are always live-save. Never add a Save or Cancel button — it breaks the single source of truth and makes changes read as provisional.
• LI.FI 1.0 is the only cold-load default. Nothing auto-applies from localStorage on load; the composer paints in-session only and the editor never auto-paints on mount (only a card-click / drag paints).
• Surface re-asserts after every palette paint. --surface-sunk is a deriveTokens output, so applyPalette re-writes a baseline on every paint — paintSurface() runs last to keep the custom recess. Corners / gaps are not in deriveTokens, so a single paint sticks.
• The Button-radius slider reports the rendered radius, not the token anchor. --button-radius is the lg-tier anchor; the slider value is written as value + 4 via ThemeComposer.buttonRadiusToAnchor. Don't simplify the offset away.
• Theme Composer is the only supported surface for editing brand palettes. Don't build one-off colour editors — every other panel reads tokens, never sets them.
• Source of truth: design/theme-composer.md — the canonical architecture / composition / logic map. The per-axis paint contracts live in CLAUDE.md (Theme Composer scope · Radius system · Canvas grid-spacing · Surface contrast control · Panel primitive); this card is the rendering.