@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/foundations/layout.md

@@ -0,0 +1,508 @@
+# Layout
+
+Page structure, grid, spacing, radius, and elevation.
+
+## Overview
+
+Tempo pages are calm and orderly. Flat cards sit on a tinted page, line up on a twelve-column grid, and keep generous space between groups, so the content stands out more than its frame.
+
+Space follows relationships. Elements sit close within a group, further apart between groups, and furthest apart between sections. As the screen widens, the margins grow and the sidebar opens, while the content keeps a comfortable width.
+
+For page frames and width changes, see [Responsive Layout](/docs/patterns/responsive-layout).
+
+## Page Structure
+
+Every page shares one frame, which [App Shell](/docs/components/app-shell) provides.
+
+* **Sidebar:** Navigation on the start edge, which moves into a drawer on small screens.
+* **Top Bar:** The page title and its main action, in one bar above the content.
+* **Content:** Cards, charts, and tables, arranged on the page grid below the bar.
+
+## Grid
+
+Wide pages divide into twelve columns. Each card, chart, and table takes a share of them, and every row keeps the same gutters. [Grid](/docs/components/grid) lays out the columns.
+
+* **Summary Cards (3 of 12):** Key figures in a row of equal cards.
+* **Chart and Panel (8 and 4):** A wide chart beside a narrow panel.
+* **Tables (12 of 12):** Lists and tables across the full width.
+* **Small Screens (phone):** Cards pair up, and panels stack.
+
+## Spacing
+
+Spacing comes from one scale of steps. Pick a step by how closely the elements relate: the closer the relationship, the smaller the gap.
+
+* **Related Elements (4 to 8):** An icon and its label, or a label and its value.
+* **Items and Fields (12 to 16):** Items in a list, fields in a form, and buttons.
+* **Groups and Cards (24 to 32):** Groups within a section, such as cards in a grid.
+* **Page Sections (40 to 64):** The sections of a page, such as a table.
+
+## Radius
+
+Larger elements get rounder corners, from fields at 12px to modals at 32px. [Radius and Padding](/docs/foundations/radius-and-padding) covers each role and its padding.
+
+* `none`: `0rem`
+* `3xs`: `calc(0.25rem * var(--tds-corner-scale, 1))`
+* `2xs`: `calc(0.5rem * var(--tds-corner-scale, 1))`
+* `xs`: `calc(0.75rem * var(--tds-corner-scale, 1))`
+* `sm`: `calc(1rem * var(--tds-corner-scale, 1))`
+* `md`: `calc(1.5rem * var(--tds-corner-scale, 1))`
+* `lg`: `calc(2rem * var(--tds-corner-scale, 1))`
+* `xl`: `calc(2.5rem * var(--tds-corner-scale, 1))`
+* `2xl`: `calc(4rem * var(--tds-corner-scale, 1))`
+* `full`: `62.4375rem`
+
+## Elevation
+
+Shadows mark layers that float above the page, and most surfaces need none. In dark mode, a layer lifts with a lighter surface rather than a deeper shadow.
+
+* **Flat (none):** Cards and panels, which sit flat on the page.
+* **Small (shadow.small):** Controls that lift off a track, such as a switch thumb.
+* **Regular (shadow.regular):** Menus, toasts, and other popups over the page.
+* **Large (shadow.large):** Dialogs and drawers, above the dimmed page.
+
+## Widths
+
+[Container](/docs/components/container) centers content at a maximum width, with side gutters that grow on larger screens. Pick its size by the content, not by the screen.
+
+* **Narrow (48rem):** Forms, settings, and single-task flows.
+* **Medium (64rem):** Detail pages, such as a transaction or an API key.
+* **Wide (80rem):** The default, for dashboards, tables, and card grids.
+* **Full (none):** Charts and canvases that manage their own width.
+
+## Breakpoints
+
+Design for the smallest screen first, then let content spread into more columns as space allows. Components change layout at the same widths, so a layout that shifts beside one should switch with it.
+
+* **Phone (0 to 639px):** One column, with the sidebar in a drawer.
+* **Tablet (640 to 1023px):** Two columns, where the content allows.
+* **Desktop (1024px and up):** The sidebar opens, and grids gain columns.
+
+Write a breakpoint as a query inside a style.
+
+```tsx
+import { style } from '@tempoxyz/ds'
+
+namespace styles {
+  export const metrics = style({
+    display: 'grid',
+    gap: '16',
+    '@media >=768': { gridTemplateColumns: 'repeat(3, minmax(0, 1fr)) !custom' },
+  })
+}
+```
+
+## Layout Primitives
+
+Primitives arrange content without adding meaning. When a region needs meaning, render the primitive as a semantic element, such as a list or the main landmark.
+
+* **Stack (gap 16):** [Stack](/docs/components/stack) spaces a vertical run, such as fields in a form.
+* **Inline (gap 8):** [Inline](/docs/components/inline) spaces a horizontal run, such as actions or badges.
+* **Grid (gap 24):** [Grid](/docs/components/grid) arranges similar items, such as metric tiles.
+* **Container (size):** [Container](/docs/components/container) sets the page width and side gutters.
+* **Inset (space):** [Inset](/docs/components/inset) pads a region without drawing a container.
+* **Surface (size):** [Surface](/docs/components/surface) is a visible card that groups related content.
+
+## Guidelines
+
+### Space Siblings With Gap
+
+Space siblings from their parent. Margins on each child collapse, double up when items reorder, and leave stray space after the last item.
+
+**Do:** Space the items of a list from their parent.
+
+```tsx
+/**
+ * Do example for "Space Siblings With Gap" on the Layout page.
+ * Space the items of a list with `gap` on the parent.
+ * @module
+ */
+import { style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <span {...styles.item()}>Sent 25.00 USDC to 0x3c44…93bc</span>
+      <span {...styles.item()}>Received 120.00 USDC</span>
+      <span {...styles.item()}>Sent 8.50 USDC to 0x90f7…b906</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const item = style({
+    backgroundColor: 'container.regular',
+    borderRadius: '2xs',
+    color: 'content.primary',
+    paddingBlock: '8',
+    paddingInline: '12',
+    typography: 'body.b2',
+  })
+
+  export const list = style({
+    borderColor: 'line.secondary',
+    borderRadius: 'xs',
+    borderStyle: 'dashed',
+    borderWidth: 'regular',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '12',
+    maxWidth: '100% !custom',
+    padding: '12',
+    width: '18rem !custom',
+  })
+}
+```
+
+**Don't:** Add a margin to each child, which leaves space after the last one.
+
+```tsx
+/**
+ * Don't example for "Space Siblings With Gap" on the Layout page.
+ * Don't add a margin to each child, which leaves space after the last one.
+ * @module
+ */
+import { style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.list()}>
+      <span {...styles.item()}>Sent 25.00 USDC to 0x3c44…93bc</span>
+      <span {...styles.item()}>Received 120.00 USDC</span>
+      <span {...styles.item()}>Sent 8.50 USDC to 0x90f7…b906</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const item = style({
+    backgroundColor: 'container.regular',
+    borderRadius: '2xs',
+    color: 'content.primary',
+    marginBottom: '12',
+    paddingBlock: '8',
+    paddingInline: '12',
+    typography: 'body.b2',
+  })
+
+  export const list = style({
+    borderColor: 'line.secondary',
+    borderRadius: 'xs',
+    borderStyle: 'dashed',
+    borderWidth: 'regular',
+    display: 'flex',
+    flexDirection: 'column',
+    maxWidth: '100% !custom',
+    padding: '12',
+    width: '18rem !custom',
+  })
+}
+```
+
+### Group Related Content by Proximity
+
+Put less space inside a group than between groups. A label sits close to its value, and separate pairs sit well apart, so they need no dividers.
+
+**Do:** Keep each label close to its value and leave more space between pairs.
+
+```tsx
+/**
+ * Do example for "Group Related Content by Proximity" on the Layout page.
+ * Keep each label close to its value and leave more space between pairs.
+ * @module
+ */
+import { Stack, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Stack gap="24">
+      <Stack gap="4">
+        <span {...styles.label()}>Recipient</span>
+        <span {...styles.value()}>0x3c44…93bc</span>
+      </Stack>
+      <Stack gap="4">
+        <span {...styles.label()}>Amount</span>
+        <span {...styles.value()}>250.00 PathUSD</span>
+      </Stack>
+      <Stack gap="4">
+        <span {...styles.label()}>Network fee</span>
+        <span {...styles.value()}>0.01 PathUSD</span>
+      </Stack>
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const value = style({ color: 'content.primary', typography: 'body.b1Strong' })
+}
+```
+
+**Don't:** Space every line equally, which makes labels and values hard to pair.
+
+```tsx
+/**
+ * Don't example for "Group Related Content by Proximity" on the Layout page.
+ * Don't space every line equally, which makes labels and values hard to pair.
+ * @module
+ */
+import { Stack, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <Stack gap="12">
+      <span {...styles.label()}>Recipient</span>
+      <span {...styles.value()}>0x3c44…93bc</span>
+      <span {...styles.label()}>Amount</span>
+      <span {...styles.value()}>250.00 PathUSD</span>
+      <span {...styles.label()}>Network fee</span>
+      <span {...styles.value()}>0.01 PathUSD</span>
+    </Stack>
+  )
+}
+
+namespace styles {
+  export const label = style({ color: 'content.secondary', typography: 'body.b3' })
+
+  export const value = style({ color: 'content.primary', typography: 'body.b1Strong' })
+}
+```
+
+### Keep Cards Flat
+
+Separate a [Surface](/docs/components/surface) from the page with its lighter background, not a shadow. Keep shadows for content that floats over other content.
+
+**Do:** Keep cards flat, and add a shadow only to the layer above them.
+
+```tsx
+<LayoutDemo kind="elevated" />
+```
+
+**Don't:** Give every card a shadow.
+
+```tsx
+<LayoutDemo kind="shadowed" />
+```
+
+### Use One Surface per Group
+
+**Do:** Use one surface with a title for one group.
+
+```tsx
+<Surface>
+  <Surface.Header>
+    <Surface.Title>Balances</Surface.Title>
+    <Button size="small" variant="tertiary">View all</Button>
+  </Surface.Header>
+  <span>120.00 USDC</span>
+</Surface>
+```
+
+**Don't:** Nest surfaces to create structure.
+
+```tsx
+<Surface>
+  <Surface>
+    <Surface>
+      <span>120.00 USDC</span>
+    </Surface>
+  </Surface>
+</Surface>
+```
+
+### Size Containers by Content
+
+Pick the narrowest [Container](/docs/components/container) that fits the content.
+
+**Do:** Keep a form in a narrow container, so each field is as wide as its content needs.
+
+```tsx
+<Field.Root>
+  <Field.Label>Recipient</Field.Label>
+  <TextInput.Group>
+    <TextInput.Control placeholder="Address or username" />
+  </TextInput.Group>
+</Field.Root>
+```
+
+**Don't:** Stretch a form across a wide page.
+
+```tsx
+<LayoutDemo kind="container" width="full" />
+```
+
+### Let Collections Reflow
+
+For cards and metric tiles, let the grid fit as many columns as the width allows. A fitted grid collapses to one column on a phone without extra breakpoints.
+
+**Do:** Let a collection reflow to one column at 320px.
+
+```tsx
+<LayoutDemo kind="columns" width="phone" />
+```
+
+**Don't:** Fix a column count that runs past a narrow screen.
+
+```tsx
+<LayoutDemo kind="overflow" />
+```
+
+### Keep Source Order Visual Order
+
+Don't reorder content visually. Keyboard focus and screen readers follow the source, so a reordered layout makes focus jump.
+
+**Do:** Write elements in the order they appear, so focus moves left to right.
+
+```tsx
+/**
+ * Do example for "Keep Source Order Visual Order" on the Layout page.
+ * Write elements in the order they appear, so focus moves left to right.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <span {...styles.item()}>
+        <span {...styles.step()}>1</span>
+        <Button variant="secondary">Cancel</Button>
+      </span>
+      <span {...styles.item()}>
+        <span {...styles.step()}>2</span>
+        <Button>Send payment</Button>
+      </span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const item = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '8',
+  })
+
+  export const row = style({ alignItems: 'flex-end', display: 'flex', gap: '12' })
+
+  export const step = style({
+    alignItems: 'center',
+    backgroundColor: 'accent.blue.background',
+    borderRadius: 'full',
+    color: 'white !custom',
+    cornerShape: 'round',
+    display: 'inline-flex',
+    height: '20',
+    justifyContent: 'center',
+    typography: 'body.b3Strong',
+    width: '20',
+  })
+}
+```
+
+**Don't:** Reverse the visual order, which makes focus jump backward.
+
+```tsx
+/**
+ * Don't example for "Keep Source Order Visual Order" on the Layout page.
+ * Don't reverse the visual order, which makes focus jump backward.
+ * @module
+ */
+import { Button, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.row()}>
+      <span {...styles.item()}>
+        <span {...styles.step()}>1</span>
+        <Button>Send payment</Button>
+      </span>
+      <span {...styles.item()}>
+        <span {...styles.step()}>2</span>
+        <Button variant="secondary">Cancel</Button>
+      </span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const item = style({
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '8',
+  })
+
+  export const row = style({
+    alignItems: 'flex-end',
+    display: 'flex',
+    flexDirection: 'row-reverse',
+    gap: '12',
+    justifyContent: 'flex-end',
+  })
+
+  export const step = style({
+    alignItems: 'center',
+    backgroundColor: 'accent.blue.background',
+    borderRadius: 'full',
+    color: 'white !custom',
+    cornerShape: 'round',
+    display: 'inline-flex',
+    height: '20',
+    justifyContent: 'center',
+    typography: 'body.b3Strong',
+    width: '20',
+  })
+}
+```
+
+## Accessibility
+
+* **Reflow (320px):** Content reflows without sideways scrolling, as fitted grids do by default.
+* **Regions (render):** Primitives add no roles, so render regions as meaningful elements.
+* **Text Size (200%):** Spacing grows with larger default text, so check layouts at 200%.
+
+## Related
+
+[Responsive Layout](/docs/patterns/responsive-layout)
+
+Covers page frames and width changes.
+
+[Stack](/docs/components/stack)
+
+Use for arranging content.
+
+[Inline](/docs/components/inline)
+
+Use for arranging content.
+
+[Grid](/docs/components/grid)
+
+Use for arranging content.
+
+[Container](/docs/components/container)
+
+Use for width and padding.
+
+[Inset](/docs/components/inset)
+
+Use for width and padding.
+
+[Surface](/docs/components/surface)
+
+Use for cards.
+
+[App Shell](/docs/components/app-shell)
+
+Use for the application frame.
+
+[Radius and Padding](/docs/foundations/radius-and-padding)
+
+Covers how padding pairs with each radius.