---
title: Pages with the page kit
nav: Page kit
group: Guides
order: 1.65
---
# Pages with the page kit

Draw a report, plan or comparison as a page with the Mainmind page kit.
Copy this starter, then replace the sample data.

## Write the page

Save `pages/<name>.md`: frontmatter, a sentence or two for search, then one
fenced `jsx` block. Push it like any other page. Keep `write-class` as shown,
or the push is refused. More on the file: [A visual page](/docs/agent-coordination#a-visual-page).

```markdown
---
type: Page
title: "Alder & Ash sales"
keeper: reports
write-class: ledger
---

# Alder & Ash sales

Sample sales for Monday and Tuesday, drawn with the page kit.
```

Then the `jsx` block, in the same file:

```jsx
import React from 'react';
import { Page, Header, Grid, Kpi, Card, Line, format } from '@mainmind/kit';

const data = {
  days: [{ label: 'Mon', value: 42000 }, { label: 'Tue', value: 51000 }],
};

export default function SalesPage() {
  return (
    <Page id="sales-page">
      <Header id="heading" title="Alder & Ash sales"
        subtitle="Sample data · Tuesday sales rose from Monday." />
      <Grid id="summary">
        <Kpi id="total" label="Two-day sales" value={data.days.reduce((sum, day) => sum + day.value, 0)}
          valueFormat={format.inr} span={12} />
        <Card id="trend-card" title="Daily sales" span={12}>
          <Line id="trend" label="Sales in rupees" data={data.days} valueFormat={format.inr} />
        </Card>
      </Grid>
    </Page>
  );
}
```

- Use only static imports from `react` and `@mainmind/kit`. No dynamic
  `import()` or `import.meta`.
- Use `export default` for the page component.
- Keep the JSX source within 120,000 bytes.
- Do not use `require`, `module` or `exports` as names. Names starting with
  `__mainmind_` are reserved too.
- No `fetch` or other network calls. Keep the data in the page.
- No outside URLs, custom fonts or hex colours. Use the kit and its tokens.
- Hooks through `React.useState` or named imports from `react` are fine.

A page that does not compile is refused at save with its line number.
A pushed page that does not compile shows an error card and tells its keeper.
A page that compiles but fails while drawing shows the error card only; read
the error it names, fix the page and push again.

The page runs in an isolated frame with `sandbox="allow-scripts"` and no
network access. Mainmind sets light or dark mode; let the kit follow it.
Links go through the host's **Open this link?** dialog. To link to another
page, use `<a id="plan-link" data-page="pages/plan.md">Read the plan</a>`.

## Eight design rules

1. Lead with the answer. Use a `Header` whose subtitle says what changed in
   one sentence, then 3 or 4 `Kpi` cards.
2. Use `Grid`. Put the main chart in a `Card` with `span={8}` and a supporting
   card with `span={4}` beside it.
3. Use kit components and tokens only. No hex colours, custom fonts or
   outside URLs. Use flavours for series: `sky`, `mint`, `grape`, `tangerine`,
   `sunny`.
4. Give the page at most one main action. Use few, warm words.
5. Give every component a stable `id`. Keep ids when editing.
6. Put the data in one `const data = {...}` at the top. Edits should change
   numbers, not layout.
7. Check at 390px wide. Nothing should be wider than the screen. Tables
   should scroll inside their card.
8. Label sample or estimated numbers as such. For example, put “Sample data”
   in the subtitle.

## Components

Every component accepts `id`. Give each one a unique, stable value.
`span` is a number from 1 to 12 within a `Grid`. It defaults to 12 on `Card`
and `Stack`, and 4 on `Kpi`. The kit stacks these on small screens.

### Layout

| Component | Props besides `id` | Use |
|---|---|---|
| `Page` | `children`, `className` | Wrap the whole page. |
| `Header` | `title`, `subtitle`, `actions`, `children` | State the answer; put a control in `actions`. |
| `Section` | `title`, `children` | Group related content under a heading. |
| `Grid` | `children` | Arrange content in 12 columns. |
| `Stack` | `children`, `span` | Put parts in a vertical group. |
| `Cluster` | `children` | Put small parts together in a wrapping row. |
| `Card` | `title`, `span`, `children` | Frame a chart or supporting detail. |

### Numbers

| Component | Props besides `id` | Use |
|---|---|---|
| `Kpi` | `label`, `value`, `delta`, `data`, `valueFormat`, `span` | Show a key number, a short change note and an optional sparkline. |
| `Progress` | `label`, `value` (default 0), `max` (default 100) | Show progress as a share of a target. |
| `Badge` | `children`, `tone` | Mark a status; `tone` is `neutral` or a flavour. |
| `Callout` | `title`, `children` | State a finding, next step or risk. |

`Kpi.value` can be a number or display text. `valueFormat` formats numbers
and defaults to `format.number`. Its `data` uses the single-value chart shape
below. `delta` is display text, such as “Up 12% from last week”.

### Choices

| Component | Props besides `id` | Use |
|---|---|---|
| `Tabs` | `label`, `items`, `value`, `defaultValue`, `onChange` | Switch between panels supplied as item `content`. |
| `Segmented` | `label`, `items`, `value`, `defaultValue`, `onChange` | Choose a value, such as a chart's date range. |

Items have `{value, label, content?, disabled?}`. `Tabs` displays `content`;
`Segmented` only chooses a value. Control either with `value` and
`onChange(value)`, or let it keep its own choice with `defaultValue`.
Both support arrow keys, Home and End.

### Lists

| Component | Props besides `id` | Use |
|---|---|---|
| `Table` | `caption`, `columns`, `rows`, `rowKey` (default `'id'`) | Show exact values and optional bars, with scrolling inside the table. |
| `Timeline` | `items` | Show dated steps with descriptions and statuses. |
| `Checklist` | `items`, `onChange` | Track tasks with checkboxes. |
| `Legend` | `items` | Explain series colours. |

- Table columns: `{key, label, number?, bar?, format?, max?}`. Rows are plain
  objects with those keys. `number` aligns values; `bar` adds a bar.
  `format(value)` supplies display text. A positive `max` sets the bar scale;
  otherwise the largest absolute value in that column sets it, with a minimum of 1.
- Timeline items: `{id, title, date?, description?, status?}`. Dates use
  `format.date`; status is text shown in a badge.
- Checklist items: `{id, label, checked?, disabled?}`. Its callback is
  `onChange(id, checked)`. Update your state there. Without it, boxes are disabled.
- Legend items: `{key?, label, color?}`. Use a flavour for `color`.

### Charts

| Component | Props besides `id` | Use |
|---|---|---|
| `Line` | `data`, `series`, `label`, `valueFormat` | Compare trends over time. |
| `Area` | `data`, `series`, `label`, `valueFormat` | Fill each trend down to zero. |
| `Stacked` | `data`, `series`, `label`, `valueFormat` | Stack areas to show each series' share over time. |
| `Bar` | `data`, `series`, `label`, `valueFormat` | Compare categories or negative values; series sit side by side. |
| `Donut` | `data`, `label`, `valueFormat` | Show positive parts of one whole. |
| `Sparkline` | `data`, `series`, `label`, `valueFormat` | Add a small trend without axes. |

Chart data is `[{label, value}]` for one series, or
`[{label, <seriesKey>...}]` with `series: [{key, label, color}]`.
For example, use `{label: 'Mon', sales: 42000, costs: 27000}` with series
keys `sales` and `costs`. Values must be numbers. A plain number array also
works; its labels become 1, 2, 3 and so on.

Donut data is `[{label, value, color?}]`. Each slice uses its row's flavour;
`series` does not control a donut. Negative values show a message asking for
a bar chart. Missing or non-finite values are gaps, never invented zeroes.

Charts already include keyboard focus and a **View values** table.
Charts with more than one series include a legend, except sparklines.
Donuts include a slice legend. `valueFormat` defaults to `format.number`.

### format

| Helper | Arguments | Use |
|---|---|---|
| `format.number` | `value`, `options?` | Indian digit grouping; `{compact: true}` uses lakh and crore. |
| `format.inr` | `value`, `options?` | Rupees, with no decimals by default; compact lakh/crore also works. |
| `format.percent` | `value`, `options?` | Format a fraction: `0.12` becomes `12%`. |
| `format.date` | `value`, `options?` | Format a date in India time (`Asia/Kolkata`) by default. |

Number helpers take `Intl.NumberFormat` options as well as `compact`.
Dates take a date string, timestamp or `Date`, plus `Intl.DateTimeFormat`
options. Invalid or missing values show “—”.

## Patterns

- KPI strip: a `Grid` with three `Kpi` cards at span 4, or four at span 3.
- Wide chart and side card: span 8 for the chart, span 4 for progress and a
  short finding. Use `Segmented` with `React.useState` to switch the chart's range.
- Detail panels: put `Tabs` below the main answer for deeper tables or notes.
- Rankings: use a `Table` with a bar column. Use `Bar` for negative values;
  use `Donut` only for parts of a whole.
- Plan: pair a `Timeline` with a `Checklist`, then state the next risk in a
  `Callout`.

## Examples

Each block is a complete JSX page component. Put one in the page file described
above. All figures below are sample data for Alder & Ash, a small Indian café
and bakery chain. Choices and checkboxes change the current view; they do not
save task changes back to the page.

### Weekly report

The range control changes the main chart. The cards and other charts show the
whole week.

```jsx
import React from 'react';
import {
  Page, Header, Grid, Kpi, Card, Stack, Segmented, Line,
  Progress, Badge, Callout, Bar, Donut, Table, format,
} from '@mainmind/kit';

const data = {
  ranges: [{ value: 'week', label: 'This week' }, { value: 'recent', label: 'Last 3 days' }],
  days: [
    { label: 'Mon', sales: 42000, costs: 27000, orders: 140 },
    { label: 'Tue', sales: 51000, costs: 32000, orders: 160 },
    { label: 'Wed', sales: 47000, costs: 28000, orders: 150 },
    { label: 'Thu', sales: 65000, costs: 36000, orders: 190 },
    { label: 'Fri', sales: 72000, costs: 40000, orders: 200 },
    { label: 'Sat', sales: 89000, costs: 49000, orders: 220 },
    { label: 'Sun', sales: 76000, costs: 44000, orders: 188 },
  ],
  series: [
    { key: 'sales', label: 'Sales', color: 'sky' },
    { key: 'costs', label: 'Costs', color: 'mint' },
  ],
  mix: [
    { label: 'Coffee', value: 282000, color: 'sky' },
    { label: 'Bakery', value: 113000, color: 'mint' },
    { label: 'Other', value: 47000, color: 'grape' },
  ],
  stores: [
    { id: 'indiranagar', name: 'Indiranagar', sales: 186000, orders: 510 },
    { id: 'jayanagar', name: 'Jayanagar', sales: 144000, orders: 416 },
    { id: 'whitefield', name: 'Whitefield', sales: 112000, orders: 322 },
  ],
  columns: [
    { key: 'name', label: 'Café' },
    { key: 'sales', label: 'Sales', number: true, bar: true, format: format.inr },
    { key: 'orders', label: 'Orders', number: true },
  ],
  target: 450000,
  previousSales: 395000,
};

export default function WeeklyReport() {
  const [range, setRange] = React.useState('week');
  const shown = range === 'week' ? data.days : data.days.slice(-3);
  const sales = data.days.reduce((sum, day) => sum + day.sales, 0);
  const costs = data.days.reduce((sum, day) => sum + day.costs, 0);
  const orders = data.days.reduce((sum, day) => sum + day.orders, 0);
  return (
    <Page id="weekly-report">
      <Header id="report-heading" title="Alder & Ash: a stronger week"
        subtitle="Sample data · Sales rose 12% from last week, led by Saturday."
        actions={<Segmented id="chart-range" label="Sales chart range" items={data.ranges}
          value={range} onChange={setRange} />} />
      <Grid id="weekly-kpis">
        <Kpi id="weekly-sales" label="Weekly sales" value={sales} span={4}
          valueFormat={format.inr} delta={`Up ${format.percent(sales / data.previousSales - 1)}`}
          data={data.days.map(day => ({ label: day.label, value: day.sales }))} />
        <Kpi id="weekly-orders" label="Orders" value={orders} span={4}
          data={data.days.map(day => ({ label: day.label, value: day.orders }))} />
        <Kpi id="weekly-balance" label="Sales less costs" value={sales - costs} span={4}
          valueFormat={format.inr}
          data={data.days.map(day => ({ label: day.label, value: day.sales - day.costs }))} />
      </Grid>
      <Grid id="weekly-overview">
        <Card id="sales-chart-card" title="Sales and costs" span={8}>
          <Line id="sales-chart" label="Daily sales and costs" data={shown}
            series={data.series} valueFormat={format.inr} />
        </Card>
        <Card id="weekly-goal-card" title="Nearly there" span={4}>
          <Stack id="weekly-goal-details">
            <Progress id="weekly-goal" label="Weekly sales goal" value={sales} max={data.target} />
            <Badge id="weekly-status" tone="mint">Close to goal</Badge>
            <Callout id="weekly-gap" title="A small gap to close">
              {format.inr(data.target - sales)} short of the weekly goal. Keep coffee ready for Saturday.
            </Callout>
          </Stack>
        </Card>
      </Grid>
      <Grid id="weekly-breakdown">
        <Card id="daily-bars-card" title="Where the week grew" span={6}>
          <Bar id="daily-bars" label="Daily sales beside costs" data={data.days}
            series={data.series} valueFormat={format.inr} />
        </Card>
        <Card id="sales-mix-card" title="What sold" span={6}>
          <Donut id="sales-mix" label="Weekly sales by category" data={data.mix} valueFormat={format.inr} />
        </Card>
      </Grid>
      <Card id="store-table-card" title="Café rankings">
        <Table id="store-table" caption="Sample weekly sales by café" rows={data.stores} columns={data.columns} />
      </Card>
      <Callout id="weekly-next" title="Next week">
        Prepare extra coffee for Saturday. Review Whitefield's morning bakery range with the team.
      </Callout>
    </Page>
  );
}
```

### Plan with timeline

The checklist updates the task count and progress in this view.

```jsx
import React from 'react';
import {
  Page, Header, Grid, Kpi, Card, Stack, Progress,
  Timeline, Checklist, Stacked, Callout, format,
} from '@mainmind/kit';

const data = {
  budget: 180000,
  asOf: '2026-11-16T00:00:00+05:30',
  launch: '2026-11-30T00:00:00+05:30',
  milestones: [
    { id: 'menu', title: 'Choose the winter menu', date: '2026-11-16',
      description: 'Four bakes and two warm drinks.', status: 'Done' },
    { id: 'tasting', title: 'Team tasting', date: '2026-11-20',
      description: 'Check portions and allergens.', status: 'In progress' },
    { id: 'training', title: 'Practise the morning service', date: '2026-11-25',
      description: 'Try the new menu at all three cafés.', status: 'Planned' },
    { id: 'launch', title: 'Open the winter menu', date: '2026-11-30',
      description: 'Start with a small first batch.', status: 'Planned' },
  ],
  tasks: [
    { id: 'recipes', label: 'Write the recipes', checked: true },
    { id: 'prices', label: 'Check ingredient prices', checked: true },
    { id: 'allergens', label: 'Review the allergen cards', checked: false },
    { id: 'practice', label: 'Book the team practice', checked: false },
    { id: 'signs', label: 'Prepare the menu signs', checked: false },
  ],
  hours: [
    { label: '16 Nov', kitchen: 18, service: 8, design: 10 },
    { label: '20 Nov', kitchen: 24, service: 12, design: 8 },
    { label: '25 Nov', kitchen: 16, service: 24, design: 6 },
    { label: '30 Nov', kitchen: 12, service: 20, design: 2 },
  ],
  teams: [
    { key: 'kitchen', label: 'Kitchen', color: 'tangerine' },
    { key: 'service', label: 'Service', color: 'mint' },
    { key: 'design', label: 'Design', color: 'grape' },
  ],
};

export default function WinterMenuPlan() {
  const [tasks, setTasks] = React.useState(data.tasks);
  const done = tasks.filter(task => task.checked).length;
  const daysLeft = Math.ceil((new Date(data.launch) - new Date(data.asOf)) / 86400000);
  const updateTask = (id, checked) => setTasks(current =>
    current.map(task => task.id === id ? { ...task, checked } : task));
  return (
    <Page id="winter-plan">
      <Header id="plan-heading" title="Alder & Ash: winter menu"
        subtitle="Sample data · The menu is chosen; tasting is the next step." />
      <Grid id="plan-kpis">
        <Kpi id="plan-budget" label="Budget" value={data.budget} valueFormat={format.inr} />
        <Kpi id="plan-days" label="Days left" value={daysLeft}
          delta={`As of ${format.date(data.asOf)}`} />
        <Kpi id="plan-done" label="Tasks done" value={`${done} of ${tasks.length}`} />
      </Grid>
      <Card id="plan-progress-card" title="Ready for the next step">
        <Progress id="plan-progress" label="Preparation complete" value={done} max={tasks.length} />
      </Card>
      <Grid id="plan-effort-row">
        <Card id="team-hours-card" title="Time by team" span={8}>
          <Stacked id="team-hours" label="Sample planned hours by team and date"
            data={data.hours} series={data.teams} valueFormat={format.number} />
        </Card>
        <Card id="plan-focus-card" title="Before the tasting" span={4}>
          <Stack id="plan-focus">
            <Callout id="plan-tasting-note" title="Keep it small">
              Try each bake with the morning team. Record portion sizes before pricing the final menu.
            </Callout>
            <Callout id="plan-date-note" title="Launch date">
              Aim for {format.date(data.launch)}. Use the tasting to decide what needs another try.
            </Callout>
          </Stack>
        </Card>
      </Grid>
      <Grid id="plan-steps">
        <Card id="milestones-card" title="Milestones" span={6}>
          <Timeline id="plan-timeline" items={data.milestones} />
        </Card>
        <Card id="tasks-card" title="Preparation checklist" span={6}>
          <Checklist id="plan-checklist" items={tasks} onChange={updateTask} />
        </Card>
      </Grid>
      <Callout id="plan-risks" title="Watch the ingredient delivery">
        Confirm butter and cocoa before the tasting. If either is late, test the drinks first.
      </Callout>
    </Page>
  );
}
```

### Comparison

Choose an option to see its cost split. The table and bars keep both options
in view.

```jsx
import React from 'react';
import {
  Page, Header, Grid, Kpi, Card, Stack, Cluster, Segmented,
  Table, Bar, Donut, Badge, Callout, format,
} from '@mainmind/kit';

const data = {
  choices: [
    { value: 'refresh', label: 'Refresh the counter' },
    { value: 'expand', label: 'Add a second counter' },
  ],
  options: [
    { id: 'refresh', name: 'Refresh', cost: 300000, days: 4, extraOrders: 60,
      badge: 'Best value', tone: 'mint' },
    { id: 'expand', name: 'Second counter', cost: 480000, days: 9, extraOrders: 90,
      badge: 'More capacity', tone: 'sky' },
  ],
  columns: [
    { key: 'name', label: 'Option' },
    { key: 'cost', label: 'Setup cost', number: true, bar: true, format: format.inr, max: 480000 },
    { key: 'days', label: 'Days closed', number: true },
    { key: 'extraOrders', label: 'Extra orders/day', number: true, bar: true, max: 90 },
  ],
  costs: [
    { label: 'Equipment', refresh: 150000, expand: 240000 },
    { label: 'Fit-out', refresh: 90000, expand: 160000 },
    { label: 'Training', refresh: 60000, expand: 80000 },
  ],
  series: [
    { key: 'refresh', label: 'Refresh', color: 'mint' },
    { key: 'expand', label: 'Second counter', color: 'sky' },
  ],
  parts: [
    { label: 'Equipment', color: 'sky' },
    { label: 'Fit-out', color: 'tangerine' },
    { label: 'Training', color: 'grape' },
  ],
};

export default function CounterComparison() {
  const [choice, setChoice] = React.useState('refresh');
  const selected = data.options.find(option => option.id === choice);
  const split = data.costs.map((row, index) => ({ ...data.parts[index], value: row[choice] }));
  const saving = data.options[1].cost - data.options[0].cost;
  return (
    <Page id="counter-comparison">
      <Header id="comparison-heading" title="Alder & Ash: refresh first"
        subtitle="Sample estimates · Refreshing the counter cuts cost and days closed versus adding another."
        actions={<Segmented id="option-choice" label="Option details" items={data.choices}
          value={choice} onChange={setChoice} />} />
      <Grid id="comparison-kpis">
        <Kpi id="option-cost" label={`${selected.name}: setup`} value={selected.cost} valueFormat={format.inr} />
        <Kpi id="option-days" label="Days closed" value={selected.days} />
        <Kpi id="option-capacity" label="Estimated extra orders/day" value={selected.extraOrders} />
      </Grid>
      <Grid id="comparison-overview">
        <Card id="cost-bars-card" title="Costs beside each other" span={8}>
          <Bar id="cost-bars" label="Sample setup costs by option" data={data.costs}
            series={data.series} valueFormat={format.inr} />
        </Card>
        <Card id="option-notes-card" title="What each option gives you" span={4}>
          <Stack id="option-notes">
            {data.options.map(option => (
              <Cluster id={`option-${option.id}`} key={option.id}>
                {option.name}
                <Badge id={`badge-${option.id}`} tone={option.tone}>{option.badge}</Badge>
              </Cluster>
            ))}
            <Callout id="saving-note" title="Start with the smaller change">
              The refresh saves {format.inr(saving)}. Check morning queues before adding more capacity.
            </Callout>
          </Stack>
        </Card>
      </Grid>
      <Card id="options-table-card" title="Compare the trade-offs">
        <Table id="options-table" caption="Sample estimates for Indiranagar"
          rows={data.options} columns={data.columns} />
      </Card>
      <Grid id="selected-detail">
        <Card id="option-split-card" title={`${selected.name}: cost split`} span={8}>
          <Donut id="option-split" label="Parts of the selected setup cost"
            data={split} valueFormat={format.inr} />
        </Card>
        <Card id="assumptions-card" title="Before deciding" span={4}>
          <Callout id="estimate-note" title="Check these estimates">
            Ask for equipment quotes and time the morning queue. Extra orders depend on demand.
          </Callout>
        </Card>
      </Grid>
      <Callout id="comparison-recommendation" title="Choose the refresh">
        Spend less now and close for fewer days. Review demand after four weeks before adding another counter.
      </Callout>
    </Page>
  );
}
```

## Check it

The page compiles at save. Check it at 390px wide and in light and dark mode.
If your page shows an error card, read the line it names, fix it and push again.

Serving: JSX pages with the kit v1. Not yet: selecting a part to comment on, or live data inside pages.
