Brief format

A brief comes in two forms with the same content: Markdown for pasting into any agent, and JSON (pointbrief/brief@1) for tools. The JSON Schema describes every field; an example is built from the same code as the toolbar on every deploy.

The Markdown

# UI feedback brief

Recorded on http://localhost:5173/, viewport 1440x900. 5 change items, 1 marked high priority.

How to read this: …

## 1. [HIGH] "make this button bigger it's way too small"
- Priority: high (said "way too")
- Likely kind of change: style
- Target, pointed at: `button#start-trial` "Start free trial" (button)
  - selector: `#start-trial`
  - component: `Hero` in `src/components/Hero.tsx:18` (inside App > Landing)
  - now: font-size 12px · font-weight 500 · color rgb(124, 134, 173) · …
  - where: / at x=664 y=318, 112x27px

Each item is one thought: what the reviewer said or typed, and what they pointed at while saying it. When one sentence covers several elements, markers in the words show which part goes with which target: make this [1] bigger and this [2] blue.

Top level

FieldMeaning
schemaAlways pointbrief/brief@1 for this version
idpb_<date>_<time>_<random>, unique per recording
createdAtWhen the recording ended (ISO 8601)
apporigin, title, page (path where it started), viewport {w, h}, framework (detected, e.g. react)
summaryitems, high (how many are high priority), seconds (length), voice (speech-local, speech-cloud, typed, none)
itemsThe change list (below)
trailPages visited and elements clicked, with times, for context
tool{ name: "pointbrief", version }

Items

FieldMeaning
nItem number, from 1
saidThe reviewer's words (speech or typed note); empty for a silent mark
saidMarkedThe same words with [1], [2] markers, when there are several targets
sourcespeech, typed, or gesture (a mark with no words)
t[start, end] in seconds from the start of the recording
pagePath the item refers to
priorityhigh or normal
whyWhy it's high: said "really", circled twice, repeated "no", …
hintsLikely kinds of change, guessed from the words and gestures: style, copy, remove, move, add, bug
targetsThe elements (below); empty for a general comment
restingFor a general comment: an element the pointer was parked on, which may or may not be the subject

Targets

FieldMeaning
nTarget number within the item, matching the [n] markers
roletarget, or from / to for an arrow
gesture, gestureKind, gestureCountHow it was referenced: pointed at (hover), clicked, tapped, marked (pin), circled, underlined, struck through, crossed out, scribbled over, drew an arrow
tag, id, classesThe element itself
selectorA short CSS selector that matched only this element when it was recorded
textVisible text, trimmed to 100 characters; empty for form fields and private elements
nameAccessible name (aria-label, alt, placeholder or label) when different from the text
ariaRoleExplicit or implicit role (button, link, heading 1, …)
attrsA few useful attributes: href, src, type, name, alt, aria-label, data-testid, … (never value)
rectPosition and size in page pixels
stylesThe computed styles that matter for feedback: font size and weight, colours, padding, margin, radius, display, alignment, gap
componentWhen the dev build exposes it: framework, name, chain (owners, outermost first), file, line
shadowHostSelector of the shadow host, when the element is inside a shadow root
privatetrue when its text was left out (data-pointbrief-private or a password field)

Compatibility

Fields may be added within brief@1; tools should ignore fields they don't know. A change that removes or redefines a field gets a new schema version.