# Grammar and Mechanics

Rules for numbers, amounts, dates, addresses, abbreviations, and punctuation in Tempo products.

## Overview

Consistent mechanics let people compare values at a glance and copy them without mistakes. `Amount`, `Hex`, and `DatePicker` apply most of these rules for you, in the reader's locale. Use them instead of formatting strings by hand.

The rules start from how [tempo.xyz](https://tempo.xyz), the [developer docs](https://tempo.xyz/developers), Tempo Wallet, and the Tempo token list write values. [Where the Sources Differ](#where-the-sources-differ) records each place they disagree.

## Numbers

* Use numerals for every number in the interface, including one to nine, such as 3 transactions or 1 API key.
* Group digits with the locale's separator, such as 1,250 in US English. `Amount` formats with `Intl.NumberFormat` in the reader's locale.
* Put a space between a number and its unit, such as 633 ms or 14,960 TPS. Percent signs and currency symbols attach to the number, as in 0.3% and $5.
* Use tabular figures for numbers that sit in columns or update in place. `Amount` sets them. For other numbers, set `fontVariantNumeric: 'tabular-nums !custom'` through `style`.
* Show exact values where they fit. Use compact notation, such as 1.4M, only in metric tiles and chart axes, and give the exact value in a tooltip or detail view.
* Write ranges with to in sentences, such as 1 to 3 business days.

## Currency and Amounts

Every amount needs a unit, so the reader never has to infer it from the surrounding screen. Pass `currency` or `symbol` to every `Amount`.

**Do:** Show a token amount with its symbol, and a fiat value with its currency.

**Don't:** Show a bare number and rely on the context to supply the unit.

| Value                         | Format        | `Amount` props                  |
| ----------------------------- | ------------- | ------------------------------- |
| Fiat value, such as a total   | $1,250.00     | `currency="USD"`                |
| Token amount                  | 1,250.00 USDC | `symbol="USDC"`                 |
| Credit in an activity list    | +250.00 USDC  | `sign="+"`                      |
| Debit in an activity list     | −250.00 USDC  | `sign="−"`                      |
| Value below the smallest unit | `<$0.01`      | `currency="USD"`                |
| Small fee shown in full       | $0.0003       | `currency="USD"` with `precise` |

* Use `currency` for a value in fiat, such as a total balance in USD. Use `symbol` for an amount of a specific token, such as a payment of 250.00 USDC.
* Don't write a stablecoin amount with a dollar sign. The reader needs to know which token moves.
* Put the symbol after the number, separated by a space, as `Amount` does. Write the symbol exactly as the token list spells it, such as pathUSD or USDC.e.
* TIP-20 tokens have 6 decimal places. Show the exact amount on review screens and receipts, and cap digits with `maxDecimals` only in lists and summaries.
* Pass amounts as decimal strings, such as `"1250.50"`, to avoid floating-point rounding. A string keeps its own fraction digits, including trailing zeros.
* Use the minus sign (−), not a hyphen, for debits, as in the `Amount` examples.
* Show USD stablecoin amounts with at least two decimals, such as 100.00 USDC, so they line up with fiat values in the same column.
* Show 0.00 for a zero balance. Save an empty state for when there's nothing to list at all.
* In explanatory text, an approximate cost reads well, as the docs write it: a transfer costs under a cent. On a review screen, show the fee as an `Amount`.

## Dates and Times

* Format dates for the reader's locale. `DatePicker` uses `Intl.DateTimeFormat` with `dateStyle: 'medium'`, which reads Oct 20, 2026 in US English.
* Don't write numeric-only dates, such as 10/20/2026, which mean different days in different locales.
* Use the locale's 12-hour or 24-hour clock. Add the time zone when a time matters across regions, such as when a payment is scheduled or a key expires.
* Use relative times for recent events, such as 5 minutes ago, and absolute dates for older ones. Show the exact timestamp in a tooltip or detail view.
* In dense displays, write durations as 2m 35s. In sentences, write 2 minutes 35 seconds.

## Addresses, Hashes, and Keys

Readers compare addresses by their first and last characters. Show the `0x` prefix and both ends, and let them copy the full value.

**Do:** Use `Hex`, which truncates in the middle and keeps both ends visible.

**Don't:** Cut an address or hash off at the end, which hides the characters people check.

* `formatHex` keeps 4 characters on each side by default, such as 0x3c44…93bc. Use it where `Hex` can't render, such as in a toast title or the document title.
* Set `copy` wherever someone needs the full value. Name the copy button by what it copies, such as Copy address.
* On a payment review, give `Hex` enough width to show the full address.
* Keep the case of an address as it is. A mixed-case address carries a checksum.
* Show API keys and other secrets with `SecretValue`, which masks them until you reveal them.

## Abbreviations and Units

Spell out a term the first time it appears in explanatory text, then abbreviate it. In dense displays such as metric tiles and table headers, use the abbreviation alone when your readers know it.

| Term                    | Write         | Example       |
| ----------------------- | ------------- | ------------- |
| Transactions per second | TPS           | 14,960 TPS    |
| Gas per second          | gas/s         | 1.38 Ggas/s   |
| Milliseconds            | ms            | 633 ms        |
| Percentile              | p50, p95, p99 | p95 latency   |
| Identifier              | ID            | Chain ID 4217 |
| Remote procedure call   | RPC           | RPC node      |

* Gas belongs on developer and performance surfaces. Tempo has no native gas token and charges fees in USD stablecoins, so payment screens say network fee and show it as an amount.
* Write the plural without an apostrophe, such as APIs and TIPs.
* Avoid Latin abbreviations. Write for example instead of e.g., and that is instead of i.e.

## Punctuation

* End full sentences with a period, in descriptions, errors, helper text, and banners. Leave the period off labels, buttons, headings, tags, and one-phrase toasts.
* Use a question mark for confirmation titles, such as Delete this webhook? Don't use exclamation marks.
* Use the serial comma, as in Send, receive, and swap.
* Use a colon between a label and its value in running text, such as Balance: $250.00. Don't put a colon after a form label.
* Use the ellipsis character (…) for in-progress labels, such as Confirming…, and for truncated values. Don't use it to trail off.
* Write and instead of an ampersand, except in a proper name.
* Avoid semicolons and em dashes in interface text. Split the sentence, or use a comma or colon.
* Use the straight apostrophe ('), as the library's examples and most docs pages do.

## Where the Sources Differ

| Topic                    | What the sources do                                                                                                                      | Product screens                                          |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| Small numbers            | The docs mostly use numerals, but one quickstart step spells out one.                                                                    | Numerals for every number.                               |
| Large figures            | tempo.xyz rounds with a plus and a word, such as $36+ billion and 100+ countries.                                                        | Exact values. Compact notation only in tiles and axes.   |
| Decimals                 | The docs drop decimals from whole amounts in prose, such as 100 AlphaUSD.                                                                | At least two decimals for USD stablecoins.               |
| Token after an amount    | The docs write some test tokens by display name (AlphaUSD) and pathUSD by its symbol. The token list's symbols are alphaUSD and pathUSD. | The token list symbol, which is what `Amount` shows.     |
| Unit spacing             | The Tempo Performance dashboard writes 633ms with no space but sets TPS apart from its value.                                            | A space before every unit except % and currency symbols. |
| Toast periods            | Tempo Wallet ends some one-phrase confirmations with a period, such as its swap confirmation, but not Address copied.                    | No period on a one-phrase toast.                         |
| Semicolons and em dashes | The docs use a few semicolons and em dashes. tempo.xyz uses em dashes in its figures.                                                    | Neither, in interface text.                              |
| Serial comma             | The docs use it consistently. tempo.xyz drops it once.                                                                                   | Always.                                                  |
| Apostrophes              | tempo.xyz uses the curly apostrophe (’). The docs and the library's examples mostly use the straight one.                                | Straight.                                                |

## Related

* [Writing Style](/docs/foundations/content/writing-style) for capitalization and messages
* [Word List](/docs/foundations/content/word-list) for preferred terms
* [Amount](/docs/components/amount) for formatting money and token amounts
* [Hex](/docs/components/hex) for addresses and hashes
* [Blockchain Values](/docs/patterns/blockchain-values) for showing onchain data