Yugen UI

Trace

Trace shows execution step by step (an AI agent calling tools, a CI pipeline, a deployment) so people see what the system is doing and why.

Each TraceStep has a status (pending, running, success, error, skipped, cancelled) shown with an icon and text, a duration or a live timer, metadata badges, expandable details (logs, JSON, CodeBlock) and nested child steps. The header counts steps by status, shows the total time and has an expand / collapse all button. Status changes are announced through a polite live region.
Yugen Labs · experimentalThis component is outside SemVer: its API can change in a minor release, and What's new says so. Versioning policy

Agent: schedule a team meeting

Pending

  • Read the request, Pending

    A 60-minute meeting this week with all 4 people.

  • calendar.readparallel
  • Send the invite, Pending

Import

Install from npm, copy the source into your project with @yugen-ui/cli or the shadcn CLI, or import directly when working in this repo.

TSX
// npm install yugen-uiimport { Trace, TraceStep, TraceLog } from "yugen-ui";

Variants

Each tile is a standalone example: hover to copy, or press Code to see the source.

  • pending — Waiting, Pending
  • running — In progress, Running
  • success — Done, Completed
    1.2s
  • error — Failed, Failed
    320ms
  • skipped — Skipped, Skipped
  • cancelled — Cancelled, Canceled

Six statuses

The icon and token color come with a text label, so color is never the only signal. A running step starts its timer on its own.

Deploy sakura-web

Pending

Duration: 48.3s
  • Install dependencies, Completed
    12.4s
  • Run tests, Completed
    31.8s
    212 tests
  • 4.1s

    The bundle is over the 180 KB budget.

    ✖ dist/index.js  214.6 KB > 180 KB
  • Deploy preview, Skipped
  • Deploy to production, Canceled

Pipeline with an error

A failed step opens its details on its own; here the steps after it are set to skipped / cancelled.

Answer a returns question

Pending

Duration: 3.1s
  • 812ms
    tool3 results
    {  "query": "return policy",  "top_k": 3}
  • Write the answer, Completed
    2.3s
    1.2k tokens

Tool call with JSON

The details slot takes any content, here a JSON CodeBlock.

Usage

Do
  • Name steps with a short verb phrase that says what the system is doing (“Check calendars”, “Send invites”).
  • Open the details of a failed step by default and state the cause and the fix.
  • Give people actions in the header: Stop, Run again, View full log.
Don't
  • Don't dump the whole raw log into description. Put it in details, collapsed by default.
  • Don't nest more than 2 levels; group steps if the agent makes dozens of small calls.
  • Don't turn off announceChanges when Trace is the only place that reports progress.

Props

Prop · TypeDefaultDescription
Trace.title / descriptionReactNodeDefault: —Run title and secondary note.
Trace.statusTraceStatusDefault: —Overall status; derived from the steps by default.
Trace.duration / startedAtnumber (ms) / number (Date.now())Default: —Total duration once finished; start time for the live timer while running.
Trace.actionsReactNodeDefault: —Buttons in the header (Run again, Stop…).
Trace.appearance"outline" | "subtle"Default: "outline"Framed, or embedded in another surface.
Trace.size"small" | "medium"Default: "medium"16 / 20px icons, caption1 / body1 text.
Trace.hideHeader / announceChangesbooleanDefault: false / trueHides the header; announces status changes through a live region.
TraceStep.status"pending" | "running" | "success" | "error" | "skipped" | "cancelled"Default: "pending"Step status.
TraceStep.title / descriptionReactNodeDefault: —Step name (preferably a string, so it can be used in announcements) and description.
TraceStep.duration / startedAtnumberDefault: —Duration (ms) once finished; a running step records its own start time if startedAt isn't passed.
TraceStep.metadatastring[] | ReactNodeDefault: —Info badges: model, tokens, branch…
TraceStep.detailsReactNodeDefault: —Expandable content (TraceLog, CodeBlock…).
TraceStep.expanded / defaultExpanded / onExpandedChangebooleanDefault: —Controls the disclosure; open by default when running / error.
TraceStep.childrenTraceStepDefault: —Nested child steps, with a connecting line.
TraceLog.intent"neutral" | "error"Default: "neutral"Monospace log block, always LTR.

Messages

Text built into the component: labels, aria-labels, screen reader announcements.

English by default. Change it with the messages prop of YugenProvider, by the namespace below; messagesVi has the Vietnamese set. See Interface language.

messages.trace

Key · TypeDefault (English)messagesVi
pendingstring

Nhãn trạng thái — cùng tên với TraceStatus.

Default (English)"Pending"messagesVi"Đang chờ"
runningstringDefault (English)"Running"messagesVi"Đang chạy"
successstringDefault (English)"Completed"messagesVi"Hoàn tất"
errorstringDefault (English)"Failed"messagesVi"Lỗi"
skippedstringDefault (English)"Skipped"messagesVi"Bỏ qua"
cancelledstringDefault (English)"Canceled"messagesVi"Đã huỷ"
labelstring

Tên vùng khi không có title (và không truyền aria-label).

Default (English)"Progress"messagesVi"Tiến trình"
steps(done: number, total: number) => string

Tiến độ ở phần đầu: số bước đã xong / tổng số bước.

Default (English)(done, total) => `${done}/${total} ${total === 1 ? "step" : "steps"}`messagesVi(done, total) => `${done}/${total} bước`
summarystring

Tên danh sách tổng kết theo trạng thái.

Default (English)"Summary by status"messagesVi"Tổng kết theo trạng thái"
durationstring

Chữ ẩn trước thời lượng, cho trình đọc màn hình.

Default (English)"Duration:"messagesVi"Thời lượng:"
collapseAllstringDefault (English)"Collapse all"messagesVi"Thu gọn tất cả"
expandAllstringDefault (English)"Expand all"messagesVi"Mở rộng tất cả"