Dashboard design

Start with the question

A dashboard answers a few questions for one person. A promoter asks whether a show will sell out. A venue asks which nights need a push. Write those questions down first, then give each one a card. If a card answers no one’s question, cut it.

The grid

Dashboard sizes itself from its own width, not the window. It has 12 tracks from 960px, 6 from 600px and 2 below that, so it works in a side pane as well as on a phone. Cards flow in source order and the grid never moves them, so reading order always matches what people see. Cards in a row stretch to the same height. Dashboard.Section groups cards under an h2, and sections sit 32px apart.

There are no custom spans, breakpoint overrides or dense packing. If a layout needs a size that isn’t here, it gets a new size in Roadie.

This is the show dashboard. It opens with a full note that says what to do, then four stat tiles, a full chart and two md tables side by side. Two md charts and a full heatmap close it. This column is narrower than 960px, so it shows 6 tracks or fewer. Here is the same layout at each width, and the JSX behind it.

<Dashboard>
  <Dashboard.Section title='At a glance'>
    <DataCard size='full' label='What to do next'>
      <p>GA is carrying the show and VIP is 45 points short of target. Push VIP in the final month.</p>
    </DataCard>
    <StatTile label='Tickets sold' value={1464} delta={{ value: 216 }} />
    <StatTile label='Sell-through' value={0.61} format='percent' />
    <StatTile label='Pace index' value={112} format='index' />
    <StatTile label='Gross revenue' value={118400} format='compactCurrency' />
  </Dashboard.Section>
  <Dashboard.Section title='Sales'>
    <Chart size='full' label='Sales pace' source='Oztix sales.'>
      <LineChart data={pace} x='day' y='sold' format='percent' />
    </Chart>
    <DataCard size='md' label='Ticket types'>
      <DataTable columns={typeColumns} rows={types} />
    </DataCard>
    <DataCard size='md' label='Where buyers are from'>
      <DataTable columns={suburbColumns} rows={suburbs} />
    </DataCard>
  </Dashboard.Section>
  <Dashboard.Section title='Buyers'>
    <Chart size='md' label='Daily orders' takeaway='Orders peak on Fridays and grow each week'>
      <BarChart data={dailyOrders} x='day' y='orders' />
    </Chart>
    <Chart size='md' label='Ticket type mix' takeaway='GA is carrying the show'>
      <StackedBars data={salesByMonth} x='month' y='sold' series='type' />
    </Chart>
    <Chart size='full' label='When fans buy' takeaway='Fans buy most on Friday evenings'>
      <Heatmap data={ordersByHour} rows='weekday' columns='hour' value='orders' />
    </Chart>
  </Dashboard.Section>
</Dashboard>

Rows that fill

Every row must fill at desktop, tablet and phone widths. These combinations do.

On tablet, lg takes a full row and sm takes half. So lg then sm leaves half a row empty. The mirrored sm fills it.

In development, Dashboard.Section logs a warning for any row that leaves a gap. It uses the same check as validateDashboard. It only sees the section’s direct children. If you wrap a card, pass size to the wrapper so the check still sees it.

[Roadie Dashboard] "Pace" has rows that don't fill: desktop row 1 leaves 4 empty; desktop row 2 leaves 6 empty; tablet row 2 leaves 3 empty. See /charts/dashboards.

Card anatomy

DataCard is the shared card. StatTile, table cards and Chart are built on it. Its props match the JSON description field for field, so a card in JSX and a card in JSON come out the same.

The label, headline and context line never wrap. Text that doesn’t fit ends in an ellipsis. The full text goes in the tooltip and the accessible name. The legend is the only chart text that wraps.

A number or a sentence

The headline is a value with a delta, or a takeaway sentence. Never both. Use a value when one number answers the question. Use a takeaway when there’s no single number, such as a channel mix or a table.

Which card answers which question

Copy that fits

Copy is sized for the card’s narrowest width. Past these limits it truncates.

Chart cards carry the Chart/Table switch in the label’s row, so their label budget is tighter than COPY_LIMITS.

• Keep the delta short. It sits next to the value.
• Say what the delta is compared with on the context line.
• No dashes as punctuation. Use “to” for ranges.
• Sentence case for labels, context and takeaways.

States

Every card takes a state. The app sets it. A hidden sparkline is not a state.

Card actions

Actions sit at the top right of a card, in the label’s row. They carry handlers, so the app adds them and the JSON never does. Pass actions to DataCard, StatTile or Chart. For cards described as data, pass cardActions to DashboardView. It gets each card’s spec and returns its actions, or nothing. When DashboardView renders on the server, return a client component that owns the handlers, not inline handlers.

// CardMenu.tsx
'use client'

import {
  ArrowRightIcon,
  CopyIcon,
  DownloadIcon,
  EyeSlashIcon,
  ImageIcon,
  PencilSimpleIcon,
  TrashIcon
} from '@phosphor-icons/react'

import type { ChartTable } from '@oztix/roadie-charts/tables'
import { DataCard } from '@oztix/roadie-components/data-card'
import { Menu } from '@oztix/roadie-components/menu'

function csvField(value: unknown) {
  const text = Array.isArray(value) ? value.join(' ') : String(value ?? '')
  return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text
}

function tableCsv({ columns, rows }: ChartTable) {
  const lines = [
    columns.map((column) => csvField(column.header)),
    ...rows.map((row) => columns.map((column) => csvField(row[column.key])))
  ]
  return lines.map((line) => line.join(',')).join('\n')
}

