@tempoxyz/ds 0.3.10 → 0.3.11

package/dist/docs/components/button.md

@@ -0,0 +1,650 @@
+# Button
+
+Triggers an action, such as submitting a form or sending a payment.
+
+[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Button.tsx)
+
+Figma: [Button](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1186-3148), [Icon Button](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1186-3395), [Text Button](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5601-90)
+
+## Overview
+
+A native `<button>` for actions. `Button.Link` renders the same styles for navigation.
+
+## Examples
+
+### Basic
+
+```tsx
+import { Button } from '@tempoxyz/ds'
+
+export function Demo() {
+  return <Button>Continue</Button>
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Button/Basic.tsx)
+
+### Variant
+
+Set `variant` to `primary` (default), `secondary`, `tertiary`, `danger`, or `text`. A `tertiary` button has no fill until hover.
+
+```tsx
+import { Button, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['primary', 'secondary', 'tertiary', 'danger'] as const).map((variant) => (
+        <Button key={variant} variant={variant}>
+          Continue
+        </Button>
+      ))}
+    </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/Button/Variant.tsx)
+
+### Text
+
+Set `variant="text"` for a low-emphasis action in running content, such as See more. It renders the secondary label and a trailing 12px icon without a fill or padding, and ignores `size`.
+
+```tsx
+import { Button } from '@tempoxyz/ds'
+import { ChevronRight } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <Button variant="text">
+      See more
+      <ChevronRight />
+    </Button>
+  )
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Button/Text.tsx)
+
+### Inverse
+
+Set `appearance="inverse"` on an inverse surface, such as a dark banner on a light page. The surface turns light in dark mode, and the button colors flip with it.
+
+```tsx
+/** Demonstrates the inverse appearance of each Button variant on an inverse surface. @module */
+import { Button, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.surface()}>
+      {(['primary', 'secondary', 'tertiary'] as const).map((variant) => (
+        <Button appearance="inverse" key={variant} variant={variant}>
+          Continue
+        </Button>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  export const surface = style({
+    alignItems: 'center',
+    backgroundColor: 'inverse.background.primary',
+    borderRadius: 'sm',
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: '12',
+    padding: '16',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Button/Inverse.tsx)
+
+### Overlay
+
+Set `appearance="overlay"` over an image or video. The `secondary` fill is a translucent gray, and the `secondary` and `tertiary` labels stay white in both color schemes.
+
+```tsx
+/** Demonstrates the overlay appearance of each Button variant over an image. @module */
+import { Button, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.image()}>
+      {(['primary', 'secondary', 'tertiary'] as const).map((variant) => (
+        <Button appearance="overlay" key={variant} variant={variant}>
+          Continue
+        </Button>
+      ))}
+    </div>
+  )
+}
+
+namespace styles {
+  // A mid-tone gradient stands in for a photo, so the labels stay legible in both color schemes.
+  export const image = style({
+    alignItems: 'center',
+    backgroundImage: 'linear-gradient(135deg, #6b7f99, #a3866a) !custom',
+    borderRadius: 'sm',
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: '12',
+    padding: '16',
+  })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Button/Overlay.tsx)
+
+### Size
+
+Set `size` to `xsmall`, `small`, `medium` (default), or `large`. Heights step from 24px to 48px. `large` and `medium` take the `sm` corner radius, `small` takes `xs`, and `xsmall` renders a pill.
+
+```tsx
+import { Button, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['xsmall', 'small', 'medium', 'large'] as const).map((size) => (
+        <Button key={size} size={size}>
+          Continue
+        </Button>
+      ))}
+    </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/Button/Size.tsx)
+
+### Shape
+
+Set `shape="icon"` for a round button that holds only an icon. The icon renders at 16px, and at 20px on a large button. Give the button an `aria-label`.
+
+```tsx
+import { Button, style } from '@tempoxyz/ds'
+import { Plus as Add } from '@tempoxyz/ds/icons'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Button>
+        <Add />
+        Add funds
+      </Button>
+      {(['primary', 'secondary', 'tertiary'] as const).map((variant) => (
+        <Button aria-label="Add" key={variant} shape="icon" variant={variant}>
+          <Add />
+        </Button>
+      ))}
+    </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/Button/Shape.tsx)
+
+### Loading
+
+Set `loading` to disable the button and show a spinner before its label.
+
+```tsx
+import { Button, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['primary', 'secondary', 'tertiary'] as const).map((variant) => (
+        <Button key={variant} loading variant={variant}>
+          Loading
+        </Button>
+      ))}
+    </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/Button/Loading.tsx)
+
+### Disabled
+
+```tsx
+import { Button, style } from '@tempoxyz/ds'
+
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      {(['primary', 'secondary', 'tertiary'] as const).map((variant) => (
+        <Button disabled key={variant} variant={variant}>
+          Disabled
+        </Button>
+      ))}
+    </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/Button/Disabled.tsx)
+
+## Anatomy
+
+Import the component and assemble its parts.
+
+```tsx
+import { Button } from '@tempoxyz/ds'
+
+<Button />
+<Button.Link />
+```
+
+## Guidelines
+
+### When to Use
+
+* Start an action in the current view, such as Send payment, Save changes, or Open settings.
+* Submit a form. Set `type="submit"` on the form's main button.
+* Use `Button.Link` when navigation needs a button's weight, such as Create account in an empty state.
+
+### When Not to Use
+
+* Use a text link for navigation inside sentences, lists, and tables.
+* Use [CopyButton](/docs/components/copy-button) to copy a value, and [SplitButton](/docs/components/split-button) for a main action with related alternatives.
+* Use [Tabs](/docs/components/tabs) or [ChoiceGroup](/docs/components/choice-group) to switch views, and [Switch](/docs/components/switch) to turn a setting on or off.
+* If a section has more than three secondary actions, put them in a [Menu](/docs/components/menu) behind an icon button.
+
+### Choose a Variant by Emphasis
+
+* **Main Action (primary):** The main action of a view, dialog, or section, such as Send payment. Use one per section.
+* **Supporting Actions (secondary):** Supporting actions beside a primary action, or actions of equal weight.
+* **Low-Emphasis Actions (tertiary):** Dense areas, such as toolbars, table rows, and inline Cancel actions.
+
+A destructive action takes the variant of its place in the flow, and its label names the outcome, such as Revoke key. Confirm it with an [AlertDialog](/docs/components/alert-dialog), whose confirming button takes `danger`. See [Destructive Actions](/docs/patterns/destructive-actions) and [Payments](/docs/patterns/payments).
+
+### Use One Primary Action
+
+Give other actions `secondary` or `tertiary`, even if they matter. [Forms](/docs/patterns/forms#submitting) sets the order of the actions.
+
+**Do:** Pair one `primary` action with `secondary` alternatives.
+
+```tsx
+/**
+ * Do example for "Use One Primary Action" on the Button page.
+ * Pair one `primary` action with `secondary` alternatives.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Button variant="secondary">Cancel</Button>
+      <Button>Send payment</Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
+}
+```
+
+**Don't:** Give several actions in one section the `primary` variant.
+
+```tsx
+/**
+ * Don't example for "Use One Primary Action" on the Button page.
+ * Don't give several actions in one section the `primary` variant.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Button>Send</Button>
+      <Button>Deposit</Button>
+      <Button>Swap</Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
+}
+```
+
+### Match Size to Context
+
+* **Row Actions (xsmall):** A pill for an action inside a row or field, such as Copy or Edit. Never the main action.
+* **Dense Layouts (small):** Tables, toolbars, cards, and icon buttons inside fields and rows, such as Export in a toolbar.
+* **Default (medium):** Forms, page actions, and actions inside a dialog body, such as Copy address.
+* **Dialog Footers (large):** Every action in a dialog footer, and the final step of a focused flow, such as Confirm send.
+
+Lay out the actions in a dialog footer with a [ButtonGroup](/docs/components/button-group).
+
+### Show Progress With Loading
+
+**Do:** Set `loading` on the button that started the action.
+
+```tsx
+/**
+ * Do example for "Show Progress With Loading" on the Button page.
+ * Set `loading` on the button that started the action.
+ * @module
+ */
+import { Button } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return <Button loading>Send payment</Button>
+}
+```
+
+**Don't:** Disable the button and place a separate [Spinner](/docs/components/spinner) beside it.
+
+```tsx
+/**
+ * Don't example for "Show Progress With Loading" on the Button page.
+ * Don't disable the button and place a separate Spinner beside it.
+ * @module
+ */
+import { Button, Spinner, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Button disabled>Send payment</Button>
+      <Spinner aria-label="Loading" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
+}
+```
+
+### Avoid Disabled Buttons
+
+Keep a button enabled when you can, and show validation errors after a press. If a button must stay disabled:
+
+* Explain why in nearby text.
+* Set `focusableWhenDisabled` so keyboard users can reach it.
+* Don't rely on a [Tooltip](/docs/components/tooltip). Many readers can't open it on a disabled button.
+
+**Do:** Explain in nearby text why the button is unavailable.
+
+```tsx
+/**
+ * Do example for "Avoid Disabled Buttons" on the Button page.
+ * Explain in nearby text why the button is unavailable.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Button disabled focusableWhenDisabled>
+        Send payment
+      </Button>
+      <p {...styles.hint()}>Add a recipient address to send.</p>
+    </div>
+  )
+}
+
+namespace styles {
+  export const hint = style({
+    color: 'content.secondary',
+    margin: '0 !custom',
+    typography: 'body.b3',
+  })
+
+  export const stack = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+  })
+}
+```
+
+**Don't:** Disable a button without saying what is missing.
+
+```tsx
+/**
+ * Don't example for "Avoid Disabled Buttons" on the Button page.
+ * Don't disable a button without saying what is missing.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.stack()}>
+      <Button disabled>Send payment</Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const stack = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: '8',
+  })
+}
+```
+
+### Use Icons to Reinforce the Label
+
+Place an icon before the label if it aids recognition, such as a plus for Add. An icon-only button (`shape="icon"`) needs a [Tooltip](/docs/components/tooltip) with its `aria-label` text. Use it only for familiar actions, such as Close or Copy.
+
+**Do:** Add an icon only where it aids recognition.
+
+```tsx
+/**
+ * Do example for "Use Icons to Reinforce the Label" on the Button page.
+ * Add an icon only where it aids recognition.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+import { Plus } 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">
+        Export
+      </Button>
+      <Button size="small" variant="secondary">
+        Rotate key
+      </Button>
+      <Button size="small">
+        <Plus />
+        Add key
+      </Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
+}
+```
+
+**Don't:** Add icons to every button in a group.
+
+```tsx
+/**
+ * Don't example for "Use Icons to Reinforce the Label" on the Button page.
+ * Don't add icons to every button in a group.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+import { Export, Plus, Refresh } 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">
+        <Export />
+        Export
+      </Button>
+      <Button size="small" variant="secondary">
+        <Refresh />
+        Rotate key
+      </Button>
+      <Button size="small">
+        <Plus />
+        Add key
+      </Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '8' })
+}
+```
+
+## Content
+
+### Start With a Verb
+
+Name the action and its object, such as Send payment or Create key.
+
+**Do:** Repeat the action on each button, such as Revoke key and Keep key.
+
+```tsx
+/**
+ * Do example for "Start With a Verb" on the Button page.
+ * Repeat the action on each button, such as Revoke key and Keep key.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Button variant="secondary">Keep key</Button>
+      <Button>Revoke key</Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
+}
+```
+
+**Don't:** Use generic labels such as Yes, No, OK, or Submit.
+
+```tsx
+/**
+ * Don't example for "Start With a Verb" on the Button page.
+ * Don't use generic labels such as Yes, No, OK, or Submit.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <Button variant="secondary">No</Button>
+      <Button>Yes</Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const row = style({ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '12' })
+}
+```
+
+### Describe the Outcome, Not the Control
+
+Write Continue to review, not Click here. Screen readers list buttons out of context, so each label must make sense alone.
+
+## Accessibility
+
+`Button` renders a native `<button type="button">`, and `Button.Link` a native `<a>`. Both follow the [WAI-ARIA button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/). See [Accessibility](/docs/foundations/accessibility) for the baseline.
+
+### Semantics
+
+* **Button (button):** Enter and Space activate it. Name an icon-only button with `aria-label`.
+* **Button.Link (link):** Announced as a link and listed among the page's links. A modifier click opens a new tab.
+* **Disabled:** Removes the button from the tab order, so keyboards skip it. Explain the reason in nearby text.
+* **Focusable When Disabled (aria-disabled):** Keeps a disabled button in the tab order. It ignores every key except Tab.
+* **Loading (aria-busy):** Disables the button and labels its spinner "Loading" for screen readers.
+* **Icons (aria-hidden):** Hidden from assistive technology, so the button's text or label names it.
+
+### Keyboard
+
+* **Move to the Button (Tab):** Focuses the button, skipping disabled ones.
+* **Activate the Button (Enter or Space):** Activates the button.
+* **Follow a Link (Enter):** Follows a `Button.Link`.
+
+### Your Responsibilities
+
+* **Name Icon-Only Buttons (aria-label):** An icon-only button has no visible text. Name the action, such as "Copy address", not "Copy icon".
+* **Announce Loading Results:** Loading announces only the busy state. Announce the outcome with a [Toast](/docs/components/toast) or an [Alert](/docs/components/alert).
+* **Use Links for Navigation (Button.Link):** Use it for navigation, not a button with a click handler that changes the page.
+
+## Related
+
+[ButtonGroup](/docs/components/button-group)
+
+Use for the actions at the foot of a dialog.
+
+[SplitButton](/docs/components/split-button)
+
+Use for a main action with alternatives.
+
+[CopyButton](/docs/components/copy-button)
+
+Use for copying a value.
+
+[AlertDialog](/docs/components/alert-dialog)
+
+Use for confirming an action.
+
+[Forms](/docs/patterns/forms)
+
+Covers placing submit and cancel actions.
+
+[Destructive Actions](/docs/patterns/destructive-actions)
+
+Covers deleting and revoking.