@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/foundations/intent.md

@@ -0,0 +1,360 @@
+# Building From Intent
+
+Choose each component by the job of its content, not by the markup it replaces.
+
+## Overview
+
+Every part of a screen does a job, such as a list of records to compare, a status to read, or an identifier to check. Each component page documents one job, so the right component follows from the job and not from the look of the old markup.
+
+## The Method
+
+### Inventory the Screen by Job
+
+Name the job of each part before you open the catalog: records, details, status, identifier, amount, metric, message, action, choice, or navigation.
+
+### Choose by Documented Job
+
+Find the job in [Common Intents](#common-intents) or the comparisons on [Components](/docs/components#choosing-a-component). Then read the When to Use section of the component page.
+
+### Check When Not to Use
+
+Read the When Not to Use section of the same page. If it names your case, use the component that the section links instead.
+
+### Write the Labels
+
+Write every label from the [Writing Style](/docs/foundations/content/writing-style) rules. Map a raw API value, such as `payment_failed`, to a word, such as Failed.
+
+### Check the Fit
+
+Render the result at the narrowest width that its column or container reaches, and confirm that nothing overlaps or clips. In a table, follow [Keep Multi-Line Rows Readable](/docs/patterns/tables-and-lists#keep-multi-line-rows-readable).
+
+## Common Intents
+
+Each tile names a job, the component for it, and the question that tells it apart from similar components.
+
+### Data
+
+* **Records (Table):** Do people compare many records across the same fields? Use a [Table](/docs/components/table), one row per record.
+* **One Record (ListGroup):** Does the view show the fields of one record? Use [ListGroup](/docs/components/list-group) rows with `ListGroup.Label`.
+* **Identifier (Hex):** Is it an address or a hash outside a table? Use [Hex](/docs/components/hex) with `copy`. A table column uses a `mono` cell.
+* **Amount (Amount):** Is it money or a token balance? Use [Amount](/docs/components/amount) with a `currency` or a `symbol`.
+* **Metric (Surface):** Is it a headline number on a dashboard? Use a small [Surface](/docs/components/surface) tile, as [Dashboards](/docs/patterns/dashboards) shows.
+
+### Status
+
+* **Status in a Table (status):** Does the status sit in a table row? Set `status` on its [Table](/docs/components/table) cell, and keep the status word beside the color.
+* **Status of a Payment (StatusChip):** Does a payment, an authorization, or a network have a status outside a table? Use a [StatusChip](/docs/components/status-chip).
+* **Live System Status (StatusIndicator):** Does a service or a connection report its live state? Use a [StatusIndicator](/docs/components/status-indicator).
+* **Running Task (StatusRow):** Does a person wait on one task that finishes within minutes? Follow it with a [StatusRow](/docs/components/status-row).
+* **Attribute (Badge):** Does a word name a category or an attribute, such as Testnet? Use a [Badge](/docs/components/badge) beside the title.
+
+### Interaction
+
+* **Message (Alert):** Does a sentence explain a condition? Use an [Alert](/docs/components/alert) for a section and a [Banner](/docs/components/banner) for the page.
+* **Action (Button):** Does it start something in the current view? Use a [Button](/docs/components/button) with a verb label, such as Send payment.
+* **Choice (RadioGroup):** Does a person pick one option? Compare [RadioGroup](/docs/components/radio-group) and the others on [Components](/docs/components#choosing-one-option).
+* **Navigation (SidebarMenu):** Does it open another page? Use a link, or a [SidebarMenu](/docs/components/sidebar-menu) for the main destinations of an app.
+
+## Porting an Existing Interface
+
+A port replaces old markup with library components. Map the job of each part instead, since the old screen can already use the wrong element for it.
+
+### Show Records as Rows
+
+**Do:** Show records that share fields as the rows of a [Table](/docs/components/table).
+
+```tsx
+/**
+ * Do example for "Show Records as Rows" on the Building From Intent page.
+ * Show records that share fields as the rows of a Table.
+ * @module
+ */
+import { Table } from '@tempoxyz/ds'
+
+const payouts = [
+  ['Ada Lovelace', 'Oct 19', '120.00'],
+  ['Alan Turing', 'Oct 19', '80.00'],
+  ['Grace Hopper', 'Oct 18', '45.50'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Table size="small">
+      <Table.Head>
+        <Table.Row>
+          <Table.HeaderCell>Recipient</Table.HeaderCell>
+          <Table.HeaderCell>Date</Table.HeaderCell>
+          <Table.HeaderCell>Amount (USDC)</Table.HeaderCell>
+        </Table.Row>
+      </Table.Head>
+      <Table.Body>
+        {payouts.map(([recipient, date, amount]) => (
+          <Table.Row key={recipient}>
+            <Table.Cell>{recipient}</Table.Cell>
+            <Table.Cell>{date}</Table.Cell>
+            <Table.Cell numeric>{amount}</Table.Cell>
+          </Table.Row>
+        ))}
+      </Table.Body>
+    </Table>
+  )
+}
+```
+
+**Don't:** Wrap each record in a [Surface](/docs/components/surface) card because the old screen drew
+cards.
+
+```tsx
+/**
+ * Don't example for "Show Records as Rows" on the Building From Intent page.
+ * A card per record repeats each label and breaks the columns that people compare.
+ * @module
+ */
+import { Grid, style, Surface } from '@tempoxyz/ds'
+
+const payouts = [
+  ['Ada Lovelace', 'Oct 19', '120.00 USDC'],
+  ['Alan Turing', 'Oct 19', '80.00 USDC'],
+  ['Grace Hopper', 'Oct 18', '45.50 USDC'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Grid fit="small" gap="8" {...styles.grid()}>
+      {payouts.map(([recipient, date, amount]) => (
+        <Surface key={recipient} size="small" {...styles.card()}>
+          <p {...styles.title()}>{recipient}</p>
+          <p {...styles.meta()}>Date: {date}</p>
+          <p {...styles.meta()}>Amount: {amount}</p>
+        </Surface>
+      ))}
+    </Grid>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxShadow: '0 0 0 1px light-dark(#0000001a, #ffffff1f) !custom',
+  })
+
+  export const grid = style({ width: '100% !custom' })
+
+  export const meta = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })
+
+  export const title = style({ margin: '0', typography: 'body.b2' })
+}
+```
+
+### Write Status Words, Not API Values
+
+**Do:** Color a status word in sentence case with the `status` of its [Table](/docs/components/table)
+cell.
+
+```tsx
+/**
+ * Do example for "Write Status Words, Not API Values" on the Building From Intent page.
+ * Color a status word in sentence case with the `status` of its Table cell.
+ * @module
+ */
+import { Table } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Table size="small">
+      <Table.Head>
+        <Table.Row>
+          <Table.HeaderCell>Recipient</Table.HeaderCell>
+          <Table.HeaderCell>Status</Table.HeaderCell>
+        </Table.Row>
+      </Table.Head>
+      <Table.Body>
+        <Table.Row>
+          <Table.Cell>Ada Lovelace</Table.Cell>
+          <Table.Cell status="positive">Confirmed</Table.Cell>
+        </Table.Row>
+        <Table.Row>
+          <Table.Cell>Alan Turing</Table.Cell>
+          <Table.Cell status="warning">Pending</Table.Cell>
+        </Table.Row>
+        <Table.Row>
+          <Table.Cell>Grace Hopper</Table.Cell>
+          <Table.Cell status="negative">Failed</Table.Cell>
+        </Table.Row>
+      </Table.Body>
+    </Table>
+  )
+}
+```
+
+**Don't:** Copy a grey pill into a [Badge](/docs/components/badge) with the raw value from the API.
+
+```tsx
+/**
+ * Don't example for "Write Status Words, Not API Values" on the Building From Intent page.
+ * A grey pill copied from the old screen shows raw API values and no status color.
+ * @module
+ */
+import { Badge, Table } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Table size="small">
+      <Table.Head>
+        <Table.Row>
+          <Table.HeaderCell>Recipient</Table.HeaderCell>
+          <Table.HeaderCell>Status</Table.HeaderCell>
+        </Table.Row>
+      </Table.Head>
+      <Table.Body>
+        <Table.Row>
+          <Table.Cell>Ada Lovelace</Table.Cell>
+          <Table.Cell>
+            <Badge size="small">confirmed</Badge>
+          </Table.Cell>
+        </Table.Row>
+        <Table.Row>
+          <Table.Cell>Alan Turing</Table.Cell>
+          <Table.Cell>
+            <Badge size="small">PENDING</Badge>
+          </Table.Cell>
+        </Table.Row>
+        <Table.Row>
+          <Table.Cell>Grace Hopper</Table.Cell>
+          <Table.Cell>
+            <Badge size="small">payment_failed</Badge>
+          </Table.Cell>
+        </Table.Row>
+      </Table.Body>
+    </Table>
+  )
+}
+```
+
+### Fit Identifiers to Their Column
+
+[Hex](/docs/components/hex) truncates to its container, down to the prefix, one character on each side, and its copy button. A narrower column lets it overflow into the next cell.
+
+**Do:** Set `mono` on the cell and shorten the value with `formatHex` from `@tempoxyz/ds`, which keeps
+four characters on each side. Show the full value with `copy` on the details view.
+
+```tsx
+/**
+ * Do example for "Fit Identifiers to Their Column" on the Building From Intent page.
+ * Shorten an address in a table column with a `mono` cell and `formatHex`.
+ * @module
+ */
+import { formatHex, Table } from '@tempoxyz/ds'
+
+const accounts = [
+  ['Ada Lovelace', '0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc', '120.00'],
+  ['Alan Turing', '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', '80.00'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Table size="small">
+      <Table.Head>
+        <Table.Row>
+          <Table.HeaderCell>Recipient</Table.HeaderCell>
+          <Table.HeaderCell>Address</Table.HeaderCell>
+          <Table.HeaderCell>Amount</Table.HeaderCell>
+        </Table.Row>
+      </Table.Head>
+      <Table.Body>
+        {accounts.map(([recipient, address, amount]) => (
+          <Table.Row key={address}>
+            <Table.Cell>{recipient}</Table.Cell>
+            <Table.Cell mono>{formatHex(address)}</Table.Cell>
+            <Table.Cell numeric>{amount}</Table.Cell>
+          </Table.Row>
+        ))}
+      </Table.Body>
+    </Table>
+  )
+}
+```
+
+**Don't:** Place a [Hex](/docs/components/hex) with `copy` in a column narrower than its minimum
+width.
+
+```tsx
+/**
+ * Don't example for "Fit Identifiers to Their Column" on the Building From Intent page.
+ * A Hex with `copy` in a narrow column stops at its minimum width and overlaps the next cell.
+ * @module
+ */
+import { Hex, style, Table } from '@tempoxyz/ds'
+
+const accounts = [
+  ['Ada Lovelace', '0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc', '120.00'],
+  ['Alan Turing', '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', '80.00'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Table size="small" {...styles.table()}>
+      <Table.Head>
+        <Table.Row>
+          <Table.HeaderCell>Recipient</Table.HeaderCell>
+          <Table.HeaderCell {...styles.narrow()}>Address</Table.HeaderCell>
+          <Table.HeaderCell>Amount</Table.HeaderCell>
+        </Table.Row>
+      </Table.Head>
+      <Table.Body>
+        {accounts.map(([recipient, address, amount]) => (
+          <Table.Row key={address}>
+            <Table.Cell>{recipient}</Table.Cell>
+            <Table.Cell>
+              <Hex copy size="small" value={address} />
+            </Table.Cell>
+            <Table.Cell numeric>{amount}</Table.Cell>
+          </Table.Row>
+        ))}
+      </Table.Body>
+    </Table>
+  )
+}
+
+namespace styles {
+  export const narrow = style({ width: '3rem !custom' })
+
+  export const table = style({ tableLayout: 'fixed !custom' })
+}
+```
+
+## Checklist
+
+Before you ship a screen, confirm each item.
+
+* **Jobs Named:** Each part of the screen has a named job, and each component matches that job.
+* **Exclusions Checked:** No component appears in a case that its When Not to Use section excludes.
+* **Labels Written:** Labels are words in sentence case, with one word per status and no raw API values.
+* **Fit Checked:** Every cell and tile fits at the narrowest width of its layout, without overlap or clipping.
+
+## Related
+
+[Components](/docs/components)
+
+Covers the catalog and the comparisons between similar components.
+
+[Agents](/docs/foundations/agents)
+
+Covers the rules that coding agents follow.
+
+[Tables and Lists](/docs/patterns/tables-and-lists)
+
+Covers tables, lists, and the details of one record.
+
+[Feedback and Status](/docs/patterns/feedback-and-status)
+
+Covers status words and the channel for each message.
+
+[Writing Style](/docs/foundations/content/writing-style)
+
+Covers labels, status words, and sentence case.