@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/patterns/payments.md

@@ -0,0 +1,765 @@
+# Payments
+
+Build send, receive, and deposit flows, from the amount to the receipt.
+
+## Overview
+
+A payment moves money and cannot be undone. Each step shows exactly what will happen, catches mistakes before confirmation, and reports the outcome plainly. [Tempo Wallet](/docs/products/tempo-wallet) (wallet.tempo.xyz) uses three flows: Send, Receive, and Add funds. [Blockchain Values](/docs/patterns/blockchain-values) covers how each amount, address, and hash in these flows is formatted.
+
+> [!NOTE]
+> The live examples are reference layouts built from library components and `style`, not shipped components. They simulate the network, so no funds move.
+
+## Recommended Structure
+
+Run each flow in focus: a centered column about 28rem wide with global navigation hidden, or a [Dialog](/docs/components/dialog), which becomes a bottom sheet on narrow screens. Mark progress with a [Stepper](/docs/components/stepper).
+
+* **Details (1):** The asset, the amount, and the recipient.
+* **Review (2):** The full payment, with the confirm action.
+* **Status (3):** Pending, then sent or failed, on one screen.
+* **Receipt (4):** A record that stays available from activity.
+
+```tsx
+import { Amount, AmountInput, Button, Field, formatHex, Frame, Hex, Identicon, ListGroup, Stack, Stepper, style, Surface, TextInput, Token } from '@tempoxyz/ds'
+import { CheckCircle } from '@tempoxyz/ds/icons'
+import { useEffect, useRef, useState } from 'react'
+
+export const fill = true
+const balance = '1240.50'
+const fee = '0.00003'
+const hash = '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060'
+
+function valid(address: string) {
+  return /^0x[0-9a-fA-F]{40}$/.test(address)
+}
+
+// Adds decimal strings in 6-decimal base units, so the total never picks up floating-point error.
+function add(a: string, b: string) {
+  const units = (value: string) => {
+    const [whole = '', fraction = ''] = value.split('.')
+    return BigInt(`${whole || '0'}${fraction.padEnd(6, '0').slice(0, 6)}`)
+  }
+  const digits = (units(a) + units(b)).toString().padStart(7, '0')
+  return `${digits.slice(0, -6)}.${digits.slice(-6).replace(/0+$/, '').padEnd(2, '0')}`
+}
+
+export function Demo() {
+  const [step, setStep] = useState<'details' | 'review' | 'sent'>('details')
+  const [amount, setAmount] = useState('')
+  const [recipient, setRecipient] = useState('')
+  // Errors show after a field loses focus or the form submits, never while you type.
+  const [touched, setTouched] = useState({ amount: false, recipient: false })
+  const [sending, setSending] = useState(false)
+  const heading = useRef<HTMLHeadingElement>(null)
+  const previous = useRef(step)
+
+  // Each step replaces the last, so focus moves to the new heading instead of falling back to the page.
+  useEffect(() => {
+    if (previous.current !== step) heading.current?.focus()
+    previous.current = step
+  }, [step])
+
+  const amountError = (() => {
+    if (!touched.amount) return undefined
+    if (!Number(amount)) return 'Enter an amount to send.'
+    if (Number(amount) > Number(balance)) return 'Enter an amount up to 1,240.50 PathUSD.'
+    return undefined
+  })()
+  const recipientError =
+    touched.recipient && !valid(recipient)
+      ? 'Enter an address that starts with 0x and has 40 more characters.'
+      : undefined
+
+  if (step === 'sent')
+    return (
+      <Surface {...styles.card()}>
+        <Frame.Root>
+          <div {...styles.result()}>
+            <CheckCircle aria-hidden="true" {...styles.success()} />
+            <Frame.Title ref={heading} tabIndex={-1}>
+              Payment sent
+            </Frame.Title>
+            <Amount size="md" symbol="PathUSD" value={amount} />
+            <p {...styles.text()}>To {formatHex(recipient)}</p>
+          </div>
+          <ListGroup.Root {...styles.rows()}>
+            <ListGroup.Row>
+              <ListGroup.Label>Transaction</ListGroup.Label>
+              <Hex copy value={hash} />
+            </ListGroup.Row>
+          </ListGroup.Root>
+          <Frame.Footer>
+            <Button
+              onClick={() => {
+                setAmount('')
+                setRecipient('')
+                setTouched({ amount: false, recipient: false })
+                setStep('details')
+              }}
+              size="large"
+            >
+              Done
+            </Button>
+          </Frame.Footer>
+        </Frame.Root>
+      </Surface>
+    )
+
+  if (step === 'review')
+    return (
+      <Surface {...styles.card()}>
+        <Frame.Root>
+          <Stack gap="12">
+            <Stepper.Root aria-label="Send payment" count={2} value={2} />
+            <Frame.Title ref={heading} tabIndex={-1}>
+              Review payment
+            </Frame.Title>
+          </Stack>
+          <Amount size="lg" symbol="PathUSD" value={amount} />
+          {/* The review shows the whole address, so you can check it against where you got it. */}
+          <div {...styles.recipient()}>
+            <span {...styles.label()}>To</span>
+            <span {...styles.address()}>
+              <Identicon aria-hidden address={recipient} size="24" />
+              <code {...styles.code()}>{recipient}</code>
+            </span>
+          </div>
+          <ListGroup.Root {...styles.rows()}>
+            <ListGroup.Row>
+              <ListGroup.Label>Network fee</ListGroup.Label>
+              <Amount symbol="PathUSD" value={fee} />
+            </ListGroup.Row>
+            <ListGroup.Row>
+              <ListGroup.Label>Total</ListGroup.Label>
+              <Amount symbol="PathUSD" value={add(amount, fee)} />
+            </ListGroup.Row>
+          </ListGroup.Root>
+          <Frame.Footer {...styles.footer()}>
+            <Button
+              loading={sending}
+              onClick={() => {
+                setSending(true)
+                setTimeout(() => {
+                  setSending(false)
+                  setStep('sent')
+                }, 1500)
+              }}
+              size="large"
+            >
+              Confirm and send
+            </Button>
+            <Button disabled={sending} onClick={() => setStep('details')} variant="tertiary">
+              Edit payment
+            </Button>
+          </Frame.Footer>
+        </Frame.Root>
+      </Surface>
+    )
+
+  return (
+    <Surface
+      render={
+        <form
+          noValidate
+          onSubmit={(event) => {
+            event.preventDefault()
+            setTouched({ amount: true, recipient: true })
+            const amountValid = Number(amount) > 0 && Number(amount) <= Number(balance)
+            if (amountValid && valid(recipient)) return setStep('review')
+
+            // Focus moves to the first field that needs fixing.
+            const name = amountValid ? 'recipient' : 'amount'
+            event.currentTarget.querySelector<HTMLInputElement>(`input[name="${name}"]`)?.focus()
+          }}
+        />
+      }
+      {...styles.card()}
+    >
+      <Frame.Root>
+        <Stack gap="12">
+          <Stepper.Root aria-label="Send payment" count={2} value={1} />
+          <Frame.Title ref={heading} tabIndex={-1}>
+            Send
+          </Frame.Title>
+        </Stack>
+        <Field.Root invalid={amountError !== undefined}>
+          <AmountInput.Root
+            onValueChange={(value) => {
+              setAmount(value)
+              setTouched({ ...touched, amount: false })
+            }}
+            value={amount}
+          >
+            <Field.Label>Amount</Field.Label>
+            <AmountInput.Control
+              name="amount"
+              onBlur={() => setTouched({ ...touched, amount: amount !== '' })}
+              placeholder="0.00"
+            />
+            <Token readOnly symbol="PathUSD" />
+            <Field.Description>Balance: 1,240.50 PathUSD</Field.Description>
+            <Field.Error match={amountError !== undefined}>{amountError}</Field.Error>
+          </AmountInput.Root>
+        </Field.Root>
+        <Field.Root invalid={recipientError !== undefined}>
+          <Field.Label>Recipient</Field.Label>
+          <TextInput.Group>
+            <TextInput.Control
+              autoComplete="off"
+              name="recipient"
+              onBlur={() => setTouched({ ...touched, recipient: recipient !== '' })}
+              onValueChange={(value) => {
+                setRecipient(value.trim())
+                setTouched({ ...touched, recipient: false })
+              }}
+              placeholder="0x…"
+              spellCheck={false}
+              value={recipient}
+            />
+          </TextInput.Group>
+          <Field.Description>Paste a Tempo address.</Field.Description>
+          <Field.Error match={recipientError !== undefined}>{recipientError}</Field.Error>
+        </Field.Root>
+        <Frame.Footer>
+          <Button type="submit">Review payment</Button>
+        </Frame.Footer>
+      </Frame.Root>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const address = style({ alignItems: 'center', columnGap: '12', display: 'flex' })
+
+  export const card = style({
+    boxSizing: 'border-box',
+    marginInline: 'auto !custom',
+    maxWidth: '448',
+    width: '100% !custom',
+  })
+
+  export const code = style({ minWidth: '0', typography: 'mono.m1', wordBreak: 'break-all' })
+
+  export const footer = style({ rowGap: '8' })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const recipient = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
+
+  export const result = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+    textAlign: 'center',
+  })
+
+  // Surface pads 24px, so the rows reach its edges and keep their own 20px inset.
+  export const rows = style({ marginInline: '-24px !custom' })
+
+  export const success = style({ color: 'content.positive', fontSize: '36' })
+
+  export const text = style({ color: 'content.secondary', margin: '0', typography: 'body.b2' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/PaymentsSend.tsx)
+
+## Enter the Amount
+
+Place the [AmountInput](/docs/components/amount-input) first, in a [Field](/docs/components/field), with the `Field.Label` and `Field.Description` inside `AmountInput.Root`.
+
+* **Unit:** Name the token beside the amount with a [Token](/docs/components/token), such as PathUSD.
+* **Balance:** Show the available balance in `Field.Description`, such as Balance: 1,240.50 PathUSD.
+* **Limit:** Check the amount against the balance on blur and on submit, and name the limit in the error, such as Enter an amount up to 1,240.50 PathUSD.
+* **Several tokens:** Put a [Select](/docs/components/select) above the amount, with a [TokenLogo](/docs/components/token-logo) icon in `Select.ItemPrefix` and the balance in `Select.ItemSuffix`. Default to the token used last.
+
+## Enter the Recipient
+
+* **Address input:** Use a [TextInput](/docs/components/text-input) labelled Recipient, with `autoComplete="off"`, spell check off, and a `0x…` placeholder.
+* **Format check:** On blur, trim pasted spaces and check for `0x` plus 40 hex characters. Explain a bad address under the field.
+* **Saved contacts:** If the address matches a saved contact, show the name beside it, as [Blockchain Values](/docs/patterns/blockchain-values#pair-addresses-with-names) describes.
+* **New addresses:** If the account has never sent to the address, show a `warning` [Alert](/docs/components/alert), such as You haven't sent to this address before.
+
+## Review Before Confirming
+
+The review step repeats every detail of the payment in [ListGroup](/docs/components/list-group), with a `ListGroup.Label` for each.
+
+* **Amount (size=lg):** The amount and token, shown large as the main value of the review.
+* **To (Full address):** The full address and any known contact name. Ask people to check all of it against its source.
+* **Network Fee (Paid by):** The exact fee in the token that pays it. If a fee payer covers it, name the sponsor.
+* **Total:** The amount plus the fee, if both use the same token. Otherwise, list them apart.
+* **Memo:** The reference of the transfer, such as an invoice number, if one exists.
+
+**Do:** Show the fee as its own row and the total beneath it.
+
+```tsx
+/** Do example for "Payments" on the Payments page: show the fee as its own row and the total beneath it. @module */
+import { Amount, ListGroup, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="small" {...styles.card()}>
+      <ListGroup.Root>
+        <ListGroup.Row>
+          <ListGroup.Label>Amount</ListGroup.Label>
+          <Amount symbol="PathUSD" value="250.00" />
+        </ListGroup.Row>
+        <ListGroup.Row>
+          <ListGroup.Label>Network fee</ListGroup.Label>
+          <Amount symbol="PathUSD" value="0.00003" />
+        </ListGroup.Row>
+        <ListGroup.Row>
+          <ListGroup.Label>Total</ListGroup.Label>
+          <Amount symbol="PathUSD" value="250.00003" />
+        </ListGroup.Row>
+      </ListGroup.Root>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxShadow: '0 0 0 1px light-dark(#0000001a, #ffffff1f) !custom',
+    width: '17rem !custom',
+  })
+}
+```
+
+**Don't:** Fold the fee into a total without showing it.
+
+```tsx
+/** Don't example for "Payments" on the Payments page. Don't fold the fee into a total without showing it. @module */
+import { Amount, ListGroup, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="small" {...styles.card()}>
+      <ListGroup.Root>
+        <ListGroup.Row>
+          <ListGroup.Label>Total</ListGroup.Label>
+          <Amount symbol="PathUSD" value="250.00003" />
+        </ListGroup.Row>
+      </ListGroup.Root>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxShadow: '0 0 0 1px light-dark(#0000001a, #ffffff1f) !custom',
+    width: '17rem !custom',
+  })
+}
+```
+
+### Confirm With One Large Action
+
+End the review with one full-width `primary` [Button](/docs/components/button) with `size="large"`, labelled with the verb and the amount, such as Send 250.00 PathUSD or Confirm and send. Put a `text` Edit payment action beneath it. Set `loading` while the wallet signs and submits, so the button shows a spinner and blocks a second press.
+
+**Do:** Use one large, specific confirm action with a quiet way back.
+
+```tsx
+/**
+ * Do example for "Confirm With One Large Action" on the Payments page.
+ * Use one large, specific confirm action with a quiet way back.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.footer()}>
+      <Button size="large">Confirm and send</Button>
+      <Button variant="tertiary">Edit payment</Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const footer = style({
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+    width: '16rem !custom',
+  })
+}
+```
+
+**Don't:** Place a small, generic confirm among other actions.
+
+```tsx
+/**
+ * Don't example for "Confirm With One Large Action" on the Payments page.
+ * Don't place a small, generic confirm among other actions.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.footer()}>
+      <Button size="small" variant="secondary">
+        Edit
+      </Button>
+      <Button size="small" variant="secondary">
+        Save
+      </Button>
+      <Button size="small">OK</Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const footer = style({
+    display: 'flex',
+    gap: '8',
+    justifyContent: 'flex-end',
+    width: '16rem !custom',
+  })
+}
+```
+
+## Report the Outcome
+
+```tsx
+import { Amount, Button, ChoiceGroup, Frame, Spinner, Stack, style, Surface } from '@tempoxyz/ds'
+import { AlertCircle, CheckCircle } from '@tempoxyz/ds/icons'
+import { useState } from 'react'
+
+export const fill = true
+type State = 'failed' | 'pending' | 'sent'
+
+const states = {
+  failed: {
+    description: 'Your balance hasn’t changed. Check the recipient and amount, then try again.',
+    primary: 'Try again',
+    secondary: 'Edit payment',
+    title: 'Payment failed',
+  },
+  pending: {
+    description: 'Sending to 0x71C7…976F. You can close this screen.',
+    primary: undefined,
+    secondary: undefined,
+    title: 'Sending payment',
+  },
+  sent: {
+    description: 'Sent to 0x71C7…976F.',
+    primary: 'Done',
+    secondary: 'View receipt',
+    title: 'Payment sent',
+  },
+}
+
+export function Demo() {
+  const [state, setState] = useState<State>('pending')
+  const content = states[state]
+
+  return (
+    <Stack gap="16">
+      <ChoiceGroup.Root
+        aria-label="Payment state"
+        onValueChange={(value) => setState(value as State)}
+        size="small"
+        value={state}
+      >
+        <ChoiceGroup.Item value="pending">Pending</ChoiceGroup.Item>
+        <ChoiceGroup.Item value="sent">Sent</ChoiceGroup.Item>
+        <ChoiceGroup.Item value="failed">Failed</ChoiceGroup.Item>
+      </ChoiceGroup.Root>
+      <Surface {...styles.card()}>
+        <Frame.Root>
+          {/* One live region holds the outcome, so each change is announced once. */}
+          <div aria-live="polite" {...styles.result()}>
+            {state === 'pending' && <Spinner aria-label="Sending" {...styles.icon()} />}
+            {state === 'sent' && <CheckCircle aria-hidden="true" {...styles.positive()} />}
+            {state === 'failed' && <AlertCircle aria-hidden="true" {...styles.negative()} />}
+            <Frame.Title>{content.title}</Frame.Title>
+            <Amount size="md" symbol="PathUSD" value="250.00" />
+            <p {...styles.text()}>{content.description}</p>
+          </div>
+          {content.primary && (
+            <Frame.Footer {...styles.footer()}>
+              <Button size="large">{content.primary}</Button>
+              <Button variant="tertiary">{content.secondary}</Button>
+            </Frame.Footer>
+          )}
+        </Frame.Root>
+      </Surface>
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxSizing: 'border-box',
+    marginInline: 'auto !custom',
+    maxWidth: '448',
+    width: '100% !custom',
+  })
+
+  export const footer = style({ rowGap: '8' })
+
+  export const icon = style({ marginBlockEnd: '8' })
+
+  export const negative = style({ color: 'content.negative', fontSize: '36', marginBlockEnd: '8' })
+
+  export const positive = style({ color: 'content.positive', fontSize: '36', marginBlockEnd: '8' })
+
+  export const result = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'column',
+    minHeight: '200',
+    rowGap: '8',
+    textAlign: 'center',
+  })
+
+  export const text = style({ color: 'content.secondary', margin: '0', typography: 'body.b2' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/PaymentsStatus.tsx)
+
+* **Pending (Spinner):** Keep the amount and recipient on screen. State whether leaving is safe, such as You can close this screen.
+* **Sent (Toast):** Show a check, the amount, the recipient, Done, and View receipt. If the person already left, confirm with a toast.
+* **Failed:** State the result, the cause if known, and whether funds moved. Offer Try again with the same details, and Edit payment.
+
+Announce the outcome once through a polite live region, separate from the busy confirm button. Each title states the result, such as Sent or Payment failed, so the color of the icon is not the only signal.
+
+## Keep a Receipt
+
+A receipt records the payment in full, including values that the review step shortened: amount, fee, total, sender, recipient, the date with seconds and time zone, block, and transaction hash. Show the status in a [Badge](/docs/components/badge), such as Confirmed. [Blockchain Values](/docs/patterns/blockchain-values) covers the copy buttons and explorer links on each value.
+
+```tsx
+import { Amount, Badge, Button, Hex, ListGroup, style, Surface } from '@tempoxyz/ds'
+import { ExternalLink } from '@tempoxyz/ds/icons'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Surface render={<section aria-labelledby="receipt-title" />} {...styles.card()}>
+      <Surface.Header>
+        <Surface.Title id="receipt-title">Receipt</Surface.Title>
+        <Badge>Confirmed</Badge>
+      </Surface.Header>
+      <Amount size="lg" symbol="PathUSD" value="250.00" />
+      <div {...styles.rows()}>
+        <ListGroup.Root>
+          <ListGroup.Row>
+            <ListGroup.Label>From</ListGroup.Label>
+            <Hex copy value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
+          </ListGroup.Row>
+          <ListGroup.Row>
+            <ListGroup.Label>To</ListGroup.Label>
+            <Hex copy value="0x71C7656EC7ab88b098defB751B7401B5f6d8976F" />
+          </ListGroup.Row>
+          <ListGroup.Row>
+            <ListGroup.Label>Network fee</ListGroup.Label>
+            <Amount symbol="PathUSD" value="0.00003" />
+          </ListGroup.Row>
+          <ListGroup.Row>
+            <ListGroup.Label>Total</ListGroup.Label>
+            <Amount symbol="PathUSD" value="250.00003" />
+          </ListGroup.Row>
+          <ListGroup.Row>
+            <ListGroup.Label>Date</ListGroup.Label>
+            <time dateTime="2026-10-20T09:41:07Z">Oct 20, 2026, 09:41:07 UTC</time>
+          </ListGroup.Row>
+          <ListGroup.Row>
+            <ListGroup.Label>Block</ListGroup.Label>
+            <span {...styles.number()}>18,204,551</span>
+          </ListGroup.Row>
+          <ListGroup.Row>
+            <ListGroup.Label>Transaction</ListGroup.Label>
+            <Hex copy value="0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060" />
+          </ListGroup.Row>
+        </ListGroup.Root>
+      </div>
+      <div {...styles.actions()}>
+        <Button.Link
+          href="https://explore.tempo.xyz"
+          rel="noreferrer"
+          target="_blank"
+          variant="secondary"
+        >
+          View on explorer
+          <ExternalLink aria-hidden="true" />
+        </Button.Link>
+      </div>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const actions = style({ display: 'flex', marginBlockStart: '16' })
+
+  export const card = style({
+    boxSizing: 'border-box',
+    marginInline: 'auto !custom',
+    maxWidth: '448',
+    width: '100% !custom',
+  })
+
+  export const number = style({ fontVariantNumeric: 'tabular-nums !custom' })
+
+  // Surface pads 24px, so the rows reach its edges and keep their own 20px inset. A direct child
+  // `ListGroup` would bleed on its own, but this one follows the amount, so a wrapper sets the margins.
+  export const rows = style({ marginBlockStart: '16', marginInline: '-24px !custom' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/PaymentsReceipt.tsx)
+
+## Receive and Deposit
+
+Receive shows the address two ways: a [Qr](/docs/components/qr) for scanning, and a [Hex](/docs/components/hex) with `variant="filled"` across the full width for copying. Encode exactly the visible address. Name the code by purpose, such as Wallet address QR code, and state what the address accepts, such as Send stablecoins on Tempo to this address.
+
+```tsx
+import { Alert, Hex, Qr, style, Surface } from '@tempoxyz/ds'
+
+export const fill = true
+const address = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
+
+export function Demo() {
+  return (
+    <Surface render={<section aria-labelledby="receive-title" />} {...styles.card()}>
+      <Surface.Header>
+        <Surface.Title id="receive-title">Receive</Surface.Title>
+      </Surface.Header>
+      <div {...styles.body()}>
+        <Qr aria-label="Wallet address QR code" size="medium" value={address} />
+        {/* A filled Hex spans the card, so it truncates as little as possible and the whole row copies. */}
+        <div {...styles.address()}>
+          <Hex.Root size="large" value={address} variant="filled">
+            <Hex.Text />
+            <Hex.Copy aria-label="Copy address" />
+          </Hex.Root>
+        </div>
+        <Alert role="note">
+          <Alert.Icon />
+          <Alert.Content>Send stablecoins on Tempo to this address.</Alert.Content>
+        </Alert>
+      </div>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const address = style({ alignSelf: 'stretch' })
+
+  export const body = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '20',
+  })
+
+  export const card = style({
+    boxSizing: 'border-box',
+    marginInline: 'auto !custom',
+    maxWidth: '360',
+    width: '100% !custom',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/PaymentsReceive.tsx)
+
+**Do:** Pair the QR code with the address and a copy action.
+
+```tsx
+/**
+ * Do example for "Confirm With One Large Action" on the Payments page.
+ * Pair the QR code with the address and a copy action.
+ * @module
+ */
+import { Hex, Qr, style } from '@tempoxyz/ds'
+
+const address = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Qr aria-label="Wallet address QR code" size="small" value={address} />
+      <Hex.Root size="small" value={address} variant="filled">
+        <Hex.Text />
+        <Hex.Copy aria-label="Copy address" />
+      </Hex.Root>
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({
+    alignItems: 'stretch',
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '12',
+    width: '15rem !custom',
+  })
+}
+```
+
+**Don't:** Show a QR code alone. Many people cannot scan it.
+
+```tsx
+/**
+ * Don't example for "Confirm With One Large Action" on the Payments page.
+ * Don't show a QR code alone. Many people cannot scan it.
+ * @module
+ */
+import { Qr } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return <Qr size="small" value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
+}
+```
+
+Add funds starts with the method. Use `Choicebox.RadioGroup` from [Choicebox](/docs/components/choicebox), with a title and arrival time for each option, such as Bank transfer or Debit card. A crypto deposit then shows the receive layout, with the minimum deposit and the accepted tokens.
+
+## Content
+
+* **Name the movement:** Use verbs that name it: Send, Receive, Add funds, Withdraw.
+* **Repeat the amount:** Show the amount with its token in every step. No screen reads only Confirm.
+* **Name the cause:** If the cause of a failure is known, name it, such as Not enough PathUSD for the fee.
+
+## Accessibility
+
+* **Move Focus:** After a failed submit, focus the first invalid field. On a step change, focus the new step's heading.
+* **Busy Button (aria-busy):** A loading button is marked busy. Announce the outcome separately, such as in a toast.
+
+## Related
+
+[AmountInput](/docs/components/amount-input)
+
+Use for entering amounts.
+
+[ListGroup](/docs/components/list-group)
+
+Use for the review and receipt.
+
+[Qr](/docs/components/qr)
+
+Use for receiving funds.
+
+[Blockchain Values](/docs/patterns/blockchain-values)
+
+Covers addresses, hashes, and precision.
+
+[Errors and Validation](/docs/patterns/errors-and-validation)
+
+Covers error messages.
+
+[Destructive Actions](/docs/patterns/destructive-actions)
+
+Covers irreversible actions.
+
+[Tempo Wallet](/docs/products/tempo-wallet)
+
+Covers the wallet's flows.