Agentic Design Language

Show agent identity at point of action, not on demand.

Burying agent attribution in an audit log fails the moment of consequence. The user should see who is acting in the same viewport where the action occurs.

Use --ds-color-agency (red) for active agent states only.

Agency red is a semantic token meaning 'an AI is currently exercising authority here.' Using it decoratively destroys its signal value.

Distinguish agent roles visually: orchestrator, executor, observer.

A multi-agent system has a hierarchy. Orchestrators delegate; executors act; observers audit. Collapsing them into a single 'AI' label loses critical accountability information.

Never show an agent as always-on. Reflect actual execution state.

A spinning indicator on a dormant agent creates false urgency and erodes trust. StatusDot must reflect real-time state.

Every synthesized output must link to at least one source.

Synthesis without citation is assertion. Users cannot evaluate, correct, or act responsibly on information they cannot trace.

Show data freshness inline, not in a tooltip.

If data is 3 hours old in a fast-moving market, that information is decision-critical. Hiding it behind a hover interaction means most users never see it.

Distinguish retrieval confidence from model confidence.

A model may be very confident in its reasoning about uncertain data. These are different claims and require separate signals.

Use --ds-color-validation (gold) for verification and quality signals.

Gold means 'this has been checked, enriched, or validated.' It is the semantic token for epistemic status.

Render handoff events as explicit state transitions, not silent background actions.

When Agent A delegates to Agent B, that transition has implications for accountability, latency, and cost. It should be observable.

Show the delegation graph when more than two agents are involved.

Linear timelines break down at 3+ agents. A graph makes orchestration topology immediately legible.

Display agent-to-agent communication as first-class events.

An internal API call between agents is no different from a human decision-point in terms of accountability. Both should appear in the audit trail.

Label each agent's scope boundary. What was it allowed to access?

Permission scope is not just a security concern — it is the primary variable a user needs to evaluate how much to trust each agent's output.

Show consequence disclosure before, not after, the approval action.

An irreversible action that reveals its consequences only in a post-confirmation screen is a dark pattern regardless of intent.

Name the requesting agent explicitly in every approval prompt.

Approving 'access to your calendar' is meaningless without knowing which agent is requesting it and why.

Calibrate friction to reversibility. Irreversible actions require more ceremony.

A 'send email' confirmation and a 'delete all records' confirmation should not look identical. The visual weight of the interaction signals the weight of the decision.

Provide a 'why this now' explanation in the approval context.

An approval request with no explanation of why the agent needs this permission at this moment will be declined or rubber-stamped. Neither outcome serves the user.

Never auto-approve. Even low-stakes approvals must have a human moment.

The approval ceremony is also a system health check. Auto-approvals erode the human's capacity to notice when the ceremony becomes inappropriate.

Make the blocked-waiting state visually distinct from active-processing.

An agent waiting for human approval looks identical to an agent running if both show a spinner. The user cannot tell if they need to act.

Show exactly what human input is required. Not a general 'review needed.'

Vague review requests create decision paralysis. 'Approve the email draft' is actionable. 'AI needs your attention' is not.

Provide a correction path at every AI output, not just error states.

The ability to correct is not just for failures. A user should be able to redirect, refine, or reject any AI output, even a technically correct one.

After human action, confirm the AI has received it and is proceeding.

A human who approves an action and sees no visible response cannot tell if their input was registered. Explicit acknowledgment closes the feedback loop.

Distinguish streaming from loading. Use StreamingDot for token generation, Skeleton for layout reservation.

A skeleton implies a known shape will arrive. Streaming implies content is being generated in real time. These are different temporal experiences and require different signals.

Show reasoning traces when the model is thinking, not just when it responds.

Chain-of-thought reasoning is computation the user paid for. Making it visible improves calibration and builds appropriate trust in the output.

Display token cost and context window consumption inline for power users.

Context window limits and token costs are first-class constraints in LLM workflows. Hiding them produces surprise failures and unexpected bills.

Represent retry and failure states distinctly from initial loading.

A second attempt is semantically different from a first attempt. The RetryLedger pattern exists to make this distinction visible without causing alarm.

Never fake streaming with setTimeout reveals. Reveal content as it arrives.

Simulated streaming is deceptive. It delays the user's ability to act on partial output and misrepresents the model's actual generation pattern.

Map confidence scores to visual weight, not just color.

Users with color vision deficiencies cannot read a confidence heatmap. Use size, opacity, and layout density as primary uncertainty signals.

Distinguish types of uncertainty: retrieval uncertainty, model uncertainty, and data uncertainty.

'I couldn't find a source' is different from 'my training suggests this but I'm not sure' which is different from 'the source data itself is ambiguous.' Each requires a different response from the user.

Show alternatives when confidence is below threshold.

A low-confidence single answer is worse than presenting three plausible alternatives. Let the user choose rather than defaulting to the model's best guess.

Never suppress low-confidence outputs without surfacing the uncertainty.

Filtering out uncertain outputs creates a false impression of high-confidence results. Show the uncertainty; let the user decide what to do with it.