Component Catalog

--footer additions

• DOM order = visual order. Author writes the primary action first; both horizontal and stack variants render it where the user expects (right side in horizontal, top in stack).
• Equal-width by default. Two buttons split the row 50/50, three split 33/33/33. Long labels truncate inside the button via its own overflow handling — one button never forces another wider.
• Lead primary + trailing icon is auto-detected — no modifier. A .btn-icon child keeps its square size (flex: 0 0 auto) instead of taking an equal share — a 40 px glyph blown up to half the row reads as broken. The text button(s) beside it fill the remaining width, so a lone .btn-primary becomes the lead CTA with the icon pinned at its natural size. The content shape (an icon-only child) is the trigger; you don’t reach for a class. Canonical consumer: the swap widget footer (Review + Wallet icon).
• Reach for --stack when… labels are long enough to wrap, the container is narrow, or the affirmative needs visual primacy over a destructive sibling (e.g. "Delete account" / "Keep account").
• Margin above the bar is the container's job. The action-bar owns its internal layout and gap only. Inside .modal the body's bottom padding handles the breathing room; inside a drawer or sheet, the host's spacing rule does.
• Don't fork the spacing. Both orientations share var(--cluster-sm) (8 px) — the bar's internal rhythm stays consistent whether buttons stack horizontally or vertically. If a context genuinely needs a different gap, override gap at the call site rather than authoring a new modifier.
• Pair with .modal-divider when actions are destructive. The hairline reinforces the boundary between content and a consequential choice.
• Reach for --footer when neither action is primary. Panel footers that surface peer affordances (Copy code · Read docs, View · Share, Export · Import) want the variant: it adds the top hairline + bottom-pin chrome and the doc convention says "no .btn-primary inside." If one action IS clearly primary, use the bare .action-bar default with the primary button inside — --footer is specifically for the no-clear-winner case.
• --footer assumes a flex-column parent. The margin-top: auto pins the bar to the bottom only when the parent is display: flex; flex-direction: column (e.g. .panel). On a non-flex parent the auto margin is a harmless no-op — the bar still gets its top hairline + padding-top, just doesn't pin.
• Rail footers drop the divider (per-consumer opt-out). The Portal and Playground rail footers reuse --footer for the equal-width neutral-button row but override border-top: 0 on the consumer — the rail's panel gap already separates the footer, so the hairline reads as noise in the narrow column. The shared --footer keeps its divider for modals; only the rail consumers opt out (.portal-rail__foot-links.action-bar--footer in portal.css, .playground-rail__footer.action-bar--footer in swap.css). Don't drop the divider on the component itself.

Semantic tones for .alert. Each tone sets three slots — --a-bg (surface), --a-border, --a-fg (icon container) — plus the unified --a-tone for any future variant-aware state. Foundation semantic tokens drive the recipe; the alert itself just consumes them. Palette-independent so red stays red and green stays green across every brand palette.

Default tone — title + body + dismiss

<div class="alert alert--info">
  <span class="spot-icon spot-icon--info" aria-hidden="true">
    <!-- info glyph -->
  </span>
  <div class="alert-content">
    <p class="alert-title">New chain supported</p>
    <p class="alert-message">Solana mainnet is now routable.</p>
  </div>
  <button type="button"
          class="btn-neutral btn-icon btn-borderless btn-sm btn-circle alert-close"
          aria-label="Dismiss">
    <!-- close glyph -->
  </button>
</div>

Compact .alert--sm · no dismiss

<div class="alert alert--sm alert--warn alert--no-dismiss">
  <span class="spot-icon spot-icon--warn" aria-hidden="true">
    <!-- warn glyph -->
  </span>
  <div class="alert-content">
    <p class="alert-message">Slippage above threshold.</p>
  </div>
</div>

Size ladder

Status tones — surface tokens

Geometry

• Pick by placement, not message tone. Inline page flow → .alert. Floating toast → .notification. Field validation → .form-error. Tone (success / warn / danger) is orthogonal to placement.
• Surface and border always flow from the semantic token triplets. If you find yourself reaching for oklch(…) or a hex value to override the alert surface, the tone vocabulary is wrong — not the token.
• Don’t nest alerts inside alerts. Stacked tinted surfaces muddle the read; the inner alert reads as part of the outer one. Pick the right tone or escalate to .alert--lg.
• Never drop the .spot-icon — it is the non-color disambiguator. Color alone cannot communicate tone (info / success / warn / danger) to readers with color vision deficiency (~8 % of men) and is insufficient for WCAG 1.4.1 Use of Color (Level A). The icon’s SHAPE carries the meaning; the tinted surface is supporting. Dropping the icon “to save space” is an accessibility failure, not a stylistic choice. Applies to every .alert on every surface — product, marketing, catalog — without exception.
• Scope — alert MESSAGES, not inline tonal data. The rule applies to standalone messages where tone IS the meaning (the surface tint communicates urgency / status / error). It does NOT apply to inline tonal data values where the value carries the meaning and color is enhancement — .detail-list__desc--negative showing “-1.34%”, .chip-delta-pos / .chip-delta-neg showing “2.26% 6h”, .ui-quote-list__empty in muted .muted ink. The number and sign are the disambiguator; color amplifies but isn’t sole. Adding icons to every red percentage on a quote card would be noisy and unhelpful. The test: does the element require triage where color is the primary signal? If yes — icon required. If the value alone is readable — no icon needed.
• The code-bearing sibling is .error-detail — the documented tonal-DETAIL carve-out. A verbatim machine echo (RPC revert, webhook failure) hosted under a tone-bearing header shares the alert's --a-* slots and surface recipe but deliberately carries no spot-icon — its meaning lives in its own mono text. Don't “fix” it by adding one, and don't force it into .alert--danger (a second danger icon + a mono fork in the alert's prose typography).
• Compose dismiss + actions on neutral buttons. Dismiss: .btn-neutral.btn-icon.btn-borderless.btn-sm.btn-circle.alert-close. Action buttons inside .alert-actions: .btn-neutral.btn-sm. Neutral keeps every button calm against the alert's tonal context (warn / danger / success / info) — using .btn-primary or .btn-tertiary here paints them brand-blue, which fights the alert tone instead of complementing it.
• Use .alert--no-dismiss when there’s no X. Otherwise the reserved 48 px right column reads as a missing element. The modifier tightens padding to match the size tier.
• Action button copy is imperative and short. “Refresh quote”, “Approve”, “View routes” — not “Click here to refresh your quote”.
• Don’t use alerts for ephemeral feedback. If the message should disappear on its own after a few seconds, it’s a .notification. Alerts stay until the user dismisses them (or the underlying condition clears).

