# Writing Style

How Tempo writes interface text: sentence case, a verb first, and plain words.

## Overview

Tempo's interface text is short, specific, and plain. It names the thing and the action in words that a reader new to crypto knows.

The rules follow [tempo.xyz](https://tempo.xyz) and the [developer docs](https://tempo.xyz/developers). [Where the Sources Differ](#where-the-sources-differ) records the choice for product screens.

## Principles

* **Clear Before Clever:** State what happens, in familiar words.
* **Short:** Cut each word that doesn't change the meaning.
* **Specific:** Name the action and its object, not Continue.
* **Consistent:** Call one thing by one name everywhere.

## Capitalization

Use sentence case everywhere, capitalizing only the first word and proper nouns.

**Do:** Capitalize the first word of each heading, sentence, and label.

```tsx
/**
 * Do example for "Writing Style" on the Writing Style page.
 * Capitalize the first word of each heading, sentence, and label.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.card()}>
      <p {...styles.title()}>Add funds</p>
      <p {...styles.text()}>Deposit USDC from another wallet or an exchange.</p>
      <Button size="small">Copy deposit address</Button>
    </div>
  )
}

namespace styles {
  export const card = style({
    alignItems: 'flex-start',
    display: 'flex',
    flexDirection: 'column',
    gap: '8',
    maxWidth: '18rem !custom',
  })

  export const text = style({
    color: 'content.secondary',
    margin: '0 !custom',
    typography: 'body.b2',
  })

  export const title = style({
    color: 'content.primary',
    margin: '0 !custom',
    typography: 'body.b1Strong',
  })
}
```

**Don't:** Capitalize every word, in headings or anywhere else in the interface.

```tsx
/**
 * Don't example for "Writing Style" on the Writing Style page.
 * Don't capitalize every word, in headings or anywhere else in the interface.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.card()}>
      <p {...styles.title()}>Add Funds</p>
      <p {...styles.text()}>Deposit USDC From Another Wallet or an Exchange.</p>
      <Button size="small">Copy Deposit Address</Button>
    </div>
  )
}

namespace styles {
  export const card = style({
    alignItems: 'flex-start',
    display: 'flex',
    flexDirection: 'column',
    gap: '8',
    maxWidth: '18rem !custom',
  })

  export const text = style({
    color: 'content.secondary',
    margin: '0 !custom',
    typography: 'body.b2',
  })

  export const title = style({
    color: 'content.primary',
    margin: '0 !custom',
    typography: 'body.b1Strong',
  })
}
```

### Proper Nouns

* **Tempo Products and Standards:** Tempo Wallet, Tempo Explorer, and TIP-20.
* **Companies and Networks:** Other companies, products, and networks.
* **People, Places, and Languages:** Including currencies named after a place.
* **Symbols and Values:** Keep USDC, iOS, and 0x1a2b… exactly as written.
* **Lowercase Symbols:** Rewrite a sentence that starts with pathUSD.
* **Features and Concepts:** Keep access key and passkey lowercase in titles.

**Do:** Capitalize the product name and nothing else.

```tsx
<Field.Root>
  <Field.Label>Recipient address</Field.Label>
  <TextInput.Group>
    <TextInput.Control placeholder="0x…" />
  </TextInput.Group>
  <Field.Description>Paste a Tempo address or choose a saved contact.</Field.Description>
</Field.Root>
```

**Don't:** Capitalize common words or lowercase a product name.

```tsx
<Field.Root>
  <Field.Label>Recipient Address</Field.Label>
  <TextInput.Group>
    <TextInput.Control placeholder="0x…" />
  </TextInput.Group>
  <Field.Description>Paste a tempo address or choose a saved Contact.</Field.Description>
</Field.Root>
```

### Never All Caps

**Do:** Choose clearer words, or use size and weight sparingly.

```tsx
<Alert intent="warning">
  <Alert.Icon />
  <Alert.Content>This quote expires in 10 minutes.</Alert.Content>
</Alert>
```

**Don't:** Set text in all caps or use capitals for emphasis.

```tsx
<Alert intent="warning">
  <Alert.Icon />
  <Alert.Content>THIS QUOTE EXPIRES IN 10 MINUTES.</Alert.Content>
</Alert>
```

## Write Labels

### Buttons

* **Verb First:** Start each button and menu item with a verb.
* **Short Labels:** Use one to three words, such as Add funds.
* **One Label per Action:** Use the same label for an action everywhere.

**Do:** Name the action and the object it affects.

```tsx
<Button>Delete access key</Button>
```

**Don't:** Use generic labels such as "OK", "Yes", or "Submit".

```tsx
<Button>OK</Button>
```

### Form Labels

* **Name the Value:** Use a noun phrase, with no colon or Enter your.
* **Hints in the Description:** Put format hints in the field's description.
* **Example Placeholders:** Use a placeholder only for an example value.
* **Mark the Minority:** Mark optional fields when most are required.

### Headings and Titles

* **Name the Page:** Name the page or task, such as API keys.
* **Verb for a Task:** Start a task title with its verb.
* **Question to Confirm:** Write a confirmation title as a question.
* **One Phrase:** Use one phrase, with no end punctuation.

### Links

* **Name the Destination:** Name where the link goes.
* **No Typed Arrows:** Leave out →, and let [ListGroup](/docs/components/list-group) draw a chevron.

### Tooltips

* **A Few Words:** Name or clarify the trigger of a [Tooltip](/docs/components/tooltip).
* **Definitions:** A definition can be one full sentence.
* **Nothing Essential:** Keep actions and essential details on the page.

### Status Labels

* **Short Status:** Use one or two words in a [Badge](/docs/components/badge) or status column.
* **One Name per Status:** Keep one name for each status on every screen.

## Write Messages

### Structure Error Messages

Most errors state three things, in this order.

* **What Happened:** State the outcome first, in plain words.
* **Why:** State the cause if it helps the reader act.
* **What to Do:** End with the action that resolves it.
* **Beside a Field:** Lead with the fix when context shows the issue.
* **Unknown Cause:** Say what to try, not only Something went wrong.
* **Support Reference:** Add a support reference as secondary text.

**Do:** State how to fix the value, with the limit that applies.

```tsx
/**
 * Do example for "Structure Error Messages" on the Writing Style page.
 * State how to fix the value, with the limit that applies.
 * @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.field()}>
      <AmountInput.Root defaultValue="1500">
        <Field.Label>Amount</Field.Label>
        <AmountInput.Control />
        <Token readOnly symbol="USDC" />
        <Field.Error match>Enter an amount up to your balance of 1,250.00 USDC.</Field.Error>
      </AmountInput.Root>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```

**Don't:** Show raw error names, codes, or RPC messages as the message.

```tsx
/**
 * Don't example for "Structure Error Messages" on the Writing Style page.
 * Don't show raw error names, codes, or RPC messages as the message.
 * @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.field()}>
      <AmountInput.Root defaultValue="1500">
        <Field.Label>Amount</Field.Label>
        <AmountInput.Control />
        <Token readOnly symbol="USDC" />
        <Field.Error match>Error: InsufficientBalance</Field.Error>
      </AmountInput.Root>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '18rem !custom', width: '100% !custom' })
}
```

### Empty States

* **Why It's Empty:** Say why the area has nothing to show.
* **What to Do Next:** Offer the next step, as [Empty States](/docs/patterns/empty-states) shows.

### Confirmations

* **Two to Four Words:** Title a [Toast](/docs/components/toast) with the outcome.
* **Needed Detail Only:** Describe only needed detail, such as the amount.
* **Shortcut Actions:** Make each toast action reachable elsewhere too.

## Put the Important Words First

Readers scan the first few words of a line.

**Do:** Start with the subject, and put conditions after it.

```tsx
<Alert intent="warning">
  <Alert.Icon />
  <Alert.Content>Transfers over $10,000 need a second approval.</Alert.Content>
</Alert>
```

**Don't:** Open with filler or bury the rule at the end.

```tsx
<Alert intent="warning">
  <Alert.Icon />
  <Alert.Content>Please note that, depending on the amount, a second approval may be needed.</Alert.Content>
</Alert>
```

## Use Plain Words

Write for a reader new to crypto.

* **Everyday Words:** Say network fee, not gas.
* **Define at First Use:** Explain a technical term at its first use.

## Address the Reader as You

* **Your, Not My:** Use your for what belongs to the reader, not my.
* **We for Tempo:** Use we only for Tempo as a company, and rarely.

**Do:** Address the reader and state what happens next.

```tsx
<Empty.Root>
  <Empty.Icon>
    <Wallet />
  </Empty.Icon>
  <Empty.Title>No payments yet</Empty.Title>
  <Empty.Description>Payments you send or receive appear here.</Empty.Description>
</Empty.Root>
```

**Don't:** Describe the reader in the third person.

```tsx
<Empty.Root>
  <Empty.Icon>
    <Wallet />
  </Empty.Icon>
  <Empty.Title>No payments yet</Empty.Title>
  <Empty.Description>The user has not made any payments.</Empty.Description>
</Empty.Root>
```

## Keep It Short

* **Buttons (1 to 3 words):** A verb and its object.
* **Headings (under 6 words):** The page or the task.
* **Descriptions (1 sentence):** The detail that the title leaves out.
* **Error Messages (1 or 2 sentences):** The outcome, then the fix.
* **Sentences (under 20 words):** Split a longer sentence in two.

**Do:** Cut filler such as please, simply, just, and successfully.

```tsx
<Alert intent="positive">
  <Alert.Icon />
  <Alert.Content>Payment sent</Alert.Content>
</Alert>
```

**Don't:** Pad a message with words that add nothing.

```tsx
<Alert intent="positive">
  <Alert.Icon />
  <Alert.Content>Your payment was sent successfully</Alert.Content>
</Alert>
```

## Write for Everyone

* **Name the Control:** Name the control, not below, above, or click.
* **Prefer Common Words:** Skip idioms, which translate poorly.

## Where the Sources Differ

| Topic           | What the sources do                                                                                                        | Product screens       |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| Heading case    | Site and docs headings use sentence case. The docs home and one docs heading use Title Case. Tempo Performance mixes both. | Sentence case.        |
| Contractions    | The docs mix can't with cannot, and doesn't with does not. Tempo Wallet errors use Cannot.                                 | Contractions.         |
| Repeated labels | The marketing site words one contact button two ways.                                                                      | One label per action. |
| Link arrows     | Some docs links end with →.                                                                                                | No typed arrows.      |
| Colon titles    | Some docs and site titles join two phrases with a colon.                                                                   | One phrase per title. |

## Related

[Button](/docs/components/button)

Use for button labels.

[Field](/docs/components/field)

Use for labels, descriptions, and errors.

[Errors and Validation](/docs/patterns/errors-and-validation)

Covers when and where to show errors.
