For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Plan

Stream an agent plan as a collapsible list of steps with done, running, and pending status.

Migrate the dialog components to Base UI.
Install @base-ui/reactReplace the Radix importsRename asChild to renderRun the type checker

Migrated Dialog and AlertDialog. The type checker passes.

plan-demo.tsx
"use client";

import { useChat } from "@ai-sdk/react";
import type { UIMessage } from "ai";
import {
  CircleCheckIcon,
  CircleDotIcon,
  CircleIcon,
  RouteIcon,
} from "lucide-react";
import { Button } from "@/components/ui/button";
import {
  Bubble,
  BubbleContent,
  Message,
  MessageContent,
} from "@/components/ui/message";
import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceDescription,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";

type ChatMessage = UIMessage<
  unknown,
  {
    plan: {
      title: string;
      steps: { title: string; status: "done" | "running" | "pending" }[];
    };
  }
>;

type PlanPart = Extract<ChatMessage["parts"][number], { type: "data-plan" }>;

const STEPS = [
  "Install @base-ui/react",
  "Replace the Radix imports",
  "Rename asChild to render",
  "Run the type checker",
];

function planAt(current: number) {
  return {
    steps: STEPS.map((title, index) => ({
      status:
        index < current ? "done" : index === current ? "running" : "pending",
      title,
    })),
    title: "Plan: migrate to Base UI",
  } satisfies PlanPart["data"];
}

const chat = createChat<ChatMessage>()
  .user("Migrate the dialog components to Base UI.")
  .assistant(({ writer }) => {
    STEPS.forEach((_, index) => {
      writer
        .data({ data: planAt(index), id: "plan", type: "data-plan" })
        .sleep(1200);
    });
    writer.data({ data: planAt(STEPS.length), id: "plan", type: "data-plan" });
    writer.text("Migrated Dialog and AlertDialog. The type checker passes.");
  });

const transcript = chat.get();
const question = chat.get(0)[0];
const transport = chat.transport({ delayMs: 20 });

function PlanRow({
  plan,
  streaming,
}: {
  plan: PlanPart["data"];
  streaming: boolean;
}) {
  const done = plan.steps.filter((step) => step.status === "done").length;
  const running = streaming && done < plan.steps.length;

  return (
    <TraceCollapsible defaultOpen>
      <TraceCollapsibleTrigger>
        <TraceLine status={running ? "running" : undefined}>
          <TraceIcon>
            <RouteIcon />
          </TraceIcon>
          <TraceTitle>{plan.title}</TraceTitle>
          <TraceDescription>
            {done} of {plan.steps.length} done
          </TraceDescription>
        </TraceLine>
      </TraceCollapsibleTrigger>
      <TraceCollapsibleContent>
        <Trace>
          {plan.steps.map((step) => (
            <TraceLine
              key={step.title}
              status={
                step.status === "pending"
                  ? "pending"
                  : streaming && step.status === "running"
                    ? "running"
                    : undefined
              }
            >
              <TraceIcon>
                {step.status === "done" ? (
                  <CircleCheckIcon />
                ) : step.status === "running" ? (
                  <CircleDotIcon />
                ) : (
                  <CircleIcon />
                )}
              </TraceIcon>
              <TraceTitle>{step.title}</TraceTitle>
            </TraceLine>
          ))}
        </Trace>
      </TraceCollapsibleContent>
    </TraceCollapsible>
  );
}

export function PlanDemo() {
  const { messages, sendMessage, setMessages, status } = useChat<ChatMessage>({
    messages: transcript,
    transport,
  });
  const busy = status === "submitted" || status === "streaming";

  return (
    <div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
      {messages.map((message) => {
        if (message.role === "user") {
          return (
            <Message align="end" key={message.id}>
              <MessageContent>
                <Bubble align="end" variant="muted">
                  <BubbleContent>{getMessageText(message)}</BubbleContent>
                </Bubble>
              </MessageContent>
            </Message>
          );
        }

        const streaming = busy && message === messages.at(-1);
        const plan = message.parts.find((part) => part.type === "data-plan");
        const text = getMessageText(message);

        return (
          <Message key={message.id}>
            <MessageContent className="gap-4">
              {plan && (
                <Trace>
                  <PlanRow plan={plan.data} streaming={streaming} />
                </Trace>
              )}
              {text && <p>{text}</p>}
            </MessageContent>
          </Message>
        );
      })}
      {!busy && (
        <Button
          className="mt-auto self-start"
          onClick={() => {
            setMessages([]);
            sendMessage(question);
          }}
          size="sm"
          variant="outline"
        >
          Replay
        </Button>
      )}
    </div>
  );
}