• CSS — styles.css § .alert — inline tone-tinted message banner · search .alert {
• Tokens — --info-bg / --info-border / --info (and --success-*, --warn-*, --danger-*); --a-tone / --a-bg / --a-border / --a-fg on the component
• Spec — design/components/feedback.md → Alert
• Sibling primitives — Notification (floating toast), Spot Icon (leading mark atom), Status Row (multi-step receipts), Form inputs (.form-error for field validation)
• Inspiration — Tailwind UI Plus · Application UI / Feedback / Alerts, restyled with the LI.FI tone tokens and spot-icon family

<!-- Default avatar — 40px (no size modifier needed), shape square (4px) -->
<img class="avatar" src="avatars/chains/ethereum.svg" alt="Ethereum">

<!-- Sizes — xs (24) / sm (32) / default (40) / lg (48) / xl (64) / 2xl (96) -->
<img class="avatar avatar--xs" src="…">
<img class="avatar avatar--sm" src="…">
<img class="avatar avatar--lg" src="…">
<img class="avatar avatar--xl" src="…">
<img class="avatar avatar--2xl" src="…">

<!-- Shapes — square (default) / rounded / circle -->
<img class="avatar avatar--lg avatar--rounded" src="…">
<img class="avatar avatar--lg avatar--circle" src="…">

<!-- Ring modifier — 1px inset alpha border, low-contrast plates -->
<img class="avatar avatar--lg avatar--rounded avatar--ring" src="…">

<!-- Overlap stack — wrapper sets size, children inherit --avatar-size -->
<span class="avatar-stack avatar-stack--lg">
  <img class="avatar avatar--circle" src="avatars/chains/ethereum.svg" alt="Ethereum">
  <img class="avatar avatar--circle" src="avatars/chains/arbitrum.svg" alt="Arbitrum">
  <!-- … -->
</span>

<!-- Stack overflow — "+N more" tile as the last child of the stack.
     Compose with .avatar so it inherits size, shape, and the 2px page-
     coloured outline the stack adds to its .avatar children. -->
<span class="avatar-stack">
  <img class="avatar avatar--circle" src="avatars/chains/ethereum.svg">
  <img class="avatar avatar--circle" src="avatars/chains/arbitrum.svg">
  <img class="avatar avatar--circle" src="avatars/chains/optimism.svg">
  <span class="avatar avatar-stack__more avatar--circle">+12</span>
</span>

<!-- Token + chain tandem — base avatar + corner badge.
     .avatar-badge--br is canonical for "token on chain"; --tr is the
     alternate corner. Use both to render source + destination chains. -->
<span class="avatar-tandem avatar-tandem--xl">
  <img class="avatar avatar--circle" src="avatars/tokens/usdc.svg" alt="USDC">
  <img class="avatar-badge avatar-badge--br" src="avatars/chains/ethereum.svg" alt="on Ethereum">
</span>

<!-- Placeholder — unselected slot. Drop `src` and use `<span>` hosts
     so screen readers skip the empty image. Carries `.avatar--placeholder`
     on the single, `.avatar-tandem--placeholder` on the wrapper (the tandem
     modifier cascades the tint to both base + badge). The consumer chip
     (.chip-avatar) carries the "Select" label and the real aria-label. -->
<span class="avatar avatar--circle avatar--placeholder" aria-hidden="true"></span>

<span class="avatar-tandem avatar-tandem--placeholder" aria-hidden="true">
  <span class="avatar avatar--circle"></span>
  <span class="avatar-badge avatar-badge--br"></span>
</span>

<!-- Composed in a picker chip -->
<button type="button" class="chip-avatar chip-avatar-neutral" aria-label="Select source token">
  <span class="avatar-tandem avatar-tandem--placeholder">
    <span class="avatar avatar--circle"></span>
    <span class="avatar-badge avatar-badge--br"></span>
  </span>
  Select
</button>

<!-- Avatar + name pair — inline label slot. Pair .avatar-label
     with the matching avatar size when the row needs a larger
     identity tile (.avatar-label--lg with .avatar--lg, etc.). -->
<span class="avatar-label">
  <img class="avatar avatar--rounded" src="avatars/chains/ethereum.svg" alt="Ethereum">
  Ethereum
</span>

<!-- Initials monogram — identity tile when no photo / mark exists.
     Auto-derived: data-initial holds the label; shared.js fills the glyph
     (up to 2 letters) + a deterministic .avatar--tone-N from a label hash.
     Host on a <span aria-hidden="true"> when a visible name sits beside it. -->
<span class="avatar avatar--circle" data-initial="Alex Rivera" aria-hidden="true"></span>

<!-- Explicit form — set the tone class yourself (static markup, no JS) -->
<span class="avatar avatar--circle avatar--initial avatar--tone-9" aria-hidden="true">AR</span>

<!-- Flat fill (dense tables) · neutral plate (non-human entities) -->
<span class="avatar avatar--initial avatar--tone-9 avatar--flat">AR</span>
<span class="avatar avatar--initial avatar--tone-neutral" data-initial="System" data-initial-tone="neutral" aria-hidden="true"></span>

<!-- JS-rendered rows (members / orders / audit) — markup string helper -->
var html = window.lifiInitialAvatar('Alex Rivera', { size: 'sm', shape: 'circle' });

Sizes — six-tier --avatar-size ladder, tuned for the cases that ship on the 8 px grid (24 / 32 / 40 / 48 / 64 / 96).

Shapes — --avatar-radius ladder. Every shape clips the same pre-plated 32×32 viewBox.

Cluster sizing — the two cluster wrappers (.avatar-stack, .avatar-tandem) set --avatar-size so children inherit. One declaration sizes a whole cluster; child .avatar--xs/--sm/--lg/--xl/--2xl still wins if explicitly set on a single child.

Tandem badge positions. .avatar-badge renders at 42 % of the parent --avatar-size with a 20 % corner translate so it clips the corner instead of sitting flush inside. The 2 px gap between badge and base is a true cutout — mask-image on the base avatar makes the gap transparent, so whatever surface sits behind the tandem (page, card, tinted panel) shows through.

Stack overflow. .avatar-stack__more is a "+N" text tile that occupies an avatar slot inside .avatar-stack. Compose with .avatar + .avatar--circle so it inherits the cluster's size and shape; the previous avatar's mask cutout creates the gap between it and the rest of the stack.

Avatar-label sizes. Pair the label modifier with the avatar tier sitting inside it. --xs with .avatar--xs, etc. Default keeps the historic 8 px gap / 14 px font that pairs with the default 40 px avatar.

Initials monogram (.avatar--initial). Glyph: Geist, weight 700, uppercase, white; font-size is calc(var(--avatar-size) × 0.4) so it tracks the disc at every tier (the one calc-derived type value in the avatar family — a 2-letter monogram can't sit on a fixed --text-* tier). Plate: a radial of --avatar-tone (one of 12 --spectral-* hues) with its lightness capped to a deep, white-text-safe band via oklch(from var(--avatar-tone) min(l, 0.46) c h) — same value in both themes, so white glyphs clear WCAG AA (5.1:1+) on every tone.

Catalog-meta containers (kept tier-1). .ds-doc-avatar-grid and .ds-doc-avatar-cell are the asset-library display surfaces in #avatars — parallel to .ds-doc-icon-grid / .ds-doc-icon-cell. Catalog-only; never reach for them on product or marketing surfaces.

• Render plated SVGs only. Every file in marks/ ships as a 32×32 viewBox with the brand colour pre-plated as the first <path>. Don't add a CSS background, don't tint, don't recolour with filters. The plate is the brand — post-processing it is a brand violation.
• Don't render full wordmarks through .avatar. Wordmarks are wide-aspect with brand typography baked in; object-fit: cover inside a square plate will crop them. Use .ds-doc-partner-logo (catalog-meta) or a bare <img> inside .logo-cloud-item instead. The .logo-cloud-item > img:not(.avatar) rule constrains by HEIGHT, not WIDTH.
• Pick the shape by context. Square for table cells and dense data; rounded for chips, badges, pricing tiers, feature cards (the iOS-squircle adjacent curve softens without committing to a circle); circle for profile contexts, hero stacks, "latest integration" moments — use the most branded shape when the logo IS the moment.
• Pick the size from the six-tier ladder. 24 / 32 / 40 / 48 / 64 / 96. Don't extend it with one-offs. If a layout asks for 56, pick lg (48) or xl (64) — whichever sits closer to the design intent.
• Set the size at the cluster, not on every child. .avatar-stack--lg and .avatar-tandem--lg set --avatar-size at the wrapper; children inherit. One declaration sizes the whole cluster. Reach for child .avatar--xs/--sm/... only when one item in the cluster needs to differ from the rest.
• Add the ring on low-contrast plates. Ethereum's purple, Polygon's pink, anything that sits within ~10% lightness of --surface-card. Ring is always safe to opt-in — it never makes a high-contrast plate worse.
• Stack means "many of these". Use .avatar-stack for the canonical "integrated with N chains" hero, partner showcase row, or any shipping-context list of brand marks. Three or more avatars makes the stack read as a stack; two reads as a pair (use a row instead).
• Tandem means "this on that". .avatar-tandem represents a primary entity with one or two host/sibling badges — token on chain (badge bottom-right), source on destination (badges top-right + bottom-right), wallet on chain. Don't use the tandem for "many of these" — that's .avatar-stack.
• Badge corner picks the relationship. --br is canonical for "X on Y" (the host badge sits at the bottom-right); --tr alternates when the bottom corner is occupied or the visual rhythm calls for it. Use both (--tr + --br) for source & destination chains in bridging contexts, or --br + --bl for token + chain + bridge/provider. Mirror corners (--bl, --tl) are otherwise uncommon — reach for them only when the row's reading direction makes it necessary.
• One badge per tandem in product surfaces (June 2026). The dual-badge tandems above are documented, RESERVED options with ZERO live consumers — the widget's transaction flow rows (Activity, Transaction details, the execution Received card) AND the connected-wallet status card all carry only the --br chain badge. A second corner mark overloads the avatar; secondary provenance (the bridge/provider, the wallet provider) reads from the row's meta line, the Route detail head, or the body signals instead. Reach for a dual badge only when a future surface genuinely needs two relationships on one mark — and surface it first.
• Use .avatar-stack__more for truncated clusters. Real product surfaces show 3–4 avatars + "+N more" rather than every chain. Compose .avatar avatar-stack__more avatar--circle as the LAST child of the stack so it inherits the cluster's size and shape.
• Cluster gaps are transparent cutouts, not coloured rings. Stack and tandem use mask-image to punch circular holes in overlapping avatars. The gap shows whatever surface sits behind the cluster (page, card, tinted panel) — which is why the same primitive works on every surface without re-tinting.
• Pair the avatar with a name when identity is the subject. .avatar-label is the inline-flex helper for tables, chips, and list-row leads. Pair the size modifier with the avatar tier inside — .avatar-label--lg with .avatar--lg, etc. — so the label text scales with the avatar. For the full row pattern (avatar in lead, name + role in body, action in trail), reach for .list-item + Avatar list.
• Source SVGs live in marks/ only. No component-local copies, no public/images/chain-logo.svg, no base64 inlines. One directory, one source of truth. Add new logos via the Avatars library workflow.
• Pair the placeholder with a "Select" affordance, not a glyph fill. Use .avatar--placeholder on a single avatar (chain / wallet picker) or .avatar-tandem--placeholder on the wrapper (token + chain picker) when no specific brand has been chosen yet. Render the host as <span> with no src — the disc reads as a calm muted shape against the consumer's pill. The empty form IS the affordance; don't add a "?" or "+" glyph (reads as error / add-token) and don't dashed-stroke the disc (competes with real avatars). The consumer chip (.chip-avatar) carries the "Select" label.
• Reach for .avatar--initial when there's no photo or mark. A person, org, or integration with no portrait / brand SVG gets a letter monogram — the Gmail / Slack / Linear convention. Author with data-initial="<label>" and let shared.js derive the glyph (up to 2 letters) + a deterministic --spectral-* tone from the label hash, so the same entity is the same colour on every surface. aria-hidden="true" when a visible name sits beside it (the monogram is redundant); give it a real aria-label only when it stands alone. Use --tone-neutral for non-human entities (System, pending invites), --flat in dense table rows. Don't hand-pick a fill colour — the tone system owns it.

CSS: styles.css § 8d. AVATAR — .avatar — search for .avatar { (monogram variant: .avatar--initial).
Initials JS: shared.js → initInitialAvatars() + window.lifiInitialAvatar(label, opts) — glyph + deterministic --spectral-* tone from a label hash.
Tokens: --avatar-size, --avatar-radius, --space-*, --alpha-dim, --alpha-border-subtle, --surface-page.
Spec: design/components/imagery.md → Avatar. Asset library: design.md §05 → Avatars Asset Library; live grid at #avatars; row pattern at #list-avatar.
Production consumers: index.html chain marquee, playground.html chain rows, page.css .chain-item, design-system/brand-guide.html mark library.

<!-- Numeric count on an icon button -->
<span class="badge-host">
  <button class="btn-primary btn-neutral btn-icon">…</button>
  <span class="badge">4</span>
</span>

<!-- Status tone (success / warn / danger / info / neutral) -->
<span class="badge-host">
  <button class="btn-primary btn-neutral btn-icon">…</button>
  <span class="badge badge-danger">3</span>
</span>

<!-- Dot (no content) — presence / unread marker -->
<span class="badge-host">
  <button class="btn-primary btn-neutral btn-icon">…</button>
  <span class="badge badge--dot"></span>
</span>

<!-- Circular host (avatar, round button) — add .badge-host--circle so the
     badge sits at the host's tangent instead of overhanging -->
<span class="badge-host badge-host--circle">
  <img class="avatar avatar--lg avatar--circle" src="avatars/chains/base.svg" alt="Base">
  <span class="badge">NEW</span>
</span>

<!-- Separation is a TRUE CUTOUT on the host (mask-image) — same pattern as
     .avatar-tandem. The host is the first non-badge child of .badge-host;
     the badge corner gets punched out so whatever surface sits behind shows
     through (page, card, panel, accent halo). No per-surface ring tuning
     needed — the gap is transparent, not painted. -->

• Reach for .badge for indicators, not labels. If the value sits in flow (a tag next to a heading, a status pill in a table row), use .chip. .badge is for ornaments anchored to a host’s corner.
• Default tone is brand accent. Write <span class="badge">4</span> for the dominant “unread items” case; opt into .badge-success, -warn, -danger, -info, or -neutral only when the value carries explicit status meaning.
• Wrap circular hosts in .badge-host--circle. The default offsets overhang past the bounding box, which fights a round host’s tangent. The modifier shrinks the translation so the badge sits at the host’s edge.
• The host receives a mask-image cutout — trust the surface to show through. Same pattern as .avatar-tandem: the badge corner is a real transparent hole, not a painted ring. No per-surface tuning needed; whatever sits behind the host (page, card, panel, accent halo) shows through the gap. Don’t pre-paint a ring colour and don’t add --badge-ring overrides — the cutout is the separation.
• Pick a maskable host. mask-image applies to the first non-badge child of .badge-host. Plain elements (button, img, span, div, avatar) mask cleanly. Avoid hosts that already carry their own mask-image (e.g. an .avatar-tandem wrapper) — the masks conflict. If you need a badge on a tandem, put the badge on the OUTER wrapper, not the tandem itself.
• Keep text to two glyphs plus an optional “+”. 4, 12, 99+, NEW, BETA all fit; longer strings make a badge that competes with the host for attention. If the value won’t fit, the right answer is usually a .chip next to the host instead.
• Don’t overload .badge with interactive content. pointer-events: none is intentional — clicks pass through to the host. Use a .chip or a separate button if the indicator itself needs to be clickable.

CSS: styles.css § 8e. BADGE — search for .badge {.
Tokens: --accent-primary · --on-accent-primary · --success · --warn · --danger · --info · --text-primary · --surface-page · --space-8 · --space-12 · --space-20 · --space-24 · --text-caption · --text-sm.
Cutout: two-layer architecture. CSS ellipse fallback at styles.css § 8e (parallel to .avatar-tandem’s four-layer recipe). SVG mask upgrade at shared.js → initBadgeHosts() — measures each badge with ResizeObserver and writes an inline pill-shaped SVG mask-image to the host for an exact 2px gap.
Spec: design/components/imagery.md → Badge.
Related: #chips (a label in flow, not anchored), #avatar (.avatar-badge is a separate token+chain corner-clip pattern, unrelated to .badge).

Critical colours for .btn-primary. Rest fill inherits the brand accent through the shared --btn-accent slot. The hover recipe (tone-shift + lift glow) is an Override of the system's neutral --overlay-hover default — filled brand buttons need a colour shift, not a neutral wash, to keep the brand identity at the elevated state. The outline variant inverts the same recipe with the same flag mix.

<!-- Filled -->
<button class="btn-primary">Accent 1 Primary</button>
<button class="btn-primary btn-accent2">Accent 2 Primary</button>
<button class="btn-primary btn-accent3">Accent 3 Primary</button>

<!-- Outline -->
<button class="btn-primary btn-outline">Accent 1 Outline</button>
<button class="btn-primary btn-outline btn-accent2">Accent 2 Outline</button>

<!-- Icon-only — append `.btn-icon` and drop an <svg> inside -->
<button class="btn-primary btn-icon">
  <svg viewBox="0 0 24 24">…</svg>
</button>

• One primary CTA per surface. Two filled primaries on the same hero compete; the second should be outline or secondary.
• Match accent to context. Use Accent 1 for the brand action, Accent 2 for product/feature actions, Accent 3 for secondary highlights.
• Outline ≠ disabled. Outline is a valid full-strength action with lower visual weight; pair filled + outline for "Confirm / Cancel" rows.
• Disabled dims to 0.4 and is not interactive. A disabled button — via disabled or aria-disabled="true" — renders at opacity: 0.4 with cursor: not-allowed + pointer-events: none, the same whether it's gated ("Add an address") or busy ("Confirming…"). pointer-events: none is what makes aria-disabled truly non-interactive; for a "why disabled" tooltip, host it on a wrapper, not the button.
• Don't recolour with inline styles. If you need a different accent, add a new --accent-* token; never hardcode style="background:#…".

CSS: styles.css § BUTTONS — search for .btn-primary. Tokens: --accent-primary, --accent-secondary, --accent-tertiary (palette-driven; rotate via the Theme Composer).

Tone token reference across button variants. Every button family consumes the shared --btn-accent* slot system; each variant maps the slots differently to produce filled / muted / transparent / semantic / alpha looks. Brand variants are palette-aware; semantic variants override the slots with palette-independent tokens; alpha overrides them with literal alpha.

<!-- Three tones, one anatomy -->
<button class="btn-primary">Primary</button>
<button class="btn-secondary">Secondary</button>
<button class="btn-tertiary">Tertiary</button>

<!-- Semantic — standalone, palette-independent -->
<button class="btn-destructive">Delete</button>
<button class="btn-success">Save</button>

<!-- Neutral — workhorse tone, theme-adaptive currentColor overlay
     (white at 8 % in dark mode, black at 8 % in light mode). Same base
     shape, sizes, and icon variants as every other button type — compose
     with .btn-sm / .btn-lg / .btn-with-icon / .btn-icon / .btn-circle. -->
<button class="btn-neutral">Neutral button</button>
<button class="btn-neutral btn-with-icon">Neutral with icon</button>
<button class="btn-neutral btn-icon" aria-label="Add"><svg>…</svg></button>
<button class="btn-neutral btn-sm">Small</button>

<!-- Inside .alert--info / --success / --warn / --danger, the neutral
     button automatically picks up the alert's semantic tone via --a-tone.
     That's why .alert-close composes .btn-neutral.btn-icon.btn-borderless. -->

• Match accent to context. Accent 1 for the brand action; Accent 2 for product feature; Accent 3 for promotional / non-enterprise.
• One primary per surface. Two filled primaries on the same view compete; the second should be secondary or outline.
• Semantic buttons bypass the palette. .btn-destructive and .btn-success stay constant across palette swaps for safety reasons.
• Neutral buttons inherit tone from the surrounding context. Theme-adaptive by default — on a regular page surface the neutral picks up the page's primary text colour at 8 % overlay. Inside an alert with a semantic tone (info / success / warn / danger), the neutral picks up that tone automatically — which is why neutral is the canonical button for dismiss X and in-alert actions: it complements the tonal context instead of fighting it with brand-blue. Compose with the same modifiers as any other button — .btn-sm / .btn-lg for size, .btn-with-icon for trailing arrow, .btn-icon + .btn-circle for icon-only and round variants.
• Reach for Neutral when you have many buttons. Primary is the one-per-screen CTA; Secondary pairs with Primary in dialogs and cancel/confirm shapes; Neutral is the default everywhere else — toolbar buttons, settings rows, dismiss X, FAB chrome, footer socials, any "many buttons present, none of them THE action" surface. If you find yourself reaching for Primary for the second time on a single screen, the second one wants to be Neutral (or Secondary if it pairs with a clearly stronger action).
• Link buttons inherit color from accent. Add .btn-accent2 or .btn-accent3 to switch.
• Inline .ds-doc-link needs explicit class. The global a reset makes plain anchors invisible — every visible link needs .ds-doc-link or a button class.

<!-- Four sizes — append the modifier to any .btn-* variant -->
<button class="btn-primary btn-sm">Small</button>
<button class="btn-primary">Medium</button>
<button class="btn-primary btn-lg">Large</button>
<button class="btn-primary btn-xl">X-Large</button>

Every dimension is a --space-* token (4n only) or a typography token. No off-grid pixels. Three progressive ladders run in lockstep — heights, labels, and radii — with the calc-based line-heights widening the line-box on lg / xl so a bigger label still lands on the 8px height ladder. The radii resolve via calc() off --button-radius (the lg-tier anchor, 16px): sm = −8, default = −4, lg = the bare token, xl = +4. Sliding --button-radius in the playground scales the whole ladder while keeping the +4 steps.

Sibling pairing. .btn-sm ↔ .input--sm · .seg-sm · .switch-sm; default ↔ default; .btn-lg ↔ .seg-lg · .input--lg · .switch-lg; .btn-xl ↔ .seg-xl. Segs are fully aligned across all four tiers; .input--lg still drifts to ~50px, and .input--xl / .switch-xl haven't been added yet.

• Three progressive ladders, all on tokens. Heights step +8 (32 / 40 / 48 / 56), labels step +2 (12 / 14 / 16 / 18 — caption / sm / body / body-lg), radii step +4 (8 / 12 / 16 / 20, derived via calc() off --button-radius). Every value is a --space-* or --text-* token — no off-grid pixels.
• Heights emerge from token math. padY × 2 + line-box + 2px border = height. The calc-based line-heights on lg / xl widen the line-box (22px) so a bigger label still lands on the 8px height ladder. Sm uses the same trick to fit a 12px glyph in a 14px line-box at 32px height.
• Pair size to the row. .btn-sm next to .input--sm / .seg-sm / .switch-sm; default next to default; .btn-lg next to --lg; .btn-xl next to .seg-xl (input / switch xl tiers pending).
• Don't override line-height by hand. The line-height tokens are tuned so the label sits on the 8px height ladder — overriding breaks the math. If you need a different label size, switch the .btn-* size tier.
• Don't mix sizes within one button row. A small button next to a default button breaks the visual rhythm — pick one size per row.

<!-- Buttons are static by default — no class needed -->
<button type="button" class="btn-primary">Save</button>

<!-- Compose .btn-lift to opt IN to the hover lift + glow -->
<button type="button" class="btn-primary btn-lift">Get started</button>
<button type="button" class="btn-secondary btn-lift">Learn more</button>
<button type="button" class="btn-primary btn-outline btn-lift">Book a demo</button>

<!-- Stacks with every other modifier (.btn-lg, .btn-with-icon, etc.) -->
<button type="button"
        class="btn-primary btn-lg btn-with-icon btn-lift">Start free</button>

• Static is the default; .btn-lift is the opt-in. May 2026 inversion — every button holds still on hover (bg / color / border wash only). That's the right default for product UI: dense rows, toolbars, forms, cards, and short-height containers where a lift would clip or read as fidgety. You no longer declare anything to get the static behavior.
• Reach for it on marketing surfaces. Landing-page hero CTAs and spacious website sections, where the -1 px to -2 px nudge + glow reads as inviting. Rarely the right call inside product UI — compose it deliberately, per-button, not as a blanket default.
• It adds transform + box-shadow on hover, purely additively. The bg / color / border wash already fires on the static base; .btn-lift layers the lift and the tightened cast-shadow glow on top. Per-variant values: -2 px on filled / outline / neutral, -1 px on secondary / tertiary; tertiary lifts without a glow.
• Composes with every variant and every modifier. Stack onto .btn-primary / .btn-secondary / .btn-tertiary / .btn-destructive / .btn-success / .btn-neutral, plus .btn-outline, .btn-icon, .btn-circle, .btn-block, the .btn-sm / .btn-lg / .btn-xl sizes, and the .btn-accent2 / .btn-accent3 tints.
• Replaces the retired .btn-static. Inverted polarity — .btn-static used to opt OUT of a lift-by-default; now static is the default and .btn-lift opts in. Don't reach for .btn-static; it no longer exists.

CSS — styles.css · search .btn-lift (sits at the end of the button-family block, just before 1b. SEGMENTED CONTROL). Per-variant :hover rules, each fully qualified (variant + modifier) so the lift is purely additive over the static base; outline selectors carry one extra class so their tighter glow wins on specificity.
Spec — design/components/actions.md → Modifier — .btn-lift.
Why this exists — product UI is mostly static surfaces (dense rows, forms, toolbars) where a hover lift clips or reads as fidgety; the lift is mostly wanted on marketing CTAs. Making static the default (May 2026 inversion) stopped contributors from having to declare .btn-static on nearly every product button; the rare lift is now the opt-in.

<!-- Canonical: full-width CTA, label left + arrow right -->
<button type="button"
        class="btn-primary btn-block btn-with-icon btn-justify">Start building</button>

<!-- .btn-with-icon's ::after IS the Lucide arrow-right (a currentColor mask),
     so no <svg> is needed for the arrow. Pass an explicit child only for a
     DIFFERENT trailing icon (a chevron, a count); here it's the same arrow: -->
<button type="button"
        class="btn-primary btn-block btn-with-icon btn-justify">
  Connect wallet
  <svg viewBox="0 0 24 24" width="20" height="20" stroke="currentColor" stroke-width="2">
    <path d="M5 12h14"/><path d="m12 5 7 7-7 7"/>
  </svg>
</button>

<!-- Stacks with size + accent like any other button -->
<button type="button"
        class="btn-secondary btn-block btn-with-icon btn-justify btn-lg">Review your bridge route</button>

• It's pure layout — only flips justify-content to space-between. No width, no colour, no size baked in. Compose it; don't expect it to carry anything else.
• Needs a box wider than its content. On a shrink-wrapped inline button there's no free space to distribute, so the spread is invisible. Pair .btn-block for full width, or give the button a fixed / contextual width. A bare .btn-justify that "does nothing" is almost always a missing .btn-block.
• The arrow is the existing .btn-with-icon mechanism, not a new one. .btn-with-icon supplies the trailing affordance — its ::after renders the library Lucide arrow-right as a currentColor mask with no markup, so the default arrow matches an explicit <svg> child exactly. Pass a child <svg> only for a different trailing icon. .btn-justify just pushes that affordance to the trailing edge, so the trailing slot stays open for non-arrow content too (a count, a chevron).
• Long labels never collide with the icon. The base gap (--space-8) is honoured as the minimum under space-between — when the label grows to fill the row, the 8 px gap holds instead of the two items touching.
• Composes with every variant, size, and accent. Stack onto any type (.btn-primary … .btn-neutral), .btn-outline, the .btn-sm / .btn-lg / .btn-xl sizes, .btn-lift, and the .btn-accent2 / .btn-accent3 tints. Canonical full shape: .btn-primary .btn-block .btn-with-icon .btn-justify .btn-lg.
• It's space-between by design — not centered-label-with-edge-arrow. The centered-label look (label optically centred, arrow absolutely positioned) is a different shape that can collide on long labels. .btn-justify pushes label and icon to opposite edges precisely because that stays collision-proof at any length.

CSS — styles.css · search .btn-justify (one line, right after .btn-block in the button-family block). Single-class specificity declared after the type rules, so it beats the base justify-content: center on source order.
Spec — design/components/actions.md → Modifier — .btn-justify.
Canonical consumer — the Launchpad destination cards (index.html), which dropped their page-local "centred-label + absolute-arrow" override for .btn-block .btn-with-icon .btn-justify .btn-lg when this modifier was promoted (May 2026).

<!-- Bare — auto trailing arrow (no svg needed) -->
<button class="btn-secondary btn-with-icon">View routes</button>

<!-- Leading icon — svg BEFORE the label -->
<button class="btn-primary btn-with-icon">
  <svg><!-- icons/wallet.svg --></svg>
  Connect wallet
</button>

<!-- Leading + trailing — two svgs; the auto-arrow is suppressed -->
<button class="btn-neutral btn-with-icon">
  <svg><!-- icons/arrow-left-right.svg --></svg> Swap <svg><!-- icons/arrow-right.svg --></svg>
</button>

• Position is by DOM order. An <svg> before the label renders left, after renders right, both renders both. The base rule hides loose button svgs ([class*="btn-"] > svg { display: none }); .btn-with-icon is the opt-in that reveals them.
• Bare = auto trailing arrow. With no <svg>, ::after draws the library arrow-right (a currentColor mask, sized --space-20). Providing any <svg> suppresses it (.btn-with-icon:has(svg)::after { display: none }) — so you never get a stray arrow next to your own icon.
• Label-optimized padding stays. .btn-with-icon keeps the text button's asymmetric padding + --space-8 gap — it's a label button that happens to carry an icon. For an icon with no label, reach for the icon-hugging .btn-icon instead.
• Composes with the family. Stacks with any tone (.btn-primary / .btn-secondary / .btn-neutral / …), any size (.btn-sm / .btn-lg / .btn-xl), .btn-block (full-width), and .btn-justify (label and icon pushed to the edges — the Launchpad CTA pattern).

<!-- Bare primitive — 28 px on a quiet surface -->
<span class="ui-swap-arrow" aria-hidden="true">
  <svg …>…</svg>
</span>

<!-- FAB tier — 32 px button, glass surface -->
<span class="ui-swap-arrow ui-swap-arrow--lg ui-swap-arrow--glass" aria-hidden="true">
  <svg …>…</svg>
</span>

<!-- In .ui-amount-pair (vertical orientation) — cutout + hover scale auto-on -->
<span class="ui-swap-arrow ui-swap-arrow--lg ui-swap-arrow--vertical" aria-hidden="true">
  <svg …>…</svg>
</span>

/* Per-instance override — bump cutout without touching the primitive CSS */
<span class="ui-swap-arrow ui-swap-arrow--lg"
      style="--swap-arrow-cutout: var(--space-8); --swap-arrow-cutout-color: var(--surface-page);">
  <svg …>…</svg>
</span>

Modifier matrix

Custom-property API

Cutout is a consumer concern, not a FAB primitive concern. The pair / container masks its sibling cards to punch a real hole through them — see .ui-amount-pair for the canonical mask geometry. The FAB primitive itself carries no cutout chrome anymore (the box-shadow ring approach was retired in favour of true mask cutouts, same technique as .avatar-tandem badge cutouts).

Box-shadow composition (simple). The base rule paints just the composable extra-shadow slot:

box-shadow: var(--swap-arrow-extra-shadow);

Cutout (consumer-side). Cards inside .ui-amount-pair are clipped with a mask-image: radial-gradient(...) that punches a real hole at the FAB's location. Same technique as .avatar-tandem badge cutouts. The geometry on each card:

/* Top card — bottom-center cutout, centered on the seam */
.ui-amount-pair > .ui-amount-card:first-of-type {
  mask-image: radial-gradient(
    circle calc(var(--swap-arrow-size) / 2 + var(--swap-arrow-cutout))
    at 50% calc(100% + var(--card-gap) / 2),
    transparent 99.5%, black 100%
  );
}

/* Bottom card — top-center cutout, mirrored above the top edge */
.ui-amount-pair > .ui-amount-card:last-of-type {
  mask-image: radial-gradient(
    circle calc(var(--swap-arrow-size) / 2 + var(--swap-arrow-cutout))
    at 50% calc(var(--card-gap) / -2),
    transparent 99.5%, black 100%
  );
}

• Mask, not shadow. The cards become truly transparent at the cutout. Whatever surface sits behind the pair shows through — the panel surface in the canonical use, but the same recipe works on a page bg, a gradient, or any backdrop. No color matching required.
• Cutout radius = FAB radius + clearance = --swap-arrow-size / 2 + --swap-arrow-cutout. With defaults (32 px FAB, 4 px clearance), the radius is 20 px. Both math terms are CSS vars; override either and the cutout recalculates automatically.
• Cutout center is on the seam. Top card: center at (50%, 100% + card-gap/2) — just below the bottom edge, in the middle of the visible inter-card gap. Bottom card: center at (50%, -card-gap/2) — just above the top edge, in the same gap. The FAB's own center is at this seam point too (per the negative-margin seam math on the pair), so the cutout and the FAB are concentric.
• Crisp edges via transparent 99.5%, black 100%. Same trick as .avatar-tandem — the gradient's hard transition prevents the cutout edge from antialiasing into a soft halo.
• Hover — size, not transform. The hover state animates width + height from --swap-arrow-size to --swap-arrow-hover-size. The SVG inside consumes --swap-arrow-icon-size directly (no transform), so it stays geometry-pinned while the button grows around its center.
• The seam math reads the REST size, not hover. Card masks are computed from --swap-arrow-size (rest); they don't follow the FAB on hover. If hover-scale were active, the FAB would temporarily overhang the mask edge — deliberate. Cards stay put.

• Tokens are the API. Reach for the --swap-arrow-* token before re-authoring the primitive CSS. The defaults work for most cases; the per-instance overrides cover the rest.
• Size and icon-size are independent. Changing --swap-arrow-size alone doesn't touch the icon — that's the whole point of the scale-on-hover working. If you need a bigger icon too, set both --swap-arrow-size AND --swap-arrow-icon-size (the --lg modifier does both atomically).
• Cutout is a mask on the cards, not a ring on the FAB. Earlier (May 2026 first pass), the FAB carried a box-shadow ring that tried to fake a cutout by painting in the surface-beneath color. It looked correct only when that color was set carefully — and the cards never actually had a hole. The current architecture mirrors .avatar-tandem: the consumer (e.g. .ui-amount-pair) masks its sibling cards with a radial-gradient that punches a real transparent hole, and the FAB itself carries no cutout chrome. Whatever surface sits behind the cards shows through — no color matching required.
• Hover scale opt-in, not default. The base primitive has --swap-arrow-hover-size: var(--swap-arrow-size) (= no visible scale). Consumers that want the polish opt in. .ui-amount-pair previously opted in at 44 px but was reverted (caused layout / paint artifacts at the seam) — the token is preserved for future consumers in contexts where the animation doesn't conflict with surrounding geometry.
• Don't re-author the box-shadow. The base rule paints only var(--swap-arrow-extra-shadow) — one slot, intended for the surface-chrome shadow (e.g. --glass fills it with --shadow-panel-glass). Hand-authoring box-shadow on a modifier replaces that slot and loses the composability.
• Glass + mask cutout stack correctly. The glass surface modifier composes through the --swap-arrow-extra-shadow slot — it paints inside the FAB's box-shadow only. The card cutout (mask on the siblings) is independent and the two never conflict; the FAB renders glass shadow on its own footprint while the cards render a real hole at the FAB's location.
• Use aria-hidden="true" on the host. The button is decorative chrome; the real action handler lives elsewhere (e.g., a parent click handler on the pair). Screen readers should skip the FAB.

Tone palette for .chip. Nine tones — three brand accents + four semantic states + a neutral + a muted. Each renders at 12% tint bg with full-strength text colour (neutral pulls 8% with primary ink; muted pulls 6% with muted ink to read as de-emphasized). The outline modifier drops the bg and paints the border in currentColor so the tone stays.

<!-- Filled tone -->
<span class="chip chip-accent1">Active</span>

<!-- Outline modifier — composes with any tone -->
<span class="chip chip-accent1 chip--outline">Active</span>

<!-- Sizes — append --md / --lg / --xl -->
<span class="chip chip-accent1 chip--lg">Hero label</span>

<!-- Icon-left — place SVG before the text -->
<span class="chip chip-success">
  <svg class="chip-icon" viewBox="0 0 24 24">…</svg>
  Live
</span>

<!-- Icon-right — place SVG after the text -->
<span class="chip chip-neutral">
  Open
  <svg class="chip-icon" viewBox="0 0 24 24">…</svg>
</span>

Four size tiers anchored to the type scale (caption / sm / body / body-xl). The default is the print-safe floor (12 px). Each tier matches a button / input / stat-card tier — the chip is chrome, so it sits at or just under the affordance it labels, never at the same visual weight as the button it neighbours.

Print & web compatibility. Every tier hits or exceeds the 12 px legibility floor enforced by the lifi-figma-press export pipeline (2× retina → US-Letter PDF). The default tier IS the floor — there's no --xs / sub-12 px variant. If a layout feels too dense, reach for tighter padding via spacing tokens; never shrink the type below 12 px.

• Pick the tone from semantic intent. --success for delivered, --warn for pending, --danger for failed, accent tones for product / scope, .chip-neutral for active/static labels, .chip-muted for de-emphasized / inactive states (expired, archived, terminal). Neutral and muted share the grey fill family — neutral keeps primary ink, muted drops to --text-muted so it recedes.
• Pick the size by the affordance you sit next to. Chip is chrome — it labels content, doesn't act on it. Match the chip tier to the button / input tier it neighbours: default chip ↔ .btn-sm, .chip--md ↔ .btn, .chip--lg ↔ .btn-lg, .chip--xl ↔ .btn-xl / hero. The chip ends up shorter than the button at every tier — that's the visual signal "this is a label, not an affordance".
• Add .chip-icon only when the icon adds information. A Lucide glyph that reinforces the meaning (✓ for live, ⚠ for warn, → for an actionable chip) is welcome; a decorative icon adjacent to a self-explanatory label is just chrome. Position by DOM order — icon before the text for status, after the text for action / arrow.
• Outline vs filled is a context call, not a tone call. Filled reads as a status badge; outline reads as a tag / category. Don't mix the two in the same row — pick one shape and commit.
• Don't stack accent tones in a single row. A row of accent1 chips reads as one family; a row mixing accent1 + accent2 + accent3 reads as inconsistent. Lean on one tone unless the chips genuinely encode different categories.
• Interactive only when the host says so. A <span class="chip"> is a static label — no cursor, no hover, no focus ring. Render the chip as <button class="chip"> (action) or <a class="chip" href="…"> (navigation) and the system auto-adds cursor: pointer, a tone-aware :hover (currentColor 14%), a deeper :active (currentColor 20%), and an accent :focus-visible outline. Same recipe as .chip-avatar — the hover deepens the chip's own tone rather than washing it with a neutral overlay.

Six visual states. Hover and active deepen the chip's tone via currentColor mix so every chip-avatar tone shifts correctly without per-tone overrides. Focus uses an accent-primary outline; selected uses the canonical accent-primary @ 12% fill (matches .list-item--selected); locked drops the fill to a hairline outline for read-only values.

<!-- Composite avatar (token + chain badge) -->
<button type="button" class="chip-avatar chip-avatar-neutral">
  <span class="avatar-tandem">
    <img class="avatar avatar--circle" src="…/usdc.svg" alt="">
    <img class="avatar-badge avatar-badge--br" src="…/ethereum.svg" alt="">
  </span>
  USDC
</button>

<!-- Single avatar (any .avatar shape) -->
<span class="chip-avatar chip-avatar-neutral">
  <img class="avatar avatar--circle" src="…/ethereum.svg" alt="">
  Ethereum
</span>

<!-- Placeholder — unselected picker. Use <button> + aria-label
     so the affordance is announced; placeholder discs are decorative. -->
<button type="button" class="chip-avatar chip-avatar-neutral" aria-label="Select source token">
  <span class="avatar-tandem avatar-tandem--placeholder">
    <span class="avatar avatar--circle"></span>
    <span class="avatar-badge avatar-badge--br"></span>
  </span>
  Select
</button>

<!-- Locked — read-only value (a constrained pair). Non-button span;
     transparent fill + hairline outline + muted label, fully inert. -->
<span class="chip-avatar chip-avatar-neutral chip-avatar--locked" aria-label="Sell token (locked)">
  <span class="avatar-tandem">…</span>
  ETH
</span>

<!-- Borderless — no chrome at rest; tone fill reveals on hover.
     Pair with <button> (the hover is the affordance). -->
<button type="button" class="chip-avatar chip-avatar-neutral chip-avatar--borderless">
  <span class="avatar-tandem">…</span>
  ETH
</button>

• Standalone primitive. Decoupled from the .chip family (May 2026 v2). Own tones, sizes, outline, interactive states. Tweaks here don't leak into .chip and vice versa.
• Pick the chip-avatar tier, don't pick the avatar size. The chip-avatar root cascades --avatar-size to .avatar-tandem, .avatar, .avatar-badge, and the cutout mask. Omit explicit .avatar--sm/--md on the inner image.
• Default is the canonical swap-widget size. May 2026 v3 raised the default from 24 px to 40 px so the tandem badge reads at confident scale. Reach for default whenever you have an avatar-led identity in a chip.
• Render as <button> when interactive. Cursor + tone-aware hover (currentColor @ 14%) + active (@ 20%) + 2px accent-primary focus outline are wired automatically. Recipe matches .list-item--interactive.
• Borderless for no-chrome-at-rest pickers. .chip-avatar--borderless drops the resting tone fill + border so only the avatar + label show; the tone wash reveals on hover / press / focus, surfacing the pill’s footprint exactly as a filled chip would. Same ghost pattern as .seg--borderless and the borderless .btn-icon — it suppresses chrome only, leaving the interactive recipe untouched. Pair with a <button> host, where the hover IS the affordance; on a static <span> it reads as simply chrome-less. Composes with any tone and size tier.
• Selected via .is-selected. Identical recipe to .list-item--selected: accent-primary 12% bg + primary text. Palette-aware. Selected wins on hover.
• Universal — not swap-widget specific. Token chooser, chain chip, partner chip, wallet chip, sub-product chip — same recipe.
• Placeholder for unselected pickers. Compose .avatar-tandem--placeholder (token + chain) or .avatar--placeholder (chain-only) inside the chip with “Select” copy when no specific brand has been chosen yet. The chip's aria-label carries the affordance — the placeholder discs are decorative. Don't dashed-stroke the disc and don't add a glyph; the empty form is the signal.
• Label auto-quiets to muted ink when placeholder content is present. A :has() rule on .chip-avatar shifts the label color to var(--text-muted) whenever a .avatar--placeholder or .avatar-tandem--placeholder sits inside — so “Select” reads as a prompt next to the muted disc, not a confident value label. Weight stays 700 so the placeholder mirrors the typographic shape of a real token symbol (designers scan the same pill silhouette); only the ink intensity signals “awaiting” vs “committed.” Font-size stays on the size ladder so the chip's height tier holds. The moment a real avatar binds, the selector stops matching and the chip snaps back to primary ink. Markup stays clean — no .is-placeholder opt-in.
• Locked for read-only values, not disabled controls. .chip-avatar--locked shows a committed value the user can SEE but can't change in context — the canonical case is the Modify-limit-order pair (modifying an order can't re-pick the tokens). It drops the tone fill to transparent + a --border-subtle hairline outline, mutes the label to --text-muted, and is fully inert (pointer-events:none); the avatar stays full-opacity so the token stays recognizable. This is deliberately NOT the system's disabled recipe (uniform 0.4-opacity dim + not-allowed, see the .btn-* disabled family) — locked = read-only value, disabled = unavailable control. Native <button class="chip-avatar" disabled> picks up the same read-only treatment.

<!-- Wrapper composes .chip + a tone + .chip-edit. data-chip-edit opts
     into the toggle wiring in shared.js initChipEdit(). -->
<span class="chip chip-edit chip-neutral" data-chip-edit>
  <button type="button" class="chip-edit__label" data-chip-edit-label>Custom</button>
  <span class="chip-edit__field" hidden data-chip-edit-field>
    <input type="text" class="chip-edit__input" value="+0.0" data-chip-edit-input>
    <span class="chip-edit__suffix">%</span>
  </span>
</span>

• The label IS the affordance. Pick short, descriptive copy ("Custom" / "Set tip" / "Edit name") that tells the user the chip is editable. Don't reach for a pencil icon — the previous icon-driven pattern was retired when this primitive landed because the icon competed with the chip's tone tier for visual attention.
• Composes any .chip tone. .chip-neutral for default editable, .chip-success for "on target" semantics, .chip-warn / -danger for "off target" feedback. The tone applies to both label and edit states — the chip reads as one tonal unit regardless of which mode it's in.
• Field hugs content via field-sizing: content (Chrome 123+, Firefox 128+, May 2024). 5ch fallback for older browsers. Don't author a fixed input width unless you have a specific layout reason — the chip should feel snug around its value.
• Toggle behavior owned by shared.js → initChipEdit(). Click __label → activate (hide label, show field, focus + select input). Enter / Escape / blur → deactivate. Idempotent (data-chip-edit-wired stamp prevents double-binding) so re-running after dynamic markup is safe.
• Consumer wires value semantics, not toggle semantics. Listen to input on data-chip-edit-input for typing; blur for commit / revert. Don't add your own click listeners on the label or visibility-toggle code — the primitive owns that and the JS will fight your handlers.
• Accessibility — the input carries the aria-label, not the wrapper. Label text is purely visual ("Custom"); the input's aria-label tells screen readers what's being edited ("Offset percent", "Tip percent", "Slippage tolerance"). When the chip's value matters semantically (live data), set aria-live="polite" on the wrapper so screen readers announce tone / value changes.
• [hidden] + display: inline-flex needs an explicit override. The .chip-edit__field rule sets display: inline-flex, which wins over the user-agent stylesheet's [hidden] { display: none }. A scoped .chip-edit__field[hidden] { display: none } rule restores the contract. General lesson: any flex container that toggles via [hidden] needs this carve-out.

Implementation:

• styles.css — .chip-edit rules. Search the section comment "inline-editable chip primitive".
• shared.js — initChipEdit() function (toggle wiring, idempotent). Called from the main DOMContentLoaded init list.
• design/components/chips.md — spec section "Editable chip — .chip-edit".

Canonical consumer: .ui-limit-price-card's proximity / custom-offset slot — composes .chip-edit for the toggle chrome and adds its own scope class for tone updates.

Semantic tones for .chip-delta-*. Three variants bound to foundation semantic tokens — up is always green, down is always red, flat is muted. Bg renders at 14% tint (8% for neutral); text at full strength. Palette-independent.

Arrow icons inline from the DS icon library — Lucide v1.8.0 arrow-up / arrow-down at stroke-width="2" (product surface). The .chip-icon slot auto-sizes the SVG via the chip family's tier scale (12 · 16 · 16 · 20 px).

Delta chips inherit the chip family's grid-aligned size scale (24 / 32 / 40 / 48 px). The arrow slot scales with the chip tier — see the size column for the resolved arrow size at each step.

• Pick size by neighbouring metric. The size tracks the stat the delta annotates, not the button across the row. Buttons are affordances; deltas are chrome.
• Use in stat-card footers, table cells, or beside hero metrics. Always in their own UI cluster with the metric they describe.
• Don't use inline in body text. The tinted background fights prose.
• Don't match delta size to button size. They never share a height even when they share a font.
• Three tones only. --pos (success), --neg (danger), --neutral (muted ink for zero).

The chip carries arrow + value + optional .chip-window child for the time-interval label. No outer pair-wrapper — the chip itself is the cluster. Window text inherits the chip's font-size so it scales with the size tier; the chip's gap drives the rhythm between icon → value → window.

Bare drops the four chrome dimensions; everything else (gap, font-size, line-height, tone color, tabular-nums on delta chips) passes through from the composed classes.

Sub-slots inside the chip

Two chip-family sub-element classes compose inside a bare (or filled) chip to carry leading and trailing content:

Light-mode guard

The seven [data-theme="light"] .chip-tone:not(.chip--outline):not(.chip--bare) overrides exclude bare from the tone-bg re-paint — same pattern as .chip--outline's exclusion. No per-card work needed.

• Three chrome modifiers are mutually exclusive. Pick ONE per chip: filled (default) or .chip--outline or .chip--bare. They live on the same axis — composing two of them is a smell.
• The time-interval label sits INSIDE the chip via .chip-window. The chip family carries a dedicated muted-secondary-text slot for inline annotations; no outer pair-wrapper, no sibling .muted. Window text inherits the chip's font-size so it scales with the size tier; color: var(--text-muted) on the slot breaks the tone inheritance so the value still leads visually.
• Reach for .chip-window for any "muted secondary text inside a chip" use case, not just time-windows. Token chips with "Active", chain badges with chain count, status chips with timestamp — same slot, same recipe. Never inline style="color:var(--text-muted)" on an ad-hoc span instead.
• Bare is for tight inline compositions, not for "I want a quieter chip." If a chip needs to feel calmer but still read as a UI element, lower the tone opacity at the call site (or reach for .chip-neutral). Bare is the choice when the chip should disappear into the surrounding text.
• Size modifiers still apply to type, not chrome. .chip--bare.chip--md renders at 14 px with an 8 px arrow-gap but no padding or row-height. .chip--lg jumps to 16 px / weight 700, etc. Pick the size tier by the surrounding type size, not by the chip's role.
• Don't reach for bare inside a row that already carries filled chips. Mixing chrome tiers in the same cluster fights the visual rhythm — filled chips read as discrete UI units, bare chips read as inline text, and the eye loses the rhythm. One chrome tier per cluster.

Implementation:

• styles.css — .chip--bare rule. Search the section comment "Bare modifier — drops every chrome dimension". Sits next to .chip--outline in the chip family block.
• styles.css — .chip-window rule. Search "Window slot — supplementary muted text inside a chip". Sits between .chip-icon and the chip size modifiers.
• styles.css — light-mode tone-bg guards. Search :not(.chip--outline):not(.chip--bare) — one line per tone (7 selectors).
• playground.html — canonical consumer at .ui-token-info__deltas. ETH spot deltas in Limit-mode Receive panel.
• design-system/index.html#delta-chip — canonical filled delta-chip family; .chip--bare + .chip-window compose with the same three tones.

<div class="chip-shortcuts" role="group" aria-label="Send amount shortcuts">
  <button type="button" class="chip chip-neutral">25%</button>
  <button type="button" class="chip chip-neutral">50%</button>
  <button type="button" class="chip chip-neutral">75%</button>
  <button type="button" class="chip chip-neutral">MAX</button>
</div>

Slots

• Wrapper .chip-shortcuts — inline-flex row, nowrap, gap: var(--space-4) default. Carries role="group" + aria-label so the cluster announces as a related set.
• Children = .chip family — any chip variant works. Tone via .chip-neutral / .chip-success / etc.; size via .chip--md / --lg / --xl per child.
• Auto-adapting gap — wrapper detects the largest chip tier inside via :has() and bumps gap to match: default --space-4, lifts to --space-8 for md/lg, --space-12 for xl.
• Behavior modifier --reveal-on-hover — opt-in staggered fade-in from the right; see the demo below.

• Each chip is a button, not a static chip. The shortcuts are actions that fire a value into a paired field. Always <button type="button">, never <span>, never a link.
• Size on the child, not the wrapper. Don't invent .chip-shortcuts--lg — the chip family already ladders sm/md/lg/xl. Putting .chip--lg on each child gets you a 40 px cluster; the wrapper auto-adapts gap.
• Reach for it when there's a discrete set of preset values. 3-7 items is the sweet spot. Past 7, switch to a .dropdown or a number stepper — a chip row that scrolls horizontally is a misuse.
• Pair with a numeric input. The cluster is shortcuts to set a value; without a target field they're orphaned. Place inside the input card's header (swap pattern) or directly above/below the input.
• Use --reveal-on-hover selectively. Surfaces with hover (desktop product canvases) benefit from the reveal flourish — the chips read as "advanced shortcut" affordances. On touch / keyboard-only / printed contexts, leave chips visible.

<!-- Default -->
<div class="chip-shortcuts">
  <button class="chip chip-neutral">25%</button> …
</div>

<!-- Medium / Large — size class lives on each child -->
<div class="chip-shortcuts">
  <button class="chip chip-neutral chip--md">25%</button> …
</div>
<div class="chip-shortcuts">
  <button class="chip chip-neutral chip--lg">25%</button> …
</div>

<div class="ui-amount-card__header">
  <span class="ui-amount-card__label">Send</span>
  <div class="chip-shortcuts chip-shortcuts--reveal-on-hover"
       role="group" aria-label="Send amount shortcuts">
    <button type="button" class="chip chip-neutral">25%</button>
    <button type="button" class="chip chip-neutral">50%</button>
    <button type="button" class="chip chip-neutral">75%</button>
    <button type="button" class="chip chip-neutral">MAX</button>
  </div>
</div>

• Three trigger contracts — all fire automatically. Self-hover (hover the cluster itself), direct-parent hover via :has(>) in the universal rule (hover the immediate ancestor of the cluster), and ANCESTOR hover inside .ui-amount-card (hover anywhere on the card — header, body, footer). The card-level trigger is the canonical pattern for the swap widget; the smaller header-only target felt skittish in user testing. All three triggers accept :focus-within so keyboard users tab in and chips reveal.
• Availability gate via the hidden attribute. The chips are a percentage shortcut — if there's no balance to take a percentage of, the chips are dead buttons. Consumers toggle native hidden on the wrapper to remove the cluster from layout AND the a11y tree. Canonical gate (swap widget): walletConnected && balance > 0. The CSS override .chip-shortcuts[hidden] { display: none; } defeats the default display: inline-flex so hidden actually paints. Don't reach for display: none directly or a custom data-state — hidden is the right tool and screen readers already respect it.
• Rightmost reveals first. Stagger is keyed on :nth-last-child with +30 ms steps; the chip closest to the cursor is the chip that lands first. Reads as "what you're about to use snaps in immediately."
• Stagger caps at 7 items. The first 6 children get 0 / 30 / 60 / 90 / 120 / 150 ms; the 7th and beyond all use 180 ms. The cluster never feels sluggish even at unusual counts.
• Reduced motion users get a flat fade. @media (prefers-reduced-motion: reduce) drops the translate and the stagger; chips fade in 80 ms without movement.
• Opt-in only. Default cluster keeps chips visible — the safe baseline for touch, keyboard-only, printed exports, and any context that doesn't reliably have hover. Reach for the modifier on desktop product canvases where the reveal flourish reads as "advanced shortcut" affordance.

Most cases — plain <code> anywhere on the site renders as a chip. No class needed.

<!-- Bare <code> — auto-styled as a chip site-wide -->
<p>Use <code>.btn-primary</code> for primary actions.</p>

<!-- Inside a label — quieter override kicks in automatically -->
<h3 class="ds-doc-card__label">
  Brand button <code>.btn-primary</code>
</h3>

<!-- Inside an eyebrow — louder override kicks in automatically -->
<p class="ds-doc-eyebrow">
  In-page · <code>.eyebrow-numbered</code> — description
</p>

<!-- Explicit class for non-<code> hosts (rare) -->
<span class="code-chip">.feature-card</span>

<!-- Suppressed automatically inside .ds-doc-codeblock -->
<pre class="ds-doc-codeblock"><code>syntax-highlighted, no chip</code></pre>

Default chip — applies to every inline <code> on the site via the bare element selector, plus any element with the explicit .code-chip class. The shared rule cancels parent text-transform and letter-spacing so the chip always reads as actual code — never inherits uppercase or wide tracking from the surrounding context.

Label-context override — applies inside .ds-doc-card__label only. Inherits the filled-bg-no-border chrome from the default rule; only font-size / weight / colour change so the chip pairs with the 26 px heading.

Eyebrow-context override — applies inside .ds-doc-eyebrow only. Inverse of the label override above — the parent is small (12 px), so the chip must scale UP, not down. Same filled-bg-no-border chrome from the shared rule; only the font-size changes.

Hover state — applied uniformly in every context.

Trigger — the chip is applied via two selectors, in this priority order:

Context overrides — two parent containers tune the chip's size + weight via the CSS cascade. The shared rule's chrome (filled bg, no border, mono, etc.) is inherited; only the type changes.

Suppression — the chip is turned off inside one context, by design.

• Wrap inline code identifiers in bare <code>. Anywhere on the site — marketing prose, dashboard captions, catalog docs, product surfaces — the bare element selector renders the chip automatically. No class needed.
• Reach for the explicit .code-chip class only for non-<code> hosts. Rare — if semantics dictate a <span> or other inline element instead of <code>, the class delivers the same styling.
• Don't use the chip inside .ds-doc-codeblock. Code blocks have their own syntax-highlight token spans (.comment, .string, .tag, etc.) and the chip would compete with them. The CSS suppresses it automatically.
• One leading character convention. Use .foo for class names, --foo for modifiers and CSS custom properties, foo.js for file paths. The character signals the kind; no separate visual treatment per kind.
• Don't override the chip with inline style. If a context needs a different treatment, add a context override (e.g. .my-parent code { font-size: 1em; }) or a modifier (e.g. .code-chip--strong) in styles.css rather than authoring per-instance overrides.
• The chip works on any inline element. <code> is the recommended host (semantic — code identifiers ARE code), but <span class="code-chip"> works too.
• Filled, no border (Apr 2026 v2). The previous iteration was a quiet outline chip (1 px border + 4 % bg). The outline carried the visual weight; designers' eyes landed on the boxed chip first instead of the noun phrase. Dropping the outline + bumping the bg to 7 % inverts that — the chip is filled enough to read as a chip, but pairs with surrounding type instead of competing.
• Don't add a border back without a designer-side reason. If you need a stronger chip in a specific context (e.g. a UI-control reference inside a callout), add a modifier like .code-chip--strong instead of changing the base. Track the modifier on this card.
• The chip is tier-2 universal (May 2026 v10). Promoted out of the .ds-doc-* namespace because it's used everywhere — marketing, product, dashboards, catalog. The previous name .ds-doc-class is fully retired; do not introduce it back as an alias.

• CSS — styles.css · search .code-chip — universal inline-code chip for the anatomy comment block + the bare-element-selector rule.
• Spec narrative — design.md §13 → Code chip.
• Hard rule — CLAUDE.md → "Inline <code> renders as a chip site-wide".
• Skill writing-style guide — .claude/skills/lifi-ds-docs/references/writing-style.md → The label rule covers when to use <code> in labels and captions.
• Iteration history — May 2026 v10 promotion (.ds-doc-class → .code-chip + bare-element trigger) documented in CLAUDE.md → "Class-naming convention" migration history. Earlier iterations track via git log on this card's id="code-chip" anchor.

<!-- The universal primitive — chrome only -->
<button type="button" class="drawer-handle" aria-label="Toggle drawer">
  <svg class="drawer-handle__chevron" viewBox="0 0 24 24" aria-hidden="true">
    <path d="m15 18-6-6 6-6"/>
  </svg>
</button>

<!-- Consumer wiring example — playground rail's positioning + rotation -->
<!-- In CSS: -->
#playgroundRailHandle {
  position: fixed;
  top: var(--canvas-top);
  left: calc(var(--rail-left) + var(--rail-width));
  z-index: 99;
  transform: translateX(var(--rail-tx));
  transition: transform 0.4s cubic-bezier(0.2, 0.8, 0.2, 1);
}
body.rail-collapsed #playgroundRailHandle .drawer-handle__chevron {
  transform: rotate(180deg);
}

Sub-parts

• Universal owns chrome only. Size, surface, border-radius, hover, focus, chevron sizing + rotation transition. Don't put consumer-specific positioning (e.g. position: fixed) on .drawer-handle itself — the rule won't generalize.
• Consumer owns positioning. Target the handle's id (or a scoped selector) in your consumer's CSS and add position, top, left, z-index, any transform for slide animations. The playground rail uses #playgroundRailHandle.
• Consumer owns the rotation state class. The chevron has a transition but no default rotation. Add a rule like body.rail-collapsed #playgroundRailHandle .drawer-handle__chevron { transform: rotate(180deg); } in the consumer's CSS. The chevron points left at rest and right when flipped.
• Mirror the radii for a right-edge dock. Default is square-left / rounded-right (tab joins a panel on its left). For a panel docked on the page's right edge, flip to rounded-left / square-right.
• Always add aria-label. The handle is icon-only — screen readers need a name.
• Glass surface — only when the parent panel is glass. The handle reads as an extension of the panel; matching surfaces is what sells the "tab attached to a drawer" silhouette. For a panel using .panel's default opaque surface, override the handle's background / box-shadow / backdrop-filter to match.

• CSS: styles.css — search DRAWER HANDLE — .drawer-handle for the universal recipe (chrome only).
• Consumer wiring example: swap.css — search Rail handle positioning — consumer-specific wiring for .drawer-handle. Positions #playgroundRailHandle and wires the body.rail-collapsed rotation class.
• Markup consumer: playground.html — the <button id="playgroundRailHandle" class="drawer-handle"> at the top of .playground-canvas.
• JS toggle: swap.js → initRailCollapse() — toggles body.rail-collapsed, persists in localStorage.
• Migration history: May 2026 v15 — promoted from .ui-rail-handle (tier-3 product-only) to universal .drawer-handle. Positioning was intentionally NOT promoted with chrome — every drawer docks somewhere different.

State colours for .dropdown. The trigger pairs visually with .btn-neutral — same translucent-ink overlay surface, same hover/active bg progression (8 % → 14 % → 18 %). State transitions ride the bg alpha; there's no border-color flip or focus-ring inflation. The trigger sits alongside buttons in product UI (form rows, toolbars, action footers) and reads as one family with them. The panel itself uses the Paper material — solid var(--surface-card) + var(--elev-3) floating shadow + no backdrop blur.

<!-- Trigger is self-styled (alpha-family surface). Add .btn-sm for -->
<!-- the compact tier. Three chromeless variants:                   -->
<!--   .dropdown__trigger--bare  — toolbar context, keeps 8px pad   -->
<!--   .dropdown__trigger--flush — inside a card row, padding 0     -->
<!--   .dropdown__trigger--seg   — inside a .seg-overflow, host wins -->
<!--   .dropdown__trigger--card  — full-width card switcher (+ panel  -->
<!--                                .dropdown__panel--match-trigger)  -->
<div class="dropdown">
  <button type="button"
          class="dropdown__trigger"
          aria-haspopup="menu"
          aria-expanded="false">
    <span class="dropdown__label">Sort by</span>
    <svg class="dropdown__chevron"><!-- caret --></svg>
  </button>
  <div class="dropdown__panel" role="menu" popover="manual">
    <ul class="menu">
      <li><a class="menu-item is-current" role="menuitem">
        <span class="menu-item-icon"><!-- icon --></span>
        <span class="menu-item-text">
          <span class="menu-item-title">Most recent</span>
        </span>
      </a></li>
      <!-- more items, optional .menu-divider sections -->
    </ul>
  </div>
</div>

• The trigger IS the neutral-family recipe — don't pair it with another button color class. The default .dropdown__trigger already paints the .btn-neutral recipe natively (translucent ink overlay, no visible border, hover/active bg progression 8 % → 14 % → 18 %). Adding .btn-primary / .btn-secondary / etc. would overpower the dropdown's quiet content-adjacent role with a brand-accent fill. For sizing, compose .btn-sm (the size-only modifier) so a default-tier button next to a default-tier dropdown trigger lands on the same 40 px height ladder; .btn-sm next to .btn-sm at 32 px.
• Hover doesn't lift; the bg progression carries the affordance. Buttons are static by default (May 2026 inversion — the lift is the opt-in .btn-lift), so the trigger never moves on hover, with no suppression needed. That's exactly right here — the panel is JS-anchored to the trigger's bounding rect and only repositions on click/scroll/resize, not on hover. Lifting the trigger would visually disconnect it from the open panel for ~200 ms while the JS catches up. The 8 % → 14 % bg deepening alone carries the affordance.
• Two sizes only — sm and default. The trigger intentionally doesn't ship lg / xl tiers. A 48-56px dropdown reads as a primary CTA, which is the wrong role for a quiet content-adjacent control. If you genuinely need a hero-scale picker, that's a different surface — reach for a modal with a search input or a full-screen sheet, not a hyperscaled dropdown.
• Reach for .dropdown__trigger--bare in toolbar contexts. When the dropdown sits next to .btn-borderless icon buttons (table-header action rows, toolbars, navbar utility clusters), the default card surface competes visually with the surrounding borderless chrome. The bare variant strips the fill + border, leaves only a subtle text-tint hover — the dropdown reads as "one of the toolbar chips" instead of "a form control dropped in among toolbar chips."
• Reach for .dropdown__trigger--seg when the trigger lives inside a seg. The canonical use is the ··· overflow trigger (see .seg-overflow) — a .seg-item that also wires up Popover behavior via .dropdown__trigger. Without the modifier, the dropdown's default chrome (bg, border, color) fights the seg-item's borderless state recipe and the trigger renders darker than its sibling tabs. The --seg modifier suppresses every chrome property at every state so the seg's own color (--on-alpha-muted rest, --on-alpha-default hover, --text-primary active) cascades through. One modifier per host context: --bare (toolbar), --flush (setting-row), --seg (inside a seg) — same shape, named after the host primitive.
• Reach for .dropdown__trigger--card when the trigger is a prominent full-width column selector. The chromeless variants (--bare / --flush / --seg) all suppress chrome so a host's recipe shows through; --card is the opposite — it dresses the trigger as a card (the .option-card recipe: --surface-card + --elev-1, accent rim on open) and spans its column. Use it for an org / workspace switcher, an account picker, a "pick one" control that fills a rail or panel column — not a compact toolbar chip (that's the default trigger or --bare). The trigger can run taller than the 40 px ladder when it carries an avatar; that's by design (it's a card, like .option-card), not a tier break. Hover / open route through --dropdown-card-tone (default --accent-primary) so a themed switcher retints with one override. Pair the panel with --match-trigger so the menu spans the same width.
• Reuse .menu for the items, never invent dropdown-specific item classes. If you need a description line, use .menu-item-desc — same single-line ellipsis rule applies. If you need a section header, use .menu-divider. The Dropdown is a composition; the items live in the Menu family.
• Use icons when items aren't recognisable from text alone, skip them when they are. A "Sort by" dropdown of "Most recent / Highest volume / By chain / By TVL" is clearer with leading icons (clock, trend, link, dollar). A list of bridge names ("Stargate / Hop / Across") is recognised from the name; icons there are visual noise. Pick once per dropdown — don't mix iconed and un-iconed items in the same list.
• Panel uses Paper material — never glass. The dropdown renders against a solid var(--surface-card) + var(--elev-1) shadow, routed through the global Paper-by-class registry in styles.css. Glass is reserved for navigation chrome (navbar, command palette, FAB menu) where the underlying content is visually load-bearing. Anchored to a specific trigger inside a form row or settings panel, glass blur reads as visual noise — that's why the dropdown was migrated to Paper in May 2026.
• Active option carries a check. The .menu-item.is-current rule renders a right-aligned check via ::after + mask-image: url("/icons/check.svg") — sources the canonical Lucide check from the icon library, NOT an inline data URI. The mask picks up var(--accent-primary) via background-color so it auto-flips light / dark with the palette. Don't paint your own affordance — the check + the accent-tinted background pair compose universally across every .menu consumer (dropdown, command palette, standalone menus). To swap the icon globally, edit /icons/check.svg once; every consumer flips.
• Right-align the panel only when the trigger is rightmost in its row. Default left-anchored is correct everywhere else. The --align-end modifier exists for the navbar-corner / table-header-action case where a left-anchored panel would clip the viewport edge.
• Don't bury more than ~7 items. Past that, designers reach for the wrong pattern: a dropdown becomes a list view (use a popover with a real scroller and a search bar — see .cmd-palette) or a settings drawer (use a modal). Long dropdowns scroll inside the panel (max-height 75vh), but that's a fallback, not a target.
• Panel width is content-sized, not fixed. The panel hugs the longest .menu-item's intrinsic content (width: max-content), floored at 10rem and ceilinged at var(--w-3) (288 px). A "USD / EUR / GBP / JPY" panel renders at ~160 px; a "Most recently active / Highest volume / Lowest fees" panel grows to fit; an "Auto / Off / Always require manual approval" panel hits the 288 px ceiling and wraps the longest item. Don't hardcode width per-instance — if your panel needs to be wider, the content's pushing the ceiling and you probably want .cmd-palette instead. If it needs to be narrower, the items are too terse — let the floor carry them. The floor is deliberate: short-label panels still read as "a menu" rather than a chip-shaped strip.

