@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/patterns/errors-and-validation.md

@@ -0,0 +1,808 @@
+# Errors and Validation
+
+Check values at the right moment, and state how to fix each problem.
+
+## Overview
+
+An error message states what happened and how to fix it, beside the problem. It never blames the reader and never discards what they entered. Problems come from three sources:
+
+* **Validation:** An entered value is unusable, such as a malformed address. Show it on the field.
+* **Network Failure:** A request did not complete, so nothing changed. Show it beside the failed action.
+* **Transaction Failure (Failed):** The network received a transaction and rejected it, such as a transfer without funds for its fee.
+
+[Forms](/docs/patterns/forms) covers layout. [Feedback and Status](/docs/patterns/feedback-and-status) defines the Couldn't load and Failed states.
+
+## Structure
+
+1. **Field errors:** Each invalid field shows its own `Field.Error`, which replaces the field's description.
+2. **Summary:** If a submit finds two or more problems, a negative [Alert](/docs/components/alert) at the top lists them.
+3. **Failed request:** The form keeps its values, and an [Alert](/docs/components/alert) above the actions states the failure.
+4. **Retry:** The primary action stays enabled, so a second press retries.
+
+```tsx
+import { Alert, AmountInput, Button, Field, Frame, style, Surface, TextInput, Toast, Token } from '@tempoxyz/ds'
+import { useRef, useState } from 'react'
+
+export const fill = true
+const balance = 1250
+
+type Errors = { amount?: string | undefined; recipient?: string | undefined }
+
+type Problem = { id: string; message: string }
+
+function recipientError(value: string) {
+  if (value === '') return "Enter the recipient's address."
+  if (!/^0x[0-9a-fA-F]{40}$/.test(value)) return 'Enter a 42-character address that starts with 0x.'
+  return undefined
+}
+
+function amountError(value: string) {
+  if (value === '' || Number(value) === 0) return 'Enter an amount greater than 0.'
+  if (Number(value) > balance) return 'Enter 1,250.00 USDC or less, your available balance.'
+  return undefined
+}
+
+function PaymentForm() {
+  const toast = Toast.useToast()
+  const summaryRef = useRef<HTMLDivElement>(null)
+  const [amount, setAmount] = useState('')
+  const [errors, setErrors] = useState<Errors>({})
+  const [pending, setPending] = useState(false)
+  const [recipient, setRecipient] = useState('')
+  const [summary, setSummary] = useState(false)
+
+  const problems: Problem[] = []
+  if (errors.recipient) problems.push({ id: 'recipient', message: errors.recipient })
+  if (errors.amount) problems.push({ id: 'amount', message: errors.amount })
+
+  return (
+    <Surface
+      {...styles.form()}
+      render={
+        <form
+          noValidate
+          onSubmit={(event) => {
+            event.preventDefault()
+
+            const next = { amount: amountError(amount), recipient: recipientError(recipient) }
+            setErrors(next)
+
+            const count = [next.recipient, next.amount].filter(Boolean).length
+            setSummary(count > 1)
+
+            // One problem moves focus to its field. Several move focus to the summary that lists them.
+            // The summary mounts on this render, so focus moves to it once it exists.
+            if (count > 1) return void setTimeout(() => summaryRef.current?.focus())
+            if (next.recipient) return void document.getElementById('recipient')?.focus()
+            if (next.amount) return void document.getElementById('amount')?.focus()
+
+            setPending(true)
+            setTimeout(() => {
+              setPending(false)
+              toast.add({
+                description: `${amount} USDC to ${recipient.slice(0, 6)}…${recipient.slice(-4)}`,
+                intent: 'positive',
+                title: 'Payment sent',
+              })
+            }, 1200)
+          }}
+        />
+      }
+    >
+      <Frame.Root>
+        <Frame.Header>
+          <Frame.Title>Send payment</Frame.Title>
+        </Frame.Header>
+        {summary && problems.length > 0 && (
+          <Alert intent="negative" ref={summaryRef} tabIndex={-1}>
+            <Alert.Icon />
+            <Alert.Content>
+              <p {...styles.heading()}>
+                {problems.length === 1 ? 'Fix 1 problem' : `Fix ${problems.length} problems`} to
+                send this payment
+              </p>
+              <ul {...styles.list()}>
+                {problems.map((problem) => (
+                  <li key={problem.id}>
+                    <a
+                      {...styles.link()}
+                      href={`#${problem.id}`}
+                      onClick={(event) => {
+                        event.preventDefault()
+                        document.getElementById(problem.id)?.focus()
+                      }}
+                    >
+                      {problem.message}
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            </Alert.Content>
+          </Alert>
+        )}
+        <Field.Root invalid={!!errors.recipient}>
+          <Field.Label>Recipient</Field.Label>
+          <TextInput.Group>
+            <TextInput.Control
+              autoComplete="off"
+              onBlur={(event) => {
+                // Format errors wait until you leave the field. An empty field waits for submit.
+                const value = event.currentTarget.value
+                if (value !== '') setErrors({ ...errors, recipient: recipientError(value) })
+              }}
+              onValueChange={(value) => {
+                setRecipient(value)
+                if (errors.recipient) setErrors({ ...errors, recipient: recipientError(value) })
+              }}
+              id="recipient"
+              placeholder="0x…"
+              spellCheck={false}
+              value={recipient}
+            />
+          </TextInput.Group>
+          <Field.Description>A Tempo address that starts with 0x.</Field.Description>
+          <Field.Error match={!!errors.recipient}>{errors.recipient}</Field.Error>
+        </Field.Root>
+        <Field.Root invalid={!!errors.amount}>
+          <AmountInput.Root
+            onValueChange={(value) => {
+              setAmount(value)
+              if (errors.amount) setErrors({ ...errors, amount: amountError(value) })
+            }}
+            value={amount}
+          >
+            <Field.Label>Amount</Field.Label>
+            <AmountInput.Control id="amount" placeholder="0.00" />
+            <Token readOnly symbol="USDC" />
+            <Field.Description>Available: 1,250.00 USDC</Field.Description>
+            <Field.Error match={!!errors.amount}>{errors.amount}</Field.Error>
+          </AmountInput.Root>
+        </Field.Root>
+        <Frame.Footer>
+          <Frame.Actions>
+            <Button loading={pending} type="submit">
+              Send payment
+            </Button>
+          </Frame.Actions>
+        </Frame.Footer>
+      </Frame.Root>
+    </Surface>
+  )
+}
+
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Toast.Provider>
+        <PaymentForm />
+        <Toast.Viewport />
+      </Toast.Provider>
+    </div>
+  )
+}
+
+namespace styles {
+  export const form = style({
+    boxSizing: 'border-box',
+    maxWidth: '28rem !custom',
+    width: '100% !custom',
+  })
+
+  export const heading = style({ margin: '0', typography: 'body.b2Strong' })
+
+  export const link = style({ color: 'inherit !custom', textUnderlineOffset: '2px !custom' })
+
+  export const list = style({ margin: '0', paddingInlineStart: '20' })
+
+  export const page = style({
+    backgroundColor: 'background.primary',
+    display: 'grid',
+    justifyItems: 'center',
+    padding: '16',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/PaymentValidation.tsx)
+
+This reference layout uses [Field](/docs/components/field), [AmountInput](/docs/components/amount-input), and [Alert](/docs/components/alert). A short address shows a format error on Tab. An empty amount on submit shows the summary.
+
+## Guidelines
+
+### Place Errors Near Their Cause
+
+* **One Field (Field.Error):** Set `invalid` on the [Field](/docs/components/field), with the error below.
+* **A Section or Action (Alert):** Show a negative [Alert](/docs/components/alert) above what it describes.
+* **The Whole Page (Banner):** Show a negative [Banner](/docs/components/banner) at the top of the page.
+* **A Background Task (Toast):** Show a [Toast](/docs/components/toast). If a retry exists, add it as an action.
+
+### Validate at the Right Moment
+
+Validate when the reader can act on the result. An empty required field is not an error until the reader tries to continue.
+
+* **On Submit (Default):** Check every field, even empty required ones, in `onSubmit`. Pass each result to `invalid`.
+* **On Blur (Tab):** Check a format when focus leaves the field. Pass `validate` and `validationMode="onBlur"`.
+* **On Change (Clear only):** Clear a shown error as soon as the value is valid, without another submit.
+
+Do not validate a format on every keystroke before blur, since every partial address is malformed.
+
+**Do:** Check an amount against the balance on blur, so the limit shows before submit.
+
+```tsx
+<Field.Root invalid>
+  <AmountInput.Root defaultValue="300">
+    <Field.Label>Amount</Field.Label>
+    <AmountInput.Control />
+    <Field.Error match>Exceeds your balance of $250.00.</Field.Error>
+  </AmountInput.Root>
+</Field.Root>
+```
+
+**Don't:** Flag an empty field before the reader tries to continue.
+
+```tsx
+<Field.Root invalid>
+  <Field.Label>Recipient address</Field.Label>
+  <TextInput.Group>
+    <TextInput.Control />
+  </TextInput.Group>
+  <Field.Error match>Enter an address.</Field.Error>
+</Field.Root>
+```
+
+### Write Errors That Say How to Fix the Value
+
+State what to enter, in one sentence that starts with a verb, such as Enter a 42-character address that starts with 0x. Most messages need only the fix, not the fault.
+
+* **Say How to Fix It:** Write "Enter a valid email", not "Invalid email" or "You entered an invalid email".
+* **Name the Limit:** If a limit exists, name it, such as a length or the available balance.
+* **Use Plain Words:** Never show raw codes, stack traces, or revert strings alone. Skip apologies and exclamation marks.
+* **Keep the Value:** Keep the typed value, so the reader corrects it instead of starting over.
+* **Reuse the Label:** Use the field's label in the message, so it also reads well in a summary.
+
+**Do:** State what a valid value looks like.
+
+```tsx
+/**
+ * Do example for "Write Errors That Say How to Fix the Value" on the Errors and Validation page.
+ * State what a valid value looks like.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root invalid {...styles.fill()}>
+      <Field.Label>Recipient</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control defaultValue="0x71C7656EC7ab88b098" />
+      </TextInput.Group>
+      <Field.Error match>Enter a 42-character address that starts with 0x.</Field.Error>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Write generic errors such as Invalid input or Error.
+
+```tsx
+/**
+ * Don't example for "Write Errors That Say How to Fix the Value" on the Errors and Validation page.
+ * Don't write generic errors such as Invalid input or Error.
+ * @module
+ */
+import { Field, style, TextInput } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root invalid {...styles.fill()}>
+      <Field.Label>Recipient</Field.Label>
+      <TextInput.Group>
+        <TextInput.Control defaultValue="0x71C7656EC7ab88b098" />
+      </TextInput.Group>
+      <Field.Error match>Invalid input.</Field.Error>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+### Pair Every Red Fill With Text
+
+`invalid` fills the field red and plays a short nudge, which stops under reduced motion. Always render a `Field.Error` with the reason.
+
+**Do:** Show a `Field.Error` with every invalid field.
+
+```tsx
+/**
+ * Do example for "Pair Every Red Fill With Text" on the Errors and Validation page.
+ * Show a `Field.Error` with every invalid field.
+ * @module
+ */
+import { AmountInput, Field, style, Token } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root invalid {...styles.fill()}>
+      <AmountInput.Root defaultValue="1500">
+        <Field.Label>Amount</Field.Label>
+        <AmountInput.Control />
+        <Token readOnly symbol="USDC" />
+        <Field.Error match>Enter 1,250.00 USDC or less, your available balance.</Field.Error>
+      </AmountInput.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Rely on the red fill alone to mark a problem.
+
+```tsx
+/**
+ * Don't example for "Pair Every Red Fill With Text" on the Errors and Validation page.
+ * Don't rely on the red fill alone to mark a problem.
+ * @module
+ */
+import { AmountInput, Field, style, Token } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Field.Root invalid {...styles.fill()}>
+      <AmountInput.Root defaultValue="1500">
+        <Field.Label>Amount</Field.Label>
+        <AmountInput.Control />
+        <Token readOnly symbol="USDC" />
+      </AmountInput.Root>
+    </Field.Root>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+### Summarize Several Errors
+
+* **One problem:** On submit, move focus to its field.
+* **Two or more:** Render a negative [Alert](/docs/components/alert) at the top of the form. It names the count, lists each error as a link that focuses its field, and receives focus.
+
+**Do:** Keep each `Field.Error` beside its field, and link each summary item to it.
+
+```tsx
+/**
+ * Do example for "Summarize Several Errors" on the Errors and Validation page.
+ * Keep each `Field.Error` beside its field, and link each summary item to it.
+ * @module
+ */
+import { Alert, AmountInput, Field, Stack, style, TextInput, Token } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Stack gap="16" {...styles.fill()}>
+      <Alert intent="negative">
+        <Alert.Icon />
+        <Alert.Content>
+          2 fields need attention.
+          <ul {...styles.list()}>
+            <li>
+              <a href="#summary-recipient">Enter a 42-character address.</a>
+            </li>
+            <li>
+              <a href="#summary-amount">Enter an amount.</a>
+            </li>
+          </ul>
+        </Alert.Content>
+      </Alert>
+      <Field.Root invalid>
+        <Field.Label>Recipient address</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="0x8f3a91c2" id="summary-recipient" />
+        </TextInput.Group>
+        <Field.Error match>Enter a 42-character address.</Field.Error>
+      </Field.Root>
+      <Field.Root invalid>
+        <AmountInput.Root>
+          <Field.Label>Amount</Field.Label>
+          <AmountInput.Control id="summary-amount" />
+          <Token readOnly symbol="USDC" />
+          <Field.Error match>Enter an amount.</Field.Error>
+        </AmountInput.Root>
+      </Field.Root>
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+
+  export const list = style({ margin: '0', paddingInlineStart: '16' })
+}
+```
+
+**Don't:** List errors only in the summary, away from the fields.
+
+```tsx
+/**
+ * Don't example for "Summarize Several Errors" on the Errors and Validation page.
+ * Don't list errors only in the summary, away from the fields.
+ * @module
+ */
+import { Alert, AmountInput, Field, Stack, style, TextInput, Token } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Stack gap="16" {...styles.fill()}>
+      <Alert intent="negative">
+        <Alert.Icon />
+        <Alert.Content>
+          2 fields need attention.
+          <ul {...styles.list()}>
+            <li>Enter a 42-character address.</li>
+            <li>Enter an amount.</li>
+          </ul>
+        </Alert.Content>
+      </Alert>
+      <Field.Root>
+        <Field.Label>Recipient address</Field.Label>
+        <TextInput.Group>
+          <TextInput.Control defaultValue="0x8f3a91c2" />
+        </TextInput.Group>
+      </Field.Root>
+      <Field.Root>
+        <AmountInput.Root>
+          <Field.Label>Amount</Field.Label>
+          <AmountInput.Control />
+          <Token readOnly symbol="USDC" />
+        </AmountInput.Root>
+      </Field.Root>
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+
+  export const list = style({ margin: '0', paddingInlineStart: '16' })
+}
+```
+
+### Report Failed Requests Where They Happen
+
+If a submit fails on the network, keep the form open with its values, so a retry takes one press. State the failure in a negative [Alert](/docs/components/alert) above the actions.
+
+* **Outcome First:** Lead with what did not happen, such as "Payment not sent".
+* **Say Where the Money Is:** For payments, always state whether funds moved. An unsure reader often pays twice.
+* **A Next Step:** If a retry can succeed, offer Try again. Otherwise, offer a different path.
+
+**Do:** State what failed, what it means for the funds, and what to do next.
+
+```tsx
+/**
+ * Do example for "Report Failed Requests Where They Happen" on the Errors and Validation page.
+ * State what failed, what it means for the funds, and what to do next.
+ * @module
+ */
+import { Alert, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Alert intent="negative" {...styles.fill()}>
+      <Alert.Icon />
+      <Alert.Content>
+        Couldn't send payment. No funds moved. Check your connection, then try again.
+      </Alert.Content>
+    </Alert>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Show Something went wrong, or a status code, as the whole message.
+
+```tsx
+/**
+ * Don't example for "Report Failed Requests Where They Happen" on the Errors and Validation page.
+ * Don't show Something went wrong, or a status code, as the whole message.
+ * @module
+ */
+import { Alert, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Alert intent="negative" {...styles.fill()}>
+      <Alert.Icon />
+      <Alert.Content>Something went wrong. Error 503.</Alert.Content>
+    </Alert>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+Do not report a failed payment only in a [Toast](/docs/components/toast). It dismisses itself before the reader decides what to do.
+
+### Report Page-Wide Errors in a Banner
+
+If a problem affects the whole page, such as a lost connection, keep the [Banner](/docs/components/banner) visible until the problem resolves.
+
+**Do:** Use a [Banner](/docs/components/banner) for a problem that affects the whole page.
+
+```tsx
+<Banner intent="negative">
+  <Banner.Content>You are offline. Changes save when you reconnect.</Banner.Content>
+</Banner>
+```
+
+**Don't:** Report a field error in a [Banner](/docs/components/banner), away from the field.
+
+```tsx
+<Banner intent="negative">
+  <Banner.Content>Enter a valid email.</Banner.Content>
+</Banner>
+```
+
+### Explain Transaction Failures
+
+A transaction that reached the network and failed differs from a request that never arrived. Mark it Failed with a [Badge](/docs/components/badge) and keep it in activity. A failed transfer moves no funds, but its network fee may still be charged, so state both.
+
+**Do:** Show the reason a transaction failed beside its Failed status.
+
+```tsx
+/**
+ * Do example for "Explain Transaction Failures" on the Errors and Validation page.
+ * Show the reason a transaction failed beside its Failed status.
+ * @module
+ */
+import { Badge, ListGroup, style } from '@tempoxyz/ds'
+import { AlertCircle } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ListGroup.Root {...styles.fill()}>
+      <ListGroup.Row>
+        <ListGroup.Info>
+          <ListGroup.Title>Sent 25.00 USDC</ListGroup.Title>
+          <ListGroup.Description>
+            Not enough USDC left to cover the network fee
+          </ListGroup.Description>
+        </ListGroup.Info>
+        <Badge>
+          <AlertCircle />
+          Failed
+        </Badge>
+      </ListGroup.Row>
+    </ListGroup.Root>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+**Don't:** Show only a raw revert string as the reason.
+
+```tsx
+/**
+ * Don't example for "Explain Transaction Failures" on the Errors and Validation page.
+ * Don't show only a raw revert string as the reason.
+ * @module
+ */
+import { Badge, ListGroup, style } from '@tempoxyz/ds'
+import { AlertCircle } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ListGroup.Root {...styles.fill()}>
+      <ListGroup.Row>
+        <ListGroup.Info>
+          <ListGroup.Title>Sent 25.00 USDC</ListGroup.Title>
+          <ListGroup.Description>execution reverted (0x3ee5aeb5)</ListGroup.Description>
+        </ListGroup.Info>
+        <Badge>
+          <AlertCircle />
+          Failed
+        </Badge>
+      </ListGroup.Row>
+    </ListGroup.Root>
+  )
+}
+
+namespace styles {
+  export const fill = style({ width: '100% !custom' })
+}
+```
+
+### Retry Safely
+
+```tsx
+import { Alert, Button, Frame, ListGroup, style, Surface, Toast } from '@tempoxyz/ds'
+import { useRef, useState } from 'react'
+
+export const fill = true
+function Review() {
+  const toast = Toast.useToast()
+  const attempts = useRef(0)
+  const [failed, setFailed] = useState(false)
+  const [pending, setPending] = useState(false)
+
+  return (
+    <Surface {...styles.card()}>
+      <Frame.Root>
+        <Frame.Header>
+          <Frame.Title>Review payment</Frame.Title>
+          <Frame.Description>Check the details, then send.</Frame.Description>
+        </Frame.Header>
+        <ListGroup.Root>
+          <ListGroup.Row>
+            <ListGroup.Label>To</ListGroup.Label>
+            <span {...styles.mono()}>0x71C7…976F</span>
+          </ListGroup.Row>
+          <ListGroup.Row>
+            <ListGroup.Label>Amount</ListGroup.Label>
+            25.00 USDC
+          </ListGroup.Row>
+          <ListGroup.Row>
+            <ListGroup.Label>Network fee</ListGroup.Label>
+            0.001 USDC
+          </ListGroup.Row>
+        </ListGroup.Root>
+        <Frame.Footer {...styles.footer()}>
+          {failed && (
+            <Alert intent="negative">
+              <Alert.Icon />
+              <Alert.Content>
+                Couldn't reach the Tempo network, so your payment wasn't sent and no funds moved.
+                Check your connection, then try again.
+              </Alert.Content>
+            </Alert>
+          )}
+          <Frame.Actions>
+            <Button disabled={pending} variant="secondary">
+              Back
+            </Button>
+            <Button
+              loading={pending}
+              onClick={() => {
+                attempts.current += 1
+                setPending(true)
+                setTimeout(() => {
+                  setPending(false)
+                  // The first attempt fails so you can see the retry. The second succeeds.
+                  if (attempts.current % 2 === 1) return setFailed(true)
+                  setFailed(false)
+                  toast.add({ intent: 'positive', title: 'Payment sent' })
+                }, 1200)
+              }}
+            >
+              Send payment
+            </Button>
+          </Frame.Actions>
+        </Frame.Footer>
+      </Frame.Root>
+    </Surface>
+  )
+}
+
+export function Demo() {
+  return (
+    <div {...styles.page()}>
+      <Toast.Provider>
+        <Review />
+        <Toast.Viewport />
+      </Toast.Provider>
+    </div>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxSizing: 'border-box',
+    maxWidth: '28rem !custom',
+    width: '100% !custom',
+  })
+
+  export const footer = style({ rowGap: '16' })
+
+  export const mono = style({ fontFamily: 'mono' })
+
+  export const page = style({
+    backgroundColor: 'background.primary',
+    display: 'grid',
+    justifyItems: 'center',
+    padding: '16',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/PaymentRetry.tsx)
+
+The first press fails and the second succeeds.
+
+* **Retry With the Primary Action (loading):** Let the primary action retry. Set `loading` during each attempt, and add no second Retry button.
+* **Check Unknown Outcomes (Pending):** Retry only if the first attempt never reached the network. Otherwise, check the transaction status first.
+* **Wait for a New Value:** Do not retry validation errors automatically. Nothing changes until the value does.
+* **Point Elsewhere:** After repeated failures, point to a next step, such as a status page or support.
+
+### Keep Submit Buttons Enabled
+
+A disabled button states no reason. An enabled one lets the reader submit and read every error.
+
+**Do:** Keep the button enabled and show errors on submit.
+
+```tsx
+<Button>Send payment</Button>
+```
+
+**Don't:** Disable the button without stating what is missing.
+
+```tsx
+<Button disabled>Send payment</Button>
+```
+
+## States
+
+* **Default:** Fields with descriptions and no errors. Nothing is checked before interaction.
+* **Loading (loading):** Earlier errors stay visible while a check or request runs.
+* **Disabled:** Skip validation for disabled fields. Screen readers do not announce an error on a disabled control.
+* **Success:** After a successful submit, confirm the result with a [Toast](/docs/components/toast) or the next screen.
+
+## Accessibility
+
+* **Linked Errors (aria-describedby):** A shown error is read when its control takes focus. `invalid` sets `aria-invalid`. `success` sets no state.
+* **Summary Links:** A negative alert announces the summary on render. Each link moves focus to its field.
+
+[Feedback and Status](/docs/patterns/feedback-and-status#accessibility) covers how alerts and banners announce.
+
+## Related
+
+[Field](/docs/components/field)
+
+Use for labels and error messages.
+
+[Alert](/docs/components/alert)
+
+Use for summaries and failures.
+
+[Toast](/docs/components/toast)
+
+Use for background failures.
+
+[Forms](/docs/patterns/forms)
+
+Covers layout and actions.
+
+[Feedback and Status](/docs/patterns/feedback-and-status)
+
+Covers the Failed and Couldn't load states.
+
+[Empty States](/docs/patterns/empty-states)
+
+Covers regions that couldn't load.