Foundation — Agentic Design Language
Agent Identity
Every agent action must be attributable. The agent identity system makes algorithmic authority legible at the point of action — not buried in an audit log. Identity signals answer three questions: who is acting, under what role, and with what authority?
Components: AgentIdentityBadge · RoleBadge · StatusDot · AgentCard · AvatarStack
Five-Tier Role Hierarchy
Roles define authority scope, not capability. A role badge is mandatory on every surface variant — it is the primary signal a user reads to understand what an agent can do to their data.
Directs and delegates. The highest authority tier — it owns the plan.
Only one orchestrator is visible per task context.
Carries out delegated tasks. Authority is scoped to the delegated action.
May appear multiple times — show all active executors.
Reviews and approves outputs before they proceed.
Always paired with a pending-approval state indicator.
Provides analysis and recommendations. Cannot initiate actions.
Never show an ADVISOR with agency red — it misrepresents authority.
Monitors without taking action. Audit-only presence.
Never show an OBSERVER with a StatusDot in active/running state.
Surface Variants — Live Preview
AgentIdentityBadge renders in three surfaces depending on context: inline (mention chip), card (compact panel), panel (full sidebar). Role selection below updates all three.
Inline
Card
Panel
Geometric Monogram System
The monogram is the avatar system for agents. It replaces human faces with a deliberate geometric treatment that signals "this is an algorithm with a defined role." The design rule is absolute: never render an agent with a human face avatar.
Anatomy
- Background: role-tier color at 12% opacity over --ds-surface-raised
- Monogram letter: initial of agent name, role-tier color, DISPLAY font, bold
- Shape: square (never circular — circles imply human social context)
- Size: 24px inline / 32px card / 48px panel
- Border: 1px solid role-tier color at 40% opacity
Token Reference
All agent identity components consume semantic tokens only. Never hardcode hex values in agent identity components — color semantics must survive theme changes.
| Token | Value | Meaning | Use in agent identity |
|---|---|---|---|
| --ds-color-agency | #D42020 | Agent exercising authority NOW | Active state indicator, ORCHESTRATOR role badge |
| --ds-color-temporal | #2B44D4 | Agent processing / in-flight | EXECUTOR role badge, streaming state dot |
| --ds-color-validation | #C49A1A | Elevated trust, requires human review | VALIDATOR role badge, approval-gated capabilities |
| --ds-text-primary | contrast 14:1 | Full-authority, no color tint | ADVISOR role badge (black treatment) |
| --ds-text-muted | contrast 4.83:1 | Passive, no current authority | OBSERVER role badge, idle capability chips |
| --ds-surface-raised | — | Card and panel surface | Card / panel container background |
| --ds-border-structure | — | Default structural border | Badge border, panel border |
Do / Don't
DO
Use the geometric monogram
The monogram is a deliberate departure from human faces. It signals 'this is an algorithm with a defined role' — not a person.
DON'T
Use a human face avatar for agents
Anthropomorphizing agent identity creates false trust calibration. Users treat human-faced agents as social actors with human judgment.
DO
Show role badge on every surface
The role badge is non-optional. Even on inline chips, the role letter (O/E/V/A/Ob) must be present.
DON'T
Collapse all agents to a single 'AI' label
ORCHESTRATOR and OBSERVER are different accountability tiers. A generic 'AI' label destroys the signal that makes multi-agent systems auditable.
DO
Reflect actual execution state in StatusDot
Only show an active/running StatusDot while the agent has the execution lock. Idle agents must show idle state.
DON'T
Show agency red on a dormant or observer agent
--ds-color-agency means 'this agent is exercising authority right now.' Painting a dormant agent red trains users to ignore the signal.
DO
Show capabilities additively
List what the agent CAN do. Never show a 'cannot' list — it creates confusion about scope and shifts focus to restrictions over function.
DON'T
Require hover to see the agent's role
Role is not metadata — it's the primary trust signal. If it's only visible on hover, it doesn't function as a trust signal.
Usage
import { AgentIdentityBadge } from "@/components/patterns/AgentIdentityBadge";
// Inline mention
<AgentIdentityBadge
name="Treasury Agent"
role="ORCHESTRATOR"
surface="inline"
state="active"
/>
// Card (default) — use in feed items, action logs
<AgentIdentityBadge
name="Treasury Agent"
role="EXECUTOR"
surface="card"
state="pending"
model="claude-opus-4.6"
capabilities={[
{ label: "read-ledger" },
{ label: "execute-trades", requiresApproval: true },
]}
/>
// Panel — use in sidebars, detail views
<AgentIdentityBadge
name="Treasury Agent"
role="VALIDATOR"
surface="panel"
state="idle"
lastActivityAt={new Date().toISOString()}
capabilities={[{ label: "approve-payments", requiresApproval: true }]}
/>Component API
AgentIdentityBadge prop reference. All props except name and role are optional.
| Prop | Type | Default | Description |
|---|---|---|---|
| name | string | — | Agent display name. Used to derive the monogram initial. |
| role | "ORCHESTRATOR" | "EXECUTOR" | "VALIDATOR" | "ADVISOR" | "OBSERVER" | — | Role tier determines the accent color: ORCHESTRATOR=agency red, EXECUTOR=temporal blue, VALIDATOR=gold, ADVISOR=black, OBSERVER=gray. |
| surface | "inline" | "card" | "panel" | "card" | Controls information density and layout. inline: monogram + name only. card: adds model and capabilities. panel: full detail with activity. |
| state | "active" | "pending" | "idle" | "error" | "offline" | "idle" | Current execution state. Drives the status dot color and timeout UI. |
| model | string | — | Model identifier shown on card/panel surfaces (e.g. 'claude-opus-4.6'). |
| capabilities | AgentCapability[] | — | Structured list of what this agent can do. requiresApproval flags trigger the gold validation indicator. |
| lastActivityAt | string | — | ISO timestamp of last recorded activity. Shown as relative time on card/panel. |
| timeoutAt | string | — | ISO timestamp when a timeout was detected. Triggers the timeout warning UI with elapsed time. |
| timeoutThresholdSecs | number | 30 | Seconds shown in timeout copy, e.g. 'no response · 45s'. |
| agentOnline | boolean | true | False renders a degraded offline state. Never hides agent identity — legibility is maintained. |
| action | ReactNode | — | Custom action rendered at the bottom of card and panel surfaces. |
| onClick | () => void | — | Click handler applied to the root element. |
| style | CSSProperties | — | Inline style overrides for the root element. |