Trace
What an agent or a job did, step by step, each a quiet line that opens its detail.
On this page
A trace shows what an agent or a job did, step by step: what it thought, searched, read and ran. Each step is one quiet line with a marker on a column, and a hairline joins the markers. A step with something behind it is a native <details>, so its line opens the detail with no script; a step with nothing behind it is a plain line.
Trace
<div class="card max-w(440) mx-auto"> <div class="trace"> <details class="trace-step"> <summary class="trace-summary"> <span class="trace-marker"></span>Thought about the migration <span class="trace-meta">8s</span> </summary> <div class="trace-detail">The table has two million rows, so the column is added as nullable first and filled in batches.</div> </details> <details class="trace-step" open> <summary class="trace-summary"> <span class="trace-marker"></span>Searched the codebase <span class="trace-meta">12 files</span> </summary> <div class="trace-detail"><code class="code">orders.status</code> is read in 12 files, 3 of them in the billing service.</div> </details> <div class="trace-step"> <p class="trace-summary"> <span class="trace-marker"></span>Read schema.prisma <span class="trace-meta">0.4s</span> </p> </div> <div class="trace-step" aria-busy="true"> <p class="trace-summary"> <span class="trace-marker"></span>Writing the migration</p> </div> </div></div>#A step
A step is a trace-step around a trace-summary: the marker, the words, and an optional trace-meta at the end of the line for a fact in figures, such as how long it took or how many it found.
When the step has a detail, write it as a <details> with the line on its <summary> and the detail in trace-detail after it. The stylesheet sees the detail and turns the line into a toggle: a small chevron follows the words and points down while the step is open. The detail opens to its own height where the browser can transition ::details-content, and at once elsewhere. Find-in-page opens a closed step that holds a match, as it does for any <details>.
#Markers
An empty trace-marker is a small dot. A marker may hold an icon instead, to say what kind of step it was, or a spinner with spinner-inline while the step runs.
Markers
<div class="card max-w(440) mx-auto"> <div class="trace"> <div class="trace-step"> <p class="trace-summary"> <span class="trace-marker"> <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"> <circle cx="11" cy="11" r="6" /> <path d="m20 20-4.5-4.5" /> </svg> </span>Searched for "rate limit" <span class="trace-meta">4 results</span> </p> </div> <div class="trace-step"> <p class="trace-summary"> <span class="trace-marker"> <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"> <path d="M7 4h7l4 4v12H7zM14 4v4h4" /> </svg> </span>Read limits.ts <span class="trace-meta">214 lines</span> </p> </div> <div class="trace-step"> <p class="trace-summary"> <span class="trace-marker"> <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"> <path d="m5 8 4 4-4 4M12 17h7" /> </svg> </span>Ran the tests <span class="trace-meta">48 passed</span> </p> </div> <div class="trace-step" aria-busy="true"> <p class="trace-summary"> <span class="trace-marker"> <span class="spinner spinner-inline"></span> </span>Writing the answer</p> </div> </div></div>#Running and failed
The step under way carries aria-busy="true": its words take the strong ink and a bare dot sends out a ring, which rests as a still halo for a reader who asks for reduced motion. Remove the attribute when the step ends.
A step that failed is trace-failed: its marker and the fact at the end of its line take the danger ink. It is a class because ARIA has no word for a failed item of a list. Say what failed in words, in the line or behind it, so the color is never the only sign.
Failed
<div class="card max-w(440) mx-auto"> <div class="trace"> <div class="trace-step"> <p class="trace-summary"> <span class="trace-marker"></span>Installed dependencies <span class="trace-meta">14s</span> </p> </div> <div class="trace-step"> <p class="trace-summary"> <span class="trace-marker"></span>Compiled 38 routes <span class="trace-meta">48s</span> </p> </div> <details class="trace-step trace-failed" open> <summary class="trace-summary"> <span class="trace-marker"></span>Ran the test suite <span class="trace-meta">2 failed</span> </summary> <div class="trace-detail">orders.spec.ts expected the status to be "paid" and received "pending", twice.</div> </details> </div></div>#One line
A trace of one step is the line an assistant shows above its answer: what it did, and how long it took, with the reasoning behind it.
One step
<div class="trace max-w(440) mx-auto"> <details class="trace-step"> <summary class="trace-summary"> <span class="trace-marker"></span>Thought for 12 seconds</summary> <div class="trace-detail">The question is about the fallback, not the feature, so the answer starts from a browser without anchor positioning.</div> </details></div>#Trace, timeline or steps
A trace is work: its steps may be running, may have failed, and open to show what stands behind them. A timeline is a record of events with their times. Steps are a fixed sequence a reader moves through.
#Accessibility
- A step that opens is a
<details>: the browser gives its line the role, the state and the keys of a disclosure. - The marker is drawn by the stylesheet and is not announced. An icon in it is decoration: say what the step was in the line.
- A trace that grows while it is on screen should sit in a region with
aria-live="polite", so each new step is announced once it is added.aria-busyon the running step marks it for assistive technology as well as for the eye. - On a touch screen every line is 44px tall.
#Classes
| Class | Description |
|---|---|
trace | The steps, in a column; a hairline joins their markers |
trace-step | One step, on a details element when it has a detail and on any block when it has none |
trace-failed | A step that failed: its dot or icon and the fact at the end of its line take the danger ink. With trace-step |
trace-summary | The step's line, 32px tall: the marker, the words and a fact at the end. On a summary it is the toggle, with a chevron after the words |
trace-marker | The marker at the start of the line: a dot when empty, or an icon, or a spinner-inline while the step runs |
trace-meta | A fact at the end of the line, in tabular figures: how long it took, how many it found |
trace-detail | What stands behind the step, under the line on the edge of its words |
#Custom properties
| Property | Default | Description |
|---|---|---|
--trace-marker | 1.25rem | Width of the marker column |