CSS: styles.css — search for .dropdown {. Uses var(--w-3) for the panel width, the Paper material recipe (var(--surface-card) + var(--elev-1)) routed via --mat-* for the surface, var(--space-*) for every internal dimension. The active-state check on .menu-item.is-current sources /icons/check.svg via mask-image (see Icons catalog).
JS: shared.js — initDropdown(). Single delegated handler. Click trigger toggles [data-open]; outside-click and Escape close every open dropdown; item click closes the parent.
Spec: design/components/navigation.md → Dropdown.
Composition reference: .setting-row hosts the dropdown as a right-slot control — see the "Display currency" demo in the setting-row card for the canonical pattern.

<!-- Minimal: icon + message (drop __title / __action when not needed) -->
<div class="empty-state">
  <span class="spot-icon spot-icon-2xl" aria-hidden="true">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><!-- chart-candlestick --></svg>
  </span>
  <p class="empty-state__title">No price data</p>          <!-- optional -->
  <p class="empty-state__message">Select a token to see its market price.</p>
  <div class="empty-state__action">                              <!-- optional -->
    <button class="btn-primary btn-sm">Select token</button>
  </div>
</div>

/* Error empty state — add a tone modifier; it overrides the muted default */
<span class="spot-icon spot-icon-2xl spot-icon--danger">…</span>

• Compose the canonical .spot-icon — pick the glyph + size tier (.spot-icon-2xl is the default for empty states). Don't author a bespoke icon.
• Omit the slots you don't need — icon + message is the minimal shape; the gaps cascade so an omitted title or action never leaves an orphaned gap.
• The icon is muted by default — this is “nothing here”, not an alert. Add a tone modifier (.spot-icon--danger) only when the empty state genuinely IS an error / warning; the modifier overrides the muted default.
• Let it fill — drop it into a flex / grid parent that has height and it centers automatically. The .ui-price-chart placeholder is the reference consumer.
• Don't use it for loading. Content that's arriving uses .skeleton — empty-state is for content that's absent.
• Keep the message to one short line; if you need a heading, use .empty-state__title rather than a longer message.

CSS: styles.css § EMPTY STATE — search .empty-state.
Composes: the .spot-icon family (size + tone modifiers).
Spec: design/components/feedback.md → ### Empty state

<div class="error-detail" role="alert">
  <p class="error-detail__code">Error · Insufficient_gas</p>
  <p class="error-detail__msg">execution reverted: gas estimation failed at block 218682389</p>
</div>

<!-- role="alert" only when the echo APPEARS dynamically (a live failure);
     static renderings (docs, summaries) omit it. -->

• Not an .alert — and exempt from the spot-icon invariant by scope. The invariant covers standalone messages where tint carries the meaning. This box is supporting forensic detail: its meaning lives in its own text, and the tone-bearing message is the header that hosts it. That's also why forcing it into .alert--danger would be wrong — a second danger icon under the failure disc, and a mono fork inside the alert's prose typography.
• Always pair it under a tone-bearing header — a result disc + title, or an .alert--danger. It is never the only failure signal on a surface.
• Chrome follows the alert family — the --a-* slots, the borderless pastel, the --card-radius + --space-20 envelope. Don't reintroduce a hairline border; don't fork the surface per consumer.
• Content is verbatim machine output, mono on purpose. The no-mono convention governs table rows; a code echo IS code. Don't put human prose in here — prose belongs in the host's description or an alert.
• Severity is identity. Danger-pinned by default; a future warn / info echo variant rebinds the tone slots like .alert--<tone> — never hand-picked colours (variant-aware states).

CSS: styles.css — search .error-detail — machine-voice diagnostic echo (lives at the end of the alert family block).
Reference consumer: the Portal withdraw-fees error state (withdraw-fees.js; flow card at design-system/portal.html#withdraw-fees).
Spec: design/components/feedback.md → Error detail. Promoted June 2026 from the flow's page-local .wfee__error — atomic retirement, no alias.

Critical colours for .fab. The FAB composes onto .btn-primary.btn-neutral so its surface inherits the neutral-overlay recipe (palette-independent translucent fill). The FAB-specific additions are the deep contact shadow and a thin white halo ring that appears on hover and stays during the .is-open state — locked widget conventions, not system tokens.

• Don't duplicate nav entry points. If a page has a clear top-nav for the same feature, skip the FAB. DS pages skip it because ds-nav.js already owns that surface.
• One FAB per surface. Multiple floating controls competing for the corner kills the "one primary action" signal.
• Don't use for destructive actions. FAB suggests exploration. Destructive actions need explicit labels and confirmation — use an inline button.
• Compose onto button primitives. Always .btn-primary.btn-neutral.btn-icon.btn-lg.btn-circle.fab; don't redefine size, radius, or colours.

CSS: styles.css — .fab rules under "Floating Action Button". Wiring in shared.js → initDesignFab() handles open/close, outside-click dismissal, escape-key handling, and [data-fab-controls] sub-panel adoption.

Two icon-colour tokens drive the rest state. Today they consume the corresponding --text-* tokens so icons read at label weight, but they live as their own variables so we can recolour icon chrome (chrome icons darker than body type, a brand-tinted icon set on a hero, etc.) by editing one line each — without touching every consumer's rule. Always reference --icon-* from icon-bearing components — not --text-*.

See the system-wide colour-token reference at Foundations → Colors for the icon family alongside text, surface, and accent tokens.

<!-- Bare borderless circle icon button — neutral hover wash -->
<button class="btn-icon btn-borderless btn-circle" aria-label="Back">
  <svg viewBox="0 0 24 24">…</svg>
</button>

<!-- With a type for accent-tinted hover (e.g. theme toggle, hamburger) -->
<button class="btn-tertiary btn-icon btn-borderless btn-circle">…</button>

<!-- Inside .screen-header — the back slot's new default -->
<header class="screen-header">
  <button class="screen-header__back btn-icon btn-borderless btn-circle" aria-label="Back">…</button>
  …
</header>

<!-- All four sizes ladder up: 24 / 32 / 40 / 48 -->
<button class="btn-icon btn-xs btn-borderless btn-circle">…</button>
<button class="btn-icon btn-sm btn-borderless btn-circle">…</button>
<button class="btn-icon btn-borderless btn-circle">…</button>
<button class="btn-icon btn-lg btn-borderless btn-circle">…</button>

• Default for screen-header lead actions. .screen-header__back renders this composition. Don't reach for .btn-neutral in a header that carries a .seg--borderless mode picker — the neutral button's chrome competes with the borderless tabs.
• Pair the size to the row. Default (40 px) for screen headers + marketing nav + modals — pairs with the 40 px .seg--borderless mode picker that often sits in the title slot, and with the 20 px --text-body-xl title (visual proportion, not line-height match). .btn-sm (32 px) for dense secondary toolbars; .btn-lg (48 px) for hero-scale chrome. Match the sibling control (input / seg / button).
• Default colour is --text-primary. May 2026: the bare borderless icon now reads at the same weight as the labels around it (header titles, list-item titles), so back arrows / settings / search reach the eye at the same tier as the words they sit beside. Hover lifts to an 8 % primary wash (black on light, white on dark).
• Hover contract — icon color stays, background tints, fade is smooth. System-wide rule (May 2026): every variant of this primitive (bare, muted, accent-typed) shifts only the background on :hover — the icon's color holds steady at its rest token. The transition is background 0.2s ease, declared on the borderless rule itself (the base .btn-* transition is scoped to type classes so unparented borderless icons would snap without it). Same contract paints across the widget header (Activity / Settings / Disconnect), the screen-header back, the playground rail's top cluster (Mode / Reset / Settings), and every future surface that composes this recipe — one icon-button family, one hover treatment.
• Add .btn-muted for deemphasis. Opts the icon into --text-muted for cases that should defer to their context — a row-level affordance that yields focus to the row's title, a secondary toolbar action, a meta button next to a metric. The icon stays muted on hover (icon-color-stays contract); only the background wash resolves the affordance. Bring the icon back to primary by removing the modifier, not by overriding the hover.
• Add a type (e.g. .btn-tertiary) for accent-tinted hover. The accent-aware rules tint the hover BACKGROUND with --btn-accent-bg (the type's accent at low alpha). The icon color itself does not shift — the background wash is the entire affordance. Use when the action wants brand affinity — theme toggle, hamburger menu, brand CTAs that need a quieter shape than a filled .btn-primary.
• The composition is .btn-icon.btn-borderless.btn-circle, in that order. Drop any one and the recipe breaks: without .btn-icon the borderless rules don't apply (they're scoped to icon-only); without .btn-circle the radius falls back to the size-tier square (12 / 16 / 20 px); without .btn-borderless you get an alpha-chip default.
• Always set aria-label. No text inside the button — screen readers need the label or the action is unannounced. Add a contextual aria-label on the parent header / nav too if "Back" alone is ambiguous (e.g. aria-label="Back to wallet list").
• Don't use for primary CTAs. The transparent idle reads as a tertiary affordance — fine for back / close / settings / hamburger; wrong for "Confirm swap" or "Sign in." Reach for .btn-primary there.

<div class="form-group">
  <label class="form-label">Source Chain</label>
  <input class="input" placeholder="Select chain...">
  <div class="muted muted--field">Connected: 0x1a2b...8f9e</div>
</div>

Field surface & border. The input reads as a lighter, raised field on the (usually darker) canvas — not a recessed well. Every value is a neutral palette token (no raw colours), so the Theme Composer keeps working.

Dark paints --field-bg as a neutral white overlay (color-mix(var(--text-primary) 12%, transparent)) that lifts the field off the dark canvas; light uses var(--surface-card) (white), lighter than the off-white panels. These --field-* tokens drive every field control (.input / .select / .textarea / .field-inline / .checkbox / .radio / .switch) and the .search bar. Spec: design/components/forms.md → Form Inputs.

<div class="form-group">
  <label class="form-label">Use case</label>
  <select class="select">
    <option value="" disabled selected>Select a use case</option>
    <option>Wallet</option>
  </select>
</div>

<div class="form-group">
  <label class="form-label">Message</label>
  <textarea class="textarea" placeholder="..."></textarea>
</div>

<input class="input"
       type="number"
       min="1" max="100" step="1"
       value="3">

• Use type="number" for actual numbers. Quantity, slippage %, weight, port number. The browser validates and exposes nudge controls (arrow keys, scroll wheel).
• Set inputmode for decimals. inputmode="decimal" on mobile shows a numeric keypad with a decimal key — useful even when type="text", when you want to disable the spinner UI but keep numeric input.
• Suffix the unit, don't put it in the placeholder. .field-suffix with "%" or "kg" reads better than placeholder="0%", and the unit stays visible while the user types.
• Native spinners are kept. Useful for short ranges (1–10). For larger ranges, hide them via appearance: textfield at the use-site and add explicit step buttons if needed.

<div class="form-group form-group--sm">
  <label class="form-label form-label--sm" for="theme-name">Theme name</label>
  <input class="input input--sm" id="theme-name" placeholder="Untitled theme">
</div>

<label class="field-inline">
  <span class="field-label">From</span>
  <input class="field-input" type="text" placeholder="0.00">
</label>

• Wrapper owns chrome. Background, border, radius, focus ring all live on .field-inline; the bare child controls (.field-input, .field-select, .field-textarea) inherit typography only.
• Click anywhere focuses. The wrapper uses :focus-within so the ring lights up regardless of which child the user clicks.
• Use when the label is a persistent identifier — financial pairs (From / To), key-value rows. Stacked is a better fit when the label can breathe and a hint is useful.