@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/patterns/responsive-layout.md

@@ -0,0 +1,997 @@
+# Responsive Layout
+
+Adapt layouts from a 320px phone to a wide desktop with shared breakpoints.
+
+## Overview
+
+Components change at fixed widths. For example, [AppShell](/docs/components/app-shell) moves its sidebar into a drawer below 1024px. Change page layouts at the same widths, so the page and its components switch together.
+
+[Container](/docs/components/container) sets the content width, [AppShell](/docs/components/app-shell) holds the sidebar and content column, and [Grid](/docs/components/grid), [Stack](/docs/components/stack), and [Inline](/docs/components/inline) arrange the content inside.
+
+> [!NOTE]
+> The live layouts on this page are reference layouts built from library components and `style`. They are not shipped components. Copy and adapt them in your app.
+
+## Breakpoints
+
+Use these five breakpoints for every layout change.
+
+* **Small (640 (40rem)):** Dialogs stop rendering as bottom sheets, toasts move to the end corner, and the app shell widens its padding.
+* **Medium (768 (48rem)):** Containers widen their side gutters at this breakpoint and above.
+* **Large (1024 (64rem)):** The app shell sidebar becomes sticky, and its menu button hides.
+* **Extra Large (1280 (80rem)):** A wide container reaches its maximum width and stops growing past it.
+* **Wide Displays (1536 (96rem)):** No component changes here. Reserve it for layouts that add a column on very wide displays.
+
+Components write these widths as pixel literals, because media queries cannot read CSS variables. At the default 16px font size, the rem and pixel values match.
+
+### Write Breakpoints With Aliases
+
+A breakpoint name in a `style` key expands to a width query, so the numbers never repeat.
+
+* **From a Width ('@media 768'):** Applies from the breakpoint up.
+* **Below a Width ('@media <1024'):** Applies below the breakpoint.
+* **Between Widths ('@media 640..1024'):** Applies from the first breakpoint to the second.
+
+Write the narrow layout as the base style. Add wider layouts with minimum-width keys.
+
+```tsx
+namespace styles {
+  export const layout = style({
+    display: 'grid',
+    gap: '24',
+    gridTemplateColumns: 'minmax(0, 1fr) !custom',
+    '@media 1024': { gridTemplateColumns: '20rem minmax(0, 1fr) !custom' },
+  })
+}
+```
+
+## Content Widths
+
+[Container](/docs/components/container) centers content at a maximum width and adds side gutters of 24px, or 32px from 768px. Use the narrowest size that fits the content.
+
+* **Narrow (48rem (768px)):** Settings, forms, focused flows, and long text.
+* **Medium (64rem (1024px)):** List and detail pages, and tables with a few columns.
+* **Wide (80rem (1280px)):** The default, for dashboards and wide tables.
+* **Full (None):** Viewport-wide content, such as a block explorer feed.
+
+Inside [AppShell](/docs/components/app-shell), `AppShell.Main` limits the column to 1024px and adds its own padding. Set `gutter={false}` on a nested [Container](/docs/components/container), or the padding doubles. Outside [AppShell](/docs/components/app-shell), render the page landmark through [Container](/docs/components/container) with `render={<main />}`.
+
+## Page Structures
+
+Most Tempo pages use one of four structures. Each changes only at the shared breakpoints.
+
+### App Shell With Content
+
+Use [AppShell](/docs/components/app-shell) for products with persistent navigation, such as [Tempo Console](/docs/products/tempo-console). [Navigation](/docs/patterns/navigation#move-the-sidebar-into-a-drawer-below-1024px) covers its drawer below 1024px. From 1024px, the sidebar is sticky and 16.25rem wide, which `--sidebar-width` overrides. Set `align="start"` on `AppShell.Root` so a dashboard fills the width beside the sidebar.
+
+### List and Detail
+
+Use list and detail for records that people scan and then inspect, such as payments, API keys, or webhooks.
+
+```tsx
+import { Amount, Badge, Button, Grid, Hex, ListGroup, style, Surface } from '@tempoxyz/ds'
+import { ArrowLeft } from '@tempoxyz/ds/icons'
+import { useRef, useState } from 'react'
+import { flushSync } from 'react-dom'
+
+export const fill = true
+const payments = [
+  {
+    amount: '1200.00',
+    hash: '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060',
+    id: 'payroll',
+    status: 'Confirmed',
+    time: 'Today, 09:41',
+    title: 'Payroll',
+    to: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F',
+  },
+  {
+    amount: '48.50',
+    hash: '0x91bd07e1c3e05a2277a1c0d94f2a91c3b6a900fa2b585dd299e03d12fa4293bc',
+    id: 'hosting',
+    status: 'Confirmed',
+    time: 'Yesterday, 18:02',
+    title: 'Hosting',
+    to: '0x3c44cdddb6a900fa2b585dd299e03d12fa4293bc',
+  },
+  {
+    amount: '310.00',
+    hash: '0xc3e05a2291bd07e14f2a91c3b6a900fa2b585dd299e03d12fa4293bc77a1c0d9',
+    id: 'refund',
+    status: 'Pending',
+    time: 'Oct 18, 14:30',
+    title: 'Refund to Ada',
+    to: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
+  },
+]
+
+export function Demo() {
+  const [selected, setSelected] = useState('payroll')
+  // Narrow layouts show one pane at a time. From 1024px both panes show and `view` has no effect.
+  const [view, setView] = useState<'detail' | 'list'>('list')
+  const payment = payments.find((entry) => entry.id === selected) ?? payments[0]!
+  const heading = useRef<HTMLHeadingElement>(null)
+  const list = useRef<HTMLElement>(null)
+
+  return (
+    <Grid data-view={view} gap="24" {...styles.layout()}>
+      <section aria-labelledby="payments-heading" data-pane="list" ref={list} {...styles.pane()}>
+        <h2 id="payments-heading" {...styles.heading()}>
+          Payments
+        </h2>
+        <Surface size="small" {...styles.list()}>
+          <ListGroup.Root>
+            {payments.map((entry) => (
+              <ListGroup.Row
+                action="navigation"
+                aria-current={entry.id === selected || undefined}
+                key={entry.id}
+                onClick={() => {
+                  flushSync(() => {
+                    setSelected(entry.id)
+                    setView('detail')
+                  })
+                  // When the list hides, focus moves to the detail so it isn't lost.
+                  if (list.current?.offsetParent === null) heading.current?.focus()
+                }}
+              >
+                <ListGroup.Info>
+                  <ListGroup.Title>{entry.title}</ListGroup.Title>
+                  <ListGroup.Description>{entry.time}</ListGroup.Description>
+                </ListGroup.Info>
+                <Amount currency="USD" value={entry.amount} />
+              </ListGroup.Row>
+            ))}
+          </ListGroup.Root>
+        </Surface>
+      </section>
+      <section aria-labelledby="payment-heading" data-pane="detail" {...styles.pane()}>
+        <div {...styles.back()}>
+          <Button
+            onClick={() => {
+              flushSync(() => setView('list'))
+              list.current?.querySelector<HTMLElement>('[aria-current="true"]')?.focus()
+            }}
+            size="small"
+            variant="tertiary"
+          >
+            <ArrowLeft />
+            Payments
+          </Button>
+        </div>
+        <Surface>
+          <Surface.Header>
+            <Surface.Title id="payment-heading" ref={heading} tabIndex={-1}>
+              {payment.title}
+            </Surface.Title>
+            <Badge>{payment.status}</Badge>
+          </Surface.Header>
+          <ListGroup.Root>
+            <ListGroup.Row>
+              <ListGroup.Label>Amount</ListGroup.Label>
+              <Amount currency="USD" value={payment.amount} />
+            </ListGroup.Row>
+            <ListGroup.Row>
+              <ListGroup.Label>To</ListGroup.Label>
+              <Hex copy value={payment.to} />
+            </ListGroup.Row>
+            <ListGroup.Row>
+              <ListGroup.Label>Date</ListGroup.Label>
+              {payment.time}
+            </ListGroup.Row>
+            <ListGroup.Row>
+              <ListGroup.Label>Transaction</ListGroup.Label>
+              <Hex copy value={payment.hash} />
+            </ListGroup.Row>
+          </ListGroup.Root>
+        </Surface>
+      </section>
+    </Grid>
+  )
+}
+
+namespace styles {
+  export const back = style({
+    marginBlockEnd: '8',
+    marginInlineStart: '-12px !custom',
+    '@media 1024': { display: 'none' },
+  })
+
+  export const heading = style({ margin: '0', marginBlockEnd: '12', typography: 'heading.h3' })
+
+  export const layout = style({
+    alignItems: 'start',
+    backgroundColor: 'background.primary',
+    gridTemplateColumns: 'minmax(0, 1fr) !custom',
+    padding: '16',
+    '@media <1024': {
+      selectors: {
+        '&[data-view="detail"] > [data-pane="list"]': { display: 'none' },
+        '&[data-view="list"] > [data-pane="detail"]': { display: 'none' },
+      },
+    },
+    '@media 1024': { gridTemplateColumns: '20rem minmax(0, 1fr) !custom' },
+  })
+
+  export const list = style({
+    selectors: { '& [aria-current="true"]': { backgroundColor: 'container.regular' } },
+  })
+
+  export const pane = style({ minWidth: '0' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/ResponsiveListDetail.tsx)
+
+* **From 1024px:** Show the list beside the detail, and mark the selected row with `aria-current`.
+* **Below 1024px:** Show the list first. A row replaces it with the detail and a Back action.
+* **URLs:** Give each detail its own URL, so browser Back and shared links work at every width.
+
+### Settings
+
+Settings stay in one `narrow` column at every width, never several columns. Put each section of related settings in a [Surface](/docs/components/surface), with a `Surface.Title` and [ListGroup](/docs/components/list-group) or [Field](/docs/components/field) inside.
+
+```tsx
+import { Container, Field, Inset, ListGroup, style, Surface, Switch } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Inset block="32" {...styles.page()}>
+      <Container size="narrow" {...styles.column()}>
+        <h1 {...styles.title()}>Settings</h1>
+        <Surface render={<section aria-labelledby="account-heading" />}>
+          <Surface.Header>
+            <Surface.Title id="account-heading">Account</Surface.Title>
+          </Surface.Header>
+          <ListGroup.Root>
+            <ListGroup.Row action="navigation" render={<a href="#name" />}>
+              <ListGroup.Label>Name</ListGroup.Label>
+              Tempo Labs
+            </ListGroup.Row>
+            <ListGroup.Row action="navigation" render={<a href="#email" />}>
+              <ListGroup.Label>Email</ListGroup.Label>
+              ops@tempo.xyz
+            </ListGroup.Row>
+          </ListGroup.Root>
+        </Surface>
+        <Surface render={<section aria-labelledby="notifications-heading" />}>
+          <Surface.Header>
+            <Surface.Title id="notifications-heading">Notifications</Surface.Title>
+          </Surface.Header>
+          <Field.Root>
+            <Field.Label>Payment received</Field.Label>
+            <Switch defaultChecked />
+            <Field.Description>Email you when funds arrive.</Field.Description>
+          </Field.Root>
+          <Field.Root>
+            <Field.Label>Failed webhooks</Field.Label>
+            <Switch />
+            <Field.Description>Email you after three failed deliveries.</Field.Description>
+          </Field.Root>
+        </Surface>
+      </Container>
+    </Inset>
+  )
+}
+
+namespace styles {
+  export const column = style({ display: 'flex', flexDirection: 'column', rowGap: '24' })
+
+  export const page = style({ backgroundColor: 'background.primary' })
+
+  export const title = style({ margin: '0', typography: 'heading.h2' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/ResponsiveSettings.tsx)
+
+### Focused Flow
+
+Send, deposit, and onboarding flows remove global navigation and center one task in a column of about 28rem (`maxWidth: '448'`). Show progress with [Stepper](/docs/components/stepper). Keep the actions at the end of the form.
+
+```tsx
+import { AmountInput, Button, Choicebox, Field, Inset, Stepper, style, Token } from '@tempoxyz/ds'
+
+export const fill = true
+export function Demo() {
+  return (
+    <Inset block="32" inline="16" {...styles.page()}>
+      <form onSubmit={(event) => event.preventDefault()} {...styles.column()}>
+        <div {...styles.header()}>
+          <Stepper.Root aria-label="Add funds" count={3} value={1} />
+          <p {...styles.step()}>Step 1 of 3</p>
+          <h1 {...styles.title()}>Add funds</h1>
+        </div>
+        <Field.Root>
+          <AmountInput.Root defaultValue="250">
+            <Field.Label>Amount</Field.Label>
+            <AmountInput.Control />
+            <Token readOnly symbol="USDC" />
+          </AmountInput.Root>
+        </Field.Root>
+        <Choicebox.RadioGroup aria-label="Funding method" defaultValue="bank">
+          <Choicebox.Radio value="bank">
+            <Choicebox.Title>Bank transfer</Choicebox.Title>
+            <Choicebox.Description>Arrives in one to two business days</Choicebox.Description>
+          </Choicebox.Radio>
+          <Choicebox.Radio value="card">
+            <Choicebox.Title>Debit card</Choicebox.Title>
+            <Choicebox.Description>Arrives in minutes</Choicebox.Description>
+          </Choicebox.Radio>
+        </Choicebox.RadioGroup>
+        <div {...styles.actions()}>
+          <Button type="button" variant="secondary">
+            Cancel
+          </Button>
+          <Button type="submit">Continue</Button>
+        </div>
+      </form>
+    </Inset>
+  )
+}
+
+namespace styles {
+  // Below 640px the actions stack at full width with the primary action on top. The DOM keeps
+  // Cancel first, so the inline layout's tab order matches its visual order.
+  export const actions = style({
+    display: 'flex',
+    flexDirection: 'column-reverse',
+    gap: '12',
+    '@media 640': { flexDirection: 'row', justifyContent: 'flex-end' },
+  })
+
+  export const column = style({
+    display: 'flex',
+    flexDirection: 'column',
+    marginInline: 'auto !custom',
+    maxWidth: '448',
+    rowGap: '24',
+  })
+
+  export const header = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
+
+  export const page = style({ backgroundColor: 'background.primary' })
+
+  export const step = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })
+
+  export const title = style({ margin: '0', typography: 'heading.h2' })
+}
+```
+
+[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/ResponsiveFocusedFlow.tsx)
+
+## Guidelines
+
+### Start From 320px
+
+Write the base styles for a 320px viewport. Add wider layouts with `'@media 640'` and larger keys. Check every page at 320px and at 200 percent zoom.
+
+**Do:** Let every row fit 320px, so long values wrap inside their card.
+
+```tsx
+/**
+ * Do example for "Start From 320px" on the Responsive Layout page.
+ * Let every row fit 320px, so long values wrap inside their card.
+ * @module
+ */
+import { Amount, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.phone()}>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Amount</span>
+        <Amount symbol="USDC" value="250.00" />
+      </div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>To</span>
+        <span {...styles.value()}>0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045</span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({
+    color: 'content.secondary',
+    flexShrink: '0 !custom',
+    typography: 'body.b3',
+  })
+
+  export const phone = style({
+    borderColor: 'line.secondary',
+    borderRadius: 'sm',
+    borderStyle: 'solid',
+    borderWidth: 'regular',
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+    overflow: 'hidden',
+    padding: '16',
+    width: '15rem !custom',
+  })
+
+  export const row = style({ display: 'flex', gap: '16', justifyContent: 'space-between' })
+
+  export const value = style({
+    minWidth: '0',
+    overflowWrap: 'anywhere !custom',
+    textAlign: 'end',
+    typography: 'body.b3',
+  })
+}
+```
+
+**Don't:** Size a row for desktop, so it runs past the edge of a phone.
+
+```tsx
+/**
+ * Don't example for "Start From 320px" on the Responsive Layout page.
+ * Don't size a row for desktop, so it runs past the edge of a phone.
+ * @module
+ */
+import { Amount, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.phone()}>
+      <div {...styles.row()}>
+        <span {...styles.label()}>Amount</span>
+        <Amount symbol="USDC" value="250.00" />
+      </div>
+      <div {...styles.row()}>
+        <span {...styles.label()}>To</span>
+        <span {...styles.value()}>0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045</span>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const label = style({
+    color: 'content.secondary',
+    flexShrink: '0 !custom',
+    typography: 'body.b3',
+  })
+
+  export const phone = style({
+    borderColor: 'line.secondary',
+    borderRadius: 'sm',
+    borderStyle: 'solid',
+    borderWidth: 'regular',
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+    overflow: 'hidden',
+    padding: '16',
+    width: '15rem !custom',
+  })
+
+  export const row = style({ display: 'flex', gap: '16', justifyContent: 'space-between' })
+
+  export const value = style({ typography: 'body.b3', whiteSpace: 'nowrap' })
+}
+```
+
+### Let Content Reflow Before Adding Breakpoints
+
+Many layouts adapt without a media query:
+
+* **[Grid](/docs/components/grid) with `fit`:** Fits as many columns as the width allows.
+* **[Inline](/docs/components/inline) with `wrap`:** Moves items to a new line.
+* **[Hex](/docs/components/hex):** Truncates to the available space.
+
+**Do:** Use [Grid](/docs/components/grid) with `fit`, so tiles drop to fewer columns as space runs out.
+
+```tsx
+/**
+ * Do example for "Let Content Reflow Before Adding Breakpoints" on the Responsive Layout page.
+ * Use Grid with `fit`, so tiles drop to fewer columns as space runs out.
+ * @module
+ */
+import { Grid, style } from '@tempoxyz/ds'
+
+const tiles = [
+  ['Balance', '$12,480.00'],
+  ['Sent', '$3,210.50'],
+  ['Received', '$4,005.00'],
+  ['Fees', '$0.04'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Grid fit="small" gap="12" {...styles.grid()}>
+      {tiles.map(([label, value]) => (
+        <div key={label} {...styles.tile()}>
+          <p {...styles.label()}>{label}</p>
+          <p {...styles.value()}>{value}</p>
+        </div>
+      ))}
+    </Grid>
+  )
+}
+
+namespace styles {
+  export const grid = style({ width: '17rem !custom' })
+
+  export const label = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })
+
+  export const tile = style({
+    backgroundColor: 'container.regular',
+    borderRadius: 'xs',
+    minWidth: '0',
+    padding: '12',
+  })
+
+  export const value = style({
+    fontVariantNumeric: 'tabular-nums !custom',
+    margin: '0',
+    typography: 'body.b2Strong',
+  })
+}
+```
+
+**Don't:** Force a fixed `columns` count that squeezes values until they break.
+
+```tsx
+/**
+ * Don't example for "Let Content Reflow Before Adding Breakpoints" on the Responsive Layout page.
+ * Don't force a fixed `columns` count that squeezes values until they break.
+ * @module
+ */
+import { Grid, style } from '@tempoxyz/ds'
+
+const tiles = [
+  ['Balance', '$12,480.00'],
+  ['Sent', '$3,210.50'],
+  ['Received', '$4,005.00'],
+  ['Fees', '$0.04'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Grid columns="4" gap="12" {...styles.grid()}>
+      {tiles.map(([label, value]) => (
+        <div key={label} {...styles.tile()}>
+          <p {...styles.label()}>{label}</p>
+          <p {...styles.value()}>{value}</p>
+        </div>
+      ))}
+    </Grid>
+  )
+}
+
+namespace styles {
+  export const grid = style({ width: '17rem !custom' })
+
+  export const label = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })
+
+  export const tile = style({
+    backgroundColor: 'container.regular',
+    borderRadius: 'xs',
+    minWidth: '0',
+    padding: '12',
+  })
+
+  export const value = style({
+    fontVariantNumeric: 'tabular-nums !custom',
+    margin: '0',
+    overflowWrap: 'anywhere !custom',
+    typography: 'body.b2Strong',
+  })
+}
+```
+
+### Change Structure Only at Shared Breakpoints
+
+Switch between one and two panes at 1024px, the same width as [AppShell](/docs/components/app-shell). Components do not change at one-off widths, so the page drifts out of step with them.
+
+**Do:** Split into two panes at 1024px, where the app shell also changes.
+
+```tsx
+/**
+ * Do example for "Change Structure Only at Shared Breakpoints" on the Responsive Layout page.
+ * Split into two panes at 1024px, where the app shell also changes.
+ * @module
+ */
+import { Badge, ListGroup, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.root()}>
+      <Badge size="small">From 1024px</Badge>
+      <div {...styles.panes()}>
+        <ListGroup.Root {...styles.list()}>
+          <ListGroup.Row aria-current="true" action="navigation">
+            Alice
+          </ListGroup.Row>
+          <ListGroup.Row action="navigation">Bob</ListGroup.Row>
+        </ListGroup.Root>
+        <Surface size="small" {...styles.detail()}>
+          Payment to Alice
+        </Surface>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const detail = style({ flex: '1 !custom', minWidth: '0' })
+
+  export const list = style({ width: '7rem !custom' })
+
+  export const panes = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    gap: '8',
+    width: '17rem !custom',
+  })
+
+  export const root = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+  })
+}
+```
+
+**Don't:** Add a one-off breakpoint, such as 900px, for a single page.
+
+```tsx
+/**
+ * Don't example for "Change Structure Only at Shared Breakpoints" on the Responsive Layout page.
+ * Don't add a one-off breakpoint, such as 900px, for a single page.
+ * @module
+ */
+import { Badge, ListGroup, style, Surface } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.root()}>
+      <Badge size="small">From 900px</Badge>
+      <div {...styles.panes()}>
+        <ListGroup.Root {...styles.list()}>
+          <ListGroup.Row aria-current="true" action="navigation">
+            Alice
+          </ListGroup.Row>
+          <ListGroup.Row action="navigation">Bob</ListGroup.Row>
+        </ListGroup.Root>
+        <Surface size="small" {...styles.detail()}>
+          Payment to Alice
+        </Surface>
+      </div>
+    </div>
+  )
+}
+
+namespace styles {
+  export const detail = style({ flex: '1 !custom', minWidth: '0' })
+
+  export const list = style({ width: '7rem !custom' })
+
+  export const panes = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    gap: '8',
+    width: '17rem !custom',
+  })
+
+  export const root = style({
+    alignItems: 'flex-start',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+  })
+}
+```
+
+### Keep the Primary Action Within Reach
+
+Below 640px, stack form and dialog actions at full width, primary action first. From 640px, they align to the end with the primary action last.
+
+**Do:** Stack actions at full width on narrow screens, with the primary action first.
+
+```tsx
+/**
+ * Do example for "Keep the Primary Action Within Reach" on the Responsive Layout page.
+ * Stack actions at full width on narrow screens, with the primary action first.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.phone()}>
+      <Button>Send payment</Button>
+      <Button variant="secondary">Save as draft</Button>
+      <Button variant="tertiary">Cancel</Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const phone = style({
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+    width: '15rem !custom',
+  })
+}
+```
+
+**Don't:** Squeeze several actions into one row at phone width.
+
+```tsx
+/**
+ * Don't example for "Keep the Primary Action Within Reach" on the Responsive Layout page.
+ * Don't squeeze several actions into one row at phone width.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.phone()}>
+      <Button size="small" variant="tertiary">
+        Cancel
+      </Button>
+      <Button size="small" variant="secondary">
+        Save as draft
+      </Button>
+      <Button size="small">Send payment</Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const phone = style({
+    display: 'flex',
+    gap: '4',
+    justifyContent: 'flex-end',
+    overflow: 'hidden',
+    width: '15rem !custom',
+  })
+}
+```
+
+### Keep Features and Order the Same
+
+A narrow screen shows the same content and actions as a wide one, in a different arrangement. Move secondary actions into a [Menu](/docs/components/menu) instead of removing them.
+
+**Do:** Keep secondary actions behind a [Menu](/docs/components/menu) button on narrow screens.
+
+```tsx
+/**
+ * Do example for "Keep Features and Order the Same" on the Responsive Layout page.
+ * Keep secondary actions behind a Menu button on narrow screens.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+import { MoreHorizontal } from '@tempoxyz/ds/icons'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.phone()}>
+      <span {...styles.title()}>API keys</span>
+      <Button size="small">New key</Button>
+      <Button aria-label="More actions" shape="icon" size="small" variant="secondary">
+        <MoreHorizontal />
+      </Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const phone = style({
+    alignItems: 'center',
+    display: 'flex',
+    gap: '8',
+    width: '15rem !custom',
+  })
+
+  export const title = style({ flex: '1 !custom', typography: 'body.b1Strong' })
+}
+```
+
+**Don't:** Drop actions on narrow screens that the wide layout offers.
+
+```tsx
+/**
+ * Don't example for "Keep Features and Order the Same" on the Responsive Layout page.
+ * Don't drop actions on narrow screens that the wide layout offers.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.phone()}>
+      <span {...styles.title()}>API keys</span>
+      <Button size="small">New key</Button>
+    </div>
+  )
+}
+
+namespace styles {
+  export const phone = style({
+    alignItems: 'center',
+    display: 'flex',
+    gap: '8',
+    width: '15rem !custom',
+  })
+
+  export const title = style({ flex: '1 !custom', typography: 'body.b1Strong' })
+}
+```
+
+### Scroll Wide Content Inside Its Own Region
+
+Tables, code, and charts that cannot reflow scroll horizontally inside their own container. The page itself never scrolls sideways. To stack table rows instead, see [Tables and Lists](/docs/patterns/tables-and-lists#below-640px).
+
+**Do:** Scroll a wide table inside its card, and keep the page at the viewport width.
+
+```tsx
+/**
+ * Do example for "Scroll Wide Content Inside Its Own Region" on the Responsive Layout page.
+ * Scroll a wide table inside its card, and keep the page at the viewport width.
+ * @module
+ */
+import { style, Surface, Table } from '@tempoxyz/ds'
+
+const runs = [
+  ['296be2a', '219.1', '412.7', '588.0'],
+  ['8c41f0d', '224.8', '430.2', '601.3'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="small" {...styles.card()}>
+      <div aria-label="Benchmark runs" role="region" tabIndex={0} {...styles.scroll()}>
+        <Table.Root size="small" {...styles.table()}>
+          <Table.Head>
+            <Table.Row>
+              <Table.HeaderCell>Run</Table.HeaderCell>
+              <Table.HeaderCell justify="end">p50 (ms)</Table.HeaderCell>
+              <Table.HeaderCell justify="end">p95 (ms)</Table.HeaderCell>
+              <Table.HeaderCell justify="end">p99 (ms)</Table.HeaderCell>
+            </Table.Row>
+          </Table.Head>
+          <Table.Body>
+            {runs.map(([run, ...values]) => (
+              <Table.Row key={run}>
+                <Table.Cell mono>{run}</Table.Cell>
+                {values.map((value) => (
+                  <Table.Cell justify="end" key={value} numeric>
+                    {value}
+                  </Table.Cell>
+                ))}
+              </Table.Row>
+            ))}
+          </Table.Body>
+        </Table.Root>
+      </div>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const card = style({ boxSizing: 'border-box', width: '15rem !custom' })
+
+  export const scroll = style({ overflowX: 'auto' })
+
+  export const table = style({ minWidth: '22rem !custom' })
+}
+```
+
+**Don't:** Let a wide table push past its card and widen the page.
+
+```tsx
+/**
+ * Don't example for "Scroll Wide Content Inside Its Own Region" on the Responsive Layout page.
+ * Don't let a wide table push past its card and widen the page.
+ * @module
+ */
+import { style, Surface, Table } from '@tempoxyz/ds'
+
+const runs = [
+  ['296be2a', '219.1', '412.7', '588.0'],
+  ['8c41f0d', '224.8', '430.2', '601.3'],
+] as const
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Surface size="small" {...styles.card()}>
+      <Table.Root size="small" {...styles.table()}>
+        <Table.Head>
+          <Table.Row>
+            <Table.HeaderCell>Run</Table.HeaderCell>
+            <Table.HeaderCell justify="end">p50 (ms)</Table.HeaderCell>
+            <Table.HeaderCell justify="end">p95 (ms)</Table.HeaderCell>
+            <Table.HeaderCell justify="end">p99 (ms)</Table.HeaderCell>
+          </Table.Row>
+        </Table.Head>
+        <Table.Body>
+          {runs.map(([run, ...values]) => (
+            <Table.Row key={run}>
+              <Table.Cell mono>{run}</Table.Cell>
+              {values.map((value) => (
+                <Table.Cell justify="end" key={value} numeric>
+                  {value}
+                </Table.Cell>
+              ))}
+            </Table.Row>
+          ))}
+        </Table.Body>
+      </Table.Root>
+    </Surface>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    boxSizing: 'border-box',
+    overflow: 'visible',
+    width: '15rem !custom',
+  })
+
+  export const table = style({ minWidth: '22rem !custom' })
+}
+```
+
+## States
+
+* **Nothing Selected (Empty):** From 1024px, select the first record or show an empty detail pane, such as Select a payment.
+* **Loading (Skeleton):** Render a [Skeleton](/docs/components/skeleton) in the shape of each pane, so the layout does not jump.
+
+## Accessibility
+
+* **Scroll Regions (tabIndex={0}):** Give each scrolling region a name and make it focusable, so keyboards can scroll it.
+* **Matching Order:** Match the DOM order to the visual order. Stacked actions that reverse on phones keep Cancel first.
+* **Hidden Panes (display: none):** Hidden panes leave the accessibility tree. Move focus to the replacement pane.
+* **Landmarks (main):** The app shell or a container renders one per page. Label each `section` with `aria-labelledby`.
+* **Rem Widths (rem):** Size widths in rem, so layouts follow the font size setting.
+
+## Related
+
+[Container](/docs/components/container)
+
+Use for content width and gutters.
+
+[Grid](/docs/components/grid)
+
+Use for collections that reflow.
+
+[AppShell](/docs/components/app-shell)
+
+Use for the sidebar and content column.
+
+[Layout](/docs/foundations/layout)
+
+Covers spacing and alignment.
+
+[Navigation](/docs/patterns/navigation)
+
+Covers moving between pages.
+
+[Tables and Lists](/docs/patterns/tables-and-lists)
+
+Covers tables on narrow screens.
+
+[Dashboards](/docs/patterns/dashboards)
+
+Covers metric grids that reflow.