# AI conversation and agent activity

North brand guidelines for AI agents · https://identity.north.ae/AGENTS/ai · Updated 2026-10-14
Use when: Designing chat, composer, agent status, reasoning, plans, tool calls, approvals, artifacts or thinking orbs in North AI products (Mai, NorthStar).
Rules that always apply: https://identity.north.ae/AGENTS

## Principles
- Show the work in proportion (reasoning, sources, tool calls one click away, collapsed by default). Say which model answered and where it ran (on-premises / approved cloud). Cite exact sources. Ask before acting. Everything recoverable: stop, edit, retry, branch.

## Thinking orbs (agent activity indicator)
- Library: thinking-orbs (MIT; React `<ThinkingOrb state size color>`; hub web component `<n-orb state size tone>`, engine in /assets/vendor/thinking-orbs).
| State | Use when the agent is… | Status line |
|---|---|---|
| working | running a multi-step task (default) | Mai is working on 3 tasks… |
| searching | retrieving documents, mail, web | Searching 12 documents… |
| solving | reasoning, calculating, planning, analysing | Working out the licence totals… |
| listening | taking voice input | Listening… |
| connecting | calling tools, MCP servers, systems; syncing; handing off | Connecting to Admiral Server… |
| weaving | combining or cross-checking sources or agents | Combining 5 sources… |
| composing | writing before text streams | Writing a reply… |
| breathing | brief thinking; paused frame = waiting for the user | Thinking… |
| shaping | building an artifact (slides, diagram, form) | Building the slide deck… |
- Sizes: 64 (agent avatar, empty state, Mai header), 32 (task rows, activity panel), 20 (inline with 14–16px status text, tool rows).
- Ink = --n-text-heading; AI tone --n-ai (Oasis 70 light / Oasis 30 dark) only for the agent's own presence, one per view. No status colours, gradients or glows.
- Start after 300ms; always with a status line (role="status"); change state with the work (≤ every 1.5s); on done replace with the result/check; on failure an error icon + message + Retry; waiting for the user = paused frame + confirmation card; reduced motion = still frame.
- Never for non-AI loading, never inside buttons, never the North star or logo as an orb.

## Conversation
- Person: right-aligned bubble (panel bg, radius 18/18/4/18, ≤ 80% width). Agent: full width, no bubble, 32px avatar with orb, name Text SemiBold 13.5px + model and location in caption. Body Text 15/1.6. 22px between messages; column ≤ 760px.
- Actions under the answer: branch ‹ 2/3 ›, copy, regenerate, thumbs up/down, branch from here (30px icon buttons, tooltips; always visible on the latest answer and on touch).
- Streaming: orb + status before first token; 2px AI-colour caret; no per-word animation; don't auto-scroll if the user scrolled up ("Jump to latest"); stopped answers keep partial text + "Stopped" + Continue/Regenerate. Shimmer text only for one short status label.
- Composer: radius 20, 1px UI border, raised surface, shadow 1, grows to 240px; placeholder "Ask Mai, or type / for commands"; tools: attach, voice, model button (20px tile + name), context ring, round 36px send (disabled when empty; becomes Midnight stop while answering). Field stays usable while the agent works (messages queue).
- Attachments: 72px thumbnails (radius 12) for images, 40px file chips for documents, list rows in sources; progress + red error chip with reason; classified files show a lock and "Classified: not sent", never dropped silently.
- Model menu grouped by where models run (On-premises first, Approved cloud); disallowed models disabled with the reason; switching adds a divider.
- Context ring: ≥ 80% warning colour + "Summarise and continue"; never drop messages silently.
- Citations: 18px numbered pills after the sentence; hover card with title, owner, date, quoted passage; collapsed "N sources" list below; cite exact documents.
- Suggestions: ≤ 3 follow-up chips in the user's words; hidden while the agent works.
- Voice: listening orb + live editable transcript; never auto-send unless hands-free mode.

## Agent activity
- Reasoning: collapsible, "Thought for 6 seconds"; body caption colour with 2px leading rule; never invent reasoning.
- Chain of thought: vertical steps (done check / running orb / waiting dashed / failed cross) with what was found as tags/chips; collapse into one line when done.
- Plan card for ≥ 3 steps, shown before starting; editable; steps needing approval marked "Needs approval" up front; Stop always available.
- Queue: messages sent while busy, reorderable, removable, above the composer.
- Tool call: collapsed row (orb or plug icon, tool name in mono, server tag, badge Running / Done · 0.8s / Failed / Needs approval); open shows Input and Result; secrets masked; failures open with the fix; group runs ("Called 6 tools · 4.2s").
- Confirmation (required before send, publish, delete, pay, book, share externally, change access): title says exactly what will happen ("Mai wants to send 1 email"), facts list, action-named buttons ("Send email", "Don't send", "Review draft"), narrow opt-in session permission, 3px --n-ai leading edge + shield icon; stays as a record (who, when, what).
- Tasks: > ~10s → activity panel row with 32px orb, title, step, elapsed; done → check + toast + badge.
- Checkpoint: dashed divider "Checkpoint · 14:02 · before sending · Restore" before hard-to-undo changes.
- Artifacts: card (type icon, title, version, copy/download/open) opening in a side panel with versions; web previews sandboxed; brand assets via /AGENTS/api.
- Developer surfaces: terminal on the dark code surface (Oasis prompt, ✓ green, ✗ red), test summary bar + counts, failures first, stack traces collapse library frames, env vars masked with separate reveal/copy.
- Classes: n-chat, n-msg(--user), n-msg__avatar/meta/body/actions, n-branch, n-caret, n-shimmer-text, n-cite, n-hovercard, n-sources, n-prompt(__bar, __send, __send--stop), n-model-btn, n-context(__ring), n-attach(__thumb, __file, __x), n-reasoning, n-steps, n-step__icon(--done/--failed/--pending), n-card-ai, n-queue, n-tool(--error), n-confirm, n-checkpoint, n-artifact, n-urlbar, n-terminal, n-tests, n-env.