@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/components/icon-tile.md

@@ -0,0 +1,292 @@
+# IconTile
+
+Anchors a centered modal with one icon in a rounded square.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/IconTile.tsx)
+
+Figma: [Elements/Icon Tile](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-1245)
+
+## Overview
+
+An icon tile is a 56px rounded square with a 24px icon. It sits above the centered title of a modal, and `intent` tints it for the modal's outcome.
+
+## Examples
+
+### Basic
+
+```tsx
+import { IconTile } from '@tempoxyz/ds'
+import { Settings } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <IconTile>
+      <Settings />
+    </IconTile>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/IconTile/Basic.tsx)
+
+### Intent
+
+Set `intent` to `neutral` (default), `positive`, `warning`, or `negative`. Each tints the fill and the icon.
+
+```tsx
+import { IconTile, style } from '@tempoxyz/ds'
+import { AlertTriangle, Check, Delete, Passkey } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <IconTile intent="neutral">
+        <Passkey />
+      </IconTile>
+      <IconTile intent="positive">
+        <Check />
+      </IconTile>
+      <IconTile intent="warning">
+        <AlertTriangle />
+      </IconTile>
+      <IconTile intent="negative">
+        <Delete />
+      </IconTile>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/IconTile/Intent.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { IconTile } from '@tempoxyz/ds'
+
+<IconTile />
+```
+
+## Guidelines
+
+### When to Use
+
+* Top a centered acknowledgment, onboarding, success, or destructive confirmation modal with one chip above the title.
+
+### When Not to Use
+
+* Use [Avatar](/docs/components/avatar) with an icon to lead a list row, such as a wallet or app.
+* Use [Button](/docs/components/button) with `shape="icon"` for an icon that does something. The chip isn't interactive.
+* Use [Badge](/docs/components/badge) to show a status.
+* Use [Visual](/docs/components/visual) for an illustrated onboarding or feature modal. Never pair the two.
+
+### Pair the Chip With a Title
+
+**Do:** Place the chip above a centered title that states the outcome.
+
+```tsx
+/**
+ * Do example for "Pair the Chip With a Title" on the IconTile page.
+ * Place the chip above a centered title that states the outcome.
+ * @module
+ */
+import { IconTile, style } from '@tempoxyz/ds'
+import { Check } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <IconTile intent="positive">
+        <Check />
+      </IconTile>
+      <span {...styles.title()}>Payment sent</span>
+      <span {...styles.detail()}>Jane Cooper received 25.00 USDC.</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const detail = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const stack = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '4',
+    textAlign: 'center',
+    width: '100% !custom',
+  })
+
+  export const title = style({
+    color: 'content.primary',
+    marginBlockStart: '20',
+    typography: 'body.b1Strong',
+  })
+}
+```
+
+**Don't:** Rely on the chip alone to state the outcome.
+
+```tsx
+/**
+ * Don't example for "Pair the Chip With a Title" on the IconTile page.
+ * Don't rely on the chip alone to state the outcome.
+ * @module
+ */
+import { IconTile, style } from '@tempoxyz/ds'
+import { Check } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <IconTile intent="positive">
+        <Check />
+      </IconTile>
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({ display: 'flex', justifyContent: 'center', width: '100% !custom' })
+}
+```
+
+### Use One Icon From the Library
+
+The icon inherits the intent's color and the chip's 24px font size, so leave its size and color unset.
+
+**Do:** Pass one icon from `@tempoxyz/ds/icons`.
+
+```tsx
+/**
+ * Do example for "Pair the Chip With a Title" on the IconTile page.
+ * Place the chip above a centered title that states the outcome.
+ * @module
+ */
+import { IconTile, style } from '@tempoxyz/ds'
+import { Check } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <IconTile intent="positive">
+        <Check />
+      </IconTile>
+      <span {...styles.title()}>Payment sent</span>
+      <span {...styles.detail()}>Jane Cooper received 25.00 USDC.</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const detail = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const stack = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '4',
+    textAlign: 'center',
+    width: '100% !custom',
+  })
+
+  export const title = style({
+    color: 'content.primary',
+    marginBlockStart: '20',
+    typography: 'body.b1Strong',
+  })
+}
+```
+
+**Don't:** Put text, numbers, or images in the chip.
+
+```tsx
+/**
+ * Don't example for "Use One Icon From the Library" on the IconTile page.
+ * Don't put text, numbers, or images in the chip.
+ * @module
+ */
+import { IconTile, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <IconTile intent="positive">OK</IconTile>
+      <span {...styles.title()}>Payment sent</span>
+      <span {...styles.detail()}>Jane Cooper received 25.00 USDC.</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const detail = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const stack = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '4',
+    textAlign: 'center',
+    width: '100% !custom',
+  })
+
+  export const title = style({
+    color: 'content.primary',
+    marginBlockStart: '20',
+    typography: 'body.b1Strong',
+  })
+}
+```
+
+### Match the Intent to the Outcome
+
+Use one chip per modal, and leave it out of form and review modals.
+
+* **Feature (neutral):** Introduces a feature, such as passkeys.
+* **Done (positive):** Confirms a finished task, such as a payment.
+* **Risk (warning):** Flags a risk to read before you continue.
+* **Irreversible (negative):** Marks an action that can't be undone.
+
+## Accessibility
+
+An icon tile renders a `<span>` with no role and takes no focus. The icon inside sets what assistive technology perceives.
+
+### Semantics
+
+* **Chip (span):** Has no role of its own.
+* **Unnamed Icons (aria-hidden):** Icons without an `aria-label` are hidden, so the chip is silent.
+* **Named Icons (img):** An icon with an `aria-label` is announced as an image.
+
+### Your Responsibilities
+
+* **Leave Decorative Icons Unnamed:** If the title below the chip names the outcome, leave the icon unnamed.
+* **Name Icons That Stand Alone (aria-label):** If the icon carries meaning alone, label it, such as "Wallet connected".
+* **State the Outcome in Text (intent):** The tint has no text alternative, so the modal title states the outcome.
+
+## Related
+
+[Avatar](/docs/components/avatar)
+
+Use for people, contacts, and wallets in list rows.
+
+[Button](/docs/components/button)
+
+Use for icon actions.
+
+[Visual](/docs/components/visual)
+
+Use for illustrated onboarding and feature modals.
+
+[Iconography](/docs/foundations/iconography)
+
+Covers choosing icons.

package/dist/docs/components/identicon.md

@@ -0,0 +1,371 @@
+# Identicon
+
+Shows a unique gradient avatar derived from an address.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Identicon.tsx)
+
+## Overview
+
+An identicon is a round gradient avatar derived from an address. The same address always renders the same colors.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Identicon } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <Identicon address="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Identicon/Basic.tsx)
+
+### Size
+
+Set `size` to `16`, `24`, `32`, `40` (default), `48`, or `64` pixels.
+
+```tsx
+import { Identicon, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['16', '24', '32', '40', '48', '64'] as const).map((size) => (
+        <Identicon address="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" key={size} size={size} />
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Identicon/Size.tsx)
+
+### Address
+
+Each `address` derives its own colors.
+
+```tsx
+import { Identicon, style } from '@tempoxyz/ds'
+
+const addresses = [
+  '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
+  '0x71C7656EC7ab88b098defB751B7401B5f6d8976F',
+  '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe',
+  '0x0000000000000000000000000000000000000000',
+  '0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984',
+  '0x6B175474E89094C44Da98b954EedeAC495271d0F',
+  '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+  '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
+]
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {addresses.map((address) => (
+        <Identicon address={address} key={address} size="64" />
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Identicon/Address.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Identicon } from '@tempoxyz/ds'
+
+<Identicon />
+```
+
+## Guidelines
+
+### When to Use
+
+* Give an address an image beside its text, in recipient lists, activity rows, and account switchers.
+* Fill an `Avatar.Fallback` for an account known only by its address.
+
+### When Not to Use
+
+* Use [Avatar](/docs/components/avatar) for people and organizations with a name.
+* Use [TokenLogo](/docs/components/token-logo) for a token contract, which has its own icon.
+* Use [Hex](/docs/components/hex) to read, compare, or copy the address.
+
+### Always Show the Address Beside It
+
+Colors come from seven hue palettes, so addresses often look alike. Color alone doesn't identify an account ([SC 1.4.1](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html)).
+
+**Do:** Place the address, with `copy`, or the account name beside each identicon.
+
+```tsx
+/**
+ * Do example for "Always Show the Address Beside It" on the Identicon page.
+ * Place the address, with `copy`, or the account name beside each identicon.
+ * @module
+ */
+import { Hex, Identicon, style } from '@tempoxyz/ds'
+
+const addresses = [
+  '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
+  '0x71C7656EC7ab88b098defB751B7401B5f6d8976F',
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      {addresses.map((address) => (
+        <div key={address} {...styles.row()}>
+          <Identicon address={address} aria-hidden size="32" />
+          <Hex copy value={address} />
+        </div>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const list = style({ display: 'grid', gap: '12', minWidth: '0' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12', minWidth: '0' })
+}
+```
+
+**Don't:** Show identicons without the address or name they stand for.
+
+```tsx
+/**
+ * Don't example for "Always Show the Address Beside It" on the Identicon page.
+ * Don't show identicons without the address or name they stand for.
+ * @module
+ */
+import { Identicon, style } from '@tempoxyz/ds'
+
+const addresses = [
+  '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
+  '0x71C7656EC7ab88b098defB751B7401B5f6d8976F',
+  '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe',
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {addresses.map((address) => (
+        <Identicon address={address} key={address} size="32" />
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+### Don't Treat It as Verification
+
+An identicon doesn't prove an address is correct. Before a send, show the full address on the review step.
+
+**Do:** Ask people to compare characters.
+
+```tsx
+/**
+ * Do example for "Don't Treat It as Verification" on the Identicon page.
+ * Ask people to compare characters.
+ * @module
+ */
+import { Hex, Identicon, style } from '@tempoxyz/ds'
+
+const address = '0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.field()}>
+      <span {...styles.label()}>Recipient</span>
+      <div {...styles.row()}>
+        <Identicon address={address} aria-hidden size="24" />
+        <Hex size="small" value={address} />
+      </div>
+      <span {...styles.hint()}>Compare every character with the address you copied.</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const field = style({ display: 'grid', gap: '8', width: '100% !custom' })
+
+  export const hint = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '8', minWidth: '0' })
+}
+```
+
+**Don't:** Ask people to compare colors.
+
+```tsx
+/**
+ * Don't example for "Don't Treat It as Verification" on the Identicon page.
+ * Don't ask people to compare colors.
+ * @module
+ */
+import { Hex, Identicon, style } from '@tempoxyz/ds'
+
+const address = '0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.field()}>
+      <span {...styles.label()}>Recipient</span>
+      <div {...styles.row()}>
+        <Identicon address={address} aria-hidden size="24" />
+        <Hex size="small" value={address} />
+      </div>
+      <span {...styles.hint()}>Make sure the colors match your contact.</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const field = style({ display: 'grid', gap: '8', width: '100% !custom' })
+
+  export const hint = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const label = style({ color: 'content.secondary', typography: 'body.b2' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '8', minWidth: '0' })
+}
+```
+
+### Derive It From the Address
+
+Letter case doesn't change the colors, so checksummed and lowercase forms match.
+
+**Do:** Pass the address, so a rename keeps the same image.
+
+```tsx
+/**
+ * Do example for "Derive It From the Address" on the Identicon page.
+ * Pass the address, so a rename keeps the same image.
+ * @module
+ */
+import { Identicon, style } from '@tempoxyz/ds'
+
+const address = '0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <div {...styles.row()}>
+        <Identicon address={address} aria-hidden size="32" />
+        <span {...styles.name()}>Alice</span>
+      </div>
+      <div {...styles.row()}>
+        <Identicon address={address} aria-hidden size="32" />
+        <span {...styles.name()}>Alice Chen</span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const list = style({ display: 'grid', gap: '12' })
+
+  export const name = style({ color: 'content.primary', typography: 'body.b2' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+**Don't:** Pass a display name. The image changes when the name does.
+
+```tsx
+/**
+ * Don't example for "Derive It From the Address" on the Identicon page.
+ * Don't pass a display name. The image changes when the name does.
+ * @module
+ */
+import { Identicon, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <div {...styles.row()}>
+        <Identicon address="Alice" aria-hidden size="32" />
+        <span {...styles.name()}>Alice</span>
+      </div>
+      <div {...styles.row()}>
+        <Identicon address="Alice Chen" aria-hidden size="32" />
+        <span {...styles.name()}>Alice Chen</span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const list = style({ display: 'grid', gap: '12' })
+
+  export const name = style({ color: 'content.primary', typography: 'body.b2' })
+
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+### Size It With the Text Beside It
+
+* **Inline (16):** Inline with body text.
+* **Dense Rows (24 or 32):** In dense rows and tables.
+* **List Rows (40):** The default, in list rows.
+* **Account Headers (48 or 64):** In account headers.
+* **Fill a Frame (fill):** Inside an avatar fallback or other sized frame.
+
+## Accessibility
+
+An identicon renders an `<svg>` with the `img` role. It takes no focus.
+
+### Semantics
+
+* **Root (img):** Announced as an image by name.
+* **Name (aria-label):** Defaults to the full address, all 42 characters.
+
+### Your Responsibilities
+
+* **Hide a Duplicate (aria-hidden):** If the address is in nearby text, hide the identicon so it isn't announced twice.
+* **Name a Standalone Identicon (aria-label):** If it stands alone, name the account, such as "Savings account".
+
+## Related
+
+[Avatar](/docs/components/avatar)
+
+Use for people and organizations.
+
+[Hex](/docs/components/hex)
+
+Use for showing and copying addresses.
+
+[TokenLogo](/docs/components/token-logo)
+
+Use for token icons.
+
+[Blockchain Values](/docs/patterns/blockchain-values)
+
+Covers displaying addresses.