# Plan Summary

A plan on one card before it runs: goal, steps, time, cost, tools and phases.

- Category: AI & Agents
- Page: https://wunderui.com/components/plan-summary
- Tier: Core and Pro

## Install

Plan Summary ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { PlanSummary, PlanSummaryPhase, PlanSummaryStat } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { PlanSummary } from "@wunderui/react"

export function Summary({ onRun }: { onRun: () => void }) {
  return (
    <PlanSummary
      goal="Ship the Tabs v2 release"
      stats={[
        { label: "Steps", value: "7" },
        { label: "Est. time", value: "18 min" },
        { label: "Est. cost", value: "$0.42" },
      ]}
      onRun={onRun}
    />
  )
}
```

Expected result: You should see a card with the title Ship the Tabs v2 release, three figures under it (7, 18 min and $0.42) and a Run plan button.

## When to use

### Use Plan Summary for

- The plan on one card before anything runs, with the estimate, the tools and the phases
- A go or no-go step where a person can still edit the plan
- A short status of a run in a few numbers, with the buttons that fit that state

### Use something else

- [Agent Plan](https://wunderui.com/components/agent-plan) for the steps of the plan, to edit them before the run or to follow them during it
- [Approval Card](https://wunderui.com/components/approval-card) for a gate in the middle of a run that a person has to answer
- [Usage Meter](https://wunderui.com/components/usage-meter) for what a run has spent against its budget, as a meter

## Keyboard

The two buttons are native buttons, so the browser provides focus and activation. There are no other controls.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous button: Edit plan, then Run plan. A button that is not drawn is not in the order. Focus shows as an indigo border with a 2 px ring. |
| `Enter` or `Space` | Presses the focused button and calls `onEdit` or `onRun`. |

## Behavior

What the card names, which parts it draws, and what it leaves to you.

- **Name:** The card is a section named by its goal. The goal is a paragraph, not a heading, so add your own heading above the card where one belongs.
- **Lists:** Stats are a definition list, tools an unordered list and phases an ordered list, so a screen reader announces each label and the number of items.
- **What is drawn:** Stats, tools and phases appear only when they have items, and Edit plan and Run plan only with their handlers. The buttons have no disabled state, so leave the handler out instead.
- **Numbers:** The card does not format numbers, so pass strings with the unit and English separators. A numeric step count in a phase reads 1 step or n steps; other values show as written.
- **Progress:** The card has no progress bar and no live region. Write progress into the stats and phase counts, and announce changes in a status line next to the card.
- **Motion:** The card has no motion of its own. The buttons only change colour when pressed, so there is nothing to reduce.

## Anatomy

- `PlanSummary`: A card named by its goal, with a 1 px border, a 16 px radius, 16 px padding and 16 px between its parts.
- `Goal`: The goal in 17 px semibold text. It is a paragraph, not a heading, and names the card for assistive technology.
- `Description`: Optional description in 13 px tertiary text under the goal, such as where the plan came from.
- `Stats`: Label and value pairs, with 12 px labels over 20 px semibold values in tabular figures. The pairs wrap onto a new line when the card is narrow.
- `Tools`: The tools as indigo pills in a list under the label Tools.
- `Phases`: An ordered list under the label Phases: title on the left, count on the right. A number reads 1 step or n steps; text is shown as given.
- `Actions`: Edit plan as a plain button and Run plan as the primary one, in that order. Each appears only when its handler is passed.

## Best practices

### When to use

- Use a Plan Summary to ask for a go before a run, or to show where a run stands in a few numbers. For the steps use Agent Plan or Plan Step; for a gate mid-run use Approval Card.

### Do

- Put the unit in the value and use English number formats, such as 18 min, $0.42 and 1,842,000. Time and cost are what people decide on.
- Say where the plan came from in the description, and list every tool it will touch. A plan that hides a tool hides what it may change.
- Pass the run handler only when the plan may start. Without it the Run plan button is not drawn, and a running or finished plan passes neither handler.
- Change the run label to what the button does now, such as Resume or Retry failed step.
- Say what happened in a status line next to the card. The card is not a live region.

### Don't

- Don't start the run before Run plan is pressed. A plan that starts itself is a pre-approved plan.
- Don't use the stats as a progress bar, since the card has none. Write progress as a stat such as 3 of 7, or put a Progress next to the card.

## API reference

### PlanSummary

| Prop | Type | Default | Description |
|---|---|---|---|
| goal* | React.ReactNode |  | What the plan is for. It is the title of the card and names it for assistive technology. |
| className | string |  | Extra classes for the card, for example a width. |
| description | React.ReactNode |  | Where the plan came from or where the run stands, such as `Drafted 3 min ago from the release notes`. |
| editLabel | string | "Edit plan" | The words on the edit button. Defaults to Edit plan. |
| onEdit | () => void |  | Draws the Edit plan button and is called when it is pressed. Leave it out to hide the button. |
| onRun | () => void |  | Draws the Run plan button and is called when it is pressed. Leave it out to hide the button. |
| phases | PlanSummaryPhase[] | [] | How the work splits up, `{ title, steps }`. A number for `steps` reads `1 step` or `n steps`; text such as `1 of 3` or `Done` is shown as written. |
| runLabel | string | "Run plan" | The words on the run button, such as Resume or Retry failed step. Defaults to Run plan. |
| stats | PlanSummaryStat[] | [] | Label and value pairs, `{ label, value }`, usually Steps, Est. time and Est. cost. The value is a node you format, with its unit. |
| tools | string[] | [] | The names of the tools the plan will use, as strings. They are drawn as indigo pills. |

## Examples

### Contents: the goal, stats, tools, phases

### Stats: an estimate, progress, a result, large numbers

### Actions: edit and run, run only, own labels, none

## In context

### Run: the summary follows the plan

Press Run plan. The stats count up, each phase shows how far it is, and a status line announces each step; a failure offers Retry failed step and Edit plan, and the demo runs fast-forward.

### Conversation: the agent proposes the plan

The plan sits under the message that proposes it. Nothing starts until Run plan is pressed, and the message then says the run has started.

## For AI agents

`get_component("plan-summary")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
