# Tone

How Tempo's voice adjusts to the reader, from a first visit to an error.

## Overview

[Voice](/docs/foundations/content/voice) stays the same everywhere. Tone shifts with what the reader is doing and how they feel, and grows plainer and more specific as more money or access is at stake.

## Situations

### Onboarding

Welcome a new reader, and explain each new term once, in one sentence.

**Do:** Explain the first step and why it matters.

```tsx
<Empty.Root>
  <Empty.Icon>
    <Wallet />
  </Empty.Icon>
  <Empty.Title>Add funds to start</Empty.Title>
  <Empty.Description>Deposit dollars or stablecoins to send your first payment.</Empty.Description>
  <Empty.Actions>
    <Button size="small">Add funds</Button>
  </Empty.Actions>
</Empty.Root>
```

**Don't:** Assume crypto vocabulary.

```tsx
<Empty.Root>
  <Empty.Icon>
    <Wallet />
  </Empty.Icon>
  <Empty.Title>Bridge assets</Empty.Title>
  <Empty.Description>Bridge ERC-20s to the L1 to bootstrap liquidity.</Empty.Description>
</Empty.Root>
```

### Success

State what finished in a positive [Toast](/docs/components/toast) when nothing is left to do, then stop.

* **Name the Result:** Use a noun and a past-tense verb.
* **Add the Detail:** Add the amount or recipient as confirmation.
* **Skip the Celebration:** Leave out praise, exclamation marks, and emoji.
* **Wait for the Network:** Show a pending state until the network confirms.

### In Progress

Be calm and specific about what happens next and how long it takes.

* **Name the Step:** End a status label with an ellipsis (…).
* **Explain Long Waits:** Name the wait, and whether to stay on the page.

**Do:** State what the system does and set an expectation.

```tsx
<Progress.Root value={60}>
  <Progress.Label>Confirming payment</Progress.Label>
  <Progress.Track>
    <Progress.Indicator />
  </Progress.Track>
</Progress.Root>
<p>This usually takes less than a second.</p>
```

**Don't:** Leave the reader with an open-ended wait.

```tsx
<Spinner />
<p>Please wait…</p>
```

### Warnings

State a risk once, beside the content it affects, and only if the reader can act on it.

**Do:** State the risk and what to check in one or two plain sentences.

```tsx
/**
 * Do example for "Warnings" on the Tone page.
 * State the risk and what to check in one or two plain sentences.
 * @module
 */
import { Alert, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Alert intent="warning" {...styles.alert()}>
      <Alert.Icon />
      <Alert.Content>
        Payments are final. Check that the address matches the one you were given.
      </Alert.Content>
    </Alert>
  )
}

namespace styles {
  export const alert = style({ maxWidth: '20rem !custom' })
}
```

**Don't:** Shout, stack exclamation marks, or use the `negative` intent for a warning.

```tsx
/**
 * Don't example for "Warnings" on the Tone page.
 * Don't shout, stack exclamation marks, or use the `negative` intent for a warning.
 * @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.alert()}>
      <Alert.Icon />
      <Alert.Content>
        WARNING!! Double-check everything or your money is GONE forever!
      </Alert.Content>
    </Alert>
  )
}

namespace styles {
  export const alert = style({ maxWidth: '20rem !custom' })
}
```

* **Local Risk (Alert):** Use a warning [Alert](/docs/components/alert) for a field or section.
* **Product-Wide Condition (Banner):** Use a warning [Banner](/docs/components/banner) for the whole product.

### Errors

Stay neutral and direct, and follow the [error message structure](/docs/foundations/content/writing-style#structure-error-messages).

* **Lead With the Fix:** Add the cause only if it helps the reader act.
* **Show It Inline:** Show a blocking error inline, not in a [Toast](/docs/components/toast).
* **Keep the TextInput:** Keep the input, and state what to change.
* **Skip Blame and Jokes:** Don't apologize at length, blame, or joke.

### Security and Keys

**Do:** State the exact consequence and who is responsible.

```tsx
<Empty.Root>
  <Empty.Icon>
    <Key />
  </Empty.Icon>
  <Empty.Title>Save your recovery key</Empty.Title>
  <Empty.Description>Anyone with this key can move your funds. Tempo cannot recover it for you.</Empty.Description>
</Empty.Root>
```

**Don't:** Use humor for a security step.

```tsx
<Empty.Root>
  <Empty.Icon>
    <Key />
  </Empty.Icon>
  <Empty.Title>Your secret sauce 🤫</Empty.Title>
  <Empty.Description>Keep it somewhere safe-ish!</Empty.Description>
</Empty.Root>
```

### Sending Money

Repeat the exact amount, recipient, and fee on every step.

**Do:** Put the exact amount on the final action.

```tsx
<Button><Send />Send 25.00 USDC</Button>
```

**Don't:** Use a playful label for a payment.

```tsx
<Button>Let's go</Button>
```

### Irreversible Actions

Use a serious, explicit tone, as [Destructive Actions](/docs/patterns/destructive-actions) shows.

* **Name the Consequence:** Name exactly what the action removes or ends.
* **Confirm Payments on Review:** On review, state once that payments are final.
