PlanCard

Hero example

When to use

Reach for PlanCard when a tier_2 or tier_3 agent has decomposed a user request into ordered steps and the user is watching progress unfold ("File Delaware franchise tax: compute → generate AR → submit → archive"). The card is the canonical surface for agentic plan execution — each step represents a discrete operation, and completed advances as the agent finishes each one. Render the card inline in the composer reply; the wrapping agent thread shows live updates.

Don't reach for PlanCard when the items are independent (not ordered) — use a checklist inside FilingStatusCard for unordered compliance sub-items, or a generic list. Don't use it for finished plans either; an archived plan reads better as a Timeline of the events that happened.

Anatomy

Two structural regions:

1. Header. List icon + title (defaults to "Plan") + right-aligned {completed}/{total} progress in mono.
2. Ordered list (<ol>). One row per item. Each row has:
   • 16px circular indicator. Done items: filled --status-green with white ✓. Active item (i === completed): empty circle with a 5px filled inner dot in --fg. Pending items: empty circle with 1.4px --ink-18 border.
   • Item label. Done items have line-through decoration in --ink-28. Active and pending items render in --fg and --fg-muted respectively.

The <ol> carries no visible numbering — the indicator + ordering of children supplies it. Screen readers announce position via the ordered-list semantics.

Props

The completed prop is a 0-indexed cursor — completed: 0 means "no steps done yet, first step is active." completed: items.length means "all steps done, no active step."

States

The card surfaces three per-item states via the completed cursor:

The card-level "complete" state (every item done) is implicit when completed === items.length. Consumer is responsible for transitioning the card away (or rendering a follow-up surface) when this happens.

Density

In compact, item vertical padding drops from 7px to 4px. Indicator and font sizes stay constant.

Themes

Tokens consumed

Done-indicator fill reads --status-green. Active-indicator inner dot reads --fg. Pending border reads --ink-18. Done-label line-through reads --ink-28.

Accessibility

• Keyboard interactions. None — the card is non-interactive.
• ARIA roles and properties. The <ol> carries its native list semantics. Indicators are decorative spans (aria-hidden). The visible ✓ character on done items is text, so screen readers announce it.
• Focus order. N/A.
• Screen-reader expectations. Reading order: title, "{completed} of {total}", then each item in order. The ordered-list semantics implicitly announce "1.", "2.", etc.
• Reduced motion. No keyframes in steady state. If the consumer animates the completed cursor advancing, the motion contract requires the transition to collapse to opacity under reduced motion.
• Forced colors. Done fill maps to ButtonText; active inner dot to Highlight; pending border to ButtonBorder.
• WIG rules. <ol> over a <div> list (semantic-element rule). Color is not the sole differentiator — done items also carry line-through; active items carry the inner-dot pattern.

Do / Don't

Recipes

This card appears in:

• Docs corpus recipe — agent replies that propose multi-step compliance plans.
• Board recipe — pre-meeting agenda surfaced as a plan.

Code example

import { PlanCard } from "@matter/components";

export function PlanInline({ plan }: { plan: AgentPlan }) {
  return (
    <PlanCard
      title={plan.title}
      items={plan.steps.map((s) => s.label)}
      completed={plan.steps.filter((s) => s.state === "complete").length}
    />
  );
}

Source