@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/foundations/content/tone.md

@@ -0,0 +1,194 @@
+# 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.

package/dist/docs/foundations/content/voice.md

@@ -0,0 +1,194 @@
+# Voice
+
+Tempo's personality in words, consistent across every product.
+
+## Overview
+
+Voice is how Tempo sounds in every product: a knowledgeable colleague who explains plainly and wastes no time, as on [tempo.xyz](https://tempo.xyz) and in the [developer docs](https://tempo.xyz/developers). [Tone](/docs/foundations/content/tone) adapts it to each situation, such as a first visit or a failed payment.
+
+## How Tempo Writes
+
+* **Cover Three Points:** State what is happening, what it costs, and what happens next.
+* **Define Before Explaining:** Open with one sentence that defines the thing, then list its parts.
+* **State Rules as Facts:** State limits and protections as what Tempo enforces, not as warnings.
+* **Name Availability Plainly (Testnet only):** Name a stage, such as beta or devnet only, with where it applies and what changes it.
+* **State What an Operation Doesn't Do:** State plainly that a refund is a new payment, not a reversal.
+
+## Traits
+
+Each trait names the line it must not cross.
+
+### Clear, Not Simplistic
+
+**Do:** Describe a payment in everyday money words, and format each value with
+[Amount](/docs/components/amount) or [Hex](/docs/components/hex).
+
+```tsx
+/**
+ * Do example for "Clear, Not Simplistic" on the Voice page.
+ * Describe a payment in everyday money words, and format each value with Amount or Hex.
+ * @module
+ */
+import { Amount, Hex, ListGroup, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ListGroup.Root {...styles.rows()}>
+      <ListGroup.Row>
+        <ListGroup.Label>To</ListGroup.Label>
+        <Hex value="0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc" />
+      </ListGroup.Row>
+      <ListGroup.Row>
+        <ListGroup.Label>Amount</ListGroup.Label>
+        <Amount symbol="USDC" value="250.00" />
+      </ListGroup.Row>
+      <ListGroup.Row>
+        <ListGroup.Label>Network fee</ListGroup.Label>
+        <Amount currency="USD" precise value="0.0003" />
+      </ListGroup.Row>
+    </ListGroup.Root>
+  )
+}
+
+namespace styles {
+  export const rows = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+}
+```
+
+**Don't:** Show protocol fields, base units, or gas parameters on a payment review.
+
+```tsx
+/**
+ * Don't example for "Clear, Not Simplistic" on the Voice page.
+ * Don't show protocol fields, base units, or gas parameters on a payment review.
+ * @module
+ */
+import { ListGroup, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <ListGroup.Root {...styles.rows()}>
+      <ListGroup.Row>
+        <ListGroup.Label>Recipient EOA</ListGroup.Label>
+        <span {...styles.value()}>0x3c44cddd…</span>
+      </ListGroup.Row>
+      <ListGroup.Row>
+        <ListGroup.Label>Value</ListGroup.Label>
+        <span {...styles.value()}>250000000</span>
+      </ListGroup.Row>
+      <ListGroup.Row>
+        <ListGroup.Label>Gas limit</ListGroup.Label>
+        <span {...styles.value()}>21000</span>
+      </ListGroup.Row>
+    </ListGroup.Root>
+  )
+}
+
+namespace styles {
+  export const rows = style({ maxWidth: '18rem !custom', width: '100% !custom' })
+
+  export const value = style({ typography: 'mono.m1' })
+}
+```
+
+### Precise, Not Approximate
+
+**Do:** State the exact amount, time, or limit.
+
+```tsx
+<Alert>
+  <Alert.Icon />
+  <Alert.Content>This quote expires in 10 minutes.</Alert.Content>
+</Alert>
+```
+
+**Don't:** Use vague words such as soon or shortly.
+
+```tsx
+<Alert>
+  <Alert.Icon />
+  <Alert.Content>This quote expires soon.</Alert.Content>
+</Alert>
+```
+
+### Confident, Not Boastful
+
+**Do:** Confirm the result as a fact, and stop.
+
+```tsx
+<Empty.Root>
+  <Empty.Icon>
+    <Receipt />
+  </Empty.Icon>
+  <Empty.Title>Payment sent</Empty.Title>
+  <Empty.Description>Alice received 25.00 USDC.</Empty.Description>
+</Empty.Root>
+```
+
+**Don't:** Use hype, hedging, exclamation marks, or emoji for a routine result.
+
+```tsx
+<Empty.Root>
+  <Empty.Icon>
+    <Receipt />
+  </Empty.Icon>
+  <Empty.Title>Woohoo! 🎉</Empty.Title>
+  <Empty.Description>Your lightning-fast payment is on its way!</Empty.Description>
+</Empty.Root>
+```
+
+### Calm, Not Casual
+
+**Do:** State what failed, and reassure the reader with a fact.
+
+```tsx
+<Alert intent="negative">
+  <Alert.Icon />
+  <Alert.Content>The payment did not go through. Your balance has not changed.</Alert.Content>
+</Alert>
+```
+
+**Don't:** Joke about a failure that involves money.
+
+```tsx
+<Alert intent="negative">
+  <Alert.Icon />
+  <Alert.Content>Oops! Something broke. Our bad.</Alert.Content>
+</Alert>
+```
+
+### Respectful, Not Condescending
+
+**Do:** Address the reader as you, and describe the problem and the fix.
+
+```tsx
+<Alert intent="negative">
+  <Alert.Icon />
+  <Alert.Content>This address isn't valid. Check it and try again.</Alert.Content>
+</Alert>
+```
+
+**Don't:** Blame the reader for an error.
+
+```tsx
+<Alert intent="negative">
+  <Alert.Icon />
+  <Alert.Content>You entered an invalid address.</Alert.Content>
+</Alert>
+```
+
+### Helpful, Not Pushy
+
+**Do:** Offer the next step plainly, and let the reader decide.
+
+```tsx
+<Button variant="secondary">Turn on notifications</Button>
+```
+
+**Don't:** Use fear or urgency to drive a choice.
+
+```tsx
+<Button variant="secondary">Don't miss out</Button>
+```