Agent-facing rendering
Density, text state, identifiers, stable selectors, and determinism.
Rule
The primary user of every surface is an AI agent. A browser rendering must let an agent with no prior context discover what exists, learn the rules, act idempotently, verify the result, and leave enough provenance for the next session.
- Density is correctness. Decorative chrome spends context without adding state.
- State is written text. Colour, position, and animation may reinforce it but never own its meaning.
- Identifiers, cursors, versions, sequence numbers, and timestamps are mono, selectable, copyable, and recoverable in full.
- Every interactive element carries a stable
data-testidnamed for its purpose. - The same state renders the same way.
- No required information exists only on hover, after animation, or inside a collapsed region.
- Errors expose machine code, retryability, and legal next action.
Token contract
Machine truth uses typography.data-md and typography.code. Compact interface copy
uses typography.ui-sm or typography.ui-md. State consumes the relevant
components.badge-* recipe with a written label. Dense regions use spacing.xs and
spacing.sm, while grouping still uses spacing.lg for hierarchy.
Correct example
A Task row renders tsk_01JAV, “in review,” version, lease expiry, last event sequence,
and the legal next transition as visible text. Its actions expose stable selectors such
as task-row-open and task-row-status. Re-rendering the same Task preserves the same
order and labels.
Rejected example
A Task row truncates its id, expresses status as a pulsing dot, reveals lease details
only on hover, and identifies its action as row-3-button. An agent must infer state,
cannot cite the record, and receives an unstable selector.
Agent experience check
Before review, start with no context and answer from the rendered page alone: What records exist? What state is each in? Which identifier names it? What can happen next? How do I know the last action succeeded? If any answer requires guessing or external documentation, the browser contract is incomplete.
Reasoning
Read the agent persona, the agent-facing pattern rules, and the Agent Experience specification.