Milestone

import { Canvas, Controls, Meta, Title } from '@storybook/addon-docs/blocks';

import * as MilestoneStories from './Milestone.stories';

<Meta of={MilestoneStories} name='Usage' />

<Title />

## Purpose

One milestone in a sequence: a dot on a line, a title, a subtitle and a short body, on a card or flat.

## TL;DR: Chain of Thought, Timeline or Milestone List?

- **Chain of Thought:** an agent's reasoning under a reply, behind a summary line ("Thought for 17s") that opens on demand. No line, no rail.
- **Timeline:** events that happened or are happening, one line each (status icon, label, time). Always open, and the main content of a screen: a deploy history, an event log, an agent's run. Optional rail between the icons.
- **Milestone List:** steps people read in order, often still ahead of them, with a heading and a paragraph each on a card. One line runs down the whole list: the stages of an application process.

Quick test:

1. Do the steps sit under a reply and need to stay out of the way? **Chain of Thought.**
2. Otherwise, does each entry have a status icon or a time at the end of the row? **Timeline.**
3. Otherwise, does each have a heading and a paragraph? **Milestone List.**

A Chain of Thought is built from a Timeline and uses the same rows, and it can sit inside a Timeline as one entry in a log. Do not mix Timeline Items and Milestones in one list.

## Usage

Use it for steps over time that people read in order, for example the stages of an application process. If the entry is something that happened, with a status icon and a time at the end of the row (a deploy, a check, an agent's work), use Timeline Item instead; the Timeline page compares them.

- Put it in a Milestone List; that draws the line and places the dots.
- Set `isActive` on the milestone in focus, such as the current step: its dot takes the accent color with a ring and it gets `aria-current='step'`. The others are neutral.
- `subtitle` is the quiet line under the title in the secondary color: a date, a range, a stage or a short description. Pass it already formatted and translated; wrap a date in a `time` element if it needs a machine-readable value.
- Set `headingLevel` to fit the page's outline.
- The card is the default Panel. It follows the Milestone List: `variant` there is `card` (default) or `flat`, for text on the line, and a milestone can set `variant` itself to differ from the rest.

## Implementation

See the table below for the available props. The Milestone List page shows several milestones together.

<hr />

<Canvas of={MilestoneStories.Default} />
<Controls of={MilestoneStories.Default} />