function downloadCsv(label: string, table: ChartTable) {
  const url = URL.createObjectURL(
    new Blob([tableCsv(table)], { type: 'text/csv' })
  )
  const link = document.createElement('a')
  link.href = url
  link.download = `${label.toLowerCase().replace(/[^a-z0-9]+/g, '-')}.csv`
  link.click()
  // Revoking in the same task can cancel the download in some browsers.
  setTimeout(() => URL.revokeObjectURL(url))
}

export function CardMenu({ label, table }: { label: string; table?: ChartTable }) {
  return (
    <Menu>
      <Menu.Trigger render={<DataCard.MoreButton label={label} />} />
      <Menu.Content align='end'>
        <Menu.Group>
          <Menu.GroupLabel>Chart</Menu.GroupLabel>
          <Menu.Item icon={<PencilSimpleIcon weight='bold' />}>Edit</Menu.Item>
          <Menu.Item icon={<CopyIcon weight='bold' />}>Duplicate</Menu.Item>
        </Menu.Group>
        <Menu.Separator />
        <Menu.Group>
          <Menu.GroupLabel>Display</Menu.GroupLabel>
          <Menu.Item icon={<EyeSlashIcon weight='bold' />}>Hide description</Menu.Item>
        </Menu.Group>
        <Menu.Separator />
        <Menu.Group>
          <Menu.GroupLabel>Export</Menu.GroupLabel>
          {table && (
            <Menu.Item
              icon={<DownloadIcon weight='bold' />}
              onClick={() => downloadCsv(label, table)}
            >
              Download CSV
            </Menu.Item>
          )}
          <Menu.Item icon={<ImageIcon weight='bold' />}>Copy as image</Menu.Item>
        </Menu.Group>
        <Menu.Separator />
        <Menu.Group>
          <Menu.GroupLabel>Dashboard</Menu.GroupLabel>
          <Menu.Item icon={<ArrowRightIcon weight='bold' />}>Move to</Menu.Item>
          <Menu.Item intent='danger' icon={<TrashIcon weight='bold' />}>
            Remove from dashboard
          </Menu.Item>
        </Menu.Group>
      </Menu.Content>
    </Menu>
  )
}

// page.tsx
import { cardTable } from '@oztix/roadie-charts/tables'

<DashboardView
  spec={spec}
  cardActions={(card) => (
    <CardMenu label={card.label} table={cardTable(card)} />
  )}
/>

Slot order

• The Chart and Table switch comes first, on chart cards.
• Then at most one visible action, for the thing people do most on that card.
• More comes last, always. Every other action goes in its menu.

Always visible

• Actions show all the time, not only on hover, so they work on touch and by keyboard.
• Tab order follows reading order: the view switch, then the action, then More.
• Actions stay in every state, so Refresh data and Remove from dashboard still work on a card that failed to load. The view switch shows only when there’s data.

<DataCard
  label='Ticket types'
  actions={
    <DataCard.MoreButton
      label='Ticket types'
      className='opacity-0 group-hover/card:opacity-100'
    />
  }
/>

The More menu

Group the menu in this order and leave out what a card can’t do. Build it with Menu: pass DataCard.MoreButton to Menu.Trigger as its render. The button keeps its name, “More actions for” the card’s label, and its ref. Name each group with Menu.GroupLabel, split groups with Menu.Separator, and open the menu with align='end' so it opens back over the card.

• Download CSV from the card’s table. cardTable(card) from @oztix/roadie-charts/tables builds it on the server, for a chart card or a table card.
• Copy as image with renderChartSvg from @oztix/roadie-charts/static.
• Refresh data shows when the numbers were last updated, as helper text under the item.

Copy

• Sentence case, verb first: “Download CSV”, not “CSV download”.
• No dashes as punctuation.
• Destructive actions confirm first. Remove from dashboard asks before it removes.

Label room

More takes room from the label, which truncates past it. Beside More, keep chart labels to 18 characters at sm and md and 23 at lg and full, and stat labels to 14. ACTIONS_LABEL_LIMITS holds them. Table and note labels keep their COPY_LIMITS. validateDashboard can’t check this, because actions aren’t part of the JSON.

Tables on dashboards

• Use at most two visual columns, sparkline or meter, per table.
• Give each column a priority. As the card narrows, higher numbers hide first. Columns without one always show.
• The “Show all columns” button switches to horizontal scrolling and holds the pin column in place.
• A sparkline cell needs 5 points. With fewer, it shows “Not enough history”.

At this width the sparkline column hides first. Show all columns brings it back.

Describe it as data

Any dashboard can be written as a JSON description with its numbers inline. Card fields match the component props, and DashboardView from @oztix/roadie-charts renders it. Agents can build and check a dashboard this way before anyone sees it.

{
  "id": "sold", "kind": "stat", "size": "stat",
  "label": "Tickets sold", "value": 1464,
  "delta": { "value": 216 }, "context": "This week, of 2,400"
}

validateDashboard from @oztix/roadie-core/dashboard returns every problem with its path.

import { validateDashboard } from '@oztix/roadie-core/dashboard'

const { problems } = validateDashboard(spec)

Here the second section puts a pace card at lg before a channels card at md. It returns these problems.

It also checks sizes per card kind, unique ids, visual columns, a source on every chart and table card, copy lengths, dashes and sentence case.

CARD_SPANS and COPY_LIMITS hold the sizes and limits above. Import them from @oztix/roadie-core/dashboard-layout when you only need the layout rules, because that entry doesn’t load Zod.

Accessibility

• Each card is a section named by its label. Dashboard sections use h2 headings.
• Values and deltas read as sentences, such as “Sell-through, 61%, up 9 points, better. This week, target 85%.”
• A plot is an image with a one-line summary from its headline or takeaway. The Table tab is the full alternative, reachable by keyboard.
• Colour is never the only signal. Deltas have arrows and words, table status has text, and textures turn on under forced colours.
• Nothing animates.