Schematic, not to scale. Click a region to open its documentation.
The shell is the shared .app-shell / .app-rail / .app-canvas foundation (Components → Side nav).
<body class="playground-body">
<!-- Left customization rail (playground-specific) -->
<aside class="panel playground-rail" data-screen="root"> … </aside>
<button class="drawer-handle"> … </button>
<!-- Canvas — scrolls; hosts the widget stage -->
<main class="playground-canvas">
<div class="widget-stage">
<aside class="side-nav side-nav--rail widget-stage__view-rail"> … </aside>
<section class="widget-stage__form"> … </section>
<section class="widget-stage__receive"> … </section>
</div>
</main>
<!-- Optional right rail for live A/B comparison -->
<aside class="panel variants-rail"> … </aside>
<!-- Theme Composer FAB — injected by shared.js (shared) -->
</body>
| Region | Primitive | Role | Scope | Documented at |
|---|---|---|---|---|
| Left rail | .playground-rail | Customization drawer with drill screens for theme, layout and mode | Playground | Playground rail |
| Drawer handle | .drawer-handle | Collapse / expand the rails | Shared | Drawer handle |
| View rail | .side-nav--rail | Simple / Advanced tier switch (sets the layout) | Shared + Playground | Presentation |
| Widget stage | .widget-stage | Form and receive panel, dual or compact | Playground | Dual layout |
| Form | .ui-card | Send / Receive / Review state machine | Playground | Widget shell |
| Receive panel | .widget-stage__receive | Quotes, market chart, orders (mode-dependent) | Playground | Dual layout |
| Variants rail | .variants-rail | Right-docked live A/B comparison (workshop) | Playground | Variants rail |
| Theme Composer FAB | .fab | Theme Composer and surface switcher | Shared | FAB menu |
| Command palette | .cmd-palette | ⌘K search + scope filter | Shared | Command palette |
- Link to shared chrome; don't duplicate it. The left rail and variants rail are Playground-only and documented here. The app-shell foundation (
.app-rail/.app-canvas/.side-nav/.drawer-handle/.cmd-palette/.fab) is shared with the Portal and documented once on Components. - The stage hosts the product. Today that is the swap, bridge and limit widget. A new widget type goes into the same stage without changing the shell.
- The view rail sets the layout. Simple gives the adaptive layout and Advanced the dual layout. See Presentation and Dual layout.
- Every load starts on LI.FI 1.0. The Theme Composer can change the theme during a session, but it never restores a saved palette on load.
- Markup:
playground.html, the live build. - Shell CSS:
styles.css→ "App shell" (.app-shell/.app-rail/.app-canvas);swap.css→.widget-stage,.playground-rail,.variants-rail. - Behavior:
shared.js→initDesignFab()(FAB),lifiInitAppRailScreens()/lifiInitAppRailCollapse()(rail drill + collapse);swap.js→ rail screens + view rail. - Canonical contract: CLAUDE.md → "Playground default config" + "App shell".
Playground rail .playground-rail
A fixed glass panel that holds the head, screens, sections and footer. Its surface comes from .panel.
The rail's real root-screen markup from playground.html, with position: fixed changed to relative on the rail and handle and the JS hooks removed. The live rail fills its theme cards from localStorage; the mock hardcodes three.
<!-- Composes .panel; adds fixed position and the screen container -->
<aside class="panel playground-rail"
id="playgroundRail"
data-screen="root"
aria-label="Widget customization">
<!-- One screen per drill destination; root shows by default -->
<div class="playground-rail__screen" data-screen-id="root">
<!-- Head — brand lockup + top action cluster -->
<header class="playground-rail__head">
<a class="brand-lockup brand-lockup--back" href="…">…</a>
<div class="playground-rail__top-actions">
<button class="btn-tertiary btn-neutral btn-icon btn-sm btn-circle">…</button>
</div>
</header>
<!-- Sections — group of setting rows under a quiet eyebrow -->
<div class="playground-rail__section">
<div class="playground-rail__section-title">Layout</div>
<button class="setting-row setting-row--drill" data-drill="layout-mode">…</button>
</div>
</div>
<!-- Sub-panels: siblings of root, header is .screen-header -->
<div class="playground-rail__screen" data-screen-id="layout-height">
<header class="screen-header">
<button class="screen-header__back btn-icon btn-borderless btn-circle" data-action="back">…</button>
<h3 class="screen-header__title">Height</h3>
<div class="screen-header__trailing"></div>
</header>
<p class="playground-rail__caption">…</p>
<!-- option-card grid, custom input, etc. -->
</div>
<!-- Footer — pinned to the bottom, action strip -->
<div class="playground-rail__footer">…</div>
</aside>
<!-- Sibling: the drawer handle (catalogued at #drawer-handle) -->
<button class="drawer-handle" id="playgroundRailHandle">…</button>
| Property | Value | Source |
|---|---|---|
| Width | var(--w-6) (384 px) | Fits the theme cards and editor |
| Position | fixed · left edge · full-height | top: var(--canvas-top); bottom: var(--canvas-bottom) |
| Surface | Composes .panel | Background, shadow, backdrop, padding flow from .panel |
| Border-radius | 16 0 16 16 (top-right squared) | Squared corner is where the drawer handle docks |
| z-index | 100 | Above canvas, below navbar (1000) and modals (9000+) |
| Transform | translateX(var(--rail-tx)) | Slide-out toggle via the drawer handle |
| Active-screen rule | .playground-rail[data-screen="X"] .playground-rail__screen[data-screen-id="X"] | One screen visible at a time |
| Sections internal stack | gap: var(--space-12) | From .panel's flex column |
| Section eyebrow | --text-caption · --fw-semibold · uppercase mono | .playground-rail__section-title |
| Footer | 2-button action strip · .btn-sm · flex: 1 each | Pinned to bottom via margin-top: auto |
| Collapsed state | body.rail-collapsed | Persists in localStorage (key: lifi-playground-rail-collapsed) |
| Part | Class | Source |
|---|---|---|
| Shell | .playground-rail | Composes .panel · fixed positioning · multi-screen container |
| Screen | .playground-rail__screen | One per drill destination; the data-screen rule shows the active one |
| Head | .playground-rail__head | Flex row · brand lockup left, action cluster right · root screen only |
| Top action cluster | .playground-rail__top-actions + __top-btn | Three icon buttons: light/dark toggle, reset, settings |
| Section | .playground-rail__section | Group of setting rows under one eyebrow · flex column · 4 px gap |
| Section title | .playground-rail__section-title | Quiet uppercase-mono eyebrow above a section |
| Caption | .playground-rail__caption | Short paragraph under a sub-panel head that introduces its controls |
| Footer | .playground-rail__footer + __footer-btn | Pinned action strip · Copy code · Read docs |
| Setting row | .setting-row | See #setting-row |
| Drawer handle (sibling) | .drawer-handle | Universal primitive · toggle affordance · see #drawer-handle |
- Compose, don't fork. Build the rail from the universal primitives (
.panel,.setting-row,.brand-lockup,.option-card,.theme-card,.drawer-handle,.btn-tertiary). Don't add.playground-rail__*classes for chrome that already exists. - Screens are siblings inside the shell. The
data-screenrule shows one at a time, so drilling in and out never reflows the page. - Only the root screen has the brand head (lockup, light/dark toggle, reset, settings). Sub-panels use the universal
.screen-header, the same back-arrow header the widget's pickers use. Don't repeat the brand lockup in a sub-panel. - The footer stays pinned.
margin-top: autoholds it at the bottom. Long content scrolls inside the active.playground-rail__screenand never pushes the footer down. - Width is
--w-6(384 px), and the rail's content targets that column. If it needs more room, step to--w-7rather than an off-ladder width. - The drawer handle is a sibling, not a child, so the panel's
overflowcan't clip it during the slide. Both read the body-level--rail-tx.
- CSS:
swap.css, the.playground-railrule and thePLAYGROUND RAIL — multi-screen / drill-down primitivesblock. - Markup:
playground.html, the<aside class="panel playground-rail">at the top of.playground-canvas. - JS wiring:
swap.js:initRailScreens()(drill handler),initRailCollapse()(drawer toggle),initRailFooter()(Copy code / Read docs),initRailHeightPanel()(Height drill),initRailThemeCards()(theme card list), plus per-panel inits. - Universal primitives composed: .panel · .brand-lockup · .setting-row · .option-card · .drawer-handle · .theme-card.
Multi-screen drill data-screen · data-screen-id
Sibling screens inside the shell, one visible at a time, switched by one data attribute.
A drill row sets data-screen on the rail to show the matching sub-panel, and the back arrow restores data-screen="root". Every screen renders in the same fixed-height container, so nothing reflows.
Root screen
Click the highlighted row → data-screen="layout-height".
<!-- The contract: data-screen on the rail picks one screen by id -->
<aside class="panel playground-rail" data-screen="root">
<!-- Root screen — visible when data-screen="root" -->
<div class="playground-rail__screen" data-screen-id="root">
<button class="setting-row setting-row--drill"
data-drill="layout-height">
<!-- click sets data-screen="layout-height" on the rail -->
<!-- …icon / label / value / chevron… -->
</button>
</div>
<!-- Sub-panel, visible when data-screen="layout-height" -->
<div class="playground-rail__screen" data-screen-id="layout-height">
<header class="screen-header">
<button class="screen-header__back btn-icon btn-borderless btn-circle" data-action="back">
<!-- click sets data-screen="root" -->
</button>
<h3 class="screen-header__title">Height</h3>
<div class="screen-header__trailing"></div>
</header>
<!-- …screen content… -->
</div>
</aside>
<!-- Adding a new sub-panel:
1. Pick a kebab-case id (e.g. "developer-events")
2. Add <div class="playground-rail__screen" data-screen-id="developer-events">
3. Author the screen content (.screen-header + caption + controls)
4. Add the matching selector to swap.css's active-screen rule
5. Add the data-drill="developer-events" attribute to the root setting-row
The drill handler in swap.js → initRailScreens() is generic. -->
| Attribute | Lives on | Role |
|---|---|---|
data-screen | .playground-rail (shell) | Active screen id, default "root". JS sets it on drill and back; CSS shows the matching screen. |
data-screen-id | Each .playground-rail__screen | The screen's kebab-case id, matched against data-screen. |
data-drill | Drill row (e.g. .setting-row--drill) | Target screen id. initRailScreens() sets data-screen="<value>" on the rail when clicked. |
data-action="back" | Back button in .screen-header | Returns to root. initRailScreens() sets data-screen="root". |
CSS contract
.playground-rail__screen { display: none; }
.playground-rail[data-screen="root"] .playground-rail__screen[data-screen-id="root"],
.playground-rail[data-screen="layout-mode"] .playground-rail__screen[data-screen-id="layout-mode"],
.playground-rail[data-screen="layout-height"] .playground-rail__screen[data-screen-id="layout-height"],
/* … one selector per registered screen … */ {
display: flex;
flex-direction: column;
flex: 1 1 auto;
min-height: 0;
overflow-y: auto;
}
- Keep screens flat. Every screen is a direct child of the shell. Don't nest screens inside screens.
- Always include the root screen.
data-screen-id="root"is the default, and the back action returns to it. - One kebab-case
data-screen-idper screen, prefixed by group (layout-mode,theme-edit,developer-events). Register every new id inswap.css's active-screen selector chain. - Long content scrolls inside its own screen and never pushes the footer off the bottom.
- Don't add per-row click handlers.
initRailScreens()listens once on the rail and finds the nearest[data-drill]or[data-action="back"]. - Back always returns to root, never to a previous sub-panel. If a sub-panel needs to drill further, register the destination as a sibling screen.
- CSS contract:
swap.css, searchScreen visibilityfor the selector chain and the active-screen rule with its flex envelope. - JS handler:
swap.js,initRailScreens(). - Registered screens today:
root·layout-mode·layout-variant·layout-height·theme-appearance·theme-edit·theme-list·theme-typography. - Scrolling: the active screen scrolls, not the shell, so the footer stays pinned. Its
min-height: 0lets it shrink below its content height.
.ds-doc-variants-railShown at its natural 384 px width. The live rail is position: fixed and slides in from the right; see it in the playground. The drawer handle here is decorative.
<!-- Drawer-handle — consumer-wired to the rail's left edge -->
<button type="button" class="drawer-handle" id="variantsRailHandle"
aria-label="Toggle variants rail"
aria-controls="variantsRail" aria-expanded="false">
<svg class="drawer-handle__chevron" viewBox="0 0 24 24" aria-hidden="true">
<path d="m15 18-6-6 6-6"/>
</svg>
</button>
<!-- The rail — composes .panel for glass chrome -->
<aside class="panel ds-doc-variants-rail" id="variantsRail"
aria-label="Compare variants">
<header class="ds-doc-variants-rail__head">
<h2 class="ds-doc-variants-rail__title">Compare variants</h2>
<p class="ds-doc-variants-rail__caption">Click a card to swap the live widget.</p>
</header>
<div class="ds-doc-variants-rail__group">
<p class="ds-doc-variants-rail__group-label">Receive — Quote card</p>
<div class="ds-doc-variants-rail__cards"
data-variants-target=".widget-stage__receive .ui-quote-list">
<!-- .ds-doc-variant-card siblings, one per variant -->
</div>
</div>
</aside>
/* Consumer wiring — body-level CSS vars + fixed positioning */
body.playground-body {
--vrail-width: var(--w-6);
--vrail-right: 24px;
/* Default collapsed — rail sits off-screen-right */
--vrail-tx: calc(var(--vrail-width) + var(--vrail-right));
}
body.playground-body.vrail-expanded { --vrail-tx: 0px; }
.ds-doc-variants-rail {
position: fixed;
right: var(--vrail-right);
top: var(--canvas-top);
bottom: var(--canvas-bottom);
width: var(--vrail-width);
transform: translateX(var(--vrail-tx));
}
| Property | Value | Source |
|---|---|---|
| Width | var(--w-6) (384 px) | Same as the left .playground-rail |
| Height | calc(100vh - canvas-top - canvas-bottom) | Full-height between the canvas's top/bottom insets (24 px each) |
| Surface | var(--surface-panel-glass) | From .panel; follows light / dark |
| Shadow | var(--shadow-panel-glass) | Inherited from .panel |
| Backdrop blur | var(--backdrop-panel-glass) | Inherited from .panel |
| Border-radius | 0 var(--space-16) var(--space-16) var(--space-16) | Top-left squared where the drawer-handle docks |
| Padding | var(--space-24) | Consumer-set in the playground wiring |
| Internal stack gap | var(--space-24) | Between __head and each __group |
| Cards gap | var(--gap-card-md) (12 px) | Local --card-gap on .ds-doc-variants-rail__cards; override per instance |
| z-index | 100 | Above canvas; below navbar (1000) and modals (9000+) |
| Slide transition | 0.4s cubic-bezier(0.2, 0.8, 0.2, 1) | Shared between rail and drawer-handle via --vrail-tx |
| Title typography | var(--text-h3) · var(--fw-bold) | Heading-scale, sans |
| Caption typography | var(--text-sm) · var(--lh-sm) | One supporting paragraph |
| Group label typography | var(--text-caption) · uppercase mono · --text-faint | Quiet eyebrow over the cards |
| Layer | Owned by | What's in it |
|---|---|---|
| Surface chrome | .panel (composed) | Glass background, shadow and backdrop filter from the --surface-panel-glass family |
| Geometry | .ds-doc-variants-rail | Flex column, vertical gap, border-radius corner override for the docked edge, internal padding |
| Positioning | Consumer | position: fixed, right/top/bottom offsets, width, z-index, the translateX slide transform |
| State binding | Consumer | The body class that toggles --vrail-tx between collapsed (off-screen-right) and expanded (0) |
| Variant-switch handler | Consumer | Click on .ds-doc-variant-card → move .is-active → set data-variant on the live target → re-render |
Sub-parts
| Part | Class | Role |
|---|---|---|
| Root | .ds-doc-variants-rail | Glass panel · flex column · slide-in transform host. Composed on <aside> with .panel. |
| Head | .ds-doc-variants-rail__head | Title + caption stack at the top of the rail |
| Title | .ds-doc-variants-rail__title | h2-scale name of the variant set |
| Caption | .ds-doc-variants-rail__caption | One paragraph on what is being tested and how to use it |
| Group | .ds-doc-variants-rail__group | Labeled cluster of variant cards |
| Group label | .ds-doc-variants-rail__group-label | Mono uppercase eyebrow naming the component under test |
| Cards container | .ds-doc-variants-rail__cards | Flex column of .ds-doc-variant-card items. Reads data-variants-target (CSS selector for the live widget) |
- Always start collapsed. At rest only the drawer handle shows; opening on every load would crowd the canvas.
- Free space before opening. Two open rails squeeze the widget. On open, either collapse the existing chrome (the playground sets
vrail-took-railon the body and restores the rail on close) or let the rail overlay the canvas. - Switch variants through
data-variant. On click, move.is-active, setdata-varianton the live target and call the consumer's render function.data-variant="default"removes the attribute so the canonical render applies. - Don't re-fetch data on a variant switch. Variants are render branches over cached state, and re-fetching flickers.
- The catalog documents the default card. Alternates stay as render branches behind
data-variant, easy to keep or drop after the review.
CSS: styles.css § VARIANTS RAIL — .ds-doc-variants-rail / .ds-doc-variant-card.
Consumer wiring: swap.css § .ds-doc-variants-rail consumer wiring.
Spec: design/components/design-feedback.md → ## Variants rail.
Live reference: the inline script at the bottom of playground.html wires the handle, card clicks and the left-rail auto-collapse.
.ui-card shell. Widget primitives use the .ui- prefix; the live build is playground.html.Widget modes
Bridge, Swap, Limit, Gas and Private share one .ui-card shell and differ in labels, picker route and side panel. Private also requires a receiving wallet.
Each mode is shown without its tab strip, which lives in the form's .screen-header--main.
Bridge
Any token on any chain to any token on any chain. Both sides are independent.
Swap
Swap
Token to token on one chain. Both sides snap to the same chain on every pick.
Limit
Limit
Market price
Trades at a target price on one chain. Adds the limit-price card and expires-in row, labels the slots Sell / Buy, and the side panel shows market price and chart.
Gas
Gas
Tops up native gas on a destination chain. The only mode whose To side opens a chain picker; the receive token locks to that chain's native gas (ETH on Arbitrum, POL on Polygon, BNB on BSC, …). Only chains with a native-gas avatar are listed.
Private
Private
Route
- Network cost
- $2.87
- Bridge fee
- $2.55
- Price impact
- -0.49%
- Max. slippage
- 0.30%
- Min. received
- 1,117.87 USDC
Bridge routed through Houdini Swap, a privacy aggregator. Its single route shows as a compact inline .ui-quote-card after the receiving wallet, with a shield + “Private” chip instead of “Best return”, and the route panel is hidden. Once connected, the .ui-destination-wallet-card is always shown and an address is required. Until it is filled, the card shows an address input (type, paste or “Select”) with a “Required” chip, and Review stays disabled.
<article class="ui-card" data-state="form" data-mode="bridge | swap | limit | gas | private">
<header class="screen-header screen-header--main">
<div class="seg seg--borderless" role="tablist">
<button data-mode="bridge">Bridge</button>
<button data-mode="swap">Swap</button>
<button data-mode="limit">Limit</button>
<button data-mode="gas">Gas</button>
</div>
<h2 class="screen-header__title">Swap</h2>
</header>
<div class="ui-form-stack">
<!-- Limit only --- hidden via [data-limit-only] in other modes -->
<div class="ui-limit-price-card" data-limit-only>…</div>
<!-- Always: send + arrow + receive -->
<div class="ui-amount-pair">
<div class="ui-amount-card" data-amount-side="send">
<!-- Label: "Send" (bridge/swap/gas) | "Sell" (limit) -->
</div>
<button class="ui-swap-arrow ui-swap-arrow--lg">…</button>
<div class="ui-amount-card" data-amount-side="receive">
<!-- Label: "Receive" (bridge/swap/gas) | "Buy" (limit) -->
<!-- Chip: tandem (token + chain) in every mode -->
<!-- Gas: tandem but TOKEN auto-locked to chain's native gas -->
</div>
</div>
<!-- Limit only -->
<div class="setting-row setting-row--sm" data-limit-only>
<span>Expires in</span> <div class="dropdown">…</div>
</div>
<div class="ui-quote-mini-list" data-limit-only>…</div>
</div>
<!-- CTA: "Review" in every mode -->
<button class="btn-primary">Review</button>
</article>
<!-- To-side picker route in initCard():
bridge | swap | limit → token-picker (full token list + chain-filter sidebar)
gas → chain-picker (chain-only; no follow-up token-picker step)
Gas: on chain commit, swap.js → snapToToNativeGas() forces the
To token to LifiPickerData.findChain(chainKey).nativeSymbol. -->
<!-- Sibling panel (.widget-stage__receive) - CSS-gated via body[data-widget-mode]:
bridge | swap | gas → .ui-quote-list (full route comparison)
limit → [data-limit-receive] (.ui-token-info + .ui-price-chart) -->
| Axis | Bridge | Swap | Limit | Gas | Private |
|---|---|---|---|---|---|
| Tier placement | Both tiers | Advanced tier | Advanced tier (3rd tab) | Simple tier (3rd tab) | Simple tier (2nd tab) |
| Purpose | any token → any token, any chain | token → token, same chain | trade at a target price, same chain | top up native gas on a destination chain | any token → any token, any chain, via Houdini Swap |
| Slot labels | Send / Receive | Send / Receive | Sell / Buy | Send / Receive | Send / Receive |
| Picker headings | Send token / Receive token | Send token / Receive token | Sell token / Buy token | Send token / — (To opens chain-picker) | Send token / Receive token |
| To-side picker route | token-picker | token-picker | token-picker | chain-picker | token-picker |
| Receive chip | .chip-avatar tandem (token + chain) | .chip-avatar tandem (token + chain) | .chip-avatar tandem (token + chain) | .chip-avatar tandem, token auto-locked to chain's native gas | .chip-avatar tandem (token + chain) |
| Chain constraint | independent, any chain → any chain | both sides snap to From chain | To-side chain snaps to From | sides may differ (cross-chain by intent) | independent (same as Bridge) |
| Symbol constraint | independent | independent | independent | To-symbol locked to To-chain's native gas (ETH / POL / BNB / AVAX / …) | independent |
| Adds to form | — | — | .ui-limit-price-card + Expires in setting-row + .ui-quote-mini-list | — | .ui-destination-wallet-card, required, always shown once connected |
| Receiving wallet | Optional, footer trigger | Optional, footer trigger | None (fills to the connected wallet) | Optional, footer trigger | Required, always-shown .ui-destination-wallet-card |
| Side panel content | .ui-quote-list | .ui-quote-list | .ui-token-info + .ui-price-chart | .ui-quote-list | None. The single Houdini route renders as a compact inline .ui-quote-card in the form, after the receiving wallet. |
| Side panel header | "Receive" | "Receive" | "Market price" | "Receive" | "Receive" |
| Side panel trailing | .refresh-timer | .refresh-timer | Expand-panel button | .refresh-timer | .refresh-timer |
| Primary CTA | "Review" | "Review" | "Review" | "Review" | "Review", disabled until a receiving address is set |
| CSS gates | [data-mode="bridge"] · body[data-widget-mode="bridge"] | [data-mode="swap"] · body[data-widget-mode="swap"] | [data-mode="limit"] · body[data-widget-mode="limit"] · descendant [data-limit-only] | [data-mode="gas"] · body[data-widget-mode="gas"] | [data-mode="private"] · body[data-widget-mode="private"] |
| Persisted | localStorage["lifi-playground-widget-mode"], default bridge | ||||
- Each view tier shows three modes. The
.segtab bar shows Swap · Bridge · Limit in Advanced and Bridge · Private · Gas in Simple. Bridge is in both, so a tier switch that drops the active mode falls back to Bridge. Cold load opens the Advanced tier on Bridge. - The shell never changes. Every mode uses the same
.ui-cardwith.ui-amount-pairin the middle. Modes change what surrounds the pair (limit-price card, expires-in row, mini-quote list) and what the side panel shows (quote list or market chart). - Two attributes drive every gate.
data-modeon the form.ui-cardgates in-card behavior.data-widget-modeon<body>gates the form's siblings, chiefly the Receive panel, which CSS can't reach from the card.swap.js → applyMode()keeps them in sync. - Mark Limit-only elements with
[data-limit-only]. CSS hides them in Bridge, Swap and Gas. Don't gate visibility with mode-specific class names; they drift when a new mode is added. - Limit relabels the slots and pickers to Sell / Buy and Sell token / Buy token, through
MODE_LABELSinswap.js, so the picker title matches the slot that opened it. The primary CTA reads “Review” in every mode. - Chain constraints differ by mode. Bridge has none: both sides are independent. Swap adds a chain mirror, so both sides share one chain. Limit snaps the To chain to the From chain but keeps the token pickers independent. Gas lets the chains differ and locks the destination token to that chain's native gas.
- Gas locks the destination token. The To chip opens
[data-state-content="chain-picker"], never a token list. On chain commit,swap.js → snapToToNativeGas()readsLifiPickerData.findChain(chainKey).nativeSymbol, resolves it throughfindToken()and stamps the trigger withapplyTokenToTrigger(). Resolve throughfindToken()so aliases such as POL→matic.svgwork; never buildavatars/tokens/<sym>.svgby hand. - Gas lists only chains with a native-gas avatar.
picker-render.js → renderChainPickerList()drops chains wherefindToken(nativeSymbol, chainKey)fails (Mantle/MNT, Gnosis/xDAI, Celo, Sonic, …) rather than show a broken glyph. Adding the avatar to/avatars/tokens/makes the chain selectable. - Private is Bridge routed through Houdini Swap.
ui-quote-list.jspassesoptions.forceProvidertogetRoutes()whenbody[data-widget-mode="private"], which returns one route. The receive panel is hidden (body[data-widget-mode="private"] .widget-stage__receive { display: none }, and the Dual grid drops to one column), and the quote renders as a compact inline.ui-quote-cardafter the receiving-wallet card, with a shield + “Private” chip. Private is the Simple tier's second tab (not in Advanced) and can also be a Single-presentation lock. - Private requires a receiving address, because the output goes to an address the user names. Once connected, the
.ui-destination-wallet-cardis always shown, gated onbody[data-widget-mode="private"][data-playground-wallet-connected], not[data-destination-set].swap.js → syncPrivateGate()shows the inline input with a “Required” chip and disables Review until an address is set, in every presentation. - The receiving wallet is offered, required or hidden, by mode. Swap, Bridge and Gas offer it through the optional footer
[data-send-wallet-trigger]; choosing an address swaps in the.ui-destination-wallet-card. Private requires it. Limit hides both the trigger and the card, even if an address was set in another mode, because a limit order fills to the connected wallet. The send-wallet screen has no other entry point. - The side panel changes most. In Bridge, Swap and Gas,
.ui-quote-listslides in once an amount is entered. In Limit the panel always shows.ui-token-info+.ui-price-chart, because the market price matters before anything is typed. - Limit puts a compact route picker in the form. The chart takes the side panel, so
.ui-quote-mini-listsits under the amount pair. It uses the same mode and readiness gates as the full list. - The mode persists in
localStorage["lifi-playground-widget-mode"]. First visits and unknown values fall back to Bridge. - Source of truth:
swap.js(applyMode(),MODE_LABELS),swap.css(body[data-widget-mode]rules),playground.html(canonical markup composition). When in doubt, match playground.html.
Presentation
The widget's modes show in a two-tier View rail (Simple / Advanced) or as one locked type with a title only.
Picked in the playground rail's Presentation drill (body[data-presentation]). View rail is a two-tier left rail that drives the .seg tab bar in the form header; Single shows one widget type with a title. Both call applyMode; only the chrome differs.
View rail
Two tiers on the panel surface (--surface-raised + --elev-3). Simple (shuffle) → Adaptive layout, tabs Bridge · Private · Gas; Advanced (candlesticks) → Dual layout, tabs Swap · Bridge · Limit.
data-presentation on <body> is the only CSS gate for the single lock, the view rail and the Dual grid. The View rail is a .side-nav--rail with two tier buttons; the .seg tab bar stays in the form header.
<!-- Set from the playground rail's Presentation drill -->
<!-- "view-rail" (default) | "single" -->
<body data-presentation="view-rail" data-view-tier="simple">
<!-- View rail: two tier buttons, shown only in view-rail -->
<aside class="side-nav side-nav--rail widget-stage__view-rail" role="tablist" aria-label="Widget view">
<span class="tooltip-wrap">
<button class="btn-icon btn-borderless" role="tab" data-view-tier="simple" aria-label="Simple">…</button>
<span class="tooltip" data-tooltip-pos="right">Simple</span>
</span>
<!-- … Advanced tier button -->
</aside>
body[data-presentation] | What it shows | Layout | Tabs |
|---|---|---|---|
| single | One widget type, static title, no switcher | Any (free pick) | — (locked) |
| view-rail | 2-tier left rail (Simple / Advanced) | Set by tier: Simple→Adaptive, Advanced→Dual | Per tier: Simple→Bridge·Private·Gas / Advanced→Swap·Bridge·Limit |
Persisted across lifi-playground-presentation, lifi-playground-single-type, lifi-playground-view-tier, and lifi-playground-layout-variant via swap.js → initRailPresentationPanel() + initViewRail().
swap.js → migratePlaygroundConfigRev(), stamped by lifi-playground-config-rev, runs once to clear the saved presentation, tier and layout (and the retired lifi-playground-flow-mode / lifi-playground-mode-nav keys), so returning users land on the default view-rail + Advanced.
| Part | Class | Role |
|---|---|---|
| View rail | .widget-stage__view-rail | A .side-nav--rail on the panel surface (--surface-raised + --elev-3 + --panel-radius). display:none until the view-rail presentation shows it. |
| Tier button | .btn-icon.btn-borderless | One per tier, role="tab" + data-view-tier (simple / advanced). Drives layout + tab set via initViewRail. |
| Tab strip | .seg in .screen-header--main | Stays in the form header; the tier drives all three slots (2 fixed .seg-item + 1 .seg-item--menu), so the fixed pair differs per tier: Advanced leads Swap·Bridge, Simple leads Bridge·Private. |
| Item wrapper | .tooltip-wrap | Hosts each icon button + its hover .tooltip for the label. |
- One axis, two values.
data-presentationisview-railorsingle. - The View rail owns the layout. Simple→Adaptive, Advanced→Dual, so the standalone Layout drill hides under view-rail. Single keeps the free Layout pick.
- Tiers relabel the seg; they don't rebuild it. Click handlers read
data-modeat click time, sosyncTierSegrewrites all three slots'data-modeand label per tier (Advanced: Swap·Bridge·Limit; Simple: Bridge·Private·Gas). The third slot is the.seg-item--menu. Markup order is display order, with no CSSorder. A tier switch moves the active mode to Bridge when the new tier doesn't have it. - Gate on
body[data-presentation]directly. The single lock, view-rail visibility and the Dual grid all read it; there is no translation layer. - Don't bring back a standalone icon rail of all modes. The View rail's two-tier switcher replaced it.
- Don't bring back the Tabs presentation. Its overflow screen duplicated the View rail's tiers. The
.seg-menusplit tab is kept: re-mount its overflow chevron in the view-rail seg when there are more than three modes (DCA, perps). - Source of truth:
swap.js → initRailPresentationPanel()+initViewRail(),playground.html(the#railPresentationGrid+#railSingleTypeGridoption cards + the.widget-stage__view-railmarkup). When in doubt, match playground.html.
- CSS:
swap.css, searchView rail(surface + show gate) andView-rail tier tabs(tier-driven slots, where markup order is display order; menu-tab right-padding restore). - JS:
swap.js → initRailPresentationPanel()(presentation axis + Single type pick) andinitViewRail()(tiers → layout + tab set + re-home). - Markup:
playground.html: the#railPresentationGrid+#railSingleTypeGridoption cards (the drill) and the.widget-stage__view-railaside.
Dual layout
The form plus an always-visible side panel that shows the route list (Swap / Bridge / Gas) or the chart (Limit).
Set from the Layout drill or the View rail's Advanced tier. In Adaptive the panel slides in once a quote is ready; in Dual it is a fixed grid column, so it needs an idle state when there is nothing to show yet.
Route list
Receive
The full .ui-quote-list moves to the side panel, as in Adaptive, rather than into the form's quotes drill. The header has a refresh timer while routes are live.
Market-price chart
Market price
.ui-token-info + .ui-price-chart show before an amount is typed, since you read the price to set a limit. The header has an expand button instead of a refresh timer.
No amount yet
Receive
Enter an amount to compare routes
Swap, Bridge or Gas with no amount entered shows the .empty-state, never the chart or fake routes. In production it carries [data-routes-idle], is gated on data-quotes-state, and the route list replaces it once there is a quote.
<!-- The receive panel is a sibling of the form and always mounted -->
<body data-layout="dual" data-widget-mode="swap">
<aside class="widget-stage__receive">
<article class="panel ui-card">
<header class="screen-header screen-header--main">
<h2 class="screen-header__title">Receive</h2>
</header>
<!-- Idle: shown until data-quotes-state="visible" -->
<div class="empty-state" data-routes-idle aria-live="polite">
<span class="spot-icon spot-icon-4xl" aria-hidden="true"><!-- route icon --></span>
<p class="empty-state__message">Enter an amount to compare routes</p>
</div>
<!-- Route list; Limit uses .ui-token-info + .ui-price-chart -->
<div class="ui-quote-list"><!-- ui-quote-list.js populates --></div>
</article>
</aside>
</body>
| Mode | Side panel content | Idle state (no amount) |
|---|---|---|
| Bridge | Route list (.ui-quote-list) | Routes-idle placeholder |
| Swap | Route list (.ui-quote-list) | Routes-idle placeholder |
| Gas | Route list (.ui-quote-list) | Routes-idle placeholder |
| Limit | Market chart (.ui-token-info + .ui-price-chart) | Chart's own "select a token" empty-state |
Adaptive uses the same mapping. The stage grid is 416px 416px ("form chart"), widening to auto 416px 416px when the View rail adds its leading column.
| Hook | Role | Notes |
|---|---|---|
| body[data-layout="dual"] | Layout gate | Set by the Layout drill or the View rail's Advanced tier; switches .widget-stage to a CSS grid. |
| .widget-stage__receive | Persistent panel | Fixed grid area that never slides. Holds the route list or chart, by mode. |
| .ui-quote-list | Route list | Moved to the aside, as in Adaptive, not into the form's quotes drill. One node, so the selection and getReviewModel() move with it. |
| [data-routes-idle] | Idle placeholder | An .empty-state shown when the stage isn't quote-ready. Hidden in Adaptive (panel slides away) and Limit (chart owns the panel). |
| .widget-stage[data-quotes-state="visible"] | Readiness gate | Set on tokens-picked + amount > 0 (wallet-optional). Flips idle ↔ live route list. |
- Use the same mode-to-panel mapping as Adaptive: route list for Swap, Bridge and Gas, chart for Limit. Don't fork it per layout.
- Never show fake data while idle. With no amount, show the
.empty-state, not the price chart (a seeded demo series) or fake routes. The chart means little for Bridge anyway, since the asset price is the same on every chain. - Routes live in the side panel. Only Compact moves them into the form. Dual hides the in-form
.ui-quote-inlinepreview. - Header controls follow the panel: a refresh timer for routes, expand and chart-token tabs for the chart (Limit). The refresh timer is hidden while idle.
- Source of truth:
design/components/swap.md → Layout variantsdefines the mapping; this card renders it.
- CSS:
swap.css, searchDual layout variant(grid + persistent panel + mode-gated chart/list +[data-routes-idle]gates). - JS:
swap.js → relocateQuoteList()(routes → aside in Dual;routesInForm()= Compact only) plus the title / expand-collapse logic inapplyMode()andapplyLayout(). - Markup:
playground.html: the.widget-stage__receiveaside and the[data-routes-idle]empty-state. - Spec:
design/components/swap.md → Layout variants — Adaptive · Compact · Dual.
Widget shell .ui-card
The widget's outer container. data-state swaps its content (form, picker, review, tx-progress).
Exchange
<article class="ui-card" data-state="form">
<header class="screen-header screen-header--main">…</header>
<div class="ui-amount-pair">
<div class="ui-amount-card">… <!-- Send --></div>
<button class="ui-swap-arrow ui-swap-arrow--lg ui-swap-arrow--vertical">…</button>
<div class="ui-amount-card">… <!-- Receive --></div>
</div>
<button class="btn-primary">Review swap</button>
</article>
| Dimension | Value |
|---|---|
| Max width | var(--w-7) · 416px |
| Padding | var(--space-24) · 24px |
| Inner gap | var(--space-16) · 16px |
| Border radius | 24px |
| Background | var(--surface-raised) |
| Shadow | 0 1px 2px / 0.04 + 0 8px 24px / 0.06 |
| State attribute | data-state="form | picker | review | tx-progress" |
| Sub-card pair gap | var(--card-gap) defaults to var(--gap-card-sm) · 8px (see .ui-amount-pair) |
- Two elevation tiers. The shell is
--surface-raised; the Send and Receive.ui-amount-cards sit on it at--surface-card. Both tokens follow light / dark. - One
.ui-cardper widget. It holds the whole flow, anddata-stateswaps its content at each stage. - Sub-cards go inside
.ui-amount-pair, which keeps the.ui-swap-arrow--lg.ui-swap-arrow--glassbutton on the seam between Send and Receive at any card height. - Don't bake interactivity into the CSS. State changes happen in
swap.jsby togglingdata-state. - Source of truth: the v2 widget mockups in Figma (file
rGJrqtE7660rPUTrtS3yqR). When in doubt, match the Figma frame, not playground.li.fi v1.
Amount pair .ui-amount-pair
Two .ui-amount-cards with a swap-direction button that stays on the seam at any card height.
Matched heights
Different heights
Disconnected
Both cards use .ui-amount-card--zero (derived values fade), both chips use .avatar-tandem--placeholder with “Select”, and balance and fiat are hidden.
<div class="ui-amount-pair">
<div class="ui-amount-card">… <!-- Send sub-card --></div>
<button class="ui-swap-arrow ui-swap-arrow--lg ui-swap-arrow--vertical"
aria-label="Swap direction">
<svg viewBox="0 0 24 24">…</svg>
</button>
<div class="ui-amount-card">… <!-- Receive sub-card --></div>
</div>
| Property | Value | Notes |
|---|---|---|
| Display | flex · column | Cards stack vertically; FAB sits as the middle flex item. |
--card-gap | var(--gap-card-sm) · 8px | Visible gap between the cards, from the Card gap family. Override on the pair to widen. |
--swap-arrow-size | var(--space-32) · 32px | Button diameter at rest. The .ui-swap-arrow child and the seam math both read it. |
FAB margin-block | calc((var(--card-gap) + var(--swap-arrow-size)) / -2) · -20px | Cancels the button's resting size, so the cards meet at the seam in any hover state. |
FAB align-self | center | Horizontally centred on the pair's column axis. |
FAB z-index | 1 | Paints the glass over both cards' edges. |
| Position context | position: relative | Only for z-index; the button is not absolutely positioned. |
| Seam drift at Δh = 28px | 0.00px | Measured on an asymmetric pair. |
| Class | Role | Notes |
|---|---|---|
| .ui-amount-pair | Flex column wrapper | Owns --card-gap, passes --swap-arrow-size to the button and opts it into --swap-arrow-cutout (4 px). Children in order: Send, button, Receive. |
| .ui-amount-card ×2 | Send + Receive sub-cards | See .ui-amount-card. Either card can change height (zero balance, loading, error) without moving the button. |
| .ui-swap-arrow--lg --glass --vertical | Direction toggle FAB | 40px glass button. Use --lg + --glass in the pair; --vertical rotates the chevron 90° for stacked layouts. |
- Three children, in this order: Send
.ui-amount-card, the.ui-swap-arrow, Receive.ui-amount-card. Don't wrap the button; the recipe targets.ui-amount-pair > .ui-swap-arrowdirectly. - The button stays in flex flow, never
position: absolute. A negativemargin-blockcancels its height plus one gap, so the cards meet at the seam and the button overlaps both equally. - To resize the button, set
--swap-arrow-sizeon the pair, not on the button. The button's size and the seam math both read it. See.ui-swap-arrow. - To widen the gap, set
--card-gapon the pair. The visible gap equals--card-gapat any button size. The default isvar(--gap-card-sm)(8 px). - Either card can change height. When you add a state to Send or Receive, check that the button still sits on the seam.
- Don't use
position: absolute+top: 50%. That centres the button on the pair's total height, which is the seam only when both cards are equal. The comment inswap.cssgives the math. - The disconnected state combines:
.ui-amount-card--zeroon both cards,.avatar-tandem--placeholderwith “Select” in the token chips, and hidden per-card meta (balance, fiat, price impact). A typed Send value keeps full ink; only derived values fade (see Preserve user-typed intent through dependency loss). - The quote preview doesn't need a wallet. Once both chips hold real picks and an amount is typed, the pair shows Send fiat, Receive amount and Receive fiat, and the quote list appears, connected or not. Only the balance row, MAX chip and insufficient-balance alert need a wallet; executing needs the footer CTA's connect step.
CSS: swap.css, the .ui-amount-pair rule; its comment gives the seam math.
Live consumer: playground.html.
Related primitives: .ui-card (the outer shell), .ui-amount-card (Send / Receive sub-cards), .ui-swap-arrow (the direction-toggle FAB).
Card label .ui-card-label
The shared style for every widget card title, set by the --ui-card-label-* tokens.
The four real consumers. Change a token once and all of them follow.
Amount card
SendLimit price card
When ETH is worthDestination wallet card
Receiving walletReceived card
Received<!-- Default for new cards: add .ui-card-label to the label span -->
<span class="ui-destination-wallet-card__label ui-card-label">Receiving wallet</span>
<!-- Or point a slot-pattern card's label slot at the token: -->
<!-- .ui-amount-card { --amount-card-label-color: var(--ui-card-label-color); } -->
<!-- both resolve to the same --ui-card-label-* source -->
| Token | Default | Notes |
|---|---|---|
| --ui-card-label-size | var(--text-sm) | 14 px |
| --ui-card-label-weight | var(--fw-semibold) | 600 |
| --ui-card-label-color | var(--text-primary) | Primary ink, as dark as the card's value text. Not --text-secondary. |
| --ui-card-label-tracking | var(--tracking-normal) | 0 |
| --ui-card-label-lh | calc(20 / 14) | 20 px line box at 14 px, as .seg-item. |
Two ways to apply it, both reading the same tokens:
| Method | For |
|---|---|
Add .ui-card-label to the label span | New cards (zero-CSS default). Exemplar: .ui-destination-wallet-card__label. |
| Point the card's label slot at the token | Slot-pattern cards with an existing __label rule. .ui-amount-card (--amount-card-label-*) & .ui-limit-price-card (--limit-price-card-lead-*) default their slots to var(--ui-card-label-*), preserving per-instance override. |
- Use it for every new widget card's title label. Add
.ui-card-labelto the label span; never redeclare size, weight, colour, tracking or line height. - Not for field labels. The smaller field caption (
.ui-amount-field__label/.ui-token-select__label, 12 px /--fw-medium/--text-secondary) is deliberately quieter. Keep it out of--ui-card-label-*. - Override per instance through the token (e.g.
style="--ui-card-label-color: …"on the card), and only when a one-off really needs to differ.
- Tokens + class:
swap.css→ searchWIDGET CARD-TITLE LABEL. - Canonical contract:
CLAUDE.md→ "Widget card-title labels — one canonical style". - Spec:
design/components/swap.md→ "Card-title label".
Amount card .ui-amount-card
The Send / Receive sub-card: a header, the amount with a token chip, and a footer. It sits one tier above the .panel shell.
Send, hover for quickpicks
Receive
Zero state
Insufficient balance
<div class="ui-amount-card">
<div class="ui-amount-card__header">
<span class="ui-amount-card__label">Send</span>
<span class="ui-amount-card__trailing">
<span class="chip chip-neutral">25%</span> <!-- 50, 75, MAX -->
</span>
</div>
<div class="ui-amount-card__body">
<input class="ui-amount-card__amount" value="100">
<button class="chip-avatar chip-avatar-neutral" data-role="from">…</button>
</div>
<div class="ui-amount-card__footer">
<span class="ui-amount-card__fiat">$100.00</span>
<span class="ui-amount-card__footer-meta">
<span class="ui-amount-card__balance" data-amount-slot="balance">
<!-- Default and error twins share one grid cell -->
<span class="ui-amount-card__balance-stack">
<span class="ui-amount-card__balance-amount">2,645.15</span>
<span class="ui-amount-card__balance-error" aria-hidden="true">Insufficient balance</span>
</span>
<span class="tooltip-wrap">
<button class="btn-icon btn-borderless btn-muted btn-xs ui-amount-card__balance-trigger">
<svg class="ui-amount-card__balance-icon ui-amount-card__balance-icon--wallet">…</svg>
<svg class="ui-amount-card__balance-icon ui-amount-card__balance-icon--error">…</svg>
</button>
<span class="tooltip tooltip--multi">Balance: 2,645.15 USDC ($2,645.15)</span>
</span>
</span>
</span>
</div>
</div>
Modifier matrix
| Modifier | Padding | Radius | Amount size | Label size | Use |
|---|---|---|---|---|---|
| default | 16 / 16 | 16px | 36px | var(--text-sm) · 14px | Send / Receive in the 416 px shell. The only size. |
| --zero | inherit | inherit | inherit | inherit | State modifier. Sets --amount-card-amount-color and --amount-card-footer-color to --text-faint, dims the placeholder and hides __footer-meta. ui-amount-card.js applies it to Receive whenever the wallet is disconnected, and to Send only when its input is empty. |
Custom-property API
| Custom property | Default (rendered) | What it controls |
|---|---|---|
| --amount-card-bg | var(--surface-card) | Card surface (24% in dark, --surface-page in light), one tier above the .panel's --surface-raised. |
| --amount-card-radius | 16px | Reads --card-radius. |
| --amount-card-padding-y | var(--space-16) | Vertical padding (top + bottom). |
| --amount-card-padding-x | var(--space-16) | Horizontal padding (left + right). |
| --amount-card-gap | var(--space-12) | Gap between header / body / footer slots. |
| --amount-card-shadow | var(--elev-1) | Resting elevation, one tier above the .panel shell (--surface-raised + --elev-3). --ghost sets it to none. |
| --amount-card-label-size | var(--ui-card-label-size) | Header label size, from --ui-card-label-* (--text-sm · 14px). |
| --amount-card-label-weight | var(--ui-card-label-weight) | --fw-semibold · 600. |
| --amount-card-label-color | var(--ui-card-label-color) | --text-primary. All three label slots read --ui-card-label-*. |
| --amount-card-amount-size | 36px | Body amount type-size. Ladder: --text-h2 / 36 / --text-h1. |
| --amount-card-amount-weight | 700 | Amount weight. |
| --amount-card-amount-tracking | -0.02em | Amount letter-spacing. |
| --amount-card-amount-lh | 1.1 | Amount line-height. |
| --amount-card-amount-color | var(--text-primary) | Amount colour. Override for branded summary cards. |
| --amount-card-footer-size | var(--text-caption) | Footer type-size. |
| --amount-card-footer-color | var(--text-secondary) | Footer colour. |
| Slot | Class | What goes here |
|---|---|---|
| Card | .ui-amount-card | Outer container; --surface-card background with subtle shadow. |
| Header | .ui-amount-card__header | Two-cell row: label (left) + trailing slot (right). |
| Label | .ui-amount-card__label | Bold 14px primary-text identifier (“Send”, “Receive”). |
| Trailing | .ui-amount-card__trailing | Send's quickpicks go in __header as .chip-shortcuts, not here. Receive leaves it out; route badges belong on the route-detail card. |
| Body | .ui-amount-card__body | Two-cell row: 36px tabular-num amount (left) + .chip-avatar (right). |
| Amount | .ui-amount-card__amount | An <input> for Send (editable) or a <span> for Receive (read-only). |
| Footer | .ui-amount-card__footer | Two-cell row: fiat value (left) + supplementary meta (right). |
| Fiat | .ui-amount-card__fiat | USD value, tabular-nums, secondary-text. |
| Meta value | .ui-amount-card__balance | Meta value on both sides, set by data-amount-slot. Send ("balance"): the wallet balance (e.g. 1,000) with a wallet-icon trigger for the full balance and USD value. Receive ("price-impact"): the signed price impact (e.g. -7.27%) with an info trigger for Price Impact: 7.27% and a one-line explainer. The trigger is .tooltip-wrap + .btn-icon.btn-borderless.btn-muted.btn-xs.ui-amount-card__balance-trigger with a .tooltip.tooltip--multi at data-tooltip-pos="left". |
| Stack | .ui-amount-card__balance-stack | 1×1 grid holding the default and error twins in the Send balance slot (Receive doesn't use it). grid-template-columns: max-content + justify-items: end keep the slot's width and height the same in both states. data-state="error" on the parent slides the twins. |
| Default twin | .ui-amount-card__balance-amount | Send's balance (2,645.15) or Receive's price impact (-7.27%). Inside the stack it sets --text-secondary, so the Receive slot's danger ink doesn't bleed into it during the cross-fade. |
| Error twin | .ui-amount-card__balance-error | The "Insufficient balance" message in --danger. Always in the DOM at opacity: 0; transform: translateX(60%) so the transition can play; aria-hidden follows the state. |
| Trigger | .ui-amount-card__balance-trigger | The info button. position: relative lets the error glyph sit over the info glyph without changing the button's size. Its aria-label follows the state ("Balance details" → "Insufficient balance — see details"). |
| Wallet glyph | .ui-amount-card__balance-icon--wallet | Default Lucide wallet svg; fades out on error. |
| Error glyph | .ui-amount-card__balance-icon--error | Lucide circle-alert in --danger; cross-fades over the wallet glyph on error. |
| Meta | .ui-amount-card__footer-meta | Holds .ui-amount-card__balance on both sides. .ui-amount-card--zero hides it. |
- Send and Receive are one primitive; composition makes the difference. Send has an
<input>in__amount, quickpick chips in__headerand the balance in__footer-meta. Receive has a<span>in__amount, the token chip and fiat. Route details (bridge, best return, gas, time) go on the route-detail card. Don't add--send/--receivemodifiers. - Pair the cards inside
.ui-cardwith.ui-amount-pair, which places the swap-direction button. A single card on its own is fine for the disconnected zero state; the default is Send, button, Receive. - Zero state:
.ui-amount-card--zerowhen the wallet is disconnected. Amount and fiat show"0"/"$0"in--text-faint(about 40 % alpha, like.muted) with weight, size, tracking and line height unchanged; ink carries the state.__footer-metais hidden, because the primary CTA already asks to connect. Token chips stay at full ink because they are still pickable. - Keep the user's typed amount through a disconnect.
renderEmptyState()applies--zeroto the Receive card always and to the Send card only when its input is empty. A typed Send value stays at full ink; on reconnectrenderPair()removes--zeroand recomputes fiat, balance and Receive from it. While disconnected the Send footer meta is emptied, so the slot has no width and needs no extra rule.--zerois a state and combines with--ghost. - Canonical UI card recipe:
--surface-card+--elev-1with a 1 px transparent border at rest. Cards inside the.panelshell (--surface-raised+--elev-3) sit one tier above it (dark: 16% panel, 24% card; light: the card is lifted by shadow alone). Hover adds a 3 % accent tint and--elev-2. Active /.is-activeadds a 4 % accent fill and--elev-2, and turns the border tocolor-mix(in oklch, var(--accent-primary) 64%, transparent). The rim is a border, not a box-shadow ring, so a parent'soverflow: hiddencan't clip it (the rail usesoverflow-x: hiddenfor its slide). No halo, no layout shift. New UI cards start from this recipe;.theme-card,.uc-card,.card--accent,.form-cardand the Paper family (.card,.stat-card,.notification,.content-tile) follow it. - Use existing universals in the Send slots. The balance in
__footer-metais.ui-amount-card__balance. Don't add quickpick-specific classes. Route badges, gas and time chips and the expand chevron belong on the route-detail card. - Price impact renders at neutral footer ink; the
data-stateseverity hooks are dormant.renderPriceImpactSlot()clearsdata-stateon.ui-amount-card__balanceon every render. Thewarn/errorCSS hooks stay inswap.cssfor when severity colour returns, with this ladder, matching the.ui-quote-listdetail table:|impact| ≤ 1%→ default, neutral footer ink.1% < |impact| ≤ 3%→data-state="warn",var(--warn)ink.|impact| > 3%→data-state="error",var(--danger)ink.
impactPct:impact > 0(label-X.XX%) reads as value lost,impact < 0(label+X.XX%) as value gained, and no quote yet as a neutral cost. - Insufficient balance slides in; the Send balance slot keeps its height and width. The slot is never re-rendered. It always holds two twins inside
.ui-amount-card__balance-stack, a 1×1 grid sized to the wider twin (grid-template-columns: max-content,justify-items: end):.ui-amount-card__balance-amount: the balance (2,645.15) in--text-secondary..ui-amount-card__balance-error: "Insufficient balance" in--danger, parked atopacity: 0; transform: translateX(60%).
data-state="error"on the slot slides the amount out to the left (translateX(-30%), opacity 0) and the error in from the right (translateX(0), opacity 1) over 280 msease. The trigger'swalletandcircle-alertglyphs cross-fade in 200 ms, opacity only. The tooltip changes from "Balance: 2,645.15 USDC ($2,645.15)" to "Short 154.85 USDC · Balance: 2,645.15 USDC". The input getsaria-invalid="true", the button'saria-labelbecomes "Insufficient balance — see details", andaria-hiddenmoves to the hidden twin. Withprefers-reduced-motion: reduceit is an opacity-only cross-fade (120 ms).ui-amount-card.js → renderPair()toggles the one attribute. - Quickpicks use
.chip-shortcutswith--reveal-on-hover, inside__headerin place of the static__trailingchips. Hovering anywhere on the card reveals them (the broadened selector inswap.css), and:focus-withincovers keyboard users. Hide the cluster withhiddenunless a wallet is connected and the balance is above 0; with no balance the chips would do nothing. Send only. - Token chip, not a From/To button. The token picker opens from a
.chip-avataron the right of__body; the old.ui-token-selectrow is retired in this layout. - Tune through the
--amount-card-*properties, not new modifiers. Override per instance (inlinestyleor a context selector) for background, padding, amount size and so on; use--ghostfor the flush embedded case. - Tokens, not hex. The background is
--surface-cardand text uses--text-primary/--text-secondary, so the Theme Composer themes the widget with no extra code. - Loading paints skeletons in the derived slots only. On
persona-changeandwallet-change,ui-amount-card.js → enterLoadingState()puts.skeleton.--textin Send fiat, Send balance, Receive amount and Receive fiat, setsdata-state="loading"+aria-busy="true"on each card, and runsrenderPair()after600 ms. The typed Send value, token chips, labels and button stay.balance-changeskips loading because nothing is fetched, and nothing loads while disconnected.
Destination wallet card .ui-destination-wallet-card
The chosen send-to wallet on the form: wallet avatar, ENS name or address, and a clear ×. It replaces the footer wallet trigger.
Hidden until .ui-card[data-destination-set], or in Private mode until body[data-widget-mode="private"][data-playground-wallet-connected]. The demos force display:flex.
Empty
Address typed
ENS name
Pasted address, no ENS
<!-- Above the action footer; hidden until .ui-card[data-destination-set] -->
<div class="ui-destination-wallet-card" data-destination-card>
<!-- "Required" shows only under [data-required]; omit it in optional flows -->
<div class="ui-destination-wallet-card__header">
<span class="ui-destination-wallet-card__label">Receiving wallet</span>
<span class="chip chip-warn ui-destination-wallet-card__required">
<svg class="chip-icon" viewBox="0 0 24 24" aria-hidden="true">…</svg>
Required
</span>
</div>
<!-- Zero state: [data-required] shows this row and hides __body -->
<div class="ui-destination-wallet-card__entry">
<input type="text" class="ui-destination-wallet-card__input" data-destination-input
placeholder="Enter address" aria-label="Receiving wallet address">
<button type="button" class="ui-destination-wallet-card__enter chip-avatar chip-avatar-neutral"
data-action="open-send-wallet">
<span class="avatar-tandem avatar-tandem--placeholder" aria-hidden="true">…</span>
Select
</button>
<!-- Swaps in once the input has content (placeholder hidden). -->
<button type="button" class="ui-destination-wallet-card__input-clear btn-neutral btn-icon btn-sm btn-circle"
data-destination-input-clear aria-label="Clear address">…</button>
</div>
<!-- Set state (any destination confirmed): identity row + clear ×. -->
<div class="ui-destination-wallet-card__body">
<!-- Identity = re-open the picker. Root is a <div>-free button -->
<button type="button" class="ui-destination-wallet-card__identity"
data-action="open-send-wallet" aria-label="Edit destination wallet">
<span class="avatar-tandem" aria-hidden="true">
<img class="avatar avatar--circle" src="…/wallets/metamask.svg" alt="">
<img class="avatar-badge avatar-badge--br" src="…/chains/ethereum.svg" alt="">
</span>
<span class="ui-destination-wallet-card__text">
<span class="ui-destination-wallet-card__name">vilenr.eth</span>
<span class="ui-destination-wallet-card__addr">0x2ee6…b49C</span>
</span>
</button>
<button type="button" class="ui-destination-wallet-card__clear btn-neutral btn-icon btn-sm btn-circle"
data-destination-clear aria-label="Clear destination wallet">…</button>
</div>
</div>
| Property | Token / value | Notes |
|---|---|---|
| Surface | --dest-card-bg: var(--surface-card) | Same local-slot recipe as .ui-amount-card; override per instance. |
| Radius | --dest-card-radius: var(--card-radius) | 16 px default; tracks the playground corner control. |
| Elevation | --dest-card-shadow: var(--elev-1) | box-shadow. The masked .ui-amount-pair above uses the matching --elev-1-filter, so both shadows look the same. |
| Padding | --dest-card-padding: var(--space-16) | Matches .ui-amount-card. |
| Gap (label → body) | --dest-card-gap: var(--space-12) | Matches --amount-card-gap. |
| Label type | .ui-card-label | The shared .ui-card-label, so "Receiving wallet" matches "Send" and "Receive". |
| Name type | --text-body / --fw-semibold | --text-primary; truncates with ellipsis. |
| Address type | --text-sm | --text-muted; truncates with ellipsis. |
| Avatar | .avatar-tandem | 40 px wallet-provider logo (.avatar--circle, MetaMask until provider selection ships) with the destination chain in .avatar-badge--br. |
| Zero-state entry | .ui-destination-wallet-card__entry | Private mode only. Laid out like .ui-amount-card__body (space-between, 40 px min-height): address input left, action right. Shown under [data-required], which hides __body. |
| Zero-state input | .ui-destination-wallet-card__input | Bare <input> (the card is the chrome), --text-body / --text-primary, placeholder “Enter address” in --field-placeholder. Enter / paste resolves the address or domain and routes through the confirm sheet (swap.js → initSendWallet). |
| Zero-state action | .chip-avatar ↔ .ui-destination-wallet-card__input-clear | Empty input: the token-picker “Select” pill (placeholder .avatar-tandem) opens the send-wallet flow. With content: the clear × (.btn-icon.btn-sm.btn-circle), switched by .ui-destination-wallet-card__entry:has(.ui-destination-wallet-card__input:not(:placeholder-shown)) with no JS flag. |
| Required marker | .chip.chip-warn + .chip-icon | Required flows only (Private Swap). Sits beside the label in __header, warn-toned with the triangle-alert glyph. Shown under [data-required], so it clears once an address is set. Omit it in optional flows. |
| Element | Role |
|---|---|
.ui-destination-wallet-card | Card root, a <div> because it holds two buttons. |
__header | Label row (flex-start, 8 px gap): __label with the optional __required beside it. |
__label | “Receiving wallet” eyebrow over the identity row. |
__required | .chip.chip-warn + .chip-icon (triangle-alert) reading “Required”. Shown under [data-required]; left out of the markup when the destination is optional. |
__entry | Zero-state row (Private mode): __input and the trailing action, laid out like .ui-amount-card__body. Shown under [data-required]. |
__input | Bare <input> for a 0x address or ENS domain, placeholder “Enter address”. Resolves on Enter or paste through the confirm sheet. |
__enter | The “Select” pill, a <button> .chip-avatar.chip-avatar-neutral that opens the picker (data-action="open-send-wallet"). Shown while the input is empty. |
__input-clear | Clear × <button> (.btn-icon.btn-sm.btn-circle) that empties the input. Replaces __enter when the input has content. __clear is different: it unsets a confirmed address. |
__body | Set-state row: identity (fills) and clear (square). Hidden under [data-required]. |
__identity | <button> that re-opens the picker (data-action="open-send-wallet"). Neutral hover, full UA reset and font-family. |
.avatar-tandem | Wallet-provider logo (MetaMask by default) with the destination chain in the bottom-right badge (.avatar-badge--br). |
__text · __name · __addr | ENS / label over the short address (or short address over “External wallet” when there's no ENS). |
__clear | <button> that clears the destination (data-destination-clear); the footer wallet trigger comes back. |
- Show the card on
.ui-card[data-destination-set]; the same attribute hides the footer wallet trigger. Once a destination is set the card replaces the trigger, so they never show together. Exception, Private mode:body[data-widget-mode="private"][data-playground-wallet-connected]also shows the card, with or without an address, because Private requires a receiving wallet. - Never shown in Limit mode. A limit order fills to the connected wallet, so
body[data-widget-mode="limit"]hides both the footer trigger and the card, even if a destination was set in another mode. With both entry points hidden, the send-wallet screen can't be reached. Swap, Bridge and Gas keep it optional. See the Receiving wallet row in Widget modes. - Private adds a required zero state. With a wallet connected and no address, the card gets
[data-required]and CSS swaps__bodyfor.ui-destination-wallet-card__entry, laid out like.ui-amount-card__body: an inline__input(“Enter address”) and a trailing action. Users can type or paste an address or ENS domain (Enter or paste resolves it through the confirm sheet,swap.js → initSendWallet) or click “Select”, the token-picker pill, to open the send-wallet picker.swap.js → syncPrivateGate()toggles[data-required]and keeps Review disabled until an address is set. In other modes the zero state never appears. - The trailing action switches between Select and clear × on content, with no JS flag.
.ui-destination-wallet-card__entry:has(.ui-destination-wallet-card__input:not(:placeholder-shown))swaps the pill for the clear ×. That × empties the input;__clearunsets a confirmed address. - “Required” is a warn chip beside the label, with an icon as well as colour. In mandatory flows (Private Swap),
__headerholds a.chip.chip-warn+.chip-icon(triangle-alert) next to the label (flex-start, 8 px gap). The glyph keeps the meaning without colour, as in the alert spot-icon rule.[data-required]shows it, and it clears once an address is set. Omit it in optional flows. - Uses the canonical UI card recipe with box-shadow elevation. The card follows
.ui-amount-card's local slots (--dest-card-bg / radius / padding / gap / shadow), with a 12 px gap andbox-shadow: var(--elev-1). The masked.ui-amount-pairabove it must use--elev-1-filter, because its button-cutout mask clips box-shadow; the two tokens match, so both shadows look the same. See Elevation. - The destination survives a wallet disconnect. It is the user's choice, not derived data, so only the user's
×clears it (see Preserve user-typed intent through dependency loss). - The card root is a
<div>, not a<button>. It holds two buttons (identity and clear), and a button root would make the parser close the outer button early. Keep the two buttons as siblings. - Set
font-family: var(--font-sans)on the identity button. Buttons reset to the UA font, so without it the name and address render in Arial. - The avatar shows a wallet, not a person. The
.avatar-tandemshows the wallet provider (MetaMask by default until provider selection ships) with the arrival chain in.avatar-badge--br; a destination is an external address, never a persona.
- Markup:
playground.html→ the form-stack block (grepdata-destination-card) + the[data-state-content="send-wallet"]picker + the two.ui-wallet-confirmmodals. - CSS:
swap.css→ theSEND-TO-WALLETsection (grep.ui-destination-wallet-card). - Behavior:
swap.js→initSendWallet()+initSendWalletModals()(ENS resolver, address book, confirm / bookmark flow, destination apply / clear).
Quick settings .ui-quick-settings
Drill rows above the CTA that mirror live settings, so users can review and change them before acting.
Each row is a .setting-row--sm .setting-row--drill whose data-quick-link opens a sub-screen of .ui-settings; its value mirrors the live setting (data-settings-value). Swap and Bridge have separate blocks keyed by data-quick-settings-mode: Swap has three rows, Bridge four, Limit none. The demos force visibility; in production each block is gated on body[data-layout="dual"][data-widget-mode="swap"] or …[data-widget-mode="bridge"].
Compositions per tab
Swap
Bridge
Bridge has its own block (data-quick-settings-mode="bridge") with Route priority instead of Route type and an extra Bridges row, the two settings only a cross-chain route has.
Limit
Limit has no cluster: .ui-orders-panel and .ui-limit-price-card fill the space, and price and expiry don't share these settings. The rows stay in the DOM with display: none.
Icons
Icons on
Icons are off by default. Each row keeps its .setting-row__icon, so the toggle is pure CSS: the 20 px icon column comes back with data-icons="on" on the block or body[data-quick-settings-icons="on"].
<!-- In .ui-form-stack above the action footer; rows deep-link via data-quick-link -->
<!-- Swap block: route-type, exchanges, slippage (3 rows) -->
<div class="ui-quick-settings" data-quick-settings-mode="swap">
<button type="button" class="setting-row setting-row--sm setting-row--drill"
data-quick-link="route-type">
<span class="setting-row__icon"><svg>…</svg></span>
<span class="setting-row__label">Route type</span>
<span class="setting-row__value setting-row__value--muted"
data-settings-value="route-type">All</span>
</button>
<!-- + exchanges, slippage -->
</div>
<!-- Bridge block: route-priority, exchanges, bridges, slippage (4 rows) -->
<div class="ui-quick-settings" data-quick-settings-mode="bridge">…</div>
<!-- Icons on: per instance or page-wide -->
<div class="ui-quick-settings" data-icons="on">…</div> <!-- per-instance -->
<body data-quick-settings-icons="on">…</body> <!-- page-wide -->
| Property | Value | Notes |
|---|---|---|
| display | flex (column) | Children stack; .ui-form-stack's own gap doesn't apply because .ui-quick-settings is the container. |
| gap | var(--space-8) | Row gap for the 40 px .setting-row--sm tier. |
| margin-top | var(--space-16) | Space above the cluster in .ui-form-stack, instead of a divider. |
| Gate (visibility) | body[data-layout="dual"][data-widget-mode="swap"] …[mode="swap"] body[data-layout="dual"][data-widget-mode="bridge"] …[mode="bridge"] | Only in the Dual layout, and only the active mode's block. Limit and Gas have none. |
| [data-quick-settings-mode] | swap | bridge | Swap block: route type, exchanges, slippage. Bridge block: route priority, exchanges, bridges, slippage. |
| Icons gate (page-wide) | body[data-quick-settings-icons="on"] | Page-wide opt-in. There is no UI toggle; set the attribute. |
| Icons gate (per-instance) | .ui-quick-settings[data-icons="on"] | Opt-in for one instance, without touching body. Same CSS rule as the page-wide gate. |
| Grid (default) | 1fr auto | The icon column collapses and the label takes its 20 px. Icons stay in the DOM with display: none. |
| Grid (icons-on) | var(--space-20) 1fr auto | Restores the canonical .setting-row--sm 3-col grid. |
| Class / attribute | Role | Notes |
|---|---|---|
| .ui-quick-settings | Wrapper | Flex column inside .ui-form-stack. Owns the inter-row gap + top margin; the rows own their own surface chrome. |
| .setting-row--sm | Row tier | 40 px rows with body-sm type, so four rows and the CTA fit in the Dual layout without scrolling. |
| .setting-row--drill | Affordance | Trailing chevron; a click opens the setting's sub-screen rather than changing a value inline. |
| [data-quick-link] | Drill target | Names the .ui-settings sub-screen the row opens, using the full menu's drill keys. |
| .setting-row__icon | Leading glyph | Hidden by default but kept in the DOM. Pick the icon that names the setting (route type uses icons/split.svg). |
| .setting-row__label | Axis name | The setting's name. Stays sm and semibold per the row's tier. |
| .setting-row__value (--muted) | Current value | Mirrors the live setting in .ui-settings. Muted, so the cluster reads as a summary. |
| [data-icons="on"] | Instance opt-in | Optional. Shows the icon column for this instance; same rule as the page-wide gate. |
- Use it when each summary row should open its setting. The cluster names the settings that matter most for the flow and lets users change one without losing the form. For a summary that only describes, use a definition list.
- Route type is a choice, not a toggle. Its sub-screen offers All, Simulated only and Private as a radio set, wired through
CHOICE_VALUESinswap.js → initQuickSettings, so a pick is checked and its label mirrors to everydata-settings-value="route-type"(the quick row and the full-menu row). "Simulated only" is in progress: selectable but not yet bound to routing, like the other mock choices. Route type is Swap's first row; Bridge's is Route priority (Best Return / Fastest). - Place it above the action CTA, never below. It is the last thing reviewed before the final button, so it sits directly above
.action-barin.ui-form-stack. Placed under the form header it loses that context. - Four rows at most. More rows stop reading at a glance and compete with the form. Swap has three, Bridge four. If a flow needs more, link to a full settings menu instead.
- Values mirror the live setting. Bind
data-settings-valueto the source the full menu reads, so the summary never goes stale. - No icons on quick rows; icon and label in the full Settings menu. Quick rows are the compact
.setting-row--smtier, where the labels alone are clear. The full.ui-settingsmenu uses.setting-row--lg, where icons help in a longer list. In general,--smsummaries drop the icon and--lgmenus keep it. To show quick-row icons, setbody[data-quick-settings-icons="on"]or.ui-quick-settings[data-icons="on"]. - Gate by widget mode, one block per mode. Swap and Bridge each have a
.ui-quick-settings[data-quick-settings-mode]block gated onbody[data-layout="dual"][data-widget-mode="…"], and only the active one shows. Limit and Gas have none. A new widget config gets its own block rather than reusing another mode's. - Navigation, not selection. Rows have no
.is-activestate and keep.setting-row'sborder: 0, since navigation rows skip the card's transparent border slot (CLAUDE.md§ List-row state recipe). If a value needs picking, do it on the drill screen. - Reusing the pattern? Keep the contract: a
.ui-quick-settingswrapper,.setting-row--sm --drillrows, and adata-quick-linkper row pointing at a registered.ui-settingssub-screen (for example a Gas source or a Limit price-and-expiry summary). Don't rename the wrapper per consumer.
CSS: swap.css § Quick settings — Dual + Bridge/Swap only — search .ui-quick-settings.
Markup: playground.html — search class="ui-quick-settings"; the rows (route type, exchanges, slippage) are authored inline inside .ui-form-stack. The matching route-type sub-screen + main-list row live in the .ui-settings block.
JS: swap.js — initQuickSettings(card) wires each [data-quick-link] click to the matching .ui-settings sub-screen, and registers choice settings in CHOICE_VALUES (route-type = All / Simulated only / Private) so picks mirror to every data-settings-value surface. The icons gate is pure CSS.
Catalog companion: .ui-settings for the inner state machine the deep-links navigate INTO.
Rule (canonical): CLAUDE.md § Quick settings composition. Spec rendering: design/components/swap.md → Quick settings.
Settings flow .ui-settings
An inner state machine: one outer .ui-card state holds a main list and its sub-screens, switched by data-settings-screen.
Both demos use the same .ui-settings at 368 px; only data-settings-screen differs. Changing it swaps the visible [data-settings-content] without re-mounting anything.
Main screen
Settings
Sub-screen
Appearance
<!-- Outer state machine adds ONE new value: "settings" -->
<article class="ui-card" data-state="settings">
<div data-state-content="settings">
<div class="ui-settings" data-settings-screen="main">
<!-- Main list -->
<div data-settings-content="main">
<header class="screen-header">
<button data-action="settings-back">…</button>
<h2 class="screen-header__title">Settings</h2>
</header>
<div class="setting-stack">
<button class="setting-row setting-row--drill" data-settings-drill="appearance">…</button>
<!-- N drill rows -->
</div>
</div>
<!-- One sibling per sub-screen -->
<div data-settings-content="appearance">
<header class="screen-header">
<button data-action="settings-sub-back">…</button>
<h2 class="screen-header__title">Appearance</h2>
</header>
<div class="setting-stack">…</div>
</div>
<!-- … more sub-screens -->
</div>
</div>
</article>
| Attribute / role | Value | Notes |
|---|---|---|
| .ui-card[data-state] | "settings" | Outer state value, alongside form / picker / chain-picker / review / tx-progress. |
| .ui-settings[data-settings-screen] | "main" · "<sub-key>" | Inner state. JS sets it to "main" or a sub-screen key. |
| [data-settings-content] | "main" · "<sub-key>" | Sibling content blocks under .ui-settings. CSS shows the one whose key matches the wrapper's data-settings-screen. |
| [data-action="settings-back"] | — | Main-screen back button. Restores the OUTER previous state via card.dataset.settingsPrevState. |
| [data-action="settings-sub-back"] | — | Sub-screen back button. Sets data-settings-screen="main". |
| [data-settings-drill] | "<sub-key>" | Main-screen drill row. Sets data-settings-screen to the named sub-screen. |
| Class / wrapper | Role | Notes |
|---|---|---|
| .ui-card[data-state="settings"] | Outer-state shell | The widget shell, with the same transition and receive-panel rules as the other states. |
| [data-state-content="settings"] | State-content slot | Sibling of [data-state-content="form"] / "picker" / etc. Becomes visible when the outer state matches. |
| .ui-settings | Inner state-machine wrapper | Flex column, flex: 1 1 auto, min-height: 0. Hosts the inner sub-screen siblings; provides the scroll envelope for the active screen. |
| [data-settings-content="main"] | Main-screen content | Contains the section's .screen-header + .setting-stack. The stack is the scroller (bleed margins put the scrollbar in the card gutter). |
| [data-settings-content="<sub-key>"] | Sub-screen content | One per drill destination: .screen-header plus a body (.setting-stack, a list or a form). |
| .screen-header__back | Back button | On the main screen, restores the previous outer state; on a sub-screen, returns to "main". |
- Use it when one outer state needs its own navigation. Settings is the main case; a multi-step review, a wallet-connect wizard or an order-history drill-down could follow. For a single static screen, add an outer state instead.
- Scope the attributes per flow:
data-<flow>-screen+data-<flow>-content(data-settings-screen/data-settings-content,data-review-screen/data-review-content), so inner state machines never share an attribute. - Main-screen back restores the previous outer state, not "form". Store
card.dataset.<flow>PrevStateon open, read it on back, then delete it, so users return to wherever they opened settings from. - Each
[data-settings-content]is a flex column with its.screen-headerat the top and a scrolling body, the same clip-and-host pattern as.ui-form-stack. - CSS owns visibility.
.ui-settings > [data-settings-content] { display: none }plus one rule per active key; JS only sets the attribute. A new sub-screen needs one selector, one sibling div and its drill and back wiring. - Don't add an outer state per sub-screen. Keep the outer list (form / picker / settings / review / …) for top-level states; positions such as
settings-appearancebelong to the inner machine. - The wrapper is the scroll envelope.
.ui-settingsisflex: 1 1 auto+min-height: 0, so long sub-screens (Bridges, Exchanges) scroll in.setting-stackwithout growing the card. Don't override it.
CSS: swap.css § .ui-settings inner state machine — search for .ui-settings > [data-settings-content].
Markup: playground.html — search for data-state-content="settings".
JS: swap.js — initSettings(card) (outer transition + prev-state restore) and initSettingsSubScreens(card) (drill + sub-back wires).
Token picker .ui-token-picker
The full picker screen inside .ui-card[data-state="picker"]: header, chain shortcuts, search and token lists.
Click a chain tile to filter the list, click the active tile to clear, or click +60 to open the full .card-avatar--more chain picker.
No filter
Send token
Popular
-
ETHEthereum
-
USDCEthereum
-
USDTEthereum
-
DAIEthereum
-
WBTCEthereum
-
ARBArbitrum
-
OPOP Mainnet
All networks is active, so Popular shows tokens from every chain. The body scrolls inside the panel's fixed height.
Arbitrum filter
Send token
Popular
-
ARBArbitrum
-
ETHArbitrum
-
USDCArbitrum
-
USDTArbitrum
-
DAIArbitrum
The Arbitrum tile carries .is-active with the 1 px accent rim, and the list shows Arbitrum tokens only.
<!-- Full token-picker screen -->
<article class="panel ui-card" data-state="picker" data-active-picker="from">
<div data-state-content="picker">
<header class="screen-header">
<button class="screen-header__back btn-icon btn-borderless btn-circle" aria-label="Back">…</button>
<h2 class="screen-header__title">Send token</h2>
<div class="screen-header__trailing"></div>
</header>
<div class="ui-token-picker" data-picker="from">
<header class="ui-token-picker__head">
<!-- Chain shortcuts row — uses #card-avatar -->
<div class="card-avatar-grid">
<button class="card-avatar card-avatar--cluster is-active">…</button>
<button class="card-avatar" data-chain-key="ethereum">…</button>
<!-- first N chains in canonical chains.json order -->
<button class="card-avatar card-avatar--more">+60</button>
</div>
<!-- Canonical search component — see #search -->
<div class="search">
<span class="search-icon">…</span>
<input type="search" class="search-input">
</div>
</header>
<div class="ui-token-picker__body">
<!-- Stack 1+ token-list-module blocks — see #token-list-module -->
<section class="token-list-module" data-list-variant="portfolio" hidden>…</section>
<section class="token-list-module" data-list-variant="popular">…</section>
</div>
</div>
</div>
</article>
Each part has its own catalog card; this card covers how they fit together.
| Region | Class | Catalog | Role |
|---|---|---|---|
| Shell | .ui-card[data-state="picker"] | #ui-card | Widget canvas, one of the card's states (form / picker / chain-picker / quotes / review / activity / tx-details). 416 px via --w-7. |
| Header | .screen-header | #screen-header | Back arrow, title and trailing slot. The title comes from data-title-from / data-title-to, depending on which chip opened the picker. |
| Picker host | .ui-token-picker | This card | Flex column with a pinned head and a scrolling body, so chain shortcuts and search stay put. |
| Chain shortcuts | .card-avatar-grid | #card-avatar | 2-row grid: All networks, the first 8 chains and +N. The active tile carries .is-active. Hidden on the Wide variant, where the sidebar takes over. |
| Search | .search | #search | Filters every visible .token-list-module as you type. |
| Body | .ui-token-picker__body | This card | Owns the scroll. Holds 1–3 modules: Featured (opt-in), Portfolio (with a wallet) and Popular (always). |
| Token modules | .token-list-module | #token-list-module | One per list section, each with a head and a .ui-token-list. |
- Every chip click opens the picker. A
[data-role="from"]or[data-role="to"]chip setsdata-state="picker"directly, with the shortcuts visible. The one exception is the Bridge/Gas To side, where the destination is a chain only: that chip opensdata-state="chain-picker"and the pick is final. - Click a shortcut to filter; click the active one to clear. The filter is stored on the stage as
data-chain-filterand repaints the shortcut grid and every visible.token-list-module. The All-networks tile (.card-avatar--cluster) also clears it. The filter survives back-out, so reopening the picker resumes where the user left off. +Nopens the full chain picker and comes back..card-avatar--moresetsdata-state="chain-picker"withdata-chain-picker-mode="drill". Picking a chain sets the filter and returns to the picker, clearing the drill flag; backing out keeps the existing filter.- The shortcut grid shows in Compact and Dual. Adaptive uses a
.split-panechain-filter rail beside the picker instead, and the grid stays in the DOM withdisplay: none. Single-panel layouts get the grid because they have no room for the sidebar. - Stack token modules in the body, one per section (Featured / Portfolio / Popular), with one continuous scroll rather than nested scroll areas. Portfolio renders only with a connected wallet (otherwise its wrapper has
hidden). Featured is opt-in; its markup is kept but disabled. - Don't render the chain picker inline. It is a sibling state (
data-state="chain-picker"), not a sub-panel, sodata-statealways says which screen the user is on. - Limit mode locks the To-side chain. When the To-side picker is open in Limit, the chain rail shows only the From-side chain. The Sell side is unaffected. See
picker-render.js → getLockedChainKey().
CSS: swap.css → .ui-token-picker (flex column · pinned head · scrolling body · L/R padding compensation for row-hover bleed).
State machine: swap.js → initCard() wires the chip click → setCardState(card, 'picker') transition. The [data-chain-shortcuts] click delegation lives there too; initChainPicker() handles the drill commit + cancel paths.
List rendering: picker-render.js → renderChainShortcuts(stage) rebuilds the grid against chains.json; renderAll() repaints the token-list modules against the active filter; setChainFilter(stage, key) writes data-chain-filter and re-renders.
Live consumer: playground.html → [data-state-content="picker"], a sibling of [data-state-content="form"].
Split pane .split-pane
A card that slides in beside a main container. It holds the picker's chain filter and future route detail panels.
<aside class="split-pane is-open">
<header class="split-pane__header">
<h3 class="split-pane__title">Networks</h3>
</header>
<div class="split-pane__body">…</div>
</aside>
- Adaptive layout only. It sits as a sibling of the main container. Compact has no drawer or bottom-sheet version yet.
- Hidden by default. Show it with
.is-open, a parent state class, or a:has()selector on the host (e.g..widget-stage:has(.ui-card[data-state="picker"])). - 320 px wide by default. Override with an inline style or a modifier class.
- Also usable on marketing pages that need a card beside a main container.
Chain selection panel .split-pane--chain-filter
The token picker's network filter in two compositions: a compact mini sidebar (Adaptive) and a balanced regular panel (Dual).
One node, two sizes, switched by layout in picker-render.js → applyChainPanelComposition(). Both filter the same way; only the scale (search, rows, avatars) and the header differ. These demos are static; live rows are rendered by JS.
Mini, Adaptive sidebar
320 px (--w-4) · .search--sm (32 px) · default-tier rows w/ .avatar--sm (32 px) · no header
Regular, Dual receive column
416 px (--w-7, matches the picker) · .search (40 px) · .list-item--lg rows w/ default .avatar (40 px) · 64 px row · directional "From network" / "To network" header (40 px)
Mini is the base node. Regular adds --regular, a title-only header, the default .search and .list-item--lg rows:
<!-- Regular composition (Dual Swap/Bridge receive column) -->
<aside class="panel split-pane split-pane--chain-filter split-pane--chain-filter--regular">
<!-- Header shown only in --regular (CSS-gated); balances the picker -->
<header class="screen-header">
<h2 class="screen-header__title" data-title-from="From network" data-title-to="To network">From network</h2>
</header>
<div class="search">…</div> <!-- mini uses .search--sm -->
<section class="chain-list-module">
<div class="ui-chain-list list" role="listbox" data-chain-list>
<!-- renderChainList() emits the row scale for the modifier -->
</div>
</section>
</aside>
The playground authors the node once as mini. applyChainPanelComposition() toggles --regular and the search tier from body[data-layout]; renderChainList() reads the modifier for the row scale and calls syncChainPanelTitle() to set the header to the open picker side ("From network" / "To network", matching "Send token" / "Receive token").
| Axis | Mini .split-pane--chain-filter | Regular .split-pane--chain-filter--regular |
|---|---|---|
| Layout | Adaptive, sidebar beside the form | Dual Swap/Bridge, the Receive column |
| Width | 320 px (--w-4) | 416 px (--w-7), as the picker |
| Search | .search--sm · 32 px | .search · 40 px |
| Rows | .list-item-interactive · 48 px | .list-item--lg · 64 px |
| Avatar | .avatar--sm · 32 px | .avatar (default) · 40 px |
| All-networks cluster | 24 px | 40 px |
| Header | none | .screen-header "From network" / "To network" · 40 px |
| Part | Class | Role |
|---|---|---|
| Panel | .panel.split-pane.split-pane--chain-filter | .panel surface + flex column; the --regular modifier upsizes the composition. |
| Header (regular only) | .screen-header > .screen-header__title | Title only, centred. Directional ("From network" / "To network" via syncChainPanelTitle()). Shown only with --regular. |
| Search | .search / .search--sm | Default in regular, --sm in mini, set by applyChainPanelComposition(). |
| Chain list | .chain-list-module > .ui-chain-list[data-chain-list] | Scroll host; rows rendered by renderChainList() at the modifier's scale. |
| Chain row | .list-item--interactive (+ --lg in regular) | Carries data-chain-key; is-selected marks the active filter. |
| All-networks row | .list-item [data-chain-all] + .list-item-all__multi | Clears the filter; the 2×2 avatar cluster sizes to the row's avatar (24 px mini / 40 px regular). |
- One node, switched by layout.
applyChainPanelComposition()(inpicker-render.js) readsbody[data-layout](dualgives regular, anything else mini) and toggles--regularand the search tier. It runs on init and from abody[data-layout]observer, so a layout switch rescales the panel. - Regular matches the token picker beside it: 416 px width, 40 px header row, 64 px rows, 40 px avatars, default search, and a directional title set by
syncChainPanelTitle(). Dual's persistent column has room for this; the Adaptive sidebar doesn't. - Mini is the Adaptive sidebar: a 320 px rail beside the form with
.search--sm, default-tier rows with.avatar--smand no header. - One render path.
renderChainList()reads--regularto choose lg rows with default avatars or default-tier rows with.avatar--sm. Don't fork the row markup. - Both filter the same way. Click a network to narrow the list; click the active one or All networks to clear. The Limit chain lock and wallet-ecosystem scope work the same in both.
- Where each appears: mini in Adaptive (Simple tier); regular in Dual Swap/Bridge (Advanced tier), in the Receive column while picking a token. Compact uses the in-picker shortcut grid instead, and Dual + Limit hides the panel because Limit is single-chain.
- CSS:
styles.css(.split-panebase) +swap.css(search"Chain-filter panel — the two documented compositions"for the mini/regular deltas;"Dual + Swap/Bridge — chain picker takes the Receive column"for the reposition). - JS:
picker-render.js → applyChainPanelComposition()(the composition switch) +renderChainList()(variant-aware row scale) +syncChainPanelTitle()(directional header → active picker side) +initChainDelegation()(filter clicks). - Markup:
playground.html→ the.split-pane--chain-filternode (with the directional From/To-network header). - Spec:
design/components/swap.md → Layout variants(the mini-vs-regular table + the Dual token-picking note).
Quotes
Limit price card .ui-limit-price-card
The Limit-mode price: a “When BASE is worth” label, invert chip, price input and presets. Past 10 % an off-market alert shows.
Default
Zero state
No token picked yet (the playground cold load). As with .ui-amount-card--zero, the price dims to --text-faint at the same weight, the label becomes “Limit price”, and the invert and preset chips hide because there is no market rate. The card stays for context.
<!-- Limit-mode price slot; symbols mirror the Sell / Buy tokens -->
<div class="ui-limit-price-card" data-denom="quote-per-base">
<div class="ui-limit-price-card__lead">
<!-- --dynamic: live sentence; --zero: static "Limit price" -->
<span class="ui-limit-price-card__label ui-limit-price-card__label--dynamic">When <span data-limit-ref="lead-symbol">USDC</span> is worth</span>
<span class="ui-limit-price-card__label ui-limit-price-card__label--zero">Limit price</span>
<button class="ui-limit-price-card__invert chip chip-neutral">
<span data-limit-ref="main-symbol">ETH</span>
<svg class="chip-icon">…</svg>
</button>
</div>
<div class="ui-limit-price-card__main">
<input type="text" class="ui-limit-price-card__amount" inputmode="decimal" value="0.000449">
</div>
<div class="ui-limit-price-card__chips" role="group">
<!-- paintActiveChip() sets .is-active on the matching chip -->
<button type="button" class="chip chip-neutral is-active" data-limit-preset="market">Market</button>
<!-- +1%, +5% -->
<!-- Custom composes .chip-edit; swap.css fixes its width and tint -->
<span class="chip chip-edit chip-neutral" data-chip-edit data-limit-proximity>
<button type="button" class="chip-edit__label" data-chip-edit-label>Custom</button>
<span class="chip-edit__field" hidden data-chip-edit-field>
<input class="chip-edit__input" value="+0.0" data-chip-edit-input data-limit-proximity-input>
<span class="chip-edit__suffix">%</span>
</span>
</span>
</div>
</div>
Same card family as .ui-amount-card. Each slot default matches the corresponding --amount-card-* token, so this card and the .ui-amount-pair below look like one family. Override a slot per instance with inline style. When a property changes on either, change the other in the same edit.
| Slot | Default | Notes |
|---|---|---|
--limit-price-card-bg | var(--surface-card) | Follows light / dark. |
--limit-price-card-radius | 16px | Matches .ui-amount-card. |
--limit-price-card-padding-y | var(--space-16) | Vertical padding inside the card. |
--limit-price-card-padding-x | var(--space-20) | Horizontal padding inside the card. |
--limit-price-card-gap | var(--space-12) · 12px | Gap between the lead, main, chip and proximity rows. Matches --amount-card-gap. |
--limit-price-card-shadow | var(--elev-1) | Resting-card tier. |
--limit-price-card-lead-size | var(--text-sm) · 14px | Matches .ui-amount-card__label. |
--limit-price-card-lead-weight | var(--fw-semibold) · 600 | |
--limit-price-card-lead-color | var(--text-primary) | Primary ink, like "Sell" / "Buy" below. |
--limit-price-card-amount-size | 36px | Matches .ui-amount-card__amount. |
--limit-price-card-amount-weight | 700 | |
--limit-price-card-amount-tracking | -0.02em | Display-tier negative tracking. |
--limit-price-card-amount-lh | 1.1 | Unitless, tight for the 36px size. |
| Sub-part | Class | Role |
|---|---|---|
| Root | .ui-limit-price-card | Card surface; carries data-denom (quote-per-base or base-per-quote). |
| Lead row | .ui-limit-price-card__lead | Label on the left, invert chip on the right, with align-items: baseline so their text shares a baseline. |
| Label | .ui-limit-price-card__label | Matches .ui-amount-card__label (14 / 600 / primary). Two spans: --dynamic (the live sentence) and --zero (the static "Limit price"); the --zero state picks which shows, in CSS. |
| Lead symbol | [data-limit-ref="lead-symbol"] | Span in the --dynamic label; paintLabel() writes the lead token's symbol on token or denom changes. |
| Invert chip | .ui-limit-price-card__invert | Flips data-denom and inverts the value (1/v). A default .chip.chip-neutral (24 px, 12 px text) pushed right with margin-left: auto; its text shows the QUOTE symbol and its trailing icon is the invert action. |
| Main symbol | [data-limit-ref="main-symbol"] | Span in the invert chip; paintLabel() writes the QUOTE symbol (BASE when data-denom="base-per-quote"). |
| Chip icon | .chip-icon | Trailing 12 × 12 invert-arrows glyph; tone from currentColor. |
| Main row | .ui-limit-price-card__main | The price input alone, full width. |
| Amount input | .ui-limit-price-card__amount | 36px / 700 / tabular-nums, matching .ui-amount-card__amount. |
| Chip row | .ui-limit-price-card__chips | Four equal .chip-neutral chips, always visible: Market, +1%, +5%, Custom. paintActiveChip() sets .is-active on the one matching the displayed percent, which takes the .chip-accent1 fill (10–12 % background, accent ink, no outline). |
| Custom chip | [data-limit-proximity] | Composes .chip-edit. Clicking "Custom" shows a +N % input filled with the current percent; typing updates the price via applyProximityInput(), and blur snaps back to the live percent. Overrides in swap.css fix the input at 5 ch and drop the chip-edit focus tint, so the chip matches its siblings. |
- Same card family as
.ui-amount-card, as a sibling, not a modifier. Surface (--surface-card), shadow (--elev-1), radius (16 px), padding (16 / 20), gap (12), label type (14 / 600 / primary) and amount type (36 / 700 / -0.02em) all match the amount card's defaults. The amount weight is shared by.ui-amount-card,.ui-limit-price-cardand.ui-token-info; each has a--*-amount-weight/--token-info-price-weightslot for one-off overrides. When a property changes on one, change the other two in the same edit. A modifier of the amount card was rejected because the layouts differ (lead / amount / presets / proximity vs. header / body / footer). - Shown only in Limit mode, through
.ui-card[data-mode="limit"] .ui-limit-price-card. The markup stays in the DOM so token sync and proximity updates keep running while it is hidden. - Limit is single-chain: Buy follows Sell. The limit engine can't settle cross-chain yet. When the Buy picker opens, the chain-filter sidebar hides (
.widget-stage:has(.ui-card[data-mode="limit"][data-active-picker="to"]) .split-pane--chain-filter { display: none; }) and the Portfolio and Popular lists scope to Sell's chain, with chain badges on every row. On entering Limit, and on every Sell-chain change,swap.js → snapToFollowFromInLimit()moves Buy to Sell's chain and keeps the Buy symbol ifLifiPickerData.findToken()finds it there; otherwise it takes the chain's alphabetically first token, as the Popular list sorts. Buy never moves Sell. The constraint lifts when the engine supports cross-chain (design/components/swap.md → Single-chain constraint (Limit mode only)). - The label symbols mirror the amount-pair tokens; they are not pickers. Base and quote come from
[data-role="from"]/[data-role="to"]on the amount cards. swap.js's MutationObservers sync them ondata-symbol/data-chainchanges; the card has no observer of its own. - A token change resets the price to market. The observer calls
LifiLimitPriceCard.handleTokenChange(), which repaints labels and chips likerenderAll()and runsapplyPreset(card, 'market'). Otherwise the old pair's rate (2253.4807 for ETH/USDC) would carry into the new pair (ETH/USDT) andrenderProximity()would select Custom with a stale offset. It is skipped while the price input or the Custom input has focus. A preset offset such as +5% resets too, because the market itself changed. - The invert chip sits in the lead row, baseline-aligned with the label. It is a
.chip.chip-neutralthat shows the QUOTE symbol and carries the invert action. Its 24 px tier matches the row'smin-height: var(--space-24), andalign-items: baselinelines its text up with the 14 px label. - The label matches
.ui-amount-card__label(14 px / 600 / primary), so it reads with "Sell" / "Buy" below as one label family. The symbol is written inline in the label text. - Presets are relative to market, not to the current value. +5% sets
marketRate * 1.05, so clicking it twice still gives +5%. The market reference flips withdata-denom, so the percent applies to whichever ratio is shown. - Presets, invert and the Custom input all move the chart's Limit line.
watchLimitPrice()intradingview-chart.jslistens for'input'on the price field (debounced 150 ms). Typing fires it, but setting<input>.valuein code does not, soapplyPreset(),invert()andapplyProximityInput()write throughwritePriceValue(), which dispatches the event. Without it the field would change but the chart line would not. - Four equal chips, always visible. Market, +1%, +5% and Custom share
.chip-neutralat rest;paintActiveChip()sets.is-active(the.chip-accent1fill, no outline) on the match. Bands:|x| < 0.5 → Market,0.5 ≤ x ≤ 1.5 → +1%,4 ≤ x ≤ 6 → +5%, anything else (including negatives outside the Market band) → Custom. The bands absorb the ~0.05 % rounding fromtoFixed(). Put.is-activeon the initial chip (usually Market) in the markup so the first paint matches. - Custom composes
.chip-edit. Clicking it shows a+N %input;applyProximityInput()applies the percent to the price, and Enter or blur closes the field.syncCustomChipLabel()then shows the committed value (e.g.+7.5%) as the label, and re-clicking opens the input with that value. When another chip is active, the label returns to "Custom". Two overrides inswap.csskeep it the same size and tone as its siblings:field-sizing: fixed; width: 5 chon the input, and no chip-edit focus tint (chip-neutralat rest, accent fill when.is-active). The off-market alert below carries the warning at|distance| ≥ 10 %. - The market rate comes from
LifiWalletSim.getPriceUsd(symbol), notLifiQuoteSim.getQuote(). AtfromAmount = 1gas (~$8) swamps the quote and zeroestoAmount; the proximity check needs the spot price. - The off-market alert is a separate primitive. At the danger tier,
ui-limit-price-card.jsremoves[hidden]from a sibling.ui-limit-off-marketholding an.alert--warn. The chip is the control; the alert carries the warning text. - Zero state:
.ui-limit-price-card--zerowhile either token is a placeholder.ui-limit-price-card.js → renderZeroState()applies it, like.ui-amount-card--zero. The price shows a faint0in--text-faintwith weight, size, tracking and line height unchanged; the label becomes "Limit price" at full--text-primary; and the invert and preset chips hide, since both need a market rate. The card stays in the DOM for context.init()must not seed a market price without tokens, or the card shows a made-up "When ETH is worth 2227" fromMARKET_DEFAULT. Once both tokens are picked,handleTokenChange()removes--zero, repaints and snaps to the market rate.
swap.css:.ui-limit-price-cardrules (search the section comment "limit-mode price slot").ui-limit-price-card.js: controller. Public API:init,render,renderAll,invert,applyPreset,renderProximity,getMarketRateonwindow.LifiLimitPriceCard.swap.js:initExchangeModeTabs()callsrenderAll()on mode change; both MutationObservers firerenderAll()when the amount-pair's tokens change.playground.html: the live markup inside the.ui-cardshell, between the screen-header and the.ui-amount-pair.design/components/swap.md: written spec for the primitive's surface recipe + denomination semantics.
Related primitives: .ui-card (widget shell), .ui-amount-pair (Send / Receive composition), .ui-amount-card (sub-card primitive that shares the surface recipe), .chip-avatar (read-only mirrors of the base / quote tokens), .chip (percent-preset chips + proximity readout).
Quote card .ui-quote-card
One route in the list. Collapsed it shows the amount and provider; the chevron expands the fee breakdown.
Route comparison
Route
- Network cost
- $7.22
- Provider fee
- $0.04
- Price impact
- -7.27%
- Max. slippage
- 0.30%
- Min. received
- 0.041028 ETH
Private mode
Route
- Network cost
- $2.87
- Bridge fee
- $2.55
- Price impact
- -0.49%
- Max. slippage
- 0.30%
- Min. received
- 1,117.87 USDC
Private mode shows one Houdini route as a compact inline card after the receiving wallet, and tagDisplay()’s private branch swaps “Best return” for the shield “Private” chip. Shown expanded: unlike the Compact inline teaser, this card keeps its chevron and expands in place.
<article class="ui-quote-card is-active is-expanded" data-route-id="route-1inch-…">
<header class="ui-quote-card__header">
<span class="chip chip-accent1">Best return</span>
</header>
<div class="ui-quote-card__body">
<!-- Same destination tandem on every card (#avatar-tandem) -->
<span class="avatar-tandem">
<img class="avatar avatar--circle" src="avatars/tokens/eth.svg" alt="" />
<img class="avatar-badge avatar-badge--br" src="avatars/chains/ethereum.svg" alt="" />
</span>
<div class="ui-quote-card__amount">
<span class="ui-quote-card__amount-value">0.041151</span>
<span class="ui-quote-card__meta">…</span>
</div>
<button class="btn-icon btn-neutral btn-circle btn-xs" data-action="quote-toggle">…</button>
</div>
<div class="ui-quote-card__detail">
<div class="ui-quote-detail-table">…</div>
</div>
<footer class="ui-quote-card__footer">…</footer>
</article>
State recipe
Same states as .theme-card and .ui-amount-card.
| State | Background | Border | Elevation |
|---|---|---|---|
| Rest | var(--surface-card) | 1px solid transparent | var(--elev-1) |
| Hover | color-mix(--accent-primary 3%, --surface-card) | unchanged | var(--elev-2) |
.is-active / :active | color-mix(--accent-primary 4%, --surface-card) | 1px solid color-mix(--accent-primary 64%, transparent) | var(--elev-2) |
Dimensions
| Property | Token / Value | Resolved |
|---|---|---|
| Padding (Y / X) | var(--space-16) var(--space-20) | 16 / 20 px |
| Border radius | var(--space-16) | 16 px |
| Card-to-card gap | var(--card-gap) defaults to var(--gap-card-md) | 12 px |
| Avatar slot | .avatar-tandem (default --avatar-size: 40px) | 40 × 40 px (token); 16 × 16 px (chain badge, 40 %) |
| Amount value | var(--text-h3) · var(--fw-bold) · var(--tracking-snug) · tabular-nums | 24 px / 700 |
| Tag pill | 11px · var(--fw-semibold) | 11 px / 600 |
| Transition | background / border-color / box-shadow 0.18s ease | — |
| Region | Class | Purpose |
|---|---|---|
| Container | .ui-quote-card | Outer card shell. .is-active moves the accent ring; .is-expanded reveals __detail. |
| Header | .ui-quote-card__header | Badge row. Rendered when the route earns “Best return” or “Fastest”, carries SAFEST, or uses Private mode. With no badge, the header is omitted; the provider name lives in __meta-provider. |
| Tag pill | .chip + .chip-accent1 / .chip-neutral | Chip primitive: .chip-accent1 for “Best return”, .chip-neutral for “Fastest” / “Safest”. A route that wins both Best return and Fastest shows both chips. In Private mode the chip is shield (icons/shield.svg in .chip-icon) + “Private” on .chip-accent1, and it replaces all route badges. Providers appear only in __meta-provider. |
| Body | .ui-quote-card__body | Flex row: avatar · amount + meta · chevron toggle. |
| Avatar slot | .avatar-tandem | Tandem at 40 × 40 (chain badge 16 × 16). Token <img class="avatar avatar--circle"> from toTok.logoURI (avatars/tokens/{symbol}.svg); chain badge <img class="avatar-badge avatar-badge--br"> via chainIdToAssetKey(toTok.chainId) (avatars/chains/{slug}.svg). Every card shows the same destination, so the list reads as different rates for one destination. |
| Amount value | .ui-quote-card__amount-value | Headline token amount; tabular-nums for cross-card alignment. |
| Meta line | .ui-quote-card__meta | Fiat · price impact · provider. Separators via __meta-dot; tiny provider logo via __meta-provider-icon (background-image set on render). |
| Expand toggle | .btn-icon.btn-neutral.btn-circle.btn-xs + data-action="quote-toggle" | 24 × 24 icon-only button (12 px chevron, .btn-neutral tint) with no per-component class and no lift on hover. Click toggles .is-expanded; aria-expanded and aria-label follow. The chevron turns 180° under aria-expanded="true" through a scoped rotate: rule in swap.css, not transform, so it stays independent of the button's own transform. In a list the toggle is delegated on .ui-quote-list. The Compact inline teaser drops the chevron; the Private inline keeps it, handled by ui-quote-list.js → attachInlineToggleDelegate() on the .ui-quote-inline wrapper. |
| Detail slot | .ui-quote-card__detail | Hidden until .is-expanded. Holds .ui-quote-detail-table; route-step or route-track views can use the same slot. Expanding animates grid-template-rows: 0fr → 1fr with margin-top, padding-top and border-top-color transitioning together, with no JS height measurement. A per-row stagger fades up children matching .detail-list__row or .ui-quote-card__detail-row in :nth-child sequence (capped at 12; tuning tokens --detail-open-duration / --detail-row-duration / --detail-stagger-step / --detail-stagger-base). See Rules for adding detail content. |
| Footer | .ui-quote-card__footer | Always visible. Rate · gas · time across three cells. |
- Canonical UI card recipe. Rest:
--surface-card, 1 px transparent border,--elev-1. Hover: 3% accent tint and--elev-2..is-active: 4% accent tint, a 1 px rim atcolor-mix(--accent-primary 64%, transparent)and--elev-2. The transparent border reserves the rim's space, so selecting causes no layout shift. - Every card is selectable, and
.is-activeis the only selection class. Clicking a card body moves.is-activeto it, andui-quote-list.jskeeps one selected. On first render the top card is selected: most tokens under Best Return, shortest time under Fastest. - The chevron expands; the body selects. The chevron toggles
.is-expandedon its own card, and several cards can be open at once. Its handler callse.stopPropagation()so expanding doesn't also select. - Cards start collapsed, except a lone quote. With several quotes, all start collapsed so users can scan the rates. With exactly one, it starts expanded, since there is nothing to choose. This matches the production LI.FI widget. See
ui-quote-list.js → applyInitialExpansion()(cards.length === 1). - Route badges. “Best return” (
.chip-accent1) marks the most tokens received (highesttoAmount); “Fastest” (.chip-neutral) the shortest total time (summedexecutionDuration). The renderer computes both itself, becauseRECOMMENDEDblends output and speed and could mark a route with fewer tokens as Best return. A route that wins both shows both chips.SAFESTmaps to “Safest” (.chip-neutral). With no badge the header is omitted and the provider stays in__meta-provider. Route priority sets the order: Best Return requestsCHEAPESTand lists most tokens first; Fastest requestsFASTESTand lists shortest time first. Priority doesn't change which routes earn badges. - Private mode replaces the badges with a shield “Private” chip. In
body[data-widget-mode="private"],tagDisplay()returns{ text: "Private", best: true, kind: "private" }before reading the route’s SDK tags, so the single Houdini route shows shield + “Private” on.chip-accent1. The chip names what the route is (private), not a ranking.slotHeaderTag()adds the.chip-iconshield (icons/shield.svg) only forkind === "private". The card renders inline in the form (see Widget modes), and unlike the Compact teaser it keeps its chevron and expands in place, the only way to see the details. See Inline quote preview. - Badges stay put when the selection moves. Badges show what each route wins; the accent ring shows the user's pick. They are independent.
- The detail slot takes other content. Today it holds
.ui-quote-detail-table; route summaries, steps or tracks can go in the same slot without changing the card. - Three rules for new detail content. (1) Wrap it in exactly ONE direct child of
.ui-quote-card__detail: thegrid-template-rows: 0fr → 1frtrick sizes one row track, and extra children land in implicit rows that don't transition. (2) Don't putmargin-top/padding-top/border-topon that wrapper; the container owns the chrome. (3) To join the row stagger, use.detail-list__row(preferred) or.ui-quote-card__detail-rowfor custom rows, as siblings inside one row container, since:nth-childcounts against the direct parent. The cascade covers 12 rows; later rows share the 11th delay. - Tokens set the reveal timing:
--detail-open-duration(container, 280 ms),--detail-row-duration(per-row fade-up, 220 ms),--detail-stagger-step(between rows, 30 ms) and--detail-stagger-base(before row 1, 60 ms). Override them at:root,.ui-quote-cardor.ui-quote-card__detailrather than editing the:nth-childcascade.prefers-reduced-motion: reducemakes the toggle instant. - Collapse clips; it doesn't reverse the stagger. Removing
.is-expandedcloses the container andoverflow: hiddentrims the rows. If a variant needs a reverse stagger, key it to a different state class. - The footer is always visible: rate · gas (USD) · ETA, below the detail table when expanded.
- Data: simulator → renderer → card.
LifiQuoteSim.getRoutes()returns aRoutesResponsein the@lifi/sdkRouteshape.ui-quote-list.jsrebuilds the list on every input change (debounced 200 ms). The token avatar comes fromtoTok.logoURI(set inbuildTokenShape()), the chain badge fromchainIdToAssetKey(toTok.chainId)(avatars/chains/{key}.svg), and tool names and logos from thedata/tools.jsonfixture. Switching to the real API is a one-line change insidegetRoutes(). - The avatar shows the destination, not the provider. The provider name and logo live in the meta line (
__meta-provider). The same destination token and chain on every card makes the list read as a choice of rate, not of exchange. - When to show skeletons.
ui-quote-list.js → renderList(listEl, opts)stamps 3 skeleton cards (.ui-quote-card.is-skeletonwith.skeletonatoms) when the list is empty (first render, or after the empty state) or whenopts.forceSkeleton === true, a deliberate refresh such as a.refresh-timerclick (refresh-timer:expiredwithdetail.source: "click", forwarded by the playground). Passive refreshes (typing, sim events, timer expiry) keep the previous render, since skeletons every 400–800 ms read as jitter. The list getsaria-busy="true"and each atomaria-hidden="true"; bothdata-stateandaria-busyclear when loading ends. - Pin type on the wrappers.
__metaand__footerset bothfont-size: var(--text-caption)(12 px) andline-height: var(--lh-caption)(16 px); without the line height,__meta-provider-name,__deltaand__footer-rateinheritline-height: normal(about 1.2).__amount-symbolsetsline-height: 1.2to match__amount-value. The card then renders the same in any host. - Price impact uses one formatter and neutral ink everywhere. The meta line, the detail row and the Receive card's footer all call
window.LifiQuoteList.formatPriceImpact(impactPct, userAmount?), which returns{ text }: positive raw impact (value lost) →-X.XX%, negative (a rare gain) →+X.XX%, zero or no quote →0.00%. None of the three applies severity colour today (no.detail-list__desc--warning/--negative, nodata-state="warn"|"error"). The CSS hooks stay dormant inswap.cssandstyles.cssuntil the formatter returns{ text, severity }(design/components/swap.md → Price impact). The opt-inrate-deltameta variant is exempt; its colour is part of the variant. - The quote list doesn't need a wallet. Routes appear once .ui-amount-pair has both tokens and an amount, and clicking a card still selects it and updates the Receive card. Only execution, through the footer CTA, needs a wallet.
- CSS:
swap.css, search.ui-quote-card; the anatomy comment and recipe are at the top of the block. - Renderer:
ui-quote-list.js. Reads picker state from.ui-amount-pair, callsLifiQuoteSim.getRoutes(), rebuilds the list innerHTML on every input change. Owns the delegatedquote-toggle+ selection click handlers. - Simulator:
quote-sim.js. ParametricRoutesResponsegenerator mirroring@lifi/sdkRoute/LiFiStep/Stepfield-for-field. Returns 4–6 routes per call withRECOMMENDED/FASTESTtags assigned across the set. - Tool catalog:
data/tools.json. Captured from/v1/tools; provides every tool'skey,name,logoURI, andsupportedChains. - Live mount:
playground.html, search.ui-quote-list. Lives inside the.widget-stage__receiveaside.
Mini quote card .ui-quote-mini-card
The Limit-mode route picker: a slim sibling of .ui-quote-card with only the provider icon, name and gas cost.
Three routes, first selected
<!-- Roving-tabindex radiogroup; roots are div role="radio" -->
<div class="ui-quote-mini-list" data-limit-only role="radiogroup">
<div class="ui-quote-mini-card is-active" role="radio"
tabindex="0" aria-checked="true" data-route-id="route-1inch">
<span class="ui-quote-mini-card__provider">
<span class="ui-quote-mini-card__provider-icon" style="background-image:url(...)"></span>
<span class="ui-quote-mini-card__provider-name">1inch</span>
</span>
<!-- Metric pill (#ui-quote-metric); fee only in Limit -->
<span class="ui-quote-metric ui-quote-metric--fee">
<span class="tooltip-wrap">
<button class="btn-icon btn-borderless btn-muted btn-xs">…fuel svg…</button>
<span class="tooltip tooltip--multi">Estimated network fee…</span>
</span>
<strong>$7.22</strong>
</span>
</div>
<!-- 1-2 more cards, each with tabindex="-1" aria-checked="false" -->
</div>
| Sub-part | Class | Role |
|---|---|---|
| List | .ui-quote-mini-list | Vertical stack of cards. --card-gap: var(--gap-card-sm) (8 px). One selection, role="radiogroup". |
| Card | .ui-quote-mini-card | One 48 px row using the canonical UI card recipe (--surface-card + --elev-1 at rest; 4 % accent fill, 64 % accent border and --elev-2 on .is-active). The root is <div role="radio" tabindex="0|-1" aria-checked>, not a <button>, because it holds the metric pill's button. Keyboard and roving tabindex: swap.js → initQuoteMiniList(). |
| Provider slot | .ui-quote-mini-card__provider | Icon + name pair. flex: 1 so the metric pill trails at the row's right edge. |
| Provider icon | .ui-quote-mini-card__provider-icon | 20 × 20 circular avatar; inline background image from the LI.FI exchange-icon CDN, as in .ui-quote-card__meta-provider-icon. |
| Provider name | .ui-quote-mini-card__provider-name | Semibold label, single line, ellipsis on overflow. |
| Metric pill | .ui-quote-metric.ui-quote-metric--fee | Trailing gas cost, the shared #ui-quote-metric. Only --fee: all Limit quotes share one execution time, so --eta is left out. |
- Limit mode only. In Swap and Bridge, providers differ on amount, conversion and time, so the full
.ui-quote-cardlist in the Receive panel is the selector. A limit order fills at the user's price, so only provider and gas differ. The mini list sits in the form above the Expires-in row, and the Receive panel shows.ui-token-info+.ui-price-chartinstead (body[data-widget-mode="limit"]). - A sibling primitive, not a modifier. It is one horizontal row with a Limit-only role; a
.ui-quote-card--minimodifier would have to hide about 80% of the parent's slots. - One selection, by mouse or keyboard. One
.is-activeat a time, mirrored byaria-checkedand a rovingtabindex(one tab stop; arrows move and select).swap.js → initQuoteMiniList()handles click, Enter/Space and Arrow / Home / End per the WAI-ARIA radiogroup pattern, and ignores clicks inside.ui-quote-metricso the tooltip button works on its own. - The root is
<div role="radio">, not<button>. Each row holds the metric pill's<button>, and a button inside a button makes the HTML parser close the outer one (CLAUDE.md→ Card root element). Keyboard activation needs the custom handlers in swap.js, and the radio role suits therole="radiogroup"parent.ui-quote-mini-list. - Two or three cards in the form. At
--gap-card-sm(8 px), three cards take about 136 px, roughly one full quote card. Past three, offer a "more routes" link instead. - Shown only when Limit mode and a quote are both ready. It needs (a) Limit mode (
data-limit-onlywith the.ui-card[data-mode="limit"]gate) and (b).widget-stage[data-quotes-state="visible"], set byui-amount-card.js → setQuotesReady()once both tokens are picked, the amount is above 0 and the quote sim returned a result. Otherwise the list is hidden, with no skeleton, since there is nothing to compare. The Receive panel's.ui-token-info+.ui-price-chartis market reference and always shows in Limit; the two gates differ on purpose. - Pin the provider name's type on the primitive.
__provider-namesetsfont-size: var(--text-sm)(14 px) andline-height: var(--lh-sm)(20 px), so it renders the same in every host. Without the line height it inheritsnormal(about 17 px).
Quote metric pill .ui-quote-metric
The shared icon + value route metric, with --fee and --eta tones. Used in .ui-quote-card footers and .ui-quote-mini-card rows.
Gas cost
Estimated network fee, paid in the source chain’s native token. $7.22Execution time
Estimated time from signature to settlement on the destination chain. 11s<!-- Tone picks icon and tooltip; leave out a span to drop a metric -->
<span class="ui-quote-metric ui-quote-metric--fee">
<span class="tooltip-wrap">
<button class="btn-icon btn-borderless btn-muted btn-xs"
aria-describedby="tt-fee-{id}" aria-label="Network fee details">
<svg viewBox="0 0 24 24">…fuel-pump path…</svg>
</button>
<span id="tt-fee-{id}" class="tooltip tooltip--multi" role="tooltip">
Estimated network fee, paid in the source chain’s native token.
</span>
</span>
<strong>$7.22</strong>
</span>
| Sub-part | Class | Role |
|---|---|---|
| Wrapper | .ui-quote-metric | inline-flex, align-items: center, gap: var(--space-4), font-size: var(--text-sm) (14 px), line-height: var(--lh-sm), tabular-nums, flex-shrink: 0. The gap sits on top of the .btn-xs padding (6 px around a 12 px glyph in a 24 px button). The font size is pinned so the pill matches in every host. |
| Tone modifier | .ui-quote-metric--fee | Fuel-pump icon + "Network fee" tooltip body. Gas-cost cell. |
| Tone modifier | .ui-quote-metric--eta | Clock icon + "Estimated time" tooltip body. Execution-duration cell. |
| Tooltip wrapper | .tooltip-wrap | Anchors the popover-API tooltip; sibling of the icon button + value. |
| Icon button | .btn-icon.btn-borderless.btn-muted.btn-xs | Leading 24 px icon button in .btn-muted, so it doesn't compete with the value. Hover or focus shows the tooltip; a click does nothing. |
| Tooltip | .tooltip.tooltip--multi | Multi-line tooltip body (see #tooltip). Uses popover API + JS positioning so it escapes any ancestor overflow: hidden. |
| Value | <strong> | Semibold primary ink, tabular-nums via the wrapper. Formatted as fiat for --fee ($0.28), as duration for --eta (6m / 11s). |
- Drop a metric by leaving out its span, not with a modifier.
.ui-quote-mini-cardomits--etabecause all Limit routes share one execution time. Fee and ETA are optional regions (CLAUDE.md → Composable slots vs variant modifiers); don't add--no-fee/--no-etamodifiers or adata-show-etaattribute. - One primitive for both cards.
.ui-quote-cardfooters (Receive panel, Swap / Bridge) and.ui-quote-mini-cardrows (Limit) render the same.ui-quote-metric: same button, tooltip and type. - Render through
ui-quote-list.js → slotFooterCell(). The big card's cells already do. The mini card is static HTML today; if it moves to JS rendering, reuseslotFooterCell(). - Ask before adding a third metric. Cost and time are the axes every route shares. A
--slippageor--mev-protectiontone may belong in the per-card detail panel instead, so check that it compares across routes first. - The font size is pinned on the wrapper at
var(--text-sm)(14 px). Otherwise the value<strong>inherits each host's size (about 16 px in the catalog). In the mini card it matches the 14 px provider name beside it. - The icon button only triggers the tooltip. Clicking it does nothing. Card click handlers should ignore clicks inside
.ui-quote-metric(seeswap.js → initQuoteMiniList()) so it doesn't also select the row. - A card that hosts the pill can't have a
<button>root. The pill's icon button is a real<button>; inside a button root the parser closes the outer button and the inner one becomes a sibling (CLAUDE.md → Card root element). The mini card uses<div role="radio">, and any new host needs the same.
Inline quote preview .ui-quote-inline
Shows only the selected .ui-quote-card in the form. In Compact it is a teaser that opens the full list; in Private it is the only quote, so it keeps its chevron and expands in place.
Compact
The live .ui-quote-card.is-active without its chevron. Clicking anywhere opens the full route list.
Private
Route
- Network cost
- $2.87
- Bridge fee
- $2.55
- Price impact
- -0.49%
- Max. slippage
- 0.30%
- Min. received
- 1,117.87 USDC
One Houdini route and no drill. The chevron toggles .is-expanded in place (attachInlineToggleDelegate() on the .ui-quote-inline wrapper), and there is no "Show all quotes" button.
<!-- [data-inline-card] is filled by ui-quote-list.js → renderInline() -->
<div class="ui-quote-inline" data-quote-inline>
<div class="ui-quote-inline__card" data-inline-card>
<!-- .ui-quote-card.is-active rendered here (Compact: chevron removed;
Private: chevron kept + expands in place) -->
</div>
<!-- .btn-with-icon appends the trailing → arrow; .btn-block spans full width -->
<button type="button" class="ui-quote-inline__more btn-secondary btn-with-icon btn-block"
data-action="show-quotes">Show all quotes</button>
</div>
| Sub-part | Class | Role |
|---|---|---|
| Wrapper | .ui-quote-inline | Flex column, gap: var(--space-8). Base display: none; revealed only in Narrow + non-Limit + quote-ready + form state (see Rules). The whole wrapper is the drill tap-target. |
| Card host | .ui-quote-inline__card | Holds the active .ui-quote-card from ui-quote-list.js → renderInline(). Compact removes the chevron, since the card opens the full list. Private keeps it (renderInline() checks body[data-widget-mode="private"]), and attachInlineToggleDelegate() on the wrapper, which survives the re-renders, handles the toggle because the list's own delegate can't reach a card outside .ui-quote-list. |
| Show-more | .ui-quote-inline__more | A .btn-secondary.btn-with-icon.btn-block: the trailing → comes from ::after and the button spans the column. Label "Show all quotes"; renderInline() hides it when there is only one route. |
- Shown in Compact and in Private. In Compact (
body[data-layout="compact"]) there is no side panel for routes. In Private (body[data-widget-mode="private"], any layout) the receive panel is hidden because there is one route (see Widget modes). In Adaptive and Dual outside Private, the full.ui-quote-cardlist lives in the Receive aside. Both are gated:not([data-widget-mode="limit"]), so Limit keeps its chart. - It mirrors the selected route. The card is the route with
.is-activein.ui-quote-list.renderInline()runs fromnotifySubscribers(), so it follows both data refreshes and selection; in Private it keeps the user's.is-expandedacross re-renders. Compact changes selection only in the drill, and Private has one route, so neither can drift. - One list, moved between places. The full list is one DOM node that moves between the Receive aside (Wide) and the form's
quotesdrill (Narrow) on a layout switch (swap.js → initRailLayoutPanel). Its handlers and selection move with it, sogetReviewModel()stays correct. - Show-more opens the drill; back returns. Clicking the wrapper sets the form card to
data-state="quotes"(full list,Routesheader), and back returns toform. Picking a route there moves.is-active, re-renders the inline card and updates the Receive amount. - Chevron: removed in Compact, kept in Private. Compact removes
[data-action="quote-toggle"]inrenderInline()(not with CSS), because the whole card opens the list. Private has no drill, so the chevron stays and expands in place;attachInlineToggleDelegate()handles it and stops propagation so the click never reaches the Compact drill handler. "Show all quotes" hides with a single route, so Private never shows it. - Scrolling at capped heights is expected. At Auto height the form grows and the preview sits above the action footer. At a capped height (Compact / Standard) the form stack scrolls, as it does for Limit, with show-more at the bottom.
- Markup:
playground.html, searchdata-quote-inline(form state) +data-quotes-drill-host(thequotesdrill). - CSS:
swap.css, searchCompact layout variantfor the single-column rules +.ui-quote-inlinegating. - Render:
ui-quote-list.js → renderInline()(projects the active route; called fromnotifySubscribers). - Navigation + relocation:
swap.js → initCompactQuotes()(drill / back) andinitRailLayoutPanel → relocateQuoteList()(list move on variant switch).
Receive panel .ui-receive-panel
The receive-column frame: a Receive header above the route list (.ui-quote-list) in Swap / Bridge / Gas, or the market chart in Limit.
Swap / Bridge / Gas
Receive
Route
- Network cost
- $7.22
- Provider fee
- $0.04
- Price impact
- -7.27%
- Max. slippage
- 0.30%
- Min. received
- 0.041028 ETH
In Swap, Bridge and Gas the body is the .ui-quote-list under a “Receive” screen-header--main with the .refresh-timer. In Limit the same frame holds .ui-token-info + .ui-price-chart; in Dual with no amount, the routes-idle .empty-state.
<!-- Composition marker over .panel.ui-card, in .widget-stage__receive -->
<aside class="widget-stage__receive" aria-label="Available routes">
<article class="panel ui-card ui-receive-panel">
<header class="screen-header screen-header--main">
<h2 class="screen-header__title">Receive</h2>
<div class="screen-header__trailing">
<!-- refresh-timer — Swap / Bridge / Gas (countdown → refresh) -->
<button class="btn-icon btn-borderless btn-circle refresh-timer" data-interval="60000">…</button>
<!-- chart-token-tabs — Limit OR Dual, once both tokens are picked -->
<div class="seg seg-sm seg--borderless chart-token-tabs" data-chart-token-tabs>…</div>
<!-- expand-panel — Limit only (paired maximize) -->
<button class="btn-icon btn-neutral btn-sm btn-circle" data-action="expand-panel">…</button>
</div>
</header>
<!-- BODY (mode-gated slot, exactly one shows) -->
<!-- 1 · Limit — market reference (always renders in Limit) -->
<div data-limit-receive>
<div class="ui-token-info">…</div>
<div class="ui-price-chart">…</div>
</div>
<!-- 2 · Dual, no amount yet — honest idle state -->
<div class="empty-state" data-routes-idle>…</div>
<!-- 3 · Swap / Bridge / Gas (+ Dual with amount): renderList() fills this -->
<div class="ui-quote-list"></div>
</article>
</aside>
| Property | Value | Source |
|---|---|---|
| Own CSS | None, a composition marker | Only names the frame for docs and JS. The look comes from .panel.ui-card. |
| Surface | var(--surface-card) · var(--elev-1) | Inherits from .ui-card |
| Border radius | var(--card-radius) · 16 px | Inherits from .ui-card |
| Padding | var(--panel-padding) · 24 px | Inherits from .panel |
| Host + width | .widget-stage__receive aside · var(--w-7) 416 px (Swap / Bridge / Gas) · var(--w-16) 704 px (Limit + Advanced) | The aside sets the column width per layout; Advanced + Limit widens it for the Orders table below. See Presentation. |
| Header | .screen-header.screen-header--main, title “Receive” | No back button. Same header shape as the Orders panel. |
| Trailing slot (CSS-gated) | .refresh-timer (Swap / Bridge / Gas) · .chart-token-tabs (Limit OR Dual) · expand-panel (Limit) | One .screen-header__trailing; the widget mode decides which control shows. |
| Body slot (mode-gated) | .ui-quote-list (Swap / Bridge / Gas) · [data-limit-receive] → .ui-token-info + .ui-price-chart (Limit) · .empty-state[data-routes-idle] (Dual, no amount) | Exactly one body content renders per widget mode. |
| Quote-list renderer | ui-quote-list.js → renderList() into .ui-quote-list | Rebuilds the list on every input change. The route preview is wallet-optional. |
| Element | Class | Role |
|---|---|---|
| Panel root | .ui-receive-panel | Composes .panel.ui-card. A top-level frame (panel), not an inner card, with no CSS of its own. |
| Host aside | .widget-stage__receive | Sets the width per layout and the Adaptive slide-in. Holds this panel and, in Limit, the Orders panel. |
| Header | .screen-header.screen-header--main | Title (“Receive”) + a .screen-header__trailing. No back affordance. |
| Trailing: refresh | .refresh-timer | Swap / Bridge / Gas. Countdown → click-to-refresh; see .refresh-timer. |
| Trailing: chart tabs | .chart-token-tabs | Limit or Dual, once both tokens are picked. Switches the chart’s token (from / to). |
| Trailing: expand | [data-action="expand-panel"] | Limit only. The paired maximize that widens the column, as on the Orders panel. |
| Body: route list | .ui-quote-list | Swap / Bridge / Gas (and Dual with an amount). Each row is a selectable .ui-quote-card. Carries the #ui-quote-list anchor; ui-quote-list.js renders it. |
| Body: market ref | [data-limit-receive] | Limit. .ui-token-info + .ui-price-chart, shown with or without an amount. |
| Body: idle | .empty-state[data-routes-idle] | Dual, no amount. An .empty-state (“Enter an amount to compare routes”) instead of the chart or fake routes. |
- A composition marker with no CSS.
.ui-receive-panelonly names the frame for docs and JS; every visual property comes from.panel.ui-card. Put styling on.panel/.ui-card(chrome) or on the body primitive (content), never on the marker. - A panel, not a card. A top-level frame takes
-panel; an inner surface takes-card. Its sibling is.ui-orders-panel. SeeCLAUDE.md → Panel vs card. - The frame stays; the body changes by mode: route list (Swap / Bridge / Gas), market chart (Limit), routes-idle empty state (Dual, no amount). Gate the body content on the widget mode rather than forking the frame.
- The trailing controls are gated by mode too.
.refresh-timer(Swap / Bridge / Gas),.chart-token-tabs(Limit or Dual) andexpand-panel(Limit) share one.screen-header__trailing. The preview shows only the refresh timer;playground.htmlswitches them live. - The route list doesn’t need a wallet. Token picks and an amount show quotes; only execution needs a wallet. Don’t gate the list on connection (
CLAUDE.md → Quote preview is wallet-OPTIONAL). - Show it with its body. A bare “Receive” header is half a component, so the preview shows the filled quote list. Document body content on its own cards (quote card, token info, price chart) rather than here.
- Markup:
playground.html, searchui-receive-panel(the live instance inside the.widget-stage__receiveaside, with the.ui-quote-listrender host + the Limit[data-limit-receive]body). - CSS: none of its own. The frame is
.panel+.ui-card(styles.css/swap.css); column width + the slide-in live on.widget-stage__receive(swap.css, searchwidget-stage__receive); the body-content gating is keyed offbody[data-widget-mode](swap.css). - Renderer:
ui-quote-list.js(window.LifiQuoteList) →renderList()populates.ui-quote-list; selection +getReviewModel()travel with the one node. - Body primitives:
.ui-quote-card(route rows),.ui-token-info+.ui-price-chart(Limit market reference),.empty-state(routes-idle). - Naming: see
CLAUDE.md → Panel vs card; the sibling frame is.ui-orders-panel.
Orders
Orders panel .ui-orders-panel
Limit mode, under Market Price: a 9-column table of limit orders that scrolls sideways with the chain column pinned.
Nine columns, chain pinned
Orders
| Chain | Pair | Sell | Buy | Limit | Market | Filled | Expires | |
|---|---|---|---|---|---|---|---|---|
ETHUSDC |
0.800.80 ETH · $1,244 |
1,264.00 |
1,580 |
1,555 |
0% |
6 days |
||
USDCETH |
1,500 |
0.9804 |
1,530 |
1,555 |
37% |
3 days |
||
BTCUSDC |
0.05 |
2,970.00 |
59,400 |
59,319 |
100% |
|||
LINKUSDC |
800 |
6,800.00 |
8.50 |
7.21 |
0% |
Expired |
||
UNIETH |
1,200 |
2.04 |
0.00170 |
0.00154 |
0% |
Cancelled |
Wider than the 640 px card, so the body scrolls sideways (drag or shift-scroll to reach the kebab). The chain mark stays pinned while the pair name and values scroll. Expires also shows the lifecycle: a countdown when active, “Expired” in muted grey, “Cancelled” in --danger, and blank when filled, since Filled already reads 100%. The kebab here is static; the live card opens a real .dropdown menu (see Markup).
<!-- data-disconnected / data-empty hide the card; orders-list.js renders rows -->
<article class="panel ui-card table-panel ui-orders-panel" data-limit-orders>
<header class="screen-header screen-header--main">
<h2 class="screen-header__title">Orders</h2>
</header>
<!-- the reusable .table-scroll primitive: viewport + body + < > nav + pinned col -->
<div class="table-scroll table-scroll--pinned"><div class="table-scroll__body">
<table class="data-table data-table--sm data-table--borderless data-table--rich data-table--orders">
<thead><tr>
<th>Chain</th> <!-- pinned chain mark --> <th>Pair</th> <th class="ta-r">Sell</th>
<th class="ta-r">Buy</th> <th class="ta-r">Limit</th>
<th class="ta-r">Market</th> <th>Filled</th>
<th>Expires</th>
<th aria-label="Row actions"></th>
</tr></thead>
<!-- Render host — orders-list.js fills this; order===null = skeleton path -->
<tbody data-orders-list>
<tr data-order-id="…">
<!-- Chain (pinned): one avatar, chain name in its tooltip -->
<td><div class="data-cell"><span class="tooltip-wrap"><img class="avatar avatar--sm avatar--circle" src="…ethereum.svg" alt="Ethereum" tabindex="0" aria-describedby="tt…"><!-- + .tooltip --></span></div></td>
<td><div class="data-cell"><span class="data-cell-text data-cell-text--bold ui-order-pair-label">ETH<svg class="ui-order-pair-arrow">…arrow-right…</svg> USDC</span></div></td>
<!-- Sell / Buy: the number is the tooltip target (symbol + fiat) -->
<td class="ta-r"><div class="data-cell data-cell--end"><span class="tooltip-wrap"><span class="data-cell-text" tabindex="0" aria-describedby="tt…">0.80</span><!-- + .tooltip --></span></div></td>
<td class="ta-r"><div class="data-cell data-cell--end"><span class="data-cell-text">1,264.00</span></div></td>
<!-- Limit (emphasized) · Market (muted) -->
<td class="ta-r"><div class="data-cell data-cell--end"><span class="data-cell-text data-cell-text--bold">1,580</span></div></td>
<td class="ta-r"><div class="data-cell data-cell--end"><span class="data-cell-text data-cell-text--muted">1,555</span></div></td>
<!-- Filled: the fill % as plain .data-cell-text (no ring) -->
<td><div class="data-cell"><span class="data-cell-text">0%</span></div></td>
<!-- Expires: countdown (active only) · Status: chip + lifecycle tooltip -->
<td><div class="data-cell"><span class="data-cell-text data-cell-text--secondary">6 days</span></div></td>
<td><div class="data-cell"><span class="tooltip-wrap"><span class="chip chip-neutral" tabindex="0">Open</span><!-- + .tooltip --></span></div></td>
<!-- Kebab: a real .dropdown via the Popover API; actions are status-gated -->
<td class="ta-r"><div class="data-cell data-cell--end">
<div class="dropdown">
<button class="btn-icon btn-neutral btn-circle btn-xs" data-dropdown-trigger aria-haspopup="menu" aria-label="Order actions"><svg>…ellipsis…</svg></button>
<div class="dropdown__panel dropdown__panel--align-end" role="menu" popover="manual" data-order-id="…">
<ul class="menu">
<li><button class="menu-item" data-order-action="modify">…Modify limit…</button></li>
<li><button class="menu-item" data-order-action="repeat">…Repeat order…</button></li>
<!-- Destructive action is ALWAYS last -->
<li><button class="menu-item menu-item--danger" data-order-action="cancel">…Cancel order…</button></li>
</ul>
</div>
</div>
</div></td>
</tr>
<!-- N more rows, rendered by orders-list.js -->
</tbody>
</table>
</div></div>
<!-- No empty-state markup: data-disconnected / data-empty hide the card -->
</article>
| Property | Value | Source |
|---|---|---|
| Surface | var(--surface-card) · var(--elev-1) | Inherits from .ui-card |
| Border radius | var(--card-radius) · 16 px | Inherits from .ui-card |
| Padding | var(--panel-padding) · 24 px | Inherits from .panel |
| Body edge bleed | margin-inline: calc(-1 * var(--panel-padding) + var(--space-12)) | Pulls table flush to --sm cell padding so “Pair” header aligns with the screen-header title |
| Columns | 9: Chain · Pair-name · Sell · Buy · Limit · Market · Filled · Expires · kebab | All nine render in the catalog and the body scrolls sideways. In the playground the Market column stays hidden until the panel is expanded (.widget-stage:not([data-expanded]) .ui-orders-panel [data-col="market"]). The identity is the pinned chain mark plus the scrolling pair name. |
| Horizontal scroll | the reusable .table-scroll primitive (.table-scroll--pinned) · table .data-table--orders at width: max-content; min-width: 100% | Wider than the receive column (416 / 736 px), so it scrolls inside .table-scroll with edge fades, < > nav and the pinned chain column. The table sizes to its content so columns keep their nowrap widths. |
| Table tier | .data-table--sm head · rows pinned to var(--space-56) (56 px) | Compact --sm head (--text-caption). Each <td> is locked to the 56 px tier with an integer line height, so rows land on the 4-grid. See CLAUDE.md → Data-table row alignment. |
| Row components | .data-cell · .data-cell-text (+ --bold / --muted / --secondary / --danger) · .ui-order-pair-label | .data-cell centres the content; .data-cell-text is the one text primitive for every value, varying only weight and ink; .ui-order-pair-label adds the arrow gap and nowrap. The Filled cell is plain .data-cell-text too. |
| Row value typography | --data-cell-text-size | Every cell value uses .data-cell-text at this one token (--text-body 16px) with line-height:1 and tabular-nums; ink and two emphasis weights (pair and Limit at 600) vary per column. The whole row centres on one line. |
| Table chrome | .data-table--borderless | Drops row borders; thead divider is a box-shadow inset (zero layout height) so the header stays an exact 32 px on the 4-grid |
| Sticky header surface | thead th { position: sticky; background: var(--surface-raised) } | The header stays while rows scroll, so it needs an opaque background matching the card. The card is .panel → --surface-raised, not --surface-card, which painted a white band in light mode. |
| Split: Stacked / fill (default) | body[data-limit-panel-split="fill"] | The default (fill is set on the playground <body>). The widget (form + view rail) sticks with position: sticky; Market Price is a capped band (min-height: 440px · max-height: min(var(--widget-max-h), 560px)); Orders takes its natural height (flex: 0 0 auto) and the page scrolls, so the form stays in view on short screens. |
| Split: ratio (opt-in) | chart flex: 2 1 0 · Orders flex: 1 1 0 | 2/3 chart, 1/3 Orders in the capped receive column; Orders scrolls inside its share (sticky thead). Opt-in: no [data-limit-panel-split] attribute (the CSS base). |
| Paired maximize | .widget-stage[data-expanded] .widget-stage__receive { flex-basis: … } | An expand-panel control in both the Market Price and Orders headers toggles data-expanded, widening the receive column to the canvas. Both cards grow sideways together and the 2/3 · 1/3 split is kept. |
| Visibility gate | body[data-widget-mode="limit"] | Outside Limit the article is display: none but stays in the markup. The catalog forces it visible with an inline style. |
| Body-state hide | [data-disconnected="true"] · [data-empty="true"] → display: none | Either flag hides the card. The orders wiring IIFE in playground.html sets data-disconnected when the wallet is disconnected; orders-list.js sets data-empty when getOrders() is empty. The card shows only when connected and with orders, an exception to the wallet-scoped rule (CLAUDE.md → Wallet-scoped surfaces gate their empty-state on connection). |
| Receive panel width (Limit + Advanced) | var(--w-16) · 704 px | Widened from var(--w-7) (416 px) so more of the table shows before it scrolls (Presentation · design/components/swap.md → Advanced widget tier) |
| Renderer | orders-list.js → renderRow(order) | Single-source slot dispatch (one helper per column); order === null is the skeleton path. Reads window.LifiOrders; re-paints on persona-change. |
| Data source | window.LifiOrders (translator) | Pivots window.LifiTransactions (type === 'limit', by persona) into rows; tx.limit carries market / distancePct / filled / state, and orders-data.js derives the expires text. See CLAUDE.md → Unified transactions data layer. |
| Element | Class | Role |
|---|---|---|
| Panel root | .ui-orders-panel | Composes .panel.ui-card. A top-level frame, not an inner card. Carries the body-state visibility gate. |
| Header | .screen-header.screen-header--main | Title “Orders” and a .screen-header__trailing with the paired expand-panel. No back button. Same as the Market Price header. |
| Scroll viewport | .table-scroll | The .table-scroll primitive (styles.css): a positioned host with edge fades and < > nav. The orders panel adds the edge-to-edge margin-inline and the --surface-raised surface. |
| Table scroller | .table-scroll__body | The overflow-x: auto scroller wrapping .data-table.data-table--orders; the avatar column (col 1) pins via .table-scroll--pinned while the rest scrolls. |
| Table | .data-table.data-table--sm.data-table--borderless | --sm head + 56 px rows (<td> height-locked to var(--space-56)). width: max-content; min-width: 100% so columns keep their widths and the table overflows for the horizontal scroll. |
| Cell wrapper | .data-cell / .data-cell--end | Block-level flex box inside every <td>. The <td> centres it geometrically (integer math); --end right-justifies the numeric columns. Keeps avatar / text / chip on one centre line without a vertical-align nudge. |
| Chain cell (col 1) | .avatar.avatar--sm.avatar--circle | One 32 px .avatar (--sm) for the order’s chain. Limit orders are same-chain, and the Pair column already names the tokens. Pinned on scroll, and wrapped in .tooltip-wrap (tabindex="0" + aria-describedby) so it shows the chain name on hover or focus. |
| Pair name cell (col 2) | .data-cell-text.data-cell-text--bold.ui-order-pair-label | SELL → BUY as .data-cell-text--bold; .ui-order-pair-label adds the arrow gap and nowrap. The arrow is a muted arrow-right (.ui-order-pair-arrow, --text-muted) so the symbols stand out. Scrolls under the pinned chain mark. |
| Sell / Buy cells | .tooltip-wrap › .data-cell-text | Number only. The value is the .tooltip-wrap target (tabindex="0" + aria-describedby) for the symbol and fiat; there is no info button. Right-aligned, tabular, base .data-cell-text. |
| Limit / Market cells | .data-cell-text--bold / .data-cell-text--muted | Limit = the key trigger price, emphasized (--bold = semibold). Market = current market price, --muted ink. Both tabular, right-aligned. |
| Filled cell | .data-cell-text | The fill percentage (0% / 37% / 100%) as plain .data-cell-text, so it shares the row’s centre line. |
| Expires cell | .data-cell-text--secondary · --muted · --danger | Also the lifecycle signal; only the ink changes. Active (open / partial) shows the countdown (“6 days”) in --secondary; expired shows “Expired” in --muted; cancelled shows “Cancelled” in --danger; filled stays blank, since Filled reads 100%. The renderer drops the leading “in” from the countdown because the header says Expires. |
| Kebab cell | .dropdown › [data-dropdown-trigger] | A real .dropdown: a .btn-icon.btn-neutral.btn-circle.btn-xs trigger with the ellipsis icon, marked data-dropdown-trigger, opening a .menu through the Popover API so it escapes .ui-card’s overflow: hidden. Active orders (open / partial) offer Modify limit and Cancel order (danger, last); finished orders (filled / expired / cancelled) offer Repeat order. The order id is mirrored on the panel. Modify and Repeat open the prefilled modal (#ui-modify-order); Cancel goes through a confirm sheet. All three update the data and re-render. |
| Hide flags | [data-disconnected="true"] / [data-empty="true"] | Either flag hides the card (swap.css → "Body-state hide"). The orders wiring IIFE in playground.html sets data-disconnected from body[data-playground-wallet-connected]; orders-list.js sets data-empty when getOrders() is empty. The form beside it already has the “Connect wallet” CTA, so an in-card prompt would repeat it. |
| Render host | tbody[data-orders-list] | The <tbody> orders-list.js fills. renderList() queries it on load + on persona-change; renderRow(order) with order === null stamps the skeleton path. |
| Card marker | [data-limit-orders] | Marker on the article (the orders-card instance). Markup-resident in every widget mode; CSS hides the card outside Limit. |
Sideways scroll with .table-scroll (.table-scroll--pinned for the chain column). .table-scroll__body sets overflow-x: auto, and the table is width: max-content; min-width: 100% so columns keep their widths. Collapsed, the panel hides the Market column; the expand control shows all nine (see Orders row).
Two ways to split the column height, set by body[data-limit-panel-split]. Orders sits under the Market Price chart:
- Stacked (default,
body[data-limit-panel-split="fill"]). The widget (form + view rail) sticks; Market Price is a capped band (min-height: 440px,max-height: min(var(--widget-max-h), 560px), a little shorter than the widget); Orders takes its natural height (flex: 0 0 auto) and the page scrolls.fillis set statically on the playground<body>. - Ratio (opt-in, no attribute). Chart
flex: 2 1 0, Ordersflex: 1 1 0. Orders scrolls inside its share under a stickythead, so any number of orders fits without growing the widget.
The paired expand-panel works with either: the control in the Market Price and Orders headers sets data-expanded on the stage and widens the receive column. Both cards grow sideways together; the vertical split is unchanged.
- Rows are locked to 56 px; the head stays
--sm. The row holds a 32 px.avatar, so each<td>isvar(--space-56)high with an integer line height. That keeps the row on the 4-grid and the avatar, text and chip on one centre line (.data-cell; seeCLAUDE.md → Data-table row alignment).min-heightorvertical-align: middlealone leave the row off-grid. - There is no Status column. The lifecycle is still stored as
tx.limit.state, separate fromtx.status, and the dormantSTATUS_MAP+statusTooltiphelpers inorders-list.jsare kept for a future cancelled-state treatment. - The kebab opens a real dropdown with status-gated actions. The trigger is a chromed
btn-icon.btn-neutral.btn-circle.btn-xswith theellipsisicon anddata-dropdown-trigger, a behaviour hook, not a.dropdown__trigger--*chrome variant (CLAUDE.md → Icon-only / standard-component triggers). It opens a.menuthrough the Popover API to escape.ui-card’soverflow: hidden. Active orders (open / partial) offer Modify limit and Cancel order; finished orders (filled / expired / cancelled) offer Repeat order. Cancel order is always last. Modify (cancelLimit→createLimit) and Repeat (createLimit) open the prefilled stepped modal (#ui-modify-order); Cancel goes through#cancelOrderModal→cancelLimit. All three update the data, then callLifiOrdersPanel.render(). - Limit mode only. The card is in the markup in every mode, but
body:not([data-widget-mode="limit"]) .ui-orders-panel { display: none }hides it outside Limit. Swap and Bridge settle in one transaction, and Gas has a fixed destination, so neither needs placed orders. - Nine columns with sideways scroll, for now. The narrow receive column scrolls the body (
overflow-x: auto, tablewidth: max-content). Collapsed, the playground hides only the Market column ([data-col="market"]inswap.css). Expires doubles as the lifecycle signal. This is an interim baseline: ask before adding more column hiding or responsive column priority. - Two height models; Stacked is the default. Stacked (
body[data-limit-panel-split="fill"]) keeps the widget fixed on the left while Market Price (a 440–560 px band) and Orders (natural height) stack on the right and the page scrolls. Ratio (opt-in, no attribute) keeps both cards in the capped column at 2/3 and 1/3, with Orders scrolling under a sticky header; use it to keep the order list in view beside the chart without page scroll. The paired maximize works with either. - With nothing to show, the card hides.
data-disconnected="true"(wallet disconnected) anddata-empty="true"(no orders) both setdisplay: none; only connected with orders renders, with no in-card connect prompt or empty state. This is an exception to theCLAUDE.md → Wallet-scoped surfaces gate their empty-state on connectionrule: the card sits beside an always-visible Market Price chart, and the form next to it already has the “Connect wallet” CTA. The standalone Activity feed (FAB sub-panel) has neither, so it keeps the standard connect prompt. - The playground owns connection, not the renderer. The orders wiring IIFE in
playground.htmlsetsdata-disconnectedfrombody[data-playground-wallet-connected];orders-list.jsonly rendersLifiOrdersinto thetbodyand setsdata-empty. Both flags sit on<article class="ui-orders-panel">, so the CSS hide reads one attribute. - Rows render live per persona through one renderer.
orders-list.js → renderRow(order)renders each column through slot helpers, andorder === nullis the skeleton path, so loading and real rows can’t drift (CLAUDE.md → Skeleton + shimmer). Data comes fromwindow.LifiOrders, a translator overwindow.LifiTransactions(type === 'limit', by persona);persona-changere-renders. Don’t hand-write rows;tbody[data-orders-list]is the render host.
- Markup:
playground.html, searchui-orders-panel(the live[data-limit-orders]instance under.widget-stage__receive, with thetbody[data-orders-list]render host). - CSS:
swap.css, searchOrders panel(visibility gate, edge bleed),Orders body scrolls(scrolling body, stickytheadon--surface-raised),Row geometry(56 px rows,.data-cell,.ui-order-*classes),Body-state hide,Market-panel split,Advanced widget tierandPaired-panel expand affordance;styles.cssfor.table-scroll. - Renderer:
orders-list.js(window.LifiOrdersList). OnerenderRow(order), whereorder === nullis the skeleton path; ten column slot helpers dispatch onopts.isSkel.renderList()stampsdata-emptyon the card when the list is empty. - Data:
orders-data.js(window.LifiOrders) filterswindow.LifiTransactions(lifi-transactions-data.js) totype === 'limit'for the active persona and pivots the extendedtx.limitpayload (triggerPrice/market/distancePct/filled/state/expiresAt) into the row shape, deriving the relativeexpirescountdown. The schema extension lives inlifi-transactions-data.js(search thetx.limit payloadheader). SeeCLAUDE.md → Unified transactions data layer. - Kebab actions:
playground.html, a delegated[data-order-action]click handler:modify→LifiModifyOrder.open(id),repeat→LifiModifyOrder.open(id, { mode: 'repeat' }),cancel→ the#cancelOrderModalconfirm sheet →LifiTransactions.cancelLimit. Order id is read off the.dropdown__panel(the top-layer popover is hoisted out of the<tr>). Controller + mutations:modify-order.js(two modes, stepped) +lifi-transactions-data.js(cancelLimit/createLimit). - Spec:
design/components/orders-table.md(this table) anddesign/components/swap.md, searchMarket-panel split(the two distribution models) andAdvanced widget tier(the receive widening).
Orders row
One order row, rendered from fixtures by the shared renderRow the playground uses.
The .ui-orders-panel row: the 9 columns of COLUMN_ORDER at --text-body (16px), with the fill as a plain %. It renders live through window.LifiOrdersList.renderRow(order), so the catalog can’t drift from the product.
Nine columns
You write a plain table shell; renderList re-heads the thead[data-orders-head] and renders the tbody from COLUMN_ORDER. The renderer owns all the column markup.
<!-- The table host. The renderer fills head + body. -->
<table class="data-table data-table--sm data-table--borderless data-table--rich data-table--orders">
<thead data-orders-head></thead>
<tbody data-orders-list></tbody>
</table>
To reorder or add columns, edit this array in orders-list.js (a new id also needs a COLUMNS entry). To use the dormant pair-stacked cell, swap it in here:
var COLUMN_ORDER = ['chain', 'pair-name', 'sell', 'buy', 'limit', 'market', 'filled', 'expires', 'actions'];
Row
| Property | Value |
|---|---|
| Columns | 9 (COLUMN_ORDER) |
| Value type | --text-body (--data-cell-text-size) |
| Fill column | fill % as plain .data-cell-text (no meter) |
| Row height | var(--space-56) |
Column vocabulary
| Column id | Header | Align |
|---|---|---|
chain | Chain | left |
pair-name | Pair | left |
pair-stacked | Pair (dormant alt) | left |
sell · buy | Sell · Buy | right |
limit · market | Limit · Market | right |
filled | Filled (fill % label) | left |
expires | Expires | left |
actions | (blank; Row actions) | center |
The row is one fixed composition on two concerns:
- Structure:
COLUMN_ORDER. An ordered list of column ids that sets which cells render, in what order, and which pair cell to use (a pinnedchainmark +pair-name, or the dormant singlepair-stackedcell). Each id maps to a{ head, align, slot }entry inCOLUMNS. - Look: the orders-table base.
--text-body(16px) values through the one--data-cell-text-sizetoken on.data-table--orders, including the fill%. No per-row modifier.
Both go through one renderer: renderRow(order) walks COLUMN_ORDER via COLUMNS, renderHead() builds the matching <thead>, and renderList runs both. order === null is the skeleton path, so skeleton columns follow COLUMN_ORDER automatically.
Row height stays var(--space-56) on the 4-grid; the avatar tier is unchanged.
- Reorder / add a column in
COLUMN_ORDER. One array inorders-list.jsdrives both head and body. A new column also needs oneCOLUMNSentry mapping its id to{ head, align, slot }; reuse the existing slot helpers. - Identity: pinned
chain+pair-name. The chain mark stays put on horizontal scroll; the pair name (SELL → BUY) scrolls with the values. The dormantpair-stackedcell (two lines, no chain mark) can replacepair-name. - Filled is a label, not a meter. The fill
%is plain.data-cell-text, so the row shares one line box. The universal.progressbar is unchanged. - Skeleton is automatic. Because the skeleton path shares
renderRow, the loading state tracksCOLUMN_ORDERwith no extra work. Don't hand-author a parallel skeleton. - Need a second composition? Bring back a registry. A
ROW_RECIPESregistry pays off at two or more compositions (CLAUDE.md→ Named-recipe registry).
- Renderer:
orders-list.js→COLUMN_ORDER+COLUMNS,renderRow(order),renderHead(),renderList. Public API:window.LifiOrdersList.renderRow / renderHead / renderList. - Styles:
swap.css→ searchOrder rowfor the dense base type (.data-table--orders→--data-cell-text-size) + the pair-separator arrow, and.ui-order-pair-stacked(the dormant stacked pair). - Live consumer:
playground.html→ the Limit-mode.ui-orders-panelrenders the order row viarenderList. - Catalog hydration:
design-system/ds-orders-rows.jsrenders this demo from static fixtures through the shared renderer. - Spec:
design/components/orders-table.md→ The order row.
Modify order modal .ui-modify-card
Stepped cancel-and-replace flow from the Orders kebab (edit, cancel, place), with the pair locked. Repeat skips the cancel.
Static snapshots of the three modify steps, for a 45 % filled order. The live modal opens from the Orders kebab (“Modify limit” / “Repeat order”) in playground.html, prefilled from the order. Repeat is the same flow in 2 steps, without the cancel.
Step 1 · Edit terms
Modify limit order
Step 2 · Cancel order
Cancel current order
Updating a limit order replaces it: the current order is cancelled first, then the new one is placed. Confirm the cancellation to continue.
- Order
- ETH → USDC
- Limit price
- 1 ETH = 4,000 USDC
- Already filled
- 45% — stays settled
- Unfilled amount
- 1.1 ETH
- Would expire in
- 12 days
This can't be undone. The current order stops filling immediately; any portion already filled stays settled.
Step 3 · Place order
Place new order
Current order cancelled. Place the new order to complete the update.
Review the new order. It becomes active as soon as it's placed.
- Order
- ETH → USDC
- Limit price
- 1 ETH = 4,000 USDC
- Sell
- 1.1 ETH
- Buy (est.)
- 4,400 USDC
- Expires in
- 30 days
Steps 2 and 3 confirm real transactions. The cancel is signed before the place step, so modify mode has no Back past step 2. Repeat shows a 2-disc stepper (Edit terms · Place order) and keeps Back on the place step.
<!-- window.LifiModifyOrder.open(orderId, { mode }); JS paints stepper, title, footer -->
<div class="modal-overlay" id="modifyOrderModal" hidden>
<div class="modal panel" role="dialog" aria-modal="true">
<div class="ui-modify-steps" data-modify-stepper><!-- .steps--circles-inline — JS-rendered per step --></div>
<header class="screen-header screen-header--main">…per-step title…</header>
<div class="modal-body">
<!-- STEP · edit — the prefilled, constrained Limit form -->
<section class="ui-modify-panel" data-modify-panel="edit">
<div class="ui-card ui-modify-card" data-standalone data-modify-scope>
<div class="ui-limit-price-card" data-denom="quote-per-base" data-limit-standalone>…</div>
<div class="ui-modify-pair">
<!-- Sell: editable amount, locked .chip-avatar--locked[data-role="from"], fiat footer -->
<!-- Buy: derived amount, locked .chip-avatar--locked[data-role="to"], fiat footer -->
</div>
</div>
<div class="setting-row setting-row--sm">…Expires in dropdown…</div>
</section>
<!-- STEP · cancel — confirm cancelling the CURRENT order (modify mode only) -->
<section class="ui-modify-panel" data-modify-panel="cancel" hidden>
<p class="modal-desc">…</p>
<dl class="detail-list detail-list--divided" data-modify-cancel-summary></dl>
<div class="alert alert--warn alert--sm alert--no-dismiss">…can't be undone…</div>
</section>
<!-- STEP · place — confirm the NEW order (receipt of the edited terms) -->
<section class="ui-modify-panel" data-modify-panel="place" hidden>
<div class="alert alert--success alert--sm alert--no-dismiss" data-modify-cancelled-note hidden>…</div>
<p class="modal-desc">…</p>
<dl class="detail-list detail-list--divided" data-modify-place-summary></dl>
</section>
</div>
<div class="action-bar" data-modify-footer><!-- footer — JS-rendered per step --></div>
</div>
</div>
Full markup in playground.html (search modifyOrderModal). The locked chips are <span>s with data-role/data-symbol/data-chain: they feed the price card’s rate but never open the picker. Footers: Cancel · Continue (edit), Back · Cancel order (cancel), Close or Back · Place order (place). While a signature is pending, the primary becomes a disabled .spinner button.
| Token / value | Resolves to | Role |
|---|---|---|
| .modal max-width | var(--w-9) · 480px | Modal panel width (shared .modal default). |
| .modal-body gutter | padding 0 var(--space-8) + matching negative margin | Shadow gutter: the overflow:auto body would clip the cards’ --elev-1 shadow, so padding makes room and the negative margin keeps content flush. Same as .list--cards. |
| .ui-modify-steps margin-top | var(--space-8) · 8px | Space between the stepper and the modal title. The stepper is .steps--circles-inline from styles.css. |
| .ui-modify-panel gap | var(--cluster-sm) · 8px | Gap between description, receipt and alert. Panels toggle with [hidden], so the rule re-asserts [hidden] { display: none }. |
| .ui-modify-card gap | var(--space-12) · 12px | Stack rhythm between price card, pair, and alert. |
| .ui-modify-pair gap | var(--gap-card-sm) · 8px | Gap between the locked Sell and Buy cards. |
| .ui-modify-card overflow | visible | Overrides .ui-card’s hidden so the inner cards cast shadows. |
| data-market-override | order's tx.limit.market | Sets the price card’s market to the order’s market rather than the wallet sim’s, so presets and the off-market alert are correct. |
| Part | Class | Notes |
|---|---|---|
| Stepper | .ui-modify-steps › .steps--circles-inline | Rendered per step into [data-modify-stepper], above the title, using .steps. 3 discs in modify (Edit terms · Cancel order · Place order), 2 in repeat; completed discs show a check. |
| Step panels | .ui-modify-panel[data-modify-panel] | One <section> per step in .modal-body, toggled with [hidden] by renderStep(); the .modal resize animates the height. |
| Confirm receipts | .detail-list--divided | Two .detail-list summaries painted by JS: [data-modify-cancel-summary] (the current order’s live terms, re-read on render) and [data-modify-place-summary] (the edited terms). Rates show the volatile token as base (1 ETH = 4,000 USDC), as in Activity. |
| Footer | .action-bar[data-modify-footer] | Rendered per step: two equal-width buttons, primaries without a trailing arrow. While a signature is pending, the primary becomes a disabled .spinner button (“Cancelling order…” / “Placing order…”). |
| Scope wrapper | .ui-modify-card | A bare .ui-card (no .panel, no surface). It scopes findReferenceTokens to the locked pair and carries the [data-standalone] opt-out. |
| Limit price | .ui-limit-price-card | A second instance of the limit price card, wired by modify-order.js through LifiLimitPriceCard.wireCard(), not the global init(). |
| Locked pair | .ui-modify-pair | Two stacked .ui-amount-cards with no flip arrow, since a modify can’t change direction. Sell is editable; Buy is Sell × price. |
| Locked chip | .chip-avatar--locked | A <span> with the .chip-avatar locked modifier: transparent fill, hairline outline, muted label, pointer-events:none. Shows the order’s pair and never opens the picker. |
| Fiat footer | .ui-amount-card__footer › .ui-amount-card__fiat | Fiat only: no balance, MAX or price-impact slots, since this edits an order, not a wallet flow. The value is amount × the order's stored unit price (from.usd/from.amount, to.usd/to.amount), repainted by recomputeBuy() on every Sell or price edit. |
| Expiry | .dropdown | Its own [data-modify-expiry-*] hooks, not the compose widget’s (those share a localStorage key). The selection is kept in memory. |
- Modify is cancel-and-replace, in 3 steps. A limit order’s terms can’t change in place on-chain, so the modal goes Edit terms → Cancel order → Place order. The cancel is a real transaction: the old row turns Cancelled in the Orders table behind the modal, there is no Back past it, and closing the modal afterwards leaves the old order cancelled, as on-chain.
- Repeat skips the cancel: 2 steps, same controller.
open(id, { mode: 'repeat' })(finished orders) fills the form with the order’s terms. Nothing is committed before the place confirm, so Back from the place step is allowed. The title reads “Repeat order”. - The pair is locked. A new pair would be a new order. The token chips show the pair but do nothing; only price, amount and expiry are editable.
- Sell prefill depends on the mode. Modify fills the remaining amount (
amount × (1 − filled/100)) with a45% filledline above it, whose info tooltip says edits change only the unfilled part (hidden whenfilled === 0). Repeat fills the full original amount, since it is a fresh order, and sets expiry to the order’s original duration. - Entry depends on status. The Orders kebab offers Modify and Cancel for active orders (open / partial) and Repeat for finished ones (filled / expired / cancelled). See
.ui-orders-panel. - Both confirms write to the data source. The cancel step calls
LifiTransactions.cancelLimit(id); the place step callscreateLimit(srcId, patch), which copies the source’s identity into a newopenorder. Each then callsLifiOrdersPanel.render(), so Activity and tx details stay consistent (CLAUDE.md → Unified transactions data layer).updateLimithas no caller now and is kept as data-layer API. - Price direction follows the reference side (as
orders-data.js → refIsFrom). The fixture’striggerPriceandmarketare the volatile side’s price, soopen()sets the price card’s denom by direction: volatile→stable isquote-per-base; stable→volatile isbase-per-quotewithdata-market-overrideinverted.placeOrder()stores the trigger in the order’s own convention with a signeddistancePct, and the receipts show the volatile token as base (1 WBTC = 92,000 USDC). - Reuse the price card without re-wiring. The modal uses its per-card methods (
render/renderProximity/wireCard). The[data-standalone]/[data-limit-standalone]opt-outs keep the compose widget’s bootstrap and document-wide loops away from the modal instance.
- Controller:
modify-order.js(window.LifiModifyOrder).open(orderId, { mode })('modify', 3 steps;'repeat', 2 steps) prefills and renders;renderStep()paints[data-modify-stepper],[data-modify-footer]and the two[data-modify-*-summary]hooks; the confirm handlers simulate a signature, then update and re-render. - Markup:
playground.html, searchmodifyOrderModal(+cancelOrderModalfor the destructive confirm); kebab wiring is the delegated[data-order-action]handler. - Kebab gating:
orders-list.js→slotKebabCell(active → Modify + Cancel; terminal → Repeat). - Price-card reuse:
ui-limit-price-card.js:wireCard(exported), thedata-market-overridehook ingetMarketRate, and the:not([data-limit-standalone])guards on the 3 document iterators. - Mutations:
lifi-transactions-data.js→cancelLimit(the cancel confirm and the kebab’s own cancel sheet) /createLimit(the place confirm; repeat uses only this). Bootstrap opt-out:swap.jsinit()skips.ui-card[data-standalone]. - CSS:
swap.css, searchModify-order modal(.ui-modify-card/.ui-modify-pair/.ui-modify-steps/.ui-modify-panel+ the net-zero shadow gutter). The stepper primitive isstyles.css→.steps--circles-inline; locked chips use.chip-avatar--locked(styles.css).
Transaction summary .ui-tx-summary
The shared from→to card, every slot optional. Used by Review, the execution recaps, Activity and Transaction details.
In the Activity list the card is .ui-tx-summary--interactive and opens Transaction details. On Transaction details it is the base variant plus the rate and gas __foot. In both, the chevron expands the Route. Built from .list-item, .avatar tandems and .detail-list.
Route expanded
- Network cost
- <$0.01
- Price impact
- 0%
- Exchange rate
- 1 USDC ≈ 1 USDC
- Estimated time
- 0s
<!-- Activity item: --interactive + role=button on a div root (hosts the chevron button) -->
<div class="card ui-tx-summary ui-tx-summary--interactive" role="button" tabindex="0">
<div class="ui-tx-summary__head">
<span class="ui-tx-summary__date">March 31, 2026</span>
<span class="ui-tx-summary__time">6:49 AM</span>
</div>
<div class="ui-tx-summary__flow">
<div class="list-item ui-tx-summary__row"> <!-- from -->
<span class="list-item__lead"><!-- avatar-tandem --></span>
<div class="list-item__body">
<div class="list-item__title ui-tx-summary__amount">4</div>
<div class="list-item__desc">$4.00 · USDC on Base</div>
</div>
</div>
<div class="ui-tx-summary__connector"><!-- ↓ --></div>
<div class="list-item ui-tx-summary__row"> <!-- to + chevron in __trail --></div>
</div>
<div class="ui-tx-summary__detail" hidden>
<div class="ui-tx-summary__detail-head"><!-- Route + provider --></div>
<dl class="detail-list"><!-- Network cost / Price impact / Rate / ETA --></dl>
</div>
<!-- Transaction details only: rate + gas foot fed from the route rows -->
<div class="ui-tx-summary__foot">
<span class="ui-tx-summary__rate">1 USDC ≈ 1 USDC</span>
<span class="ui-tx-summary__foot-trail"><!-- .ui-quote-metric--fee pill --></span>
</div>
</div>
Rendered by swap.js → initActivity() through one txSummaryInner(tx, inList) builder, shared by the Activity list and the Transaction-details card.
| Token | Value | Applies to |
|---|---|---|
| --card-radius | 16 px | Card surface (inherits .card) |
| gap | --space-12 | Head / flow / detail stack |
| --text-h3 | 24 px | .ui-tx-summary__amount (display tier) |
| --text-caption | 12 px | .ui-tx-summary__head (date / time) |
| --space-48 | 48 px | .ui-tx-summary__connector width (avatar column) |
| avatar-tandem--lg | 48 px | Lead token avatar |
| Element | Role |
|---|---|
| .ui-tx-summary | Card root (composes .card) |
| __head | Date (left) + __time (right), caption tier |
| __flow | From row · __connector (↓) · To row |
| __row | A .list-item with padding-inline cancelled to align to the card edge |
| __amount | The row headline number, bumped to the --text-h3 display tier |
| __toggle | Chevron in the to-row .list-item__trail; flips __detail[hidden] |
| __detail | Collapsible Route: __detail-head (label + provider mark, or the Review screen's route .avatar-stack at 20 px) + .detail-list |
| __foot | Optional rate and metrics line: __rate (left, tabular) + __foot-trail (.ui-quote-metric pills). Review shows rate, gas and ETA; Transaction details shows rate and gas from the route rows; the Activity list omits it. |
| --interactive | Whole card opens Transaction details (hover = canonical UI-card 3% accent + elev-2) |
Screen composition. The Activity screen is a .ui-activity-list of --interactive cards. Transaction details stacks one base card + a Receipts card (.status-row rows) + a Transfer ID card.
- One set of slots, four surfaces. Activity and Transaction details use the full anatomy; the Review summary card uses it without the head (+
__detailfee rows + the__footline); the execution flow’s.ui-tx-pairholds a bare__flowand.ui-tx-receiveda bare__row. Every slot is optional; don’t add review-only classes alongside them. - One builder for the rendered screens. The Activity list and Transaction-details card both render from
txSummaryInner(tx, inList).inListswitches the to-row meta (provider name vs. destination chain) and shows the__footonly on details. The review card is static markup filled through[data-review-ref]slots. - The
--interactiveroot is a<div role="button">, never a<button>. It holds the chevron<button>, and the HTML parser would close a button root early (see Card root element rule in CLAUDE.md). Enter and Space are handled in JS. - Flow tandems carry only the chain badge. One
--brchain badge per token avatar, never a second--blprovider badge, which overloads the avatar. The provider shows in the to-row meta (“· Eco”) and the Route__detail-head. The two-badge tandem remains an.avatar-tandemoption. - Chevron stops propagation. The toggle expands the Route inline without triggering the card's navigation.
- Receipts use
.status-row. Don’t build a separate receipt row; status-row (icon / label / action,--success/--info) covers it. - A widget state, not a modal. Activity and Transaction details are
data-statevalues on the.ui-card(likereview/settings), each remembering the previous state for Back.
- CSS:
swap.css, search.ui-tx-summary(primitive) and.ui-activity__body/.ui-tx-details__body(screen glue). - Markup:
playground.html,data-state-content="activity"anddata-state-content="tx-details". - JS:
swap.js → initActivity()(render + nav);activity-data.js(window.LifiActivitymock log).
Execution status .ui-tx-status
The widget’s execution screen: hero mark, status text and a step checklist that grows as it runs. data-tx-outcome drives running / success / partial / failed.
data-tx-outcome on the .ui-tx wrapper picks the hero mark (an 80 px .spinner while running, a .spot-icon-4xl --round tone disc after), the lower card (from/↓/to pair or Received) and the footer (See details + Done, or Remove + Retry). Steps are .status-row rows added as execution advances. On the playground, ⌥-click the Review CTA to force the failed path, ⇧-click for partial.
Success
<!-- data-tx-outcome: running | success | partial | failed (gated in swap.css) -->
<div class="ui-tx" data-state-content="tx-progress" data-tx-outcome="running">
<header class="screen-header"><!-- back + mode title --></header>
<div class="ui-tx__body">
<div class="card ui-tx-status" aria-live="polite">
<span class="ui-tx-status__icon">
<!-- 80px .spinner + three [data-tx-disc] tone discs; CSS shows one -->
</span>
<div class="ui-tx-status__text">
<div class="ui-tx-status__title">Waiting for wallet signature confirmation</div>
<p class="ui-tx-status__desc" hidden></p>
</div>
<div class="ui-tx-status__steps"><!-- progressive .status-row rows --></div>
</div>
<div class="card ui-tx-received"><!-- "Received" .ui-card-label + token row (success / partial) --></div>
<div class="card ui-tx-pair"><!-- from / ↓ / to recap (running / failed) --></div>
</div>
<div class="action-bar ui-tx-actions--done"><!-- See details + Done --></div>
<div class="action-bar ui-tx-actions--failed"><!-- Remove + Retry --></div>
</div>
Driven by swap.js → runTxProgress(card, force): the simulated steps add .status-row rows through statusRowHTML() (which also renders the Transaction-details receipts) and set data-tx-outcome.
| Token | Value | Applies to |
|---|---|---|
| --spinner-size | --space-80 | The running ring (stroke steps to --space-4 at this scale) |
| spot-icon-4xl | 80 px tile · 40 px glyph | Outcome disc (--round + --success / --warn / --danger) |
| --text-body-lg | 18 px · --fw-semibold | __title |
| --text-sm | 14 px · --text-secondary | __desc (partial / failed explanation) |
| gap | --space-8 | __steps stack (checklist rows use a --space-8 gap and --space-12 inline padding, denser than base .status-row) |
| padding-block | --space-24 --space-16 | Space around the hero |
| Element | Role |
|---|---|
| .ui-tx[data-tx-outcome] | Pane root; the outcome attribute sets the visual state (gated in swap.css) |
| .ui-tx-status | Status card (composes .card), a centred column |
| __icon | Hero mark host: the 80 px .spinner + three [data-tx-disc] tone discs; exactly one shows per outcome |
| __title / __desc | Status headline + optional explanation (partial / failed) |
| __steps | .status-row checklist: approval → transaction → sent to wallet |
| .ui-tx-received | "Received" card (.ui-card-label + token row), success / partial only |
| .ui-tx-pair | from / ↓ / to recap card, running / failed only |
| .ui-tx-actions--done / --failed | .action-bar pairs by outcome: See details + Done, or Remove + Retry |
Outcome map. running → spinner + pair card, no footer. success → success disc + steps + Received + See details / Done. partial → warn disc + desc + steps + Received + See details / Done. failed → danger disc + desc + failed step + pair card + Remove / Retry.
- The outcome attribute drives everything. JS adds steps and sets
data-tx-outcome; CSS decides which mark, lower card and footer show. Don’t toggle[hidden]per element. - Use the standard result disc:
.spot-icon-4xl --round+ tone, as in the Portal withdraw-fees results. Don’t build a separate disc. - Steps and receipts share one builder.
statusRowHTML()inswap.jsrenders both the live checklist and the Transaction-details receipts. - Every run is recorded in
LifiTransactions.addTransaction(completed / refunded / failed, in memory), so it appears first in the Activities tab. See details reads it back throughLifiActivityand opens the shared Transaction-details screen (.ui-tx-summary+ receipts + Transfer ID); there is no separate details view. - Step labels stay single-line. The checklist scope ellipsizes long labels (address short-forms) instead of wrapping the row.
- Themeable. Every colour uses semantic tones (
--success / --warn / --danger / --info) and accents, so a scoped canvas preset re-tints the discs, rows and CTAs. - Forcing outcomes in the demo. ⌥-click the Review CTA → failed; ⇧-click → partial; Retry runs the success path. Real execution plugs into
runTxProgress’s step callbacks.
- CSS:
swap.css, searchtx-progress (.ui-tx*)(layout and outcome gating). - Markup:
playground.html,data-state-content="tx-progress". - JS:
swap.js → runTxProgress() / initTxProgress() / statusRowHTML(). - Spec:
design/components/swap.md → Execution flow. - Mock: Figma Widget → Flow (Review / Waiting / Completed / Partially Successful / Failed frames).
.ui-price-chartvar(--*) token, so the chart re-tints with the palette and follows the theme. It sits under .ui-token-info, which holds the spot price and deltas; the chart shows the history.Live: drag to pan, scroll to zoom, hover for the crosshair, click a timeframe to re-range. The dashed accent line is the limit-price annotation, set here at $2,253 because the playground form isn’t on this page. Spot price and deltas are in .ui-token-info.
<!-- Section primitive, not a card: the enclosing panel carries the surface -->
<div class="ui-price-chart">
<!-- Timeframes: one .is-active chip (= aria-pressed); data-timeframe="1D|1W|1M|all" -->
<div class="ui-price-chart__timeframes" role="radiogroup" aria-label="Time range">
<button class="chip chip-neutral" data-timeframe="1D">1D</button>
<button class="chip chip-neutral is-active" data-timeframe="1W" aria-pressed="true">1W</button>
<button class="chip chip-neutral" data-timeframe="1M">1M</button>
<button class="chip chip-neutral" data-timeframe="all">All</button>
</div>
<!-- data-tradingview-chart: auto-init hook for tradingview-chart.js -->
<div class="tradingview-chart"
data-tradingview-chart
aria-label="Price chart"></div>
</div>
<!-- Load the library before tradingview-chart.js -->
<script src="https://unpkg.com/lightweight-charts@4/dist/lightweight-charts.standalone.production.js"></script>
<script src="tradingview-chart.js"></script>
The chart has only the timeframe row and the canvas; spot price and deltas are in .ui-token-info. Every canvas colour resolves to a var(--*) token at init and on every theme change.
| Slot | Default | Notes |
|---|---|---|
| Root | flex column · gap 12 · flex 1 · min-height 0 | Not a card: no background, border, shadow or padding. The enclosing panel carries the surface. |
__timeframes gap | var(--space-4) · 4 px | One tight group. |
| Chart container | flex 1 · margin-inline: calc(-1 * --space-24) | Extends past the panel’s 24 px side padding so the price axis sits flush. The bottom keeps the panel’s padding for the time-axis labels. |
| Chart canvas | autoSize: true | The canvas follows the container size; min-height: 0 lets it shrink in a flex parent. |
| Up candle | var(--success) | Resolved at init and on every theme change. |
| Down candle | var(--danger) | Same. |
| Grid lines | rgba(127,127,127,0.06) | Neutral hairline, same in light and dark. |
| Limit-price line | var(--accent-primary) · 1 px · dashed | Shown when a limit is set; brand accent in any palette. |
| Crosshair | rgba(127,127,127,0.4) · 1 px · dashed | On hover, vertical and horizontal lines. |
| Font (canvas text) | Figtree, system-ui, … | Set on layout.fontFamily so axis labels match the site. |
| Sub-part | Class | Role |
|---|---|---|
| Root | .ui-price-chart | Flex column that fills its panel; min-height: 0 lets the canvas shrink in a capped widget. |
| Timeframes group | .ui-price-chart__timeframes | Flex row, 4 px gap. role="radiogroup" for assistive tech. |
| Timeframe chip | .chip.chip-neutral[data-timeframe] | One per preset (1D / 1W / 1M / all). The selected one has .is-active + aria-pressed="true". JS re-ranges every chart on the page with chart.timeScale().setVisibleRange(). |
| Chart canvas | .tradingview-chart[data-tradingview-chart] | Auto-init hook: tradingview-chart.js creates a chart for each match on DOMContentLoaded, resized through Lightweight Charts’ autoSize. |
| Limit annotation | (no DOM; series.createPriceLine()) | Drawn on the canvas. JS reads .ui-limit-price-card__amount and the card’s data-denom, converts to the chart’s USDC-per-ETH unit, and repaints on every input or denom change (150 ms debounce). |
- Not a card. No background, border, shadow or padding; the enclosing
.panel/.ui-card/ catalog.ds-doc-card-democarries the surface. It works in any card-shaped parent (Receive panel, dashboard tile, modal), andresolvePanelBg()picks up that parent’s background. - Spot price and deltas belong in
.ui-token-info, not here. The chart shows history; current price and % deltas sit in the token-info row above, which also works alone in overlays without a chart. Don’t add a price header here: extend the timeframe row, add a sibling options row, or put new state in.ui-token-info. - Every colour resolves to a token. Candles →
var(--success)/var(--danger); limit line →var(--accent-primary); text →var(--text-secondary); background → read from the chart’s ancestors. AMutationObserverondata-themeandstylere-applies them on theme and palette changes without re-creating the chart. Don’t put a hex colour in the chart options, or palette changes won’t reach it. - The canvas extends sideways, not down.
margin-inline: calc(-1 * var(--space-24))on.tradingview-chartpushes it past the panel’s side padding so the price-axis labels sit flush. The bottom keeps the panel’s padding so the time-axis labels (21 / 26 / May / 6 / …) clear the rounded edge, and the panel’soverflow: hidden+border-radiusround the chart’s bottom corners. - Timeframes are standard chips. Each preset is a default-tier
.chip.chip-neutral(24 px, 12 px text). Exactly one has.is-active+aria-pressed="true"and takes the.chip-neutral.is-activeaccent fill. JS toggles both on click; don’t add timeframe-specific button styles. - The chart owns the limit-price line, not the form. It is a
series.createPriceLine()annotation on the canvas with no DOM node. JS reads.ui-limit-price-card__amount, inverts bydata-denomand writes throughapplyOptions(). When the form is empty or invalid, remove it withseries.removePriceLine(); never hide it with a transparent colour. - The library draws; the primitive owns the chrome. Lightweight Charts handles candles, axes, crosshair, pan and zoom; the primitive handles timeframes and the surface. Don’t add UI inside the canvas; extend the timeframe row or add a sibling row.
- One chart per
[data-tradingview-chart]. Init runs once per element. Several charts on a page are fine; one set of observers serves them all. Don’t init manually; the DOMContentLoaded auto-init handles it. - Demo data per token. Candles are a seeded random walk per buy token: the seed is hashed from the symbol, the anchor comes from
sim.getPriceUsd()(with a static fallback table for this catalog page, which doesn’t load the sim), and volatility is set per asset (ETH 1.3 %/hr, WBTC 1.1 %, SOL 1.9 %, ARB 2.2 %, …). Real data (CoinGecko, the LI.FI price feed or the route quote endpoint) replacesgenerateDemoData()intradingview-chart.jswith the same per-token API. - In the demo the latest candle updates every 2 s. A tick simulator in
tradingview-chart.jsmoves the current bar’s close on a random walk scaled from the token’s hourly volatility and callsseries.update()with{ time, open, high, low, close }. The spot price and delta chips in.ui-token-infore-render on the same tick, so they always agree with the chart. The loop pauses whiledocument.hidden. At each hour boundary a new bar opens at the previous close. A real WebSocket feed replaces the simulator;series.update()stays. - The chart follows the buy token. A
MutationObserveron[data-role="to"]’sdata-symbol+data-chainrepaints the candles, re-applies the timeframe and repaints the limit line in the same tick, with no pop-in..ui-token-inforepaints in the same pass. This page has no[data-role="to"], so the observer does nothing and the demo stays as written. - Stablecoins get a real chart at low volatility. For
USDC/USDT/DAI/USDSthe series usesTOKEN_VOLATILITY0.001: nearly flat at peg, but a depeg (USDC March 2023, UST May 2022, USDD several times) would show as candles..ui-price-chart[data-stable]is set on every to-token change as a semantic hook, but no CSS uses it. Don’t add a branch that hides the chart for stables; showing that movement is the chart’s job. - Pair it with
.ui-token-infoabove, in the Receive panel. Token info shows identity and current price (avatar tandem, ticker · chain, price, deltas); the chart shows history. Both hide in Swap / Bridge, where the quote list takes over. - Other chart types share the chrome. Future
.ui-price-chart--line/--area/--depth/--minivariants keep the timeframes and canvas and pass different series options to the library. Use modifier classes, not separate components.
swap.css:.ui-price-chartrules (search the section comment "Price chart section for Limit mode", around the__timeframes/.tradingview-chartblocks).tradingview-chart.js: the Lightweight Charts integration. It auto-inits on DOMContentLoaded and exposes no API. Internals:chartOptions(container)resolves layout / grid / scale colors from tokens;candleSeriesOptions()resolves up/down tones;getTokenDataParams(symbol)+generateDemoData(symbol)produce the per-token seeded random walk;computeDeltas(candles)derives the 5m / 1h / 6h / 24h chips from the same series;renderTokenInfo()repaints the.ui-token-inforow's identity + spot + deltas;repaintForToken()swaps the chart series on token change;ensurePriceLine()paints the limit annotation;watchTheme()+watchLimitPrice()+watchTimeframes()+watchToToken()wire the live updates.https://unpkg.com/lightweight-charts@4/dist/lightweight-charts.standalone.production.js: the library. Apache 2.0, ~35 KB gzipped. Pinned to the v4 major; check release notes before bumping.playground.html: the live consumer, in the swap widget’s Receive panel in Limit mode, with.ui-token-infoabove.ui-price-chartin the panel.design-system/playground.html: this catalog card. The Preview sets a value up front so the chart renders on first paint.design/components/swap.md: written spec for the surface recipe and why Lightweight Charts is used.
Related primitives: .chip.chip-delta-pos / .chip-delta-neg (delta tone family), .chip--bare (frameless chrome), .chip-window (annotation sub-slot inside delta chips), .ui-token-info (paired token-identity header above the chart), .ui-limit-price-card (source of the annotated limit-price value).
.ui-token-info__identity, __price, __deltas.Default, all three slots
Compact, one 24h delta
Identity only
<!-- Slots: __identity (required); __spot (optional) holds __price + __deltas -->
<div class="ui-token-info">
<!-- .list-item--lg; __identity zeroes row chrome, title + desc inline at 18 px -->
<div class="list-item list-item--lg ui-token-info__identity">
<span class="list-item__lead">
<!-- Token mark + chain badge (#avatar tandem) -->
<span class="avatar-tandem">
<img class="avatar avatar--circle" src="avatars/tokens/eth.svg" alt="">
<img class="avatar-badge avatar-badge--br"
src="avatars/chains/ethereum.svg" alt="on Ethereum">
</span>
</span>
<div class="list-item__body">
<div class="list-item__title">ETH</div>
<div class="list-item__desc">Ethereum</div>
</div>
</div>
<!-- Spot row: leave it out for identity-only -->
<div class="ui-token-info__spot">
<div class="ui-token-info__price">$2,112.40</div>
<div class="ui-token-info__deltas" aria-label="Price changes">
<!-- One delta chip per window; the window is a .chip-window inside it -->
<span class="chip chip-delta-pos chip--bare">
<svg class="chip-icon">…</svg>0.07%<span class="chip-window">5m</span>
</span>
<!-- + 1h / 6h / 24h -->
</div>
</div>
</div>
.ui-token-info is a flex column with named slots: __identity (on .list-item.list-item--lg) and __spot (a baseline row holding __price + __deltas). Include only the slots you need. The price matches .ui-amount-card__amount and .ui-limit-price-card__amount (36 px display), so the widget’s four large numbers share one weight.
| Slot | Default | Notes |
|---|---|---|
| Root | flex column · gap 12 | No background or padding; the parent panel carries the surface. |
__identity chrome | padding 0 · min-height 0 · border-radius 0 | Removes the .list-item--lg row chrome; this row sits in a panel, not a list. |
__identity --avatar-size | var(--space-40) · 40 px | Matches .list-item--lg. The badge sizes from it; never set width or height on the inner .avatar. |
__identity body direction | row · baseline · gap 8 | Title and desc inline at the same size, so they read as one heading ("ETH Ethereum"). |
__identity title font-size | var(--text-body-lg) · 18 px | Up from the .list-item--lg default (16 px) for a heading role. |
__identity desc font-size | var(--text-body-lg) · 18 px | Same as the title; ink separates them (--text-primary vs --text-secondary). |
__spot layout | flex row · baseline · space-between · wrap · gap 12 | Price left, deltas right; wraps when narrow. |
__price font-size | var(--text-h2-lg) · 36 px | Bold (--fw-bold), --tracking-firm, line-height: 1.1. |
__price color | var(--text-primary) | Same ink as .ui-amount-card__amount with a value. |
__price numerics | font-variant-numeric: tabular-nums | Keeps the price from jittering as digits change. |
__deltas gap | var(--space-12) · 12 px | Between delta chips. Spacing inside a chip comes from the chip family. |
| Sub-part | Class | Role |
|---|---|---|
| Root | .ui-token-info | Flex-column wrapper for the slots. |
| Identity row | .list-item.list-item--lg.ui-token-info__identity | The large list row. __identity removes row chrome (padding / min-height / radius) and puts title and desc inline at the same body-lg size. |
| Lead | .list-item__lead | Holds the tandem avatar, at the .list-item--lg lead width. |
| Tandem mark | .avatar-tandem | See the #avatar tandem variant. Sized by the parent’s --avatar-size, never directly. |
| Token glyph | .avatar.avatar--circle | The token’s mark, circular. |
| Chain badge | .avatar-badge.avatar-badge--br | Bottom-right badge for the token’s chain; it cuts a mask into the main avatar. |
| Body | .list-item__body | Baseline-aligned inline row for title and desc. |
| Title | .list-item__title | Ticker (ETH / USDC / WBTC): primary ink, 18 px, list-item weight. |
| Description | .list-item__desc | Chain or full name (Ethereum / USD Coin / Bitcoin): secondary ink, 18 px. |
| Spot row | .ui-token-info__spot | Baseline row for price and deltas. Leave it out for identity-only uses (picker hover cards, row headings). |
| Spot price | .ui-token-info__price | Current spot price; type matches .ui-amount-card__amount. |
| Deltas group | .ui-token-info__deltas | Bare delta chips; wraps with a 12 px gap. |
| Delta chip | .chip.chip-delta-{pos|neg}.chip--bare | See .chip-delta-* and .chip--bare. The window label is a .chip-window inside the chip. |
| Delta arrow | .chip-icon | Leading Lucide arrow: move-up positive, move-down negative, tone from currentColor. |
| Window label | .chip-window | 5m / 1h / 6h / 24h, in muted ink so the percent leads. |
- Vary by slots, not modifiers.
__identity/__spot/__price/__deltasare named slots, and consumers include only what they need: an overlay or sticky header might drop a delta chip or the whole spot row; a full token card has everything. There are no--modifierclasses for slot visibility. - The identity row is a
.list-item.list-item--lg, the same primitive as the token picker.__identityremoves row chrome and puts title and desc inline at 18 px. Changes to.list-itemreach this row. - The price matches
.ui-amount-card__amountexactly: 36 px / 700 /--tracking-firm/ 1.1 line height / tabular-nums / primary ink, so Sell, Buy, Limit and Spot share one weight. When one changes, change this in the same edit. Never use--lh-displayor--lh-herohere; those pixel tokens overlap at this size. - Spot price belongs here, not in
.ui-price-chart. That makes this a self-contained snapshot for overlays. The chart shows history; don’t add a price slot to it. - The time window goes inside the delta chip as
.chip-window. The chip is one unit (arrow + value + window); don’t add a separate label or wrapper. - Size the avatar with
--avatar-size. Never set width or height on the inner.avatar; the badge geometry depends on it.__identitysets 40 px to match.list-item--lg. - Title and desc read as one heading. Both are 18 px and inline, so “ETH Ethereum” reads as a heading, not a title and subtitle.
.list-item--lgstacks them by default, which is right for picker rows. - Read-only: the token comes from the form’s
[data-role="to"]trigger. In the playground aMutationObserverintradingview-chart.jswatches itsdata-symbol+data-chainand repaints the identity (avatar tandem, ticker, chain name), spot price (sim.getPriceUsd()) and delta chips (from the chart’s candle series) in one pass. There is no picker or click action. This page has no[data-role="to"], so the observer does nothing and the demo stays as written. - Stablecoins get the same row with real values. For
USDC/USDT/DAI/USDS, the spot shows the sim’s price throughfmtSpotUsd()and the delta chips come from the candle series like any token..ui-token-info[data-stable]is a semantic hook with no CSS..ui-price-chartdoes the same (a real chart at low volatility), because stables can depeg and these are the surfaces a trader reads to see it. Don’t add a--stablemodifier or a separate primitive. - Not for picker rows. The token picker uses bare
.list-item.list-item--lg, because picker rows want padding, hover fill and the stacked title/desc. Use.ui-token-infoonly for a self-contained snapshot (heading + spot + deltas), not for a row in a list. - New contexts change the slots, not the chrome. For a popover, sticky header, portfolio row or notification: drop
__spotfor identity only,__deltasfor price only,__identityfor a price pill. Don’t add.ui-token-info--popover/--sticky/--rowclasses; the slots and the parent surface make the variant.
swap.css:.ui-token-inforules (search the section comment "Token identity + at-a-glance state").playground.html: the live consumer, at the top of the Receive panel in[data-limit-receive], wired to the form’s[data-role="to"]trigger bytradingview-chart.js→watchToToken(). The same pass repaints the chart below. The markup starts as ETH/Ethereum and the observer overwrites it on first paint.tradingview-chart.js: renders this row’s data.renderTokenInfo(symbol, chainKey, candles)writes the token avatar src, chain badge src + alt, ticker and chain name, plus the spot price (resolvePriceUsd(), from the sim or a fallback table) and delta chips (computeDeltas()over the chart’s candles). It lives with the chart so one observer drives both.styles.css: the.list-item+.list-item--lg+.avatar-tandem+.chip.chip-delta-*+.chip--bare+.chip-windowbase rules (the primitives this row composes).
Related primitives: .list-item (identity-row base), .avatar-tandem (token + chain badge composite), .chip.chip-delta-pos / .chip-delta-neg (delta tone family), .chip--bare (frameless chrome), .chip-window (annotation sub-slot inside delta chips), .ui-price-chart (historical visualization layer that pairs below in the Receive panel).
Checkout flow panel .ui-checkout
The guided pay-in flow, inline or in a modal. The funding source picked on the first screen sets the sequence.
A static snapshot of the first screen (Choose funding source). The full flow runs in the Playground (set Widget = Checkout in the rail): token and currency picker, connect wizard, amount entry, deposit address, the Deposit-with-Cash (Transak) path (fiat entry → the fixed-brand Transak sub-modal → pipeline checklist → completion) and the cash error and refund states. LI.FI screens use a centred .screen-header (back · title · close) and a “Powered by LI.FI” footer; the Transak sub-modal keeps its own brand (see Rules).
Choose funding source
Use your tokens
Buy tokens
checkout.js renders the current screen into any [data-checkout-flow] host: an inline .ui-card.ui-checkout on the canvas, or the #checkoutModal overlay. The rail sets the widget type (body[data-widget-type]) and the host (body[data-checkout-host]).
<!-- Inline host (on the canvas) -->
<div class="checkout-stage">
<div data-checkout-host="inline">
<article class="panel ui-card ui-checkout" data-checkout-flow></article>
</div>
</div>
<!-- Modal host (over the partner page) -->
<div class="modal-overlay" id="checkoutModal" hidden>
<div class="modal panel ui-checkout" data-checkout-flow></div>
</div>
<!-- checkout.js paints the current screen into every [data-checkout-flow] -->
All methods start with funding source → select token → amount, then differ. FLOWS[source] picks the sequence; renderScreen() wraps each step’s body in the shared chrome.
| Screen | Composed from | Notes |
|---|---|---|
| Choose funding source | .list--cards · .list-item--interactive · .spot-icon--neutral · .avatar-stack · .divider--label | The first screen. The trailing stack shows each method’s chains. |
| Connect wallet (Pay from Wallet) | window.LifiWalletConnect | The shared connect wizard, skipped when a wallet is connected. |
| Select token | .ui-token-picker | Held balances (Pay from Wallet) or the full token universe (Transfer). |
| Amount | .ui-amount-card · .chip-shortcuts · .detail-list | Single-column Send / Receive with no flip arrow; live quote from LifiQuoteSim. |
| Deposit address (Transfer) | .alert--warn · .ui-checkout-qr · .ui-checkout-address | Address + scannable QR (window.LifiQR) + expiry + watching state. |
| In progress | .ui-checkout-status · .spinner | Centred ring and status; advances by itself (mock confirmation). |
| Completed | .ui-checkout-status · .spot-icon-4xl--round | Success disc + .ui-tx-summary. |
| Deposit details | .ui-tx-summary · .detail-list | The receipt. |
| Cash: currency / amount (Transak) | .ui-token-picker (flag rows) · .ui-checkout-fiat · .chip-shortcuts · .alert--info | Pick a currency and enter a fiat amount; the stETH received updates live. |
| Cash: Transak sub-modal (6 screens) | .ui-transak-* (fixed brand) | The embedded Transak widget in its own brand (see Rules). |
| Cash: in progress / completed / details | .ui-checkout-steps (.status-row --active/--pending) · .ui-checkout-countdown · .ui-checkout-received · .ui-checkout-transfer | Pipeline checklist, countdown ring and receipt. |
| Cash: error / refund | .ui-checkout-status--message · .ui-checkout-actions · .spot-icon-4xl--round | Cancelled · can't-buy · couldn't-reach · something-wrong · refund-sent. |
New sub-primitives
| Class | Role |
|---|---|
| .ui-checkout | The flow panel: .panel.ui-card inline or .modal.panel in a modal. Centres the screen-header title. |
| .ui-checkout__powered | The persistent "Powered by LI.FI" footer (LI.FI wordmark, currentColor). |
| .ui-checkout-status | Centred status: a large ring (in progress) or success disc (completed) with a label, on .card. |
| .ui-checkout-qr | The deposit-address QR: a fixed white plate with dark modules, so it scans in both themes, and the token logo in the centre. [data-checkout-qr-code] hosts window.LifiQR.toSVG. |
| .ui-checkout-address | Mono deposit address + a copy button. |
| .ui-checkout-fiat | The cash Send / Receive card: asset (flag or tandem + role + code) on top, large amount below, on the .ui-amount-card surface. |
| .ui-checkout-steps | The cash pipeline checklist: a neutral grey .status-row stack using the new --active (spinner) / --pending (empty ring) states. |
| .ui-checkout-received · -receipt · -transfer | The cash flow’s last screens: Received card, receipt, Transfer-ID card (copy + Contact Support). |
| .ui-checkout-status--message · .ui-checkout-actions | Error and refund: centred tone disc, heading and description, with stacked (errors) or side-by-side (refund) buttons. |
| .ui-transak-* | Page-local chrome for the fixed-brand Transak sub-modal, not reusable DS primitives. See Rules. |
- Checkout is a widget type, not an exchange mode.
body[data-widget-type="exchange" | "checkout"]swaps.widget-stagefor.checkout-stage. The default isexchange, the code fallback on cold load; a saved pick can override it but never sets a different default. - Any host. The same
renderScreen()output paints into an inline.ui-card.ui-checkoutor the#checkoutModaloverlay, chosen bybody[data-checkout-host="inline" | "modal"]. The modal resizes between steps (window.LifiModalResize). - One sequence per method.
FLOWS[state.source]picks the screens. Pay from Wallet adds a connect step, then goes to progress; Transfer skips connect and adds the deposit-address screen; Deposit with Cash (Transak) runs fiat entry → the Transak sub-modal → LI.FI’s closing screens. A new method is oneFLOWSentry plus its branch. - The Transak sub-modal keeps Transak’s brand, the second exception to canvas theming after the QR plate. Its six
tk-*screens recreate the embedded Transak widget (white, Transak blue, “Powered by Transak”) in both light and dark mode, because a surface that stands for an external system shows that system’s identity.render()setsdata-checkout-provider="transak"on the host;.ui-transak-*is page-local and never used elsewhere. - Error, warning and refund are end states, reached through
showState(kind), not linear steps. Closing the Transak sub-modal mid-flow →cash-cancelled; ⌥-click “Continue to payment” →cash-error(as in the swap widget demo);window.LifiCheckout.show(kind)renders any state from the catalog or console. - Reuse the existing primitives. The token and currency picker is
.ui-token-picker, the amount cards are.ui-amount-card, the receipt is.ui-tx-summary, the checklist is.status-row. Cash quotes come live from the price oracle, never from the old Figma fixtures. - Themed by the canvas, never per component. The LI.FI screens sit inside
[data-palette-canvas], so the Theme Composer re-colours them like the swap widget. - Two surfaces are not themed: the QR plate (white with dark modules, so it scans) and the Transak sub-modal (Transak’s brand). Both stay the same in dark mode.
checkout.js:window.LifiCheckout, the flow state machine (FLOWS·renderScreen· per-step body renderers), the widget-type + host axes, the modal open/close, and the screen wiring.checkout.css: thedata-widget-type/data-checkout-hostgates + the tier-3.ui-checkout-*layout glue.qr.js:window.LifiQR.toSVG, a dependency-free QR generator (Nayuki lineage) for the deposit-address screen.playground.html+swap.css: the rail Widget/Checkout sections, the.checkout-stage+#checkoutModalhosts, and thedata-widget-typeCSS gates.- Spec:
design/components/checkout.md.