Acme Wallet
Cross-chain swap embedded directly in the wallet's send sheet. 400k MAU.
Colour, type, spacing, elevation, surfaces, materials and device sizes, with the composers that tune them.
Ink, Sapphire and Pink in a 60 / 30 / 10 ratio, shared by product, marketing and docs.
#0C0E2E at 10%
Surfaces, text, borders
#405CCF
CTAs, links, focus, data
#F7C2FF
Signature accent
Semantic
--success
oklch(63% 0.16 155)
#00A35D
--danger
oklch(66% 0.18 24)
#EC5B59
--warn
oklch(78% 0.17 67)
#FF9E00
--info
oklch(71% 0.15 269)
#7C9BFD
Semantic state tokens
Each semantic state has three tokens in one hue, for alerts, callouts, toasts and info panels. Use --{name}-bg for the surface, --{name}-border for an optional border and --{name}-fg for emphasis text and icons. Both modes are set in :root and [data-theme="light"].
Success. The bridge route was found and quoted.
Info. This preset stays put across brand-preset switches.
Warn. The rate limit will reset in 30 seconds.
Danger. The transaction was rejected by the wallet.
--success-bg
--success at 14%
--success-border
--success at 30%
--success-fg
--success at 100%
--info-bg
--info at 14%
--info-border
--info at 30%
--info-fg
--info at 100%
--warn-bg
--warn at 14%
--warn-border
--warn at 30%
--warn-fg
--warn at 100%
--danger-bg
--danger at 14%
--danger-border
--danger at 30%
--danger-fg
--danger at 100%
/* 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);
| Token | Role | Use |
|---|---|---|
| --accent-primary | Brand anchor (20%) | Primary CTAs, focus rings, active tab text, links, selected states |
| --accent-secondary | Gradient sidekick (10%) | Second chart series, brand gradients, motion accents |
| --accent-tertiary | Spot accent (5%) | Third chart series, category tags, marketing emphasis. Never on enterprise surfaces. |
| --success | Semantic — went well | Positive deltas, "route found", confirmation toasts |
| --danger | Semantic — broken or destructive | Delete, disconnect, error toasts, negative deltas, SLA breaches |
| --warn | Semantic — proceed with caution | Capacity meters, rate-limit warnings |
| --text-primary | Neutral ink — anchor | Headlines, hero numbers, primary body |
| --text-muted | Neutral ink — support | Descriptions, captions, eyebrows |
| --text-faint | Neutral ink — chrome | Axis ticks, table headers, placeholder hints |
| --surface-page | Neutral surface | Page background |
--accent-primary. Everything else defers. One blue button per page, not four.color-mix, such as color-mix(in oklch, var(--accent-primary) 12%, transparent), instead of adding colours.--success means "something went well", --danger means "this is destructive or broken". If neither is true, don't reach for a semantic color.--text-* · --icon-*Grey tokens for text hierarchy and icon-only chrome. Icon tokens alias text tokens and can be overridden per theme.
Six tokens set every grey in the system. Use --text-* for prose, labels and numerals, and --icon-* for icon-only chrome. Both switch with the data-theme attribute on <html>.
Text
var(--text-primary)
Headlines, hero numbers, primary body
var(--text-secondary)
Sub-headlines, supporting copy
var(--text-muted)
Descriptions, captions, eyebrows
var(--text-faint)
Chrome · axis ticks · placeholder hints
Icon
var(--icon-primary) = var(--text-primary)
.btn-icon.btn-borderless
--text-primary.var(--icon-muted) = var(--text-muted)
.btn-icon.btn-borderless.btn-muted
--text-muted.--text-* for text: headings, paragraphs, labels, table cells and list titles.--icon-* for icon-only chrome: borderless icon buttons, dropdown carets, list-row affordances, navbar icons and status dots not beside text. Don't use --text-* there, even though the values match today.:root and for light in [data-theme="light"]. Consumers never branch on theme.--icon-primary: color-mix(in oklch, var(--text-primary) 88%, var(--accent-primary)); tints every borderless icon button.styles.css, search --text-primary: in :root and [data-theme="light"]. The icon tokens follow the text tokens in both blocks.--icon-primary at rest and --icon-muted with .btn-muted.--spectral-1 … --spectral-12Twelve hues for charts, illustrations and decorative blocks. They do not change with the theme preset.
Twelve hues about 30° apart in OKLCH, balanced for categorical data. Hover a swatch for a note on its use.
--spectral-1
oklch(0.72 0.20 20)
#FF8C7A
--spectral-2
oklch(0.74 0.20 50)
#FF9358
--spectral-3
oklch(0.82 0.18 80)
#FFB454
--spectral-4
oklch(0.84 0.20 110)
#C5E866
--spectral-5
oklch(0.78 0.22 140)
#5EEAA0
--spectral-6
oklch(0.76 0.18 175)
#3DD9D9
--spectral-7
oklch(0.78 0.18 205)
#42E2F5
--spectral-8
oklch(0.74 0.20 235)
#67BAFF
--spectral-9
oklch(0.70 0.22 265)
#7B86FF
--spectral-10
oklch(0.66 0.22 295)
#9B5DE5
--spectral-11
oklch(0.72 0.24 325)
#D472FA
--spectral-12
oklch(0.76 0.22 355)
#FF8FCB
Chart subsets
Neighbouring series should be far apart on the wheel. --series-1…--series-8 run blue, orange, green, magenta, amber, cyan, violet, coral.
Numeric form, for charts and code that loops over an index.
/* 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 the series tokens, which map to spectral hues */
.line[data-series="3"] { stroke: var(--series-3); }
Named form, when the hue matters more than its position.
/* 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)
| Token | Alias | OKLCH (L · C · H) | Notes |
|---|---|---|---|
--spectral-1 | --spectral-coral | 0.72 · 0.20 · 20 | Vivid warm red — punchy entry to the wheel |
--spectral-2 | --spectral-orange | 0.74 · 0.20 · 50 | Saturated tangerine |
--spectral-3 | --spectral-amber | 0.82 · 0.18 · 80 | Golden yellow — high L for legibility (yellow exception) |
--spectral-4 | --spectral-lime | 0.84 · 0.20 · 110 | Yellow-green — peak L of the wheel (yellow exception) |
--spectral-5 | --spectral-green | 0.78 · 0.22 · 140 | Bright leaf — vivid, distinct from --success |
--spectral-6 | --spectral-teal | 0.76 · 0.18 · 175 | Clean blue-green |
--spectral-7 | --spectral-cyan | 0.78 · 0.18 · 205 | Vivid ocean |
--spectral-8 | --spectral-sky | 0.74 · 0.20 · 235 | Punchy sky blue |
--spectral-9 | --spectral-blue | 0.70 · 0.22 · 265 | Brand-anchor blue — light mode lands on exact LI.FI Blue · default --series-1 |
--spectral-10 | --spectral-violet | 0.66 · 0.22 · 295 | Rich purple — deepest L of the dark band |
--spectral-11 | --spectral-magenta | 0.72 · 0.24 · 325 | Peak pink-purple — highest chroma in the dark band |
--spectral-12 | --spectral-pink | 0.76 · 0.22 · 355 | Punchy rose — closes the wheel |
Light mode. Lightness drops 0.16 to 0.26 for contrast on light surfaces; hue stays and chroma holds or eases. --spectral-9 lands on LI.FI Blue (0.44 · 0.23 · 268).
| Token | Dark | Light | Δ L |
|---|---|---|---|
--spectral-1 | 0.72 · 0.20 · 20 | 0.55 · 0.21 · 20 | −0.17 |
--spectral-2 | 0.74 · 0.20 · 50 | 0.58 · 0.20 · 50 | −0.16 |
--spectral-3 | 0.82 · 0.18 · 80 | 0.66 · 0.16 · 80 | −0.16 |
--spectral-4 | 0.84 · 0.20 · 110 | 0.62 · 0.20 · 110 | −0.22 |
--spectral-5 | 0.78 · 0.22 · 140 | 0.55 · 0.20 · 140 | −0.23 |
--spectral-6 | 0.76 · 0.18 · 175 | 0.55 · 0.13 · 175 | −0.21 |
--spectral-7 | 0.78 · 0.18 · 205 | 0.55 · 0.16 · 205 | −0.23 |
--spectral-8 | 0.74 · 0.20 · 235 | 0.50 · 0.20 · 235 | −0.24 |
--spectral-9 | 0.70 · 0.22 · 265 | 0.44 · 0.23 · 268 | −0.26 |
--spectral-10 | 0.66 · 0.22 · 295 | 0.45 · 0.22 · 295 | −0.21 |
--spectral-11 | 0.72 · 0.24 · 325 | 0.50 · 0.24 · 325 | −0.22 |
--spectral-12 | 0.76 · 0.22 · 355 | 0.55 · 0.22 · 355 | −0.21 |
Token forms. Every spectral colour has both.
| Form | Pattern | When to reach for it |
|---|---|---|
| Numeric | --spectral-1 … --spectral-12 | Chart libraries, JS loops, anywhere you iterate over an index |
| Named alias | --spectral-coral, --spectral-blue, … | Prose-readable CSS where the hue identity matters more than its position |
Hue lookup
| # | Name | Hue (°) | Where it sits in the wheel |
|---|---|---|---|
| 1 | coral | 20 | Warm red, slight orange shift |
| 2 | orange | 50 | True orange |
| 3 | amber | 80 | Yellow-orange, gold |
| 4 | lime | 110 | Yellow-green |
| 5 | green | 140 | True green |
| 6 | teal | 175 | Blue-green transition |
| 7 | cyan | 205 | Sky-leaning blue-green |
| 8 | sky | 235 | Light blue |
| 9 | blue | 265 | True blue |
| 10 | violet | 295 | Blue-purple |
| 11 | magenta | 325 | Pink-purple |
| 12 | pink | 355 | Soft rose, closes back to coral |
Series mapping. --series-N maps to spectral hues, so chart colours stay the same across presets.
| Series | Spectrum source | Why this index |
|---|---|---|
--series-1 | --spectral-9 (blue) | Default first series — high contrast against background |
--series-2 | --spectral-2 (orange) | Warm complement to blue — max categorical distance |
--series-3 | --spectral-5 (green) | Third axis on the wheel |
--series-4 | --spectral-11 (magenta) | Fourth axis — opposite side |
--series-5 | --spectral-3 (amber) | Adjacent to orange but distinct |
--series-6 | --spectral-7 (cyan) | Cool family fill |
--series-7 | --spectral-10 (violet) | Deep cool, distinct from blue |
--series-8 | --spectral-1 (coral) | Warm, distinct from orange |
--accent-primary, -secondary, -tertiary) carry the brand and change with the Theme Composer. The twelve spectral hues are for colour with no meaning, such as categorical data, illustration fills and decorative blocks, and stay the same across presets.--spectral-5 and --success. Both are green, but changing one does not change the other.--spectral-9 next to --spectral-8 puts deep blue beside sky blue, which reads as one series.--series-1 and --series-2 (blue and orange). They stay distinct under every brand.--spectral-N has a darker value in [data-theme="light"], so consumers don't branch on theme.styles.css, search Spectrum Palette for the dark values in :root; light values are in [data-theme="light"].design.md §02 → Color → Spectrum (extended brand palette).--accent-primary / -secondary / -tertiary (brand), --success / --warn / --danger / --info (semantic), --series-1…--series-8 (chart subset), --ink-* / --surface-* (neutrals).#series-palette), and by any decorative fill through var(--spectral-N).--series-1..12 to a ramp from its brand colour. The spectral tokens themselves never change.The swatches above are documented at Components → Swatch.
Laptops & desktops
Tablets
Phones
<!-- --dw/--dh: drawn px (logical × 0.12); data-logical-w: 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
| Device | Logical viewport | Native resolution | DPR | Notes |
|---|---|---|---|---|
| QHD display | 2560 × 1440 | 2560 × 1440 | 1 | Common external monitor; a sensible layout ceiling |
| FHD display | 1920 × 1080 | 1920 × 1080 | 1 | The most common desktop monitor worldwide |
| MacBook Pro 16" | 1728 × 1117 | 3456 × 2234 | 2 | Default scaled; notch; “More Space” goes wider |
| MacBook Pro 14" | 1512 × 982 | 3024 × 1964 | 2 | Default scaled; notch; “More Space” ≈ 1800 wide |
| MacBook Air 15" | 1496 × 967 | 2880 × 1864 | 2 | Notch |
| MacBook Air 13.6" (M2/M3) | 1470 × 956 | 2560 × 1664 | 2 | Notch; non-integer scaling |
| MacBook Air 13" (M1) | 1280 × 800 | 2560 × 1600 | 2 | Design floor for laptop and wider |
Tablets
| Device | Logical viewport | Native resolution | DPR | Notes |
|---|---|---|---|---|
| iPad Pro 11" | 834 × 1194 | 1668 × 2388 | 2 | Portrait; landscape swaps the axes |
| iPad 10.9" | 820 × 1180 | 1640 × 2360 | 2 | Portrait |
Phones
| Device | Logical viewport | Native resolution | DPR | Notes |
|---|---|---|---|---|
| iPhone 16 Pro Max | 440 × 956 | 1320 × 2868 | 3 | Dynamic Island; safe-area top + bottom |
| iPhone 14/15 Plus · Pro Max | 430 × 932 | 1290 × 2796 | 3 | Notch / Island; safe-area insets |
| Pixel 8 | 412 × 915 | 1080 × 2400 | ≈2.6 | Android; punch-hole; gesture inset |
| iPhone 16 | 393 × 852 | 1179 × 2556 | 3 | Dynamic Island |
| iPhone 12–15 | 390 × 844 | 1170 × 2532 | 3 | Notch (12–14) / Island (15); safe-area |
| iPhone SE (2/3) | 375 × 667 | 750 × 1334 | 2 | Home button; no notch; smallest modern target |
| Galaxy S (S22–S24) | 360 × 800 | 1080 × 2340 | 3 | Android; punch-hole; common compact baseline |
Breakpoints (Tailwind reference, not LI.FI tokens)
| Name | min-width | Typical target |
|---|---|---|
| base | 0–639 | Phones, portrait |
| sm | 640 px | Large phones landscape / small tablets |
| md | 768 px | Tablets portrait |
| lg | 1024 px | Tablets landscape / small laptops |
| xl | 1280 px | Laptops; our design floor |
| 2xl | 1536 px | Large laptops / desktops |
| Class | Role | Notes |
|---|---|---|
| .ds-doc-device-stage | Flex-wrap row | Holds every device figure; align-items: flex-end baselines them so heights read |
| .ds-doc-device | One device figure | Column (frame + label); carries --dw/--dh + data-logical-w |
| .ds-doc-device__frame | The screen | Size = calc(--dw × 1px) by --dh; bezel = --text-faint border on --surface-sunk |
| --monitor / --laptop / --tablet / --phone | Chrome modifiers | Stand / keyboard deck / camera dot / Dynamic Island pill |
| --notch / --home / --punch | Sub-styles | MacBook notch / iPhone SE home button / Android punch-hole |
| .ds-doc-device__label | Name + resolution | Name (caption / semibold) over res (micro / mono) |
| .ds-doc-device-ruler · .slider | Viewport-width control | Composes the .slider primitive (.slider-label-row + .slider-range); fill auto-wired by window.lifiSliderFill. The input handler toggles every device's [data-fits]. |
| .ds-doc-device-ruler__meta | Live readout row | Breakpoint .chip-accent1 + a .muted fit-count line |
| .ds-doc-bp-track | Breakpoint scale | Proportional segments base→2xl; the in-range .ds-doc-bp-seg[data-active] tints accent and .ds-doc-bp-marker tracks the value |
| .ds-doc-device[role=button] | Width preset | JS-enhanced: click / Enter / Space snaps the ruler to that device's logical width. Hover / focus-visible raise the accent border + ring. |
--w-* ladder (Surface widths) tops out at 640, so floating surfaces fit easily.swap.css → “Advanced widget tier”.--w-* ladder..slider primitive.env(safe-area-inset-*) to clear the notch, Dynamic Island and home indicator.CSS: styles.css, search Device frame — screen-size reference.
Composed primitives: .slider · .chip-accent1 · .muted · .ds-doc-divider--loose.
Ruler JS: the inline script after this section sets [data-fits] and the active .ds-doc-bp-seg, and makes each .ds-doc-device[data-logical-w] 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-*).
--elev-1/2/3 shadows show depth, --alpha-* overlays show state, and cards, rows and panels use elevation instead of hard borders. Materials bundle these tokens; components use them directly when a whole Material is more than they need.--elev-1 · --elev-2 · --elev-3Three shadow tiers for resting cards, hover and floating surfaces.
Subtle drop + 1px white-rim highlight (dark) / gentle drop (light). The default tier for content surfaces.
Stronger drop + brighter rim. The momentary lift signals interactivity without changing fill color.
Deep drop + brightest rim. Reserved for surfaces that float over the page (modals, popovers, dropdowns).
/* Resting card */
.card {
background: var(--surface-card);
box-shadow: var(--elev-1);
border-radius: var(--space-16);
}
/* Raise the tier on interaction */
.card:hover { box-shadow: var(--elev-2); }
.modal, .popover { box-shadow: var(--elev-3); }
Pick the tier by state. Light and dark values switch through [data-theme].
| Tier | UI state | Dark recipe | Light recipe |
|---|---|---|---|
| --elev-1 | Resting cards, settings rows, list rows | Subtle drop + 1px inset white-rim highlight | Gentle drop, no rim |
| --elev-2 | Hover, sticky-active, tooltips | Stronger drop + brighter rim | Card-tier drop |
| --elev-3 | Modals, popovers, dropdowns | Deep drop + brightest rim | Modal-tier drop |
Dark mode adds a 1px inset 0 1px 0 rgba(255,255,255, 0.04–0.06) rim, because drop shadows barely show on dark surfaces. Light mode has no rim.
Filter tokens for masked elements. mask-image clips box-shadow, so each --elev-N has an --elev-N-filter twin in filter: drop-shadow(…) form. It chains one drop-shadow() per outset layer; the inset rim has no filter form and is dropped.
Filters apply before masks, and mask-clip defaults to border-box, which trims the drop shadow to the element's box. Two ways around it:
Pattern A, a group of masked elements (preferred). Put filter: var(--elev-N-filter) on the unmasked parent and remove the children's own shadow. The shadow follows the children's combined outline, so cutouts read as holes. Example: .ui-amount-pair hosts the filter and its two .ui-amount-card children carry the FAB cutouts. No mask-clip override is needed.
Pattern B, a lone masked element. Put the filter on the element and set -webkit-mask-clip: no-clip; mask-clip: no-clip;. If the shadow still doesn't show, test with filter: drop-shadow(0 4px 12px rgba(255,0,0,0.9)); no red around the card means mask-clip is still trimming.
| Filter token | Use with | Shape |
|---|---|---|
| --elev-1-filter | Masked cards / rows at rest | Matches --elev-1. Light chains its two outset layers; dark is one layer, because dark --elev-1 has one outset layer plus the inset rim |
| --elev-2-filter | Masked hover state | Chains --elev-2's two outset layers, without the negative spread (filter has no spread) |
| --elev-3-filter | Masked floating surface | Chains --elev-3's layers; at this blur the chain can smear faintly |
/* Pattern A: 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: lone masked element */
.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);
}
box-shadow: 0 4px 16px ... on a card; the tier's value can then change once for the whole system.--elev-1, hover --elev-2, floating --elev-3. Show interactivity by raising the tier, not by darkening a border.--elev-3 on hover looks like it is floating away. Use --elev-2.background: var(--surface-card) or another --surface-* token.data-material="paper" the tier is in --material-paper-shadow: var(--elev-1). Use --elev-N directly only outside the Materials API. See Materials.--elev-N-filter only on masked elements, since mask-image clips box-shadow. Everywhere else, box-shadow is the method. Put the filter on an unmasked parent when you can; Specs shows both patterns, and .ui-swap-arrow shows the group case.drop-shadow() per outset layer of its twin, at the same offset, blur and opacity. To check a masked card, compare its computed filter with the same --elev-N as box-shadow 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.
Four overlays that show state on top of a surface fill.
Alpha scale. Lay these over a surface fill, never in place of it.
Text on alpha. The colour under an alpha layer varies, so text on it uses its own tokens.
/* Recessed track inside a card */
.track { background: var(--alpha-subtle); }
/* Row hover */
.row:hover { background: var(--alpha-dim); }
/* Active pill */
.pill.is-active { background: var(--alpha-raised); }
/* Active and hovered */
.pill.is-active:hover { background: var(--alpha-overlay); }
/* Text on alpha: the on-alpha scale, not --text-primary */
.pill-label { color: var(--on-alpha-default); }
| Token | Dark | Light | Use |
|---|---|---|---|
| --alpha-subtle | oklch(100% 0 0 / 0.08) | oklch(0% 0 0 / 0.06) | Recessed tracks, demo bases |
| --alpha-dim | oklch(100% 0 0 / 0.04) | oklch(0% 0 0 / 0.03) | Inactive hover fill |
| --alpha-raised | oklch(100% 0 0 / 0.18) | oklch(100% 0 0 / 0.88) | Active pills, raised tiles |
| --alpha-overlay | oklch(100% 0 0 / 0.24) | oklch(100% 0 0 / 0.95) | Active hover, top-tier elevation |
| --on-alpha-default | Default text on an alpha layer | Use instead of --text-primary over alpha | |
| --on-alpha-muted | Muted text on an alpha layer | Secondary labels over alpha | |
rgba(). The tokens switch with the theme; rgba(255,255,255,0.18) looks fine in dark mode and disappears in light.--surface-* fill is the base. Put background: var(--alpha-raised) on a child of the card, not on the card itself.--on-alpha-default and --on-alpha-muted for text.Definitions: styles.css · search --alpha-subtle.
Spec: design.md §02 → Alpha state layers.
Container surfaces lift with fill and shadow, not a hard border. The Paper material bundles this; the manual recipe is for work outside the Materials API.
A hard 1px border on a flat fill reads as a form control. A raised fill with --elev-1 and an optional 6% hairline reads as lifted off the page.
3 routes · best price via Stargate · ~12s
3 routes · best price via Stargate · ~12s
/* PREFERRED — Paper material bundles this recipe. */
.my-card { background: var(--mat-bg); box-shadow: var(--mat-shadow); border: var(--mat-border); }
/* Element: data-material="paper"; see #material-paper */
/* MANUAL — outside the Materials API only. */
.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 to crisp the corner */
border: 1px solid color-mix(in oklch, currentColor 6%, transparent);
}
| # | Mechanic | Token | Role |
|---|---|---|---|
| 1 | Fill one step above parent | --surface-raised / --surface-card | Lightness step that creates the visual lift |
| 2 | Box-shadow elevation tier | --elev-1 / --elev-2 / --elev-3 | Soft drop + (dark) inset rim highlight |
| 3 | Optional hairline | 1px solid 3-6% currentColor | Crisps the corner radius. Often omitted. |
data-material="paper" with --mat-* bundles fill, shadow, border and hover shadow. Author by hand only when Materials don’t fit: a one-off prototype, a non-component primitive or a deliberate departure.--elev-1, hover --elev-2, sticky-active --elev-2 plus an accent halo, modal or popover --elev-3. Materials use --mat-shadow-hover; manual work sets the tier in :hover..input, .select and .textarea keep their borders, segmented controls keep their pill track, and badges and chips keep tinted fills without elevation. The rule covers container surfaces: cards, rows, tiles and modals.Preferred: the Paper material, data-material="paper" with --mat-*.
Spec: design/components/foundations.md → Elevation over hard borders.
Tokens: --surface-* in Surfaces; --elev-1 / 2 / 3 in Elevation tiers above.
paper, glass, gradient and halo. Change one attribute to switch a card, tile or panel between them; the Material Composer tunes their values. Materials sit between Surfaces, whose tokens they reference, and the components that read --mat-*.data-materialComponents read --mat-*; data-material on the element picks the material.
The same markup four times; only data-material differs.
Default. Opaque fill, soft drop, 1px hairline.
Translucent + backdrop-blur. Floating panels and marketing tiles.
Brand fill (blue → pink). Hero KPIs, cover tiles.
Accent wash + radial glow. Brand-identity tiles.
<!-- Default (paper) — no attribute needed -->
<div class="card">…</div>
<!-- Switch to glass for a floating panel -->
<div class="card" data-material="glass">…</div>
<!-- Halo; set the accent with --accent-tint -->
<div class="card" data-material="halo"
style="--accent-tint: var(--lifi-sapphire);">…</div>
In component CSS:
/* --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 five tokens components read.
| Token | Role | Default value |
|---|---|---|
| --mat-bg | Fill: solid, translucent or gradient | var(--material-paper-bg) |
| --mat-border | Border shorthand | var(--material-paper-border) |
| --mat-shadow | Box shadow | var(--material-paper-shadow) |
| --mat-backdrop | backdrop-filter, glass only | none |
| --mat-highlight | Inset edge highlight on dark surfaces | 0 0 0 0 transparent |
The four materials, each defined as --material-<name>-{bg,border,shadow,backdrop,highlight} in :root.
| Material | Fill | Use for |
|---|---|---|
| paper | --surface-card opaque + 1px hairline | Stat, feature and action cards; the default |
| glass | --surface-panel-glass + backdrop-blur | FAB sub-panels, side rails, dropdowns, marketing tiles |
| gradient | linear-gradient(135deg, --lifi-sapphire, --lifi-ink) | Hero KPIs, marketing accent surfaces, cover tiles |
| halo | radial accent glow + 3% accent wash on --surface-card | Brand-identity tiles, partner showcases, ecosystem cards |
Three layers. Each references the one above it.
| Layer | Tokens | Lives in | Authored by |
|---|---|---|---|
| Definitions | --material-<name>-{bg,border,shadow,backdrop,highlight} | :root in styles.css | DS contributor when adding a material |
| Resolved API | --mat-{bg,border,shadow,backdrop,highlight} | :root default + [data-material] selectors | The DS, once |
| Consumers | background: var(--mat-bg); … | Component CSS in styles.css / swap.css / etc. | Component author |
Without the middle layer, a component would read var(--material-paper-bg) and could never switch. With it, the component reads --mat-* and data-material decides which material that resolves to.
--mat-*, never --material-*-*. .stat-card { background: var(--material-paper-bg); } hard-codes paper and can't be switched.--material-*-* tokens reference --surface-*, --lifi-*, --accent-* and --elev-*; never an oklch(), hex or rgba value.:where(<class>) { --mat-bg: …; }, at zero specificity so data-material still overrides. A component that varies per instance keeps the :root default and sets data-material in markup.[data-theme="light"] override for --mat-*. Light and dark come through the upstream tokens; if a material looks wrong in one theme, fix the definition or the upstream token.:root, its [data-material="<name>"] selector, a row in design.md §02 → Materials and a card in this section.A card's layers pulled apart, and which foundation owns each.
A glass card over a gradient. Elevation, Surfaces, Materials and Typography each own one layer, numbered 01 to 04.
--elev-1 rest · --elev-2 hover · --elev-3 floating.
02
Surface
The fill of any plate — the color or character a Material consumes. Glass uses --surface-panel-glass; opaque cards use --surface-card; recessed wells use --surface-sunk.
03
Material
A card’s surface character — opaque, translucent, gradient, or accent-tinted — plus edge styling and (for glass) backdrop filter. The diagram above showcases glass. Other recipes: paper · gradient · halo.
04
Typography
Text and glyphs that sit on top. Color from --text-primary · --text-secondary · --text-muted; sized via the type scale; weight from the role.
A glass card in CSS. The comment numbers match the diagram.
<div class="card" data-material="glass">…</div>
.card {
/* 01 · Drop shadow: Elevation; the material picks the tier */
box-shadow: var(--mat-shadow), var(--mat-highlight); /* glass → var(--elev-2) */
/* 02 · Surface fill: Surfaces */
background: var(--mat-bg); /* glass → var(--surface-panel-glass) */
backdrop-filter: var(--mat-backdrop); /* glass → blur + saturate */
/* 03 · Edge: hairline + inset rim, Material */
border: var(--mat-border);
/* Shape: the component's */
border-radius: var(--space-16);
padding: var(--space-20); /* 04 · Content gets a frame */
}
Use "paper" instead of "glass" for an opaque card; the layers stay the same.
Each layer has one owner. Material owns the edge and the surface character, never the shadow; the shadow belongs to Elevation.
| # | Layer | Foundation | Token (resolved API) | Real-world role |
|---|---|---|---|---|
| 04 | Content | Typography | color: var(--text-primary) | Text and glyphs the user reads. |
| 03 | Edge | Material | --mat-border · --mat-highlight | Crisps the corner; the rim sells lift in dark mode. |
| 02 | Surface fill | Surface | --mat-bg → --surface-panel-glass | Translucent in glass; opaque in paper. Material picks the character. |
| 01 | Drop shadow | Elevation | --elev-1 / --elev-2 / --elev-3 | Rest, hover, floating. |
Glass adds a backdrop. backdrop-filter: blur(...) sits between the fill (02) and the page behind the card. See Glass.
What each plate uses. Every plate except the shadow reads real tokens, so it follows the palette.
| Plate | Rendered with | Source of truth |
|---|---|---|
| 01 · Drop shadow | oklch(0% 0 0 / 0.55) · filter: blur(24px) | Synthetic; see Rules. |
| 02 · Surface fill (Glass) | background: var(--surface-panel-glass) · backdrop-filter: blur(20px) saturate(1.4) | Surfaces · Glass |
| 03 · Edge | border + inset 0 1px 0 rim | paper.border + paper.highlight, Paper |
| 04 · Content | color: var(--text-primary) | Typography |
Geometry. Plates are 280×180 px, 100 px apart on Z. The stack has rotateX(58deg) rotateZ(-32deg) with transform-style: preserve-3d. Badges sit in the same stack; their digits are counter-rotated (rotateZ(32deg) rotateX(-58deg)) to stay upright.
.card { background: var(--elev-1); } is wrong: a tier is a shadow, not a fill.--elev-* tier goes with it. See Materials system.--elev-* shadows would be invisible as a separate plate; production cards use the real tokens.--alpha-* token on a child inside the content layer (04), not a new layer between fill and edge. See Alpha state layers..ds-doc-iso-card is for the catalog only, such as a new material's anatomy or a tile-versus-card comparison. Never on a product or marketing surface.Primitive: styles.css, search .ds-doc-iso-card.
Layers: Elevation (01) · Surfaces (02) · Materials (03) · Typography (04).
Spec: design.md §02 → Materials.
data-material="paper"Opaque fill, soft drop shadow, 1px hairline. The default.
Cross-chain settlement across 30+ networks
<!-- 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>
| Token | Value |
|---|---|
| --material-paper-bg | var(--surface-card) |
| --material-paper-border | 1px solid color-mix(in oklch, var(--text-primary) 6%, transparent) |
| --material-paper-shadow | var(--elev-1) |
| --material-paper-backdrop | none |
| --material-paper-highlight | 0 0 0 0 transparent |
glass.--surface-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.
data-material="glass"Translucent fill, backdrop blur and a neutral drop shadow, from the Panel Surfaces tokens.
For FAB sub-panels, side rails and anything that floats over content. Built from --surface-panel-glass, --shadow-panel-glass and --backdrop-panel-glass.
Connected · block 52,830,491
<!-- glass: floating panels and rails -->
<div class="ds-doc-menu-panel" data-material="glass">
<div>Network</div>
<div>Polygon</div>
</div>
| Token | Value |
|---|---|
| --material-glass-bg | var(--surface-panel-glass) |
| --material-glass-border | 0 solid transparent (no border) |
| --material-glass-shadow | var(--shadow-panel-glass), includes the inset highlight |
| --material-glass-backdrop | var(--backdrop-panel-glass) = blur(40px) saturate(140%) |
| --material-glass-highlight | 0 0 0 0 transparent (highlight is in --shadow-panel-glass) |
backdrop-filter is GPU-heavy, and twenty glass cards on a page stutter. Keep glass for floating chrome, not cards.Definitions: styles.css · search --material-glass-bg.
Underlying recipe (3 tokens): --surface-panel-glass, --shadow-panel-glass, --backdrop-panel-glass in styles.css :root.
Consumers: .ds-doc-menu-panel, .cmd-palette__panel, .navbar::before. .dropdown__panel uses Paper.
Spec: design.md §02 → Materials + §02 → Panel Surfaces.
data-material="gradient"Brand gradient fill with white text, for hero KPIs and cover tiles.
The loudest material: --lifi-sapphire to --lifi-ink at 135°. Text turns white automatically.
Total value secured · 30+ chains
<!-- gradient: hero KPIs and one-off accent surfaces -->
<div class="card" data-material="gradient">
<div>Cross-chain TVL</div>
<div>$8.42B</div>
</div>
| Token | Value |
|---|---|
| --material-gradient-bg | linear-gradient(135deg, var(--lifi-sapphire), var(--lifi-ink)) |
| --material-gradient-border | 1px solid color-mix(in oklch, white 12%, transparent) |
| --material-gradient-shadow | var(--elev-2) |
| --material-gradient-backdrop | none |
| --material-gradient-highlight | inset 0 1px 0 rgba(255,255,255,0.18) |
--text-primary lacks contrast on the gradient; don't override back to it.Definitions: styles.css · search --material-gradient-bg.
Brand gradient tokens: --lifi-sapphire, --lifi-ink in :root.
Spec: design.md §02 → Materials.
data-material="halo"A soft accent wash with a radial glow at top right, for brand-identity tiles.
3 % accent over --surface-card, plus a 12 % accent glow from the top right that fades out by 70 %. Quieter than gradient. Shown with three tints.
--lifi-ink — the system default
Custom tint · --lifi-sapphire
Custom tint · --lifi-pink
<!-- 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>
| Token | Value |
|---|---|
| --accent-tint | var(--lifi-ink) default · override per-element |
| --material-halo-bg | radial-gradient(ellipse 85% 65% at 100% 0%, color-mix(--accent-tint 12%, transparent) 0%, transparent 70%), color-mix(--accent-tint 3%, --surface-card) |
| --material-halo-border | 1px solid color-mix(in oklch, var(--text-primary) 6%, transparent) |
| --material-halo-shadow | var(--elev-1) |
| --material-halo-backdrop | none |
| --material-halo-highlight | 0 0 0 0 transparent |
In the Material Composer, halo has tint (default 12 %) and shadow tier sliders only.
--lifi-sapphire, --lifi-ink, --lifi-pink or --accent-primary, never raw hex.Definitions: styles.css, search --material-halo-bg.
Composer: shared.js → initMaterialComposer() (MATERIALS, DEFAULTS, APPLICABLE, applyMaterialTokens).
Default consumer: .brand-card via :where(.brand-card) in styles.css. Spec: design.md §02 → Materials.
data-material="halo" + --tile-accent-* + .is-activeThe .brand-card recipe on any tile: halo, a per-tile accent and an active glow.
Three tiles with their own accents. The middle one has .is-active.
Cross-chain swap embedded directly in the wallet's send sheet. 400k MAU.
Now live — native USDC, JUP, and BONK route through the LI.FI router.
RWA settlement layer — tokenised treasuries on six chains, one quote.
One value, when the colour reads well in both themes.
<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 when the brand has a value tuned for each theme.
<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. Toggle .is-active from JS for an 8 % accent fill, a full-accent border and an 18 px glow.
<article class="tile is-active" data-material="halo"
style="--tile-accent: var(--lifi-sapphire);">…</article>
| Layer | What it does | Token / hook |
|---|---|---|
| Surface material | Radial halo at top-right + faint accent wash on base | data-material="halo" → resolves --mat-bg from --material-halo-bg |
| Per-tile accent | Tints the halo and the active glow | --tile-accent (single) or --tile-accent-light + --tile-accent-dark (dual-mode) |
| Material bridge | Passes the tile colour to the halo | .tile rule wires --accent-tint: var(--tile-accent) |
| Hover | 6 % accent wash + bumps elevation to --mat-shadow-hover | .tile:hover rule (built-in) |
| Active | Sticky-selected: 8 % accent bg, full-strength accent border, 18 px accent glow | .tile.is-active rule (built-in) |
paper.--tile-accent is enough for a mid-saturation hue. Use dual-mode when a deep value disappears on dark or a vivid one glares on light..is-active marks a lasting selection, such as the chosen theme, filter or preset. It is not :active (mouse down) and not hover..is-active from siblings before adding it.--mat-bg by hand. Tint through --tile-accent, which .tile passes to --accent-tint; a hand-set --mat-bg breaks the composer.--tile-accent-* a --text-on-accent-* companion: near-black for bright accents, white for deep ones, as .brand-card does with --brand-c-on.Tokens: styles.css, search --tile-accent-light on .tile and :where(.brand-card).
Active: search .tile.is-active, in styles.css.
Live consumer: the brand-card grid at design-system/competitors.html#brands.
Halo: #material-halo.
--space-* tokens set every padding, gap and radius; width tokens cap floating surfaces; the sizing ladder sets the sm / default / lg / xl tiers of multi-size components; and gap and radius rules cover cards and nesting.--space-2 through --space-160, in multiples of 4 px apart from the 2 px hairline.
/* Use --space-N tokens, never raw px. */
padding: var(--space-24); /* 24 px card padding */
gap: var(--space-16); /* 16 px item gap */
margin-bottom: var(--space-32); /* 32 px section break */
/* Cluster tokens for closer-grouped items: */
gap: var(--cluster-sm); /* 8 px */
gap: var(--cluster-md); /* 16 px */
| Token | Value | Use |
|---|---|---|
| --space-2 | 2px | Hairlines, dividers, tight icon gaps (border-width only) |
| --space-4 | 4px | Inline element gaps, micro-padding |
| --space-8 | 8px | Compact padding, small chip gap, icon-text rhythm |
| --space-12 | 12px | Card internal gap, dense form rows, button radii |
| --space-16 | 16px | Standard card padding base, button-lg radii |
| --space-20 | 20px | Form group margin-bottom, button-md horizontal padding |
| --space-24 | 24px | Card padding, section padding (small), icon-only btn-xs |
| --space-28 | 28px | Chips, dense touch targets |
| --space-32 | 32px | Card padding (medium), button row gap, icon-only btn-sm |
| --space-36 | 36px | Secondary controls, compact rows |
| --space-40 | 40px | Standard control height (input, btn-md, icon-only btn) |
| --space-44 | 44px | WCAG minimum touch target |
| --space-48 | 48px | Section padding (medium), btn-lg horizontal padding |
| --space-52 | 52px | Large control surfaces, icon-only btn-lg |
| --space-56 | 56px | Tile icon container, btn-lg + chrome |
| --space-64 | 64px | Section padding (large) |
| --space-72 | 72px | Token rows, dense .list-item--lg heights |
| --space-80 | 80px | Section padding (default) |
| --space-96 | 96px | Hero padding, page top spacing |
| --space-120 | 120px | Hero padding (large) |
| --space-160 | 160px | Hero padding (full-page) |
1px and 2px, and only in border, border-* and outline (hairlines, focus rings).--space-* token only for a deliberate, recurring size on the grid, such as the 44 px WCAG touch target.--w-*Seventeen max-widths for popovers, menus, modals and panels, 32 px apart.
/* Use the nearest tier, never a literal width */
.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 */
/* --w-* sets the width; --space-* sets the inside */
.modal { padding: var(--space-24); border-radius: var(--space-16); }
| Token | Value | Suggested surfaces | Currently used by |
|---|---|---|---|
| --w-1 | 224px | Tightest tooltip, pill popover | — available |
| --w-2 | 256px | Compact info popover, mini-menu | — available |
| --w-3 | 288px | Dropdown menus, single-column pickers, FAB sub-panel | .ds-doc-menu-panel |
| --w-4 | 320px | Narrow popover, empty-state text cap | .empty-state__title / __message |
| --w-5 | 352px | Reserved tier — claim for a new surface type | — reserved |
| --w-6 | 384px | Small modal (confirm), compact rail, swap rail | .modal--sm, swap rail (--rail-width) |
| --w-7 | 416px | Widget canvas, content panel, side rail | .ui-card (swap canvas) |
| --w-8 | 448px | Reserved tier — claim for a new surface type | — reserved |
| --w-9 | 480px | Default modal — settings, forms, content modals | .modal |
| --w-10 | 512px | Command palette overlay, wide popover, mid-density modal | .cmd-palette__panel |
| --w-11 | 544px | Reserved tier — claim for a new surface type | — reserved |
| --w-12 | 576px | Large modal, workshop drawer, side sheet | .modal--lg |
| --w-13 | 608px | Reserved tier — claim for a new surface type | — reserved |
| --w-14 | 640px | Reserved tier — claim for a wide panel | — reserved |
| --w-15 | 672px | Reserved tier — claim for a wide panel | — reserved |
| --w-16 | 704px | Advanced-tier Limit receive panel (chart + 7-col Orders) | Limit receive panel |
| --w-17 | 736px | Reserved tier — claim for a wide panel | — reserved |
var(--w-7).--w-N+1 is always the next tier up, 32 px wider, with no skips.--w-7 holds the swap canvas and can hold a wallet drawer too; don't rename a tier when a new surface uses it. Reserved tiers are free to claim.--w-12 (576 px) with a shorter body, or a bespoke workspace rather than a modal.--w-* width with literal padding, or the reverse, brings back the drift.width: 100% with max-width: var(--w-*) so the surface shrinks on narrow screens without a media query.max-width in a media query; don't fork the token.Each tier sets a height, label size, padding and radius together. Buttons are the reference (#btn-sizes).
sm · 32px · dense rails, tables, toolbarsdefault · 40px · forms, primary CTAslg · 48px · heroes, marketing CTAsxl · 56px · banner and poster CTAs/* Every multi-size component uses the same four tiers */
.btn-sm /* sm — 32px row */
.btn /* default — 40px row */
.btn-lg /* lg — 48px row */
.btn-xl /* xl — 56px row */
/* Neighbours in a row share a tier */
<div class="row">
<input class="input--lg">
<button class="btn-primary btn-lg">Submit</button>
</div>
Tiers
| Tier | Height | Role | Reach for it when… |
|---|---|---|---|
| sm | --space-32 (32px) | Dense / chrome | Data tables, toolbars, sidebar action rails, dashboard chrome. |
| default | --space-40 (40px) | Comfortable | Forms, primary CTAs, modal footers, settings rows. |
| lg | --space-48 (48px) | Hero | Marketing rows, hero CTAs, top-of-page actions. |
| xl | --space-56 (56px) | Statement | Banner / poster CTAs, deck-scale compositions. |
Values per tier. Padding is the button's; other components set their own.
| Ladder | sm | default | lg | xl | Step |
|---|---|---|---|---|---|
| Height | --space-32 | --space-40 | --space-48 | --space-56 | +8 |
| Label | --text-caption (12) | --text-sm (14) | --text-body (16) | --text-body-lg (18) | +2 (typography) |
| Radius | --space-8 | --space-12 | --space-16 | --space-20 | +4 |
| Pad X (button) | --space-20 | --space-24 | --space-32 | --space-40 | component-specific |
| Pad Y (button) | --space-8 | --space-12 | --space-12 | --space-16 | component-specific |
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
/* Label too big for the padY maths? Widen the line box (buttons, lg / xl) */
.btn-lg { font-size: 16px; line-height: calc(22 / 16); /* line-box → 22 */ }
Where the ladder is implemented
| Component | sm | default | lg | xl | Status |
|---|---|---|---|---|---|
.btn-* | 32 | 40 | 48 | 56 | ✓ canonical |
.seg-* | 32 | 40 | 48 | 56 | ✓ aligned |
.input--* | 32 | 40 | ~50 (drift) | missing | partial — lg drifts, no xl |
.switch-* | — | — | — | — | row-height aligned, distinct ladder (width × height) |
.card--* | — | — | — | — | separate --sm / --lg family with own padding scale |
Radius follows the theme's Corner sliders. Each multi-size primitive derives its radius with calc() from a customization token. Button shapes use --button-radius: .btn-*, .seg-* (including .seg-menu), .search-trigger, .btn-icon. Card shapes use --card-radius: .alert, .notification, .setting-row and the card family. Not yet bound: .input--* and .field-inline--* still use literal radii, and their --sm / --lg sit off the 8 / 12 / 16 / 20 ladder, so they need snapping (and an --xl) before binding. A literal that matches by value, such as var(--space-16), looks right at the default but ignores the slider.
.input--lg sits next to a .btn-lg; mixed tiers make the smaller one look wrong.padY × 2 + line-box + 2px border. If the maths doesn't land, widen the line box with a calc-based line-height instead of a non-token value..fab, .callout, .modal, .search, the auto-TOC chip strip.--gap-card-*Five tiers for the gap between sibling cards. Inline gaps use --cluster-*; content rhythm uses --stack-*.
The tokens name a position on the ladder, not a use case, so a preset can remap all five at :root and every consumer follows.
--gap-card is an alias for --gap-card-md, for short inline overrides. Write -md in component CSS.
XS (4 px), reserved
SM (8 px), compact lists
MD (12 px), default
LG (16 px), grids
XL (24 px), marketing grids
Nested rhythm. To tighten a group of children without changing the container's gap, wrap them in a stack that sets its own --card-gap. The swap form keeps 16 px between header, stack and footer, while its .ui-form-stack runs at 8 px.
Outer 16 px (lg), inner 8 px (sm)
/* The component sets a local --card-gap from 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 */
<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);
}
/* A preset remaps all five tiers at :root */
: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);
}
| Token | Default value | Tier | Typical use |
|---|---|---|---|
| --gap-card-xs | var(--space-4) · 4 px | Extra-small | Surfaces that nearly join. No consumer yet. |
| --gap-card-sm | var(--space-8) · 8 px | Small | Compact lists: .ui-amount-pair, .playground-rail__theme-cards, dense card menus. |
| --gap-card-md | var(--space-12) · 12 px | Medium (default) | Card lists such as .ui-quote-list. Start here. |
| --gap-card-lg | var(--space-16) · 16 px | Large | Multi-column grids: .theme-card-grid. |
| --gap-card-xl | var(--space-24) · 24 px | Extra-large | Marketing grids: .tile-grid, .enterprise-grid, .uc-grid. |
| --gap-card | var(--gap-card-md) | Alias | Short form for inline overrides. |
Consumers. The use cases above are guidance; a new list can take another tier if it reads better.
| Consumer | Tier | Local var |
|---|---|---|
| .ui-amount-pair | --gap-card-sm | --card-gap |
| .playground-rail__theme-cards | --gap-card-sm | --card-gap |
| .ui-form-stack | --gap-card-sm | --card-gap |
| .ui-quote-list | --gap-card-md | --card-gap |
| .theme-card-grid | --gap-card-lg | --card-gap |
| .tile-grid, .enterprise-grid | --gap-card-xl | --card-gap |
| .uc-grid | --gap-card-xl | --card-gap |
Presets. The default mapping is in styles.css; a preset goes on :root[data-card-gap-preset="…"] (see Markup).
--stack-* for vertical content rhythm (form fields, page sections), --cluster-* for inline gaps (icon and label, chip clusters), --gap-card-* between cards. A quote list using --cluster-md is drift. Padding inside a card, such as .ui-amount-card, uses that card's own tokens.--gap-card-md (12 px). Use another tier only for a reason in context, such as a tight pair with a FAB at the seam or a marketing grid, not because it looks roomier.--space-* under it. --space-12 in a card list won't follow a preset; grep "gap:.*--space-" *.css on card lists and grids should find nothing.--card-gap, as in .foo-list { --card-gap: var(--gap-card-sm); gap: var(--card-gap); }, so an instance can override it inline or from a context selector.--card-gap with any --space-* token at the call site; don't invent tier names. If the same custom value appears in three or more places, remap the ladder or reconsider the tier.:root, for example :root[data-card-gap-preset="compact"]. Component CSS doesn't change.--card-gap (see Nested rhythm in Preview). The wrapper's class is up to the page.--grid-gap-x / --grid-gap-yHorizontal and vertical canvas spacing for the Portal and Playground, set per theme in the Composer's Spacing section.
--grid-gap-x (default 16) is the gutter between side-by-side cards; --grid-gap-y (default 24) is the space between stacked sections. Neither changes with light or dark mode.
The Portal and Playground rail composers edit them with Compact, Standard and Spacious presets plus Custom sliders. Card lists use the card-gap ladder instead.
Column gap (16 px)
Row gap (24 px)
Presets set both axes. Values that match no preset select Custom.
Compact (x 12, y 16)
Standard (x 16, y 24), default
Spacious (x 24, y 32)
/* :root defaults (styles.css), 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 different default pins its own */
.playground-canvas {
--grid-gap-x: var(--space-24); /* historical widget gutter */
}
/* The composer paints the active canvas */
// shared.js
window.ThemeComposer.applyGapsToScope({ x: 24, y: 32 }, canvasEl);
| Token | Default | Axis | Drives |
|---|---|---|---|
| --grid-gap-x | var(--space-16) · 16 px | Horizontal | Gutter between side-by-side cards/panels → grid column-gap. |
| --grid-gap-y | var(--space-24) · 24 px | Vertical | Rhythm between stacked sections → section margin-bottom + grid row-gap. |
Presets and sliders. The Custom sliders step through 8 / 12 / 16 / 20 / 24 / 32 / 40; the minimum of 8 keeps cards from touching.
| Trio | x (horizontal) | y (vertical) |
|---|---|---|
| Compact | 12 px | 16 px |
| Standard (default) | 16 px | 24 px |
| Spacious | 24 px | 32 px |
Consumers. The Portal uses the 16 / 24 defaults; the Playground pins --grid-gap-x: 24.
| Canvas | Consumers | Lifecycle |
|---|---|---|
| .portal-canvas | .portal-kpi-grid, .portal-cols, .portal-metric-grid, .portal-detail-cols, .portal-roles-grid, .portal-steps + canvas section margins | Ephemeral (composer-only; resets on reload) |
| .playground-canvas | .widget-stage (form ↔ receive gutter) | Persisted per-theme (p.gaps) + applied on select |
--grid-gap-x drives column-gap; --grid-gap-y drives section margin-bottom and row-gap. Don't collapse them into one gap.--grid-gap-x/y. Every card list uses --gap-card-*.--space-*, or the composer can't change them. Gaps inside a component, such as icon and label, stay --space-*.features.gaps: !!canvas). DEFAULT_FEATURES.gaps is false; the Portal and Playground rails set features.gaps: true. Corners and surface stay in the FAB on every page.features.gaps in its rail composer. If its default isn't 16 / 24, pin it on the canvas and seed the editor from it, as the Playground does. Ask before adding gaps to the FAB.styles.css :root; ThemeComposer.readGaps, applyGapsToScope and clearGapsFromScope in shared.js; theme-editor.js → features.gaps; the rule in CLAUDE.md → Canvas grid-spacing system.For nested rounded elements, the outer radius equals the inner radius plus the padding between them.
Nested corners stay parallel only when outer radius = inner radius + padding. For a new nested element, use inner radius = outer radius − padding. Matching the two radii makes the gap pinch at the corner.
Don't — matched radii
outer = inner ignores the padding, so the corner gap pinches around the bend.
Do — radius + padding
outer = inner + padding keeps a constant gap all the way around the bend.
In real components
Inner 32 px, matched to the frame: the gap pinches.
Inner 20 px = 32 − 12: the curves stay parallel.
/* outer radius = inner radius + padding */
/* inner radius = outer radius − padding */
/* New nested element; --space-16 is the parent's padding, floor 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) */
One equation, read from either end
| Direction | Formula | Reach for it when… |
|---|---|---|
| Frame from content | outer = min(inner + padding, 32) | Choosing a container's radius around a known child. Capped at 32. |
| Nested element | inner = max(outer − padding, 0) | Choosing a new child's radius. The default. |
Inward: max(outer − padding, 0)
| Parent radius | Padding | Inner radius | Result |
|---|---|---|---|
| 32px (--space-32) | 12px (--space-12) | 20px (--space-20) | Concentric (the diagram above) |
| 24px (--space-24) | 8px (--space-8) | 16px (--space-16) | Concentric |
| 20px (--space-20) | 8px (--space-8) | 12px (--space-12) | Concentric. |
| 16px (--card-radius) | 16px (--space-16) | 0px | Square corner: inset equals the radius |
| 16px (--card-radius) | 24px (--panel-padding) | 0px (clamped) | Square corner: inset exceeds the radius |
Outward: min(inner + padding, 32), so a large padding doesn't over-round the card. .destination-card is the reference.
| Inner radius | Padding | Outer radius | Result |
|---|---|---|---|
| 16px (--button-radius) | 8px (--space-8) | 24px (--space-24) | Concentric, below the cap |
| 16px (--button-radius) | 16px (--space-16) | 32px (--space-32) | Concentric, exactly at the cap |
| 16px (--button-radius) | 32px (--space-32) | 32px (clamped) | Capped (.destination-card); 48 would over-round |
outer = min(inner + padding, 32); choosing a new child, use inner = max(outer − padding, 0).max(var(--card-radius) - var(--space-N), 0px). When the padding is at least the parent's radius, the child's corners are square.min(calc(var(--inner-radius) + var(--space-N)), var(--space-32)). Past 32 the card stops tracking the child instead of ballooning; at that size the difference is barely visible. .destination-card (16 + 32 = 48 → 32) is the reference.calc(), not a token. There is no --nest-radius. Take the parent radius from --card-radius or --panel-radius and the padding from the parent's --space-*.CLAUDE.md → Nested radius — concentric corners; design.md → Nested radius; the calc next to the radius tokens in styles.css.--surface-*[data-theme] on <html> switches them. Materials build on these fills (paper.bg = var(--surface-card)); shadow and state are under Elevation.Each ladder shows its own theme's values, whatever theme the page is in.
Dark
.panel shell
Light
.panel shell
--surface-page · lifts via shadow
Which token for which job
--surface-sunk: recessed wells and demo containers. The only tier below the page.--surface-page: the <body> background that everything sits on.--surface-raised: .panel shells, the playground rail, the swap widget shell, footer bands. One step lighter than the page.--surface-card: cards, tiles, paper-material consumers, .ui-amount-card. The top tier in dark; in light it equals --surface-page (white) and lifts by shadow alone.--glass-base: the translucent base for the Glass material, outside the solid ladder. See Materials → Glass.<!-- 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 paper, glass, gradient or halo, use a Material (#materials) */
Fill tokens. Light values are set in [data-theme="light"].
| Token | Dark | Light | Use |
|---|---|---|---|
| --surface-page | oklch(8% 0.015 268) | oklch(100% 0 268) | Page background |
| --surface-sunk | oklch(5% 0.012 268) | oklch(91% 0 268) | Recessed wells, demo containers |
| --surface-raised | oklch(16% 0.016 268) | oklch(97% 0 268) | Footer, raised page-level surface, .panel shells |
| --surface-card | oklch(24% 0.018 268) | var(--surface-page) | Cards, tiles, paper-material consumers; equals --surface-page in light |
| --glass-base | color-mix(--surface-page, white 8% / 70%) | Glass material fill base | |
| --border-subtle | oklch(100% 0 0 / 0.06) | oklch(0% 0 0 / 0.06) | Card borders, dividers |
Light mode caps at --surface-page. In light the page is already white, so --surface-card equals it and cards lift by shadow alone. The switch lives in that one token; component CSS never branches on theme.
[data-theme="dark"] or [data-theme="light"] on <html>, set before first paint by shared.js to avoid a flash.:root default. In the embed (?embed=1), the page is dark only for scheme=dark and light otherwise.--surface-raised goes on --surface-page, and --surface-card on either. Don’t skip tiers.--elev-* tier, not a hand-authored shadow. See Elevation tiers.var(--font-sans) unless set to var(--font-mono).--font-sans · --font-monoGeist for content and UI; Geist Mono for code, addresses, numbers and eyebrows.
--font-sans
Geist · 7 weights
--font-mono
Geist Mono · 4 weights
Geist weights
Geist Mono weights
★ Default weight. Geist 700 for headings, Geist Mono 500 for token labels and eyebrows. Use another weight only when the content calls for it, such as a 600 button or a 400 paragraph.
/* 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;
/* Sans by default */
html { font-family: var(--font-sans); }
/* Mono only for technical content */
code,
.mono,
.eyebrow-code,
.ds-doc-codeblock { font-family: var(--font-mono); }
/* Inline token reference in prose */
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
| Token | Family | Foundry / License | Fallback stack |
|---|---|---|---|
| --font-sans | Geist | Vercel · Open Font License | system-ui, -apple-system, 'Segoe UI', sans-serif |
| --font-mono | Geist Mono | Vercel · Open Font License | ui-monospace, 'SF Mono', Menlo, Consolas, monospace |
Loaded weights
| Family | Weights | Source |
|---|---|---|
| Geist | 300 · 400 · 500 · 600 · 700 · 800 · 900 | Google Fonts |
| Geist Mono | 400 · 500 · 600 · 700 | Google Fonts |
Where each is used
| Surface | Font | Why |
|---|---|---|
| Headings (h1–h3, hero, display) | --font-sans | Editorial voice at 24–80px. |
| Body, prose, marketing copy | --font-sans | Default. Sans at 16/24. |
| Form labels, button text, card titles | --font-sans | Sans 500/600 keeps controls neutral. |
Eyebrows (.eyebrow-code, .ds-doc-eyebrow) | --font-mono | Mono uppercase marks a section, not prose. |
Inline code · token references | --font-mono | Separates --accent-primary from “accent primary”. |
Code blocks (.ds-doc-codeblock) | --font-mono | Fixed width keeps indentation and columns aligned. |
| OKLCH / hex / pixel values | --font-mono | Numbers align down a column. |
| Wallet addresses, hashes, IDs | --font-mono | Truncated hex stays legible at small sizes. |
| Token name columns in spec tables | --font-mono | .mono / .mono-sm, so the column scans as identifiers. |
--font-sans and --font-mono from the theme's font and mono fields (LI.FI 2.0 uses Inter and IBM Plex Mono). Scale, weights and tracking stay shared. See CLAUDE.md → "Typography axis".--font-sans 400 / 16px / 24px. Don't shrink it for density.<code> when they appear in prose, such as --accent-primary, .ds-doc-card or oklch(68% 0.220 268).<h1> reads as a code snippet.--lh-* tokens. Its loose default line-height fights tables and code blocks: use --lh-sm (20px) at caption size and --lh-body (24px) at body size..mono and .mono-sm are per-cell utilities for token-name and small numeric columns, never a whole row or paragraph.--font-jumperJumper uses Urbanist for sans. Scale, weights, tracking and Geist Mono are shared with LI.FI.
--font-jumper
Urbanist · 7 weights
--font-sans · LI.FI reference
Geist
Same scale, two voices
Urbanist weights
Urbanist takes Geist's weights role for role (700 headings, 400 body, 500/600 UI). Until the brands split, Jumper differs from LI.FI in three things only: the jumper-1 / jumper-2 theme presets, the --jumper-indigo / --jumper-purple logo tokens, and this font.
/* styles.css :root, next to --font-sans */
--font-jumper: 'Urbanist', system-ui, -apple-system, 'Segoe UI', Arial, sans-serif;
/* Set once on the Jumper page or region root */
.jumper-surface { font-family: var(--font-jumper); }
/* Current consumer: the lockup 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
| Token | Family | Foundry / License | Fallback stack |
|---|---|---|---|
| --font-jumper | Urbanist | Corey Hu · Open Font License | system-ui, -apple-system, 'Segoe UI', Arial, sans-serif |
Shared and different
| Axis | LI.FI | Jumper | Status |
|---|---|---|---|
| Sans family | Geist | Urbanist | Differentiated |
| Colour palette | lifi-1 (default) | jumper-1 / jumper-2 presets | Differentiated |
| Logo tokens | currentColor mark | --jumper-indigo · --jumper-purple | Differentiated |
Type scale (--text-* / --lh-*) | one ladder | Shared | |
Weight ladder (--fw-*) + roles | one ladder | Shared | |
Tracking (--tracking-*) | one ladder | Shared | |
Mono (--font-mono) | Geist Mono | Shared | |
| Components + spacing + radius + elevation | one system | Shared | |
Loaded weights
| Family | Weights | Source |
|---|---|---|
| Urbanist | 300 · 400 · 500 · 600 · 700 · 800 · 900 | Google Fonts, on pages with Jumper chrome (this page, Assets) |
font-family: var(--font-jumper), never per component. Don't mix Geist and Urbanist in one surface.family=Urbanist:wght@300..900 to its Google Fonts link. Without it the page silently falls back to system sans.Five ways sans and mono combine.
Section header
// 03 — Foundations
Pages reference var(--accent-primary) and var(--surface-raised), never literal OKLCH.
Mono eyebrow, sans heading and body, mono code for token references.
KPI stat
Mono label and value, so numbers align when stacked; sans delta chip.
Inline references
Quotes route through the 0xb1739…ee01 aggregator on Arbitrum, return cached responses for ~80ms via the quote-cache service, and emit a QuoteReady event with amountOut and gasEstimate.
Mono code marks the things that exist in code; sans says what they do.
Detail list
0x742d35…f8e30xb1739…ee01Sans terms; hex values in mono code. Amounts use tabular-nums so they align across rows.
Tab nav + content
Routes are scored by execution time, slippage, and fee. The aggregator returns the lowest-cost path for every quote.
Sans tabs over sans content, with an accent underline on the active tab. The catalog's own card tabs use mono uppercase with the same underline.
<!-- 1. Section header -->
<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 (.stat-card) -->
<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 in <code> -->
<div class="card">
<p>Quotes route through the <code>0xb1739…ee01</code> aggregator…</p>
</div>
<!-- 4. Detail list; hex 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 above a card -->
<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>
<code> when they appear in copy.--tracking-wider. Don't decorate them further.<h1>.One size scale for product, marketing and docs, from 256 px deck type to 10 px micro.
Deck scale (256–112px) is for slide covers, single-word reveals and canvas-fill statements; web and product (80–10px) is everything else. Deck sizes use pixel --lh-* tokens; web display sizes use unitless line-heights so clamped type doesn't overlap.
/* Use the scale tokens, never raw px */
font-size: var(--text-display); /* 56 px display heading */
font-size: var(--text-h1); /* 48 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 matching --lh-* and --tracking-* */
| Token | Size | Weight | Tracking | Line-height | Utility | Use |
|---|---|---|---|---|---|---|
| --text-colossal | 256px | 800 (deck override) | --tracking-crunch | --lh-colossal · 240px | .text-colossal · .text-colossal--fluid | Single-word slide reveals such as CONNECT. |
| --text-keynote | 192px | 800 (deck override) | --tracking-crunch | --lh-keynote · 180px | .text-keynote · .text-keynote--fluid | Deck headline sized for 16:9 presentation frames |
| --text-statement | 144px | 800 (deck override) | --tracking-tighter | --lh-statement · 136px | .text-statement · .text-statement--fluid | Website statements, 2–3 words per line at 1440px |
| --text-poster | 112px | 800 (deck override) | --tracking-tighter | --lh-poster · 108px | .text-poster · .text-poster--fluid | Sub-hero / dense slide content (one step above Hero) |
| --text-hero | 80px | 700 | --tracking-tighter | 1.1 (literal) | — | Page-level hero numbers; canvas-fill |
| --text-display | 56px | 700 | --tracking-tighter | 1.18 (literal) | — | Display headlines, deck titles |
| --text-h1 | 48px | 700 | --tracking-tighter | --lh-h1 · 56px | — | Section titles |
| --text-h2-lg | 36px | 700 | --tracking-firm | 1.1 (literal) | — | Large numeric values: .ui-amount-card, .ui-limit-price-card, .ui-token-info__price |
| --text-h2 | 32px | 700 | normal | --lh-h2 · 40px | — | Subsection headings |
| --text-h3 | 24px | 700 | normal | --lh-h3 · 32px | — | Card titles, card-stat numbers |
| --text-body-xl | 20px | 400 | normal | --lh-body-xl · 32px | — | Page subtitles, hero intros |
| --text-body-lg | 18px | 400 | normal | --lh-body-lg · 28px | — | Intro paragraphs, .btn-xl labels |
| --text-body | 16px | 400 | normal | --lh-body · 24px | — | Standard body, hint text default |
| --text-sm | 14px | 400 | normal | --lh-sm · 20px | — | Captions, helpers, table cells |
| --text-caption | 12px | 500 | --tracking-wide | --lh-caption · 16px | — | Labels, hints, eyebrows, mono code |
| --text-micro | 10px | 500 | --tracking-loose | --lh-caption · 16px | — | Slider ticks, badge superscripts, dense overlay glyphs, .data-table--sm headers (uppercase and tracked). Only when 12 px would overpower the value it annotates |
Deck type is 800. Hero, Display and H1 are 700; the four deck utilities (.text-poster, .text-statement, .text-keynote, .text-colossal) and their --fluid forms use 800, because at 112 px and up 700 reads as an outline. It is one shared rule; don't fork it per class. Source: styles.css, search .text-poster, .text-poster--fluid,; spec: design.md §03 → Mega Display weight override.
Fluid deck sizes. .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 and the static form where the size is known, such as a 1920×1080 slide.
Gradient on deck type uses .text-gradient-mega, a 110° gradient at 180% width that reads across one word.
--text-caption and --text-sm take --lh-caption (16px) or --lh-sm (20px); body takes --lh-body; display sizes take their matching token. --lh-body under 12px text gives a 2:1 ratio instead of 1.5. Validator E015 flags it.--lh-*, such as .text-keynote with --lh-keynote: 180px.clamp() size takes a unitless line-height: 1.18 for display and hero, 0.95 at 112px and up. A pixel token stays fixed while the font shrinks, and the lines overlap.LI.FI or CONNECT..grad span in display type needs the descender fix: display: inline-block; padding: 0.04em 0.08em 0.04em 0; line-height: inherit. Without it, -webkit-background-clip: text cuts off g, y and p..text-gradient-mega, not .text-gradient, which compresses at that size.--tracking-tighter (−4%) for h1, display, hero, poster and statement; --tracking-crunch (−5%) for keynote and colossal; normal for body; --tracking-wide / --tracking-wider for uppercase captions and eyebrows..material-composerPick a material on the right and drag the sliders; the four surfaces wear the active material.
<!-- Empty containers; JS fills them from MATERIAL_REGISTRY -->
<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>
<!-- JS renders the active material's sliders -->
<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: #material-composer-modal at page end, same hooks, synced -->
Registry. Chips and sliders render from MATERIAL_REGISTRY in shared.js → initMaterialComposer(). Each entry has id, label, defaults, controls and writeTokens(state, root), which writes the --material-<id>-* tokens.
Markup hooks
| Hook | Role |
|---|---|
| data-mc-picker | JS adds one chip per registry entry |
| data-mc-sliders | JS adds one row per controls entry of the active material |
| data-mc-slider-class="…" | Optional class for each range input (slider-range--panel inline; omit in the modal) |
| data-mc-preview-surface | Tray surface; JS updates its data-material |
| data-mc-role="…" | Role shown in the surface label (Card · Tile · Small · Panel) |
| data-mc-open-modal | Button that opens the full-screen composer |
| data-mc-close | Modal close affordance (backdrop, × button, Esc key) |
| data-mc-reset | Restore the active material to its registry-declared defaults |
| data-mc-reset-all | Restore every material (modal-only) |
| data-mc-save | Save the current material's values as a named variant in localStorage |
| data-mc-variants | Container — JS lists saved variants here; click an entry to apply |
| data-mc-export | Copy the full state (all materials + saved variants) to clipboard as JSON |
| data-mc-export-preview | Live JSON preview of what export emits |
Material registry
| Material | Controls | Defaults |
|---|---|---|
| paper | opacity · shadow · highlight | 100 / 1 / 0 |
| glass | opacity · blur · highlight | 70 / 40 / 15 |
| gradient | opacity · shadow · highlight | 100 / 2 / 18 |
| halo | tint · shadow | 12 / 1 |
--material-<name>-* at :root. Every consumer reads var(--mat-*) through [data-material] and repaints with no per-component wiring.MATERIAL_REGISTRY entry, and the tokens plus a [data-material="…"] block in styles.css. driftCheck() warns in the console when one is missing.localStorage until someone clicks one, as with the Theme Composer.styles.css.styles.css. To promote a tuning, export the JSON, copy the values into the --material-*-* definitions, add a card in #materials and run the validator.styles.css, search MATERIAL COMPOSER.shared.js → initMaterialComposer(), run on DOMContentLoaded.design.md §02 → Materials → Material Composer.lifi-mc-variants, an array of {name, material, values, createdAt}.#theme-composer, #materials.--success--success, --danger, --warn and --info are calculated from --brand-anchor, each with its own lightness offset, chroma multiplier and fixed hue. Each theme can retune them per mode in the Theme Composer’s Semantic states section, for example when a brand colour washes a warning out to grey.Each role is oklch(from var(--brand-anchor) calc(l + L_offset) calc(max(c, 0.12) * C_mult) H). The 0.12 chroma floor keeps a muted or grey brand from turning the states grey. Everything below reads the live tokens, so it repaints when you pick or edit a theme.
Success
Route confirmed
Stargate via Polygon → Arbitrum settled in 12s with 0.04 % slippage.
Danger
Transaction reverted
Insufficient gas on destination chain. No funds were moved.
Warn
High slippage detected
This route shows 1.8 % price impact. Consider reducing trade size.
Info
New route available
Stargate just added a USDC bridge between Base and Arbitrum.
/* styles.css (excerpt): calculated from --brand-anchor, not typed */
: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 overrides the coefficients in an optional semantics field: lo / cm per mode, plus hues. Without it, the defaults above apply.
// 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 } }
}
How a theme edit paints. At :root the composer writes the --sem-* coefficients and the formulas recompute. On a scoped canvas (Playground widget, Portal brand surface) it writes the resolved colours instead, because the :root formula can’t read a canvas seed.
Who owns each channel
| Channel | Owner | Why |
|---|---|---|
H (hue) | Role. Locked. | Green is success, red is danger. |
C (chroma) | max(Brand, 0.12) × multiplier. | Follows the brand. The multiplier evens out perceived weight (red needs more); the 0.12 floor keeps grey brands legible. |
L (lightness) | Brand + offset. | Keeps each state legible; darker in light mode for WCAG contrast. |
Slider ranges
Bounded so no role leaves its legible range. lo and cm are per mode; the hue is shared by both modes.
| Channel | Range | Rationale |
|---|---|---|
L offset | −0.25 to +0.40 | Wider would push states out of the legible range. |
C × mult | 0.50 to 2.00 | A low-chroma brand needs more than 1.3. Below 0.5 looks muted; very high values can clip in sRGB on saturated brands. |
H success | 130° – 180° | Yellow-green to teal-green; never teal or blue. |
H danger | 5° – 45° | Red to red-orange; never yellow. |
H warn | 60° – 115° | Orange-amber to yellow-green; never green. |
H info | 210° – 275° | Sky-cyan to indigo; can sit near brand blue (268°). |
Where the values live
| Layer | Home | Notes |
|---|---|---|
| Formula defaults | styles.css :root + [data-theme="light"] | Mirrored in theme-composer-core.js → SEM_DEFAULTS; change both together. |
| Per-theme override | theme record → semantics | Optional { hues, dark, light }; saved by the editor, applied on theme pick, carried by Export CSS as --sem-* vars. |
:root paint | --sem-* coefficient vars | Inline vars for the active mode; the formulas recompute. |
| Canvas paint | resolved literals | deriveTokens(seeds, mode, semantics) writes --success and the others inline on the canvas. |
Browser support
OKLCH relative colour (oklch(from <color> L C H)) needs Chrome 119+, Safari 16.4+ or Firefox 128+. For older browsers, add a @supports not (color: oklch(from red l c h)) block with fixed values.
Do
--warn. The fix saves to that theme.lo and cm are per mode; the hue is shared.--brand-anchor.--sem-* values in :root (dark and hues) and the light block (light lo/cm), the same shape as styles.css.Don’t
--success: oklch(…) values into styles.css; it cuts the link to the brand.styles.css formula block (coefficients, oklch(from …), companions) and theme-composer-core.js (SEM_ROLES, SEM_DEFAULTS) plus the editor’s role list..screen-header, .theme-card, .option-card and .seg plus the shared window.ThemeComposer editor.The live Theme Composer. Edits repaint only this card and aren’t saved. Click a theme in the list to load it into the editor.
List view
Edit view
Every axis shows here; real mounts show a subset through features (see Anatomy).
The list is one .theme-card--row per preset from window.ThemeComposer.renderCardRow(preset, mode, isActive). The edit view is window.ThemeComposer.mount(opts): the host passes the axis values and a scope, and saves through onChange.
// theme-editor.js. scope: null → :root · element/array → that canvas
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 saves
});
// 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>
The Preview uses the catalog-only ds-theme-composer.js, which mounts the real editor with scope:[host] and a no-op onChange.
Themes store seeds, never derived tokens. deriveTokens rebuilds the full token map on every apply. The other axes are optional; absent means the 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 presets. store.load() installs window.BUNDLED_THEME_PRESETS from presets.js on the first visit and adds any new bundled id later, never overwriting a user’s theme. The default is DEFAULT_PALETTE (LI.FI 1.0).
Two views. data-tc-view="list" | "edit" on .tc-stage switches between the theme list and the editor, which the pencil opens with that theme’s values.
Axes
| Axis | Control | Token(s) painted | Mode-dep. | Default |
|---|---|---|---|---|
| Palette | OKLCH L / C / H sliders + hex picker per accent (Accent 1–3 + Background) | --accent-* · --surface-* · --text-* (full deriveTokens map) | Yes | LI.FI 1.0 |
| Corners | Soft / Standard / Sharp trio + Custom sliders + Pill toggle | --card-radius · --panel-radius · --button-radius | No | 16 / 16 / 12 |
| Spacing | Horizontal + Vertical gap discrete sliders | --grid-gap-x · --grid-gap-y | No | 16 / 24 |
| Surface | Canvas-contrast continuous slider | --surface-sunk | Yes | dark 1.5 / light 3 |
| Panels | Elevated / Flat option cards | --panel-surface · --panel-shadow · --panel-border | No | elevated |
| Semantic states | Default / Custom option cards + role swatch strip + L offset / Chroma × / Hue sliders | --success · --danger · --warn · --info (+ companions; --sem-* vars at :root, literals on a canvas) | Yes (lo / cm) | formula defaults (Default reverts) |
| Charts | Neutral / Brand-ramp option cards | --series-1..12 (never --spectral-*) | Yes (per-mode ramp literals) | spectral (fixed) |
| Text | Neutral / Tinted option cards + tint chroma / hue sliders | --text-primary/-secondary/-muted/-faint (rides palette.text) | Yes (per-mode tint) | neutral alpha ladder |
| Typography | Brand-font dropdown (Google Fonts; rows preview each family) | --font-sans + inline font-family on the scope | No | :root default family |
Mounts
| Mount | Container | Axes (features) | Scope (paints) | Persistence |
|---|---|---|---|---|
| FAB Theme Composer | .theme-composer--floating | palette · corners · surface · semantics · charts · text · font (+ spacing/panels on canvas pages) | content canvas, else :root | preset record + sitewide |
| Playground rail | .theme-composer--flush | palette · corners · spacing · surface · panels · semantics · charts · text · font | [.playground-canvas] | preset record |
| Playground Chrome row | a .theme-composer in a .modal-overlay (the rail Chrome row's edit pencil) | palette · corners · surface · semantics · charts · text · font (no gaps/panels — canvas axes) | [:root] (page chrome) | ephemeral (no-op) |
| Portal Settings | bare panel in .modal-overlay | all (panels = brand only) | chrome [:root] / brand [.portal-canvas] | ephemeral (no-op) |
Interaction behaviours
| Action | Effect |
|---|---|
| Click theme card body | Applies that theme (all axes) to the mount's scope; marks the card active. No drill-down |
Click pencil (theme-card-edit) | Drills to the edit view; mounts the editor pre-filled with name / description / seeds / radii / gaps / surface / panels |
| Slider / picker / option-card change | Live-save: updates state, re-derives + repaints to scope, persists via onChange. No Save button |
| Mode tab (Light / Dark) | Swaps the seeds shown and applies the mode to the page (when modeToggle is on) |
| Type name / description | Updates the card label + panel title on every keystroke (cap 40 / 80) |
| + New Theme | Deep-copies the active palette into a new user theme and drills into edit |
| Reset · Duplicate · Export CSS · Delete | Per-theme actions (store): re-seed from bundle · clone · copy derived :root + [data-theme=light] + radii · remove (user themes only) |
:root on the next flip. Canvas mounts keep a local palette; the sitewide write is guarded by if (!canvas).applyPalette rewrites --surface-sunk, so paintSurface() runs last to keep a custom value. Corners and gaps aren’t touched by deriveTokens, so one paint is enough.--button-radius is the lg anchor, written as value + 4 by ThemeComposer.buttonRadiusToAnchor. Keep the offset.design/theme-composer.md; per-axis rules in CLAUDE.md (Theme Composer scope, Radius system, Canvas grid-spacing, Surface contrast control, Panel primitive).