@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/foundations/content/writing-style.md

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

package/dist/docs/foundations/iconography.md

@@ -0,0 +1,282 @@
+# Iconography
+
+Icons from the Tempo catalog, and how to size, color, and label them.
+
+## Overview
+
+Icons support a label rather than replace it. Every icon in the catalog shares one grid and stroke weight, so any group of icons reads as one family.
+
+
+
+* **Grid (16 by 16):** Every icon draws on the same square grid.
+* **Size (1em):** An icon matches the font size of its text.
+* **Color (currentColor):** An icon fills with the color of its text.
+* **Imports (one module each):** A build carries only the icons it imports.
+
+```tsx
+import { Send } from '@tempoxyz/ds/icons'
+
+export function SendButton() {
+  return (
+    <Button>
+      <Send />
+      Send payment
+    </Button>
+  )
+}
+```
+
+## Size and Color
+
+Components size and color their own icons, so inside a [Button](/docs/components/button) you add only the icon as a child.
+
+### Size
+
+* **Beside Text (1em):** The default in buttons, links, and running text.
+* **Beside Titles (20px):** A larger icon beside a section or card title.
+* **Status Icons (20px):** A status icon beside a message, as in a [Toast](/docs/components/toast).
+* **Alert Indicator (16px):** An [Alert](/docs/components/alert) marks its tone with a square in a 16px box.
+* **Modal Icons (24px):** An [IconTile](/docs/components/icon-tile) frames the icon above a modal title.
+* **Standalone Icons (fontSize):** Set its font size, not its width and height.
+
+### Color
+
+Set the color on the icon or its parent, with the same roles as text.
+
+* **Primary (content.primary):** The default, beside primary labels and text.
+* **Secondary (content.secondary):** Beside metadata, such as an update time.
+* **Status (content.warning):** Only for an icon that reports a status.
+
+## Guidelines
+
+### Pair Icons With Text
+
+Drop the label only for actions that are familiar without words, such as Close, Copy, and More. Don't give an icon to only one of several buttons, since it draws attention to that action.
+
+**Do:** Use icon-only buttons for actions with a universal icon.
+
+```tsx
+<Button aria-label="Copy address" shape="icon" variant="secondary">
+  <Copy />
+</Button>
+<Button aria-label="Delete contact" shape="icon" variant="secondary">
+  <Delete />
+</Button>
+```
+
+**Don't:** Drop the label from actions that have no universal icon.
+
+```tsx
+<Button aria-label="Wallets" shape="icon" variant="secondary">
+  <Wallet />
+</Button>
+<Button aria-label="Access keys" shape="icon" variant="secondary">
+  <Key />
+</Button>
+```
+
+### Match Icons to Their Text
+
+An icon that inherits from its label scales with the type and stays aligned. Any other color reads as a status.
+
+**Do:** Let an inline icon inherit the size and color of its label.
+
+```tsx
+/**
+ * Do example for "Match Icons to Their Text" on the Iconography page.
+ * Let an inline icon inherit the size and color of its label.
+ * @module
+ */
+import { Copy } from '@tempoxyz/ds/icons'
+import { style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <span {...styles.label()}>
+      <Copy />
+      Copy address
+    </span>
+  )
+}
+
+namespace styles {
+  export const label = style({
+    alignItems: 'center',
+    color: 'content.primary',
+    display: 'inline-flex',
+    gap: '4',
+    typography: 'body.b2Strong',
+  })
+}
+```
+
+**Don't:** Enlarge or recolor an inline icon apart from its text.
+
+```tsx
+/**
+ * Don't example for "Match Icons to Their Text" on the Iconography page.
+ * Don't enlarge or recolor an inline icon apart from its text.
+ * @module
+ */
+import { Copy } from '@tempoxyz/ds/icons'
+import { style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <span {...styles.label()}>
+      <Copy {...styles.icon()} />
+      Copy address
+    </span>
+  )
+}
+
+namespace styles {
+  export const icon = style({ color: 'accent.blue.background', fontSize: '30' })
+
+  export const label = style({
+    alignItems: 'center',
+    color: 'content.primary',
+    display: 'inline-flex',
+    gap: '4',
+    typography: 'body.b2Strong',
+  })
+}
+```
+
+### Use Catalog Icons Only
+
+Icons from another set break the shared grid and stroke weight. If the catalog lacks an icon, propose one with its use case in the Design System project.
+
+**Do:** Draw every icon in a group from the catalog.
+
+```tsx
+/**
+ * Do example for "Use Catalog Icons Only" on the Iconography page.
+ * Draw every icon in a group from the catalog.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+import { ArrowDownLeft, Send, SwapHorizontal } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Button size="small" variant="secondary">
+        <Send />
+        Send
+      </Button>
+      <Button size="small" variant="secondary">
+        <ArrowDownLeft />
+        Receive
+      </Button>
+      <Button size="small" variant="secondary">
+        <SwapHorizontal />
+        Swap
+      </Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
+}
+```
+
+**Don't:** Mix in an icon from another set.
+
+```tsx
+/**
+ * Don't example for "Use Catalog Icons Only" on the Iconography page.
+ * Don't mix in an icon from another set.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+import { ArrowDownLeft, Send } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Button size="small" variant="secondary">
+        <Send />
+        Send
+      </Button>
+      <Button size="small" variant="secondary">
+        <ArrowDownLeft />
+        Receive
+      </Button>
+      <Button size="small" variant="secondary">
+        {/* A heavier, rounded stroke on a 24 by 24 grid, as another icon set draws it. */}
+        <svg
+          aria-hidden="true"
+          fill="none"
+          stroke="currentColor"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth="3"
+          viewBox="0 0 24 24"
+          {...styles.icon()}
+        >
+          <path d="M4 8h14l-4-4M20 16H6l4 4" />
+        </svg>
+        Swap
+      </Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const icon = style({ height: '1.25em !custom', width: '1.25em !custom' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
+}
+```
+
+* **Token Logos (TokenLogo):** Render token and network logos with [TokenLogo](/docs/components/token-logo).
+* **Account Images (Identicon):** Render accounts with [Avatar](/docs/components/avatar) or [Identicon](/docs/components/identicon).
+
+## Accessibility
+
+* **Decorative by Default (aria-hidden):** An icon without `aria-label` or `aria-labelledby` is hidden, so screen readers skip it.
+* **Meaningful Icons (role=img):** Add `aria-label` only if no nearby text states its meaning, such as a lone status icon.
+* **Icon-Only Buttons (aria-label):** Label the button, not the icon. Name the action, such as Close dialog rather than X.
+* **Tooltips (Tooltip):** Pair an icon-only button with a [Tooltip](/docs/components/tooltip) that repeats its label for sighted mouse users.
+* **Contrast (3:1):** Applies to meaningful icons. Both `content.primary` and `content.secondary` pass.
+* **Forced Colors (currentColor):** Icons follow the system text color in forced colors mode, with no extra styles.
+
+## Catalog
+
+* **Names (PascalCase):** Names match the design, such as `QRCode`.
+* **Reserved Names (InfinityIcon):** Avoids the JavaScript global `Infinity`.
+* **Shared Names (2):** A second icon with a taken name ends in `2`.
+* **Component Names (as):** Rename on import, such as `TableIcon`.
+* **Raw SVGs (.svg):** The original exports, for use outside React.
+
+```tsx
+import { Table } from '@tempoxyz/ds'
+import { Table as TableIcon } from '@tempoxyz/ds/icons'
+import copyUrl from '@tempoxyz/ds/icons/Copy.svg'
+```
+
+
+
+## Related
+
+[Button](/docs/components/button)
+
+Use for icon buttons and icons beside labels.
+
+[IconTile](/docs/components/icon-tile)
+
+Use for framed icons in headers and lists.
+
+[Tooltip](/docs/components/tooltip)
+
+Use for labelling icon buttons.
+
+[Color](/docs/foundations/color)
+
+Covers icon colors.