AI Agent Standards
Standards for AI agent interactions in Sitka-powered products. Covers verbal response patterns, visual presentation, interaction models, and component behaviors.
Verbal Principles
Six principles guiding AI agent language and tone. These ensure responses feel appropriate to the product context and build user trust.
Concise by Default
Respond with the minimum text needed to convey the answer. Use bullet points, single sentences, or code blocks. Every word must earn its place in the interface.
Action-Oriented Language
Prefer verbs over nouns. Instead of 'The settings can be found in...' say 'Go to Settings → Account.' Guide users toward the next step, not just information.
Context-Aware Tone
Match the formality to the product. A developer tool uses direct technical language. A consumer app uses friendly, approachable phrasing. Never default to corporate speak.
Consistent Identity
If the agent has a name or personality established, maintain it across all interactions. Inconsistent tone fragments trust and makes the agent feel unreliable.
Transparent Process
Show thinking steps for complex tasks. 'Searching 3 files...' builds trust. 'Here's what I found' explains the work done. Hidden effort feels like magic, not competence.
Graceful Error Handling
When uncertain, say so clearly. Offer alternatives or ask clarifying questions. Never guess when precision matters — acknowledge the gap and bridge it.
Interaction Patterns
Standard interaction flows for common agent scenarios. Use these to maintain consistency across different agent implementations.
Loading States
- • Processing request
- • Searching knowledge
- • Generating response
Searching documentation... 3 results foundClarification Prompts
- • Ambiguous request
- • Multiple interpretations
- • Missing context
Did you mean create a new component or modify an existing one?Confirmation Flows
- • Destructive actions
- • Irreversible changes
- • External commits
This will modify 5 files. Proceed?Visual Standards
Formatting and presentation rules for agent responses in chat interfaces. Maintains visual consistency while preserving readability.
Response Structure
- • Lead with the answer, then explain if needed
- • Use markdown headers sparingly (h3 maximum in chat)
- • Code blocks for multi-line content, inline for single values
- • Max 3 levels of bullet indentation
Tone Markers
- • Emojis for emotional clarity only (✅ ❌ ⚠️)
- • Bold for emphasis, never italics
- • Monospace for file names, paths, commands
- • Italics for placeholder values like `your-api-key`
AI Component Categories
Components organized by purpose. Each category serves a distinct role in the AI interaction lifecycle from input to output.
Conversation
Core chat interface components for AI interactions
Reasoning
Components that expose AI thought processes
Generation
Components for AI-assisted content creation
Component States
Visual states for AI-driven components. Each state communicates the current status of the AI interaction lifecycle.
Idle
Ready to receive input. Show subtle accent ring or placeholder text.
border-[rgb(var(--border))] placeholder-[rgb(var(--text-tertiary))]Listening
Capturing voice or preparing to process. Animate pulse on microphone.
ring-2 ring-[rgb(var(--accent))] ring-opacity-50Processing
Analyzing input or querying knowledge. Show spinner or progress dots.
animate-pulse bg-[rgb(var(--surface-raised))]Streaming
Generating response token by token. Reveal text progressively.
cursor-blink after:content-['|']Error
Failed to process or understand. Use red-tinted surface with retry.
border-[rgb(var(--danger))] bg-[rgb(var(--danger-subtle))]