Plan renders an agent plan as a collapsible step list. Each step carries a status of done, running, or pending, and the header shows how many are finished. The whole block collapses to a single line.

Plan is a composition, not a primitive. It composes Trace lines inside a collapsible and drives streaming status through a chat transport.

Installation

Usage

plan.tsx
import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceDescription,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from "@/components/ui/trace";
import { RouteIcon, CircleCheckIcon, CircleDotIcon, CircleIcon } from "lucide-react";
plan.tsx
<Trace>
  <TraceCollapsible defaultOpen>
    <TraceCollapsibleTrigger>
      <TraceLine status={running ? "running" : undefined}>
        <TraceIcon>
          <RouteIcon />
        </TraceIcon>
        <TraceTitle>Plan: migrate to Base UI</TraceTitle>
        <TraceDescription>1 of 4 done</TraceDescription>
      </TraceLine>
    </TraceCollapsibleTrigger>
    <TraceCollapsibleContent>
      <Trace>
        <TraceLine status="pending">
          <TraceIcon>
            <CircleIcon />
          </TraceIcon>
          <TraceTitle>Replace the Radix imports</TraceTitle>
        </TraceLine>
      </Trace>
    </TraceCollapsibleContent>
  </TraceCollapsible>
</Trace>

Anatomy

plan.tsx
<Trace>
  <TraceCollapsible>
    <TraceCollapsibleTrigger>
      <TraceLine>
        <TraceIcon />
        <TraceTitle />
        <TraceDescription />
      </TraceLine>
    </TraceCollapsibleTrigger>
    <TraceCollapsibleContent>
      <Trace>
        <TraceLine>
          <TraceIcon />
          <TraceTitle />
        </TraceLine>
      </Trace>
    </TraceCollapsibleContent>
  </TraceCollapsible>
</Trace>
  • Trace — outer wrapper, flex column
  • TraceCollapsibleTrigger — header row with route icon, title, and progress count
  • TraceCollapsibleContent — nested Trace with one TraceLine per step
  • TraceLine — a single step row, accepts status
  • TraceIcon — icon slot, swaps between check, running, and pending glyphs

Status

Each step carries a status. The header shows how many are done.

StatusEffect
runningForeground color, shimmer on title
pending60% opacity

Static plan

Render a fixed plan without a chat transport for a read-only summary.

Store the theme in a cookie so the server renders the right one and the page does not flash on load.

Add a dark variant to the theme tokensRead the theme from a cookie on the serverAdd a toggle to the settings pageCheck contrast on the charts
plan-description.tsx
import { CircleCheckIcon, CircleIcon, RouteIcon } from "lucide-react";

import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceDescription,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from "@/components/ui/trace";

const steps = [
  "Add a dark variant to the theme tokens",
  "Read the theme from a cookie on the server",
  "Add a toggle to the settings page",
  "Check contrast on the charts",
];

export function PlanDescription() {
  return (
    <Trace className="max-w-sm">
      <TraceCollapsible defaultOpen>
        <TraceCollapsibleTrigger>
          <TraceLine>
            <TraceIcon>
              <RouteIcon />
            </TraceIcon>
            <TraceTitle>Plan: add dark mode</TraceTitle>
            <TraceDescription>1 of {steps.length} done</TraceDescription>
          </TraceLine>
        </TraceCollapsibleTrigger>
        <TraceCollapsibleContent className="flex flex-col gap-3">
          <p>
            Store the theme in a cookie so the server renders the right one and
            the page does not flash on load.
          </p>
          <Trace>
            {steps.map((step, index) => (
              <TraceLine key={step} status={index > 0 ? "pending" : undefined}>
                <TraceIcon>
                  {index === 0 ? <CircleCheckIcon /> : <CircleIcon />}
                </TraceIcon>
                <TraceTitle>{step}</TraceTitle>
              </TraceLine>
            ))}
          </Trace>
        </TraceCollapsibleContent>
      </TraceCollapsible>
    </Trace>
  );
}

Streaming

The demo streams data-plan parts through a chat transport. Each tick replaces the plan with a new snapshot where one more step is done and the next is running. The header count updates and the shimmers settle on the current step.

Accessibility

  • Use TraceTitle as the accessible name. Write titles as verb-first sentences.
  • Status is conveyed by icon glyph and color. Do not rely on color alone.
  • The collapsible trigger is keyboard-focusable and toggles with Enter or Space.
  • prefers-reduced-motion disables shimmer and collapse animation.

Best Practices

  • Stream status, not text. Update data-plan snapshots instead of mutating the transcript.
  • Keep titles short. One step is one sentence, no sub-clauses.
  • Collapse by default for long runs. More than six steps crowds the surface.
  • Pair with a terminal message. The plan is not the answer. Close the turn with text.