Brand system

AI Interface Patterns

Foundation route: `contexts/web-app-system.html#ai-interface-patterns`.

Foundation route: contexts/web-app-system.html#ai-interface-patterns.

This source is the canonical INTO Consulting pattern library for AI-product UI. It extends brand/ai-software-platform-system.md; it does not replace the web-app component matrix, accessibility rules, tokens, or media waterfall.

Requirement

AI-native interfaces need named patterns for the surfaces that separate an AI product from a normal CRUD app: prompt input, streaming output, citations, agent traces, tool calls, generation states, model awareness, uncertainty, disclosure, refusal, evaluation, attachments, and generated artifacts.

Constraints

INTO Consulting only.
Warm Light is the default work surface; Blueprint Dark is for focus, command, review, media, and operator moments.
Use existing tokens only. Petrol is action/current/selection. Saffron is warning, milestone, comparison, or render checkpoint.
No purple-blue AI styling, sparkle fields, badge walls, or chat-only product surfaces.
AI actions must expose source/context, evidence, approval, audit, and rollback where risk warrants them.
Motion binds to brand/motion-system.md; depth binds to brand/depth-and-glass-system.md.

Bet

The system names AI patterns directly instead of asking builders to infer them from general app states. That adds one more source file, but prevents every AI screen from inventing its own chat, citation, model, and evaluation language.

Failure Modes

AI UI becomes a generic chat box with hidden evidence.
Streaming text moves critical controls or overwhelms screen readers.
Citations appear decorative instead of proving claims.
Model, confidence, and refusal states are overexposed or color-coded like traffic lights.
Tool calls and agent traces leak sensitive data or become theatrical logs.
Generated artifacts look final before review, approval, and source checks.

Pattern Summary

Pattern	Owns	Required states
Prompt input	Composer and command entry	idle, focused, attached, generating, locked, stopped, error
Slash command menu	Command discovery	closed, open, searching, empty, nested, pinned, permission-filtered
Streaming text output	Incremental generated response	waiting, streaming, paused, stopped, complete, error, reduced-motion
Citation / source attribution	Claim evidence	cited, optional, broken, low-confidence, unavailable
Agent trace / reasoning trail	Accountable process summary	collapsed, running, complete, failed, redacted
Tool call / function call display	Tool execution proof	pending, running, success, failed, retryable, redacted
Generation states	Global AI job state	idle, queued, in-progress, streaming, paused, complete, error, cancelled, refused
Model picker / model awareness	Model selection and disclosure	current, open, changed, unavailable, suggested
Confidence / uncertainty indicator	Calibrated uncertainty	hidden, qualitative, numeric, low, conflicting, stale
Disclosure markers	Provenance and review state	AI-generated, source-of-truth, human-reviewed, draft, final
Refusal / decline	Safe no plus alternative	refused, partial, escalated, alternative-offered
Evaluation feedback	User feedback capture	neutral, rated, written, submitted, disabled
Attachment and artifact panel	Source and output files	empty, uploading, scanned, failed, ready, versioned

1. Prompt Input

+----------------------------------------------------+
| Ask INTO AI...                                [mic] |
| / commands  attach source  1,420 / 6,000       Send |
+----------------------------------------------------+

Field	Rule
Purpose	Collect user intent, scoped source instructions, and optional files without pretending the composer is the whole product.
Anatomy	Label or accessible name, multi-line textarea, token/character meter, slash trigger, attachment control, voice affordance when supported, send/stop control, helper/error line.
States	idle, focused, dirty, over-limit, attachment-added, generating-locked, stop-available, error, permission-disabled.
Motion	Focus uses `--into-motion-quick`; send lock uses `--into-motion-micro`; stop/complete swaps use `--into-motion-measured`.
Depth	No card by default. Use hairline containment; command or attachment popovers may use `--into-app-shadow-floating`.
Typography	Lexend body for prompt text; IBM Plex Mono for token meter, model name, source scope, and state labels.
Color	Petrol for send/current scope; Saffron only for limit warning or risky external action; critical only for blocked input.
Accessibility	Textarea has visible label or `aria-label`; meter text is readable; send exposes busy state; Stop is keyboard reachable while generation runs.
Anti-patterns	Placeholder-as-label, giant chat bubble as product shell, purple AI border, hidden token overrun, disabled send without reason.
INTO posture vs generic SaaS	The composer is a governed input surface attached to evidence and approval, not a novelty prompt bar floating over the app.

Composer: /sou
+------------------------------+
| Sources                       |
| > /source-add   Attach source |
|   /source-scope Limit context |
| Recent                        |
|   /draft-post   Social draft  |
+------------------------------+

Field	Rule
Purpose	Expose repeated AI actions, scoped commands, and safe shortcuts without requiring recall.
Anatomy	Trigger `/`, search input, grouped command list, command description, shortcut hint, nested groups, recent/pinned, permission note, footer help.
States	closed, open, searching, empty, nested, pinned, permission-filtered, command-disabled, escape-restored.
Motion	Open/close uses `--into-motion-measured`; selection highlight uses `--into-motion-micro`; nested group shift uses `--into-motion-quick`.
Depth	Floating command surface with `--into-app-shadow-command`; glass only in Blueprint Dark command mode.
Typography	Lexend command label, IBM Plex Mono shortcut and group marker.
Color	Petrol for active command and selected group; muted text for descriptions; Saffron only for risky or milestone commands.
Accessibility	Combobox/listbox semantics, arrow keys, Enter, Escape, focus restore, visible selected item, result count.
Anti-patterns	Decorative command icons, hidden permission filtering, command groups deeper than two levels, recent items that leak unavailable records.
INTO posture vs generic SaaS	Commands read as operational routes with consequence, not a launcher full of novelty shortcuts.

3. Streaming Text Output

Answer
------------------------------------------------------
The route should remain internal until both citations...
                                                     |
Stop  Copy draft  View sources

Field	Rule
Purpose	Reveal generated text while preserving reading stability, controls, and source accountability.
Anatomy	Output region, status line before first token, readable chunks, cursor indicator, copy action, stop control, error/retry line, source route.
States	waiting-for-first-token, streaming, paused, stopped, complete, mid-stream-error, reduced-motion-static.
Motion	Do not reveal one character at a time. Stream in readable chunks every 240-420ms using `--into-motion-measured` or `--into-motion-considered`; cursor blink uses `--into-ai-stream-cursor-blink`.
Depth	Output is normally no box or hairline group; use full-width exhibit for long answer plus evidence.
Typography	Lexend body at `--into-type-floor-body`; mono status and timestamps.
Color	Text uses primary; cursor and active stream marker use `--into-ai-stream-cursor-color`; errors use critical plus recovery copy.
Accessibility	Region uses polite live updates with throttling; Stop remains reachable; reduced motion renders chunk updates without transform travel.
Anti-patterns	Typewriter character trickle, shimmer text, moving controls, auto-scroll that steals reading position, copy disabled until complete.
INTO posture vs generic SaaS	Streaming feels like a controlled draft becoming available, not a magic show.

4. Citation / Source Attribution

Claim text [1]
              +---------------------+
              | Source 1: Contract  |
              | Confidence: high    |
              | Open source pane    |
              +---------------------+

Field	Rule
Purpose	Attach evidence to claims, generated blocks, or artifacts so users can inspect source quality before action.
Anatomy	Inline marker, source title, owner/date when available, confidence or retrieval state, hover/click reveal, source pane, broken-source state.
States	cited, optional, required-missing, broken, low-confidence, source-unavailable, permission-limited.
Motion	Marker hover uses `--into-motion-micro`; source pane opens with `--into-motion-measured`; evidence reveal may use `--into-motion-considered`.
Depth	Hover preview uses floating shadow; source pane is a full-width exhibit or drawer, not a nested card wall.
Typography	Mono marker; Lexend source title and note; Newsreader only for source-pane title when it is a review surface.
Color	Marker uses `--into-ai-citation-marker`; missing required citation uses Saffron; broken source uses critical with recovery.
Accessibility	Marker is a real link or button with source name; source pane has heading and focus target; state is not color-only.
Anti-patterns	Citation badges detached from claims, fake citations, hidden broken state, raw URLs as only label, confidence shown without explanation.
INTO posture vs generic SaaS	Citations are evidence infrastructure, not decorative footnote chips.

5. Agent Trace / Reasoning Trail

[+] Agent trace
    running  Search sources
    done     Compare policy
    failed   Export packet  Open error

Field	Rule
Purpose	Show accountable process without exposing private chain-of-thought or overwhelming the primary work.
Anatomy	Default-collapsed disclosure, step list, status, step type, timestamp, expandable detail, redaction note, error expansion.
States	collapsed, expanded, in-progress, complete, failed, redacted, cancelled.
Motion	Disclosure uses `--into-motion-quick`; new step insertion uses `--into-motion-measured`; reduced motion inserts statically.
Depth	Hairline or full-width exhibit for trace; avoid per-step cards.
Typography	IBM Plex Mono for status/type/timestamp; Lexend for summaries.
Color	Petrol for current step; Saffron for waiting/needs-human; critical for failed; neutral for complete.
Accessibility	Disclosure is a button with expanded state; running trace uses polite live status; error detail receives focus when opened from an error.
Anti-patterns	Exposing hidden reasoning, theatrical “thinking” prose, unbounded logs, decorative step badges, hiding failed steps.
INTO posture vs generic SaaS	The trail is an audit summary for operators, not a performance of intelligence.

6. Tool Call / Function Call Display

Tool: search_sources
Input: 3 project files, source scope "client packet"
Output: 12 matches, 2 require review           [details]

Field	Rule
Purpose	Make tool execution inspectable enough for trust, retry, and audit.
Anatomy	Tool name, input summary, output summary, status, duration, retry action when safe, full-detail expansion, redaction marker.
States	pending, running, success, failed, retryable, no-permission, redacted.
Motion	Running pulse uses `--into-ai-generation-pulse-opacity` and `--into-motion-loop`; completion settles with `--into-motion-measured`.
Depth	Tool call rows live inside trace or activity feed; expanded detail may become a drawer.
Typography	Mono for tool name, IDs, duration; Lexend for summaries.
Color	Petrol for running/current; Saffron for waiting or partial; critical for failed; neutral for success.
Accessibility	Summary is readable without expansion; details button has accessible name; retry names consequence.
Anti-patterns	Dumping raw JSON by default, hiding failed inputs, retry without scope, leaking secrets or private prompts.
INTO posture vs generic SaaS	Tool calls are accountable execution records, not developer-console theatre.

7. Generation States

Idle -> Queued -> In progress -> Streaming -> Complete
                    |              |
                 Paused         Error / Refused / Cancelled

Field	Rule
Purpose	Give every AI job a shared state vocabulary across composers, outputs, previews, jobs, and artifacts.
Anatomy	State label, allowed actions, owner/system source, elapsed or timestamp, next expected step, recovery route.
States	idle, queued, in-progress, streaming, paused, complete, error, cancelled, refused.
Motion	Queued is static; in-progress may use `--into-motion-loop`; streaming chunks use `--into-ai-stream-chunk-interval`; complete/error/refused settle with `--into-motion-measured`.
Depth	State alone does not earn a card. Use inline status, hairline row, job tray, or full-width exhibit based on consequence.
Typography	Mono state label and elapsed time; Lexend explanation.
Color	Petrol for current/in-progress; Saffron for paused/waiting/needs-human; critical for error; refused stays neutral plus clear language unless safety risk is active.
Accessibility	Status updates use live regions; paused/cancelled/refused expose next action; no state is color-only.
Anti-patterns	”Thinking” as a permanent state, green/red/yellow traffic lights, progress without cancellation, complete state before review.
INTO posture vs generic SaaS	Generation is governed work moving through states, not vague AI activity.

8. Model Picker / Model Awareness

Model: Current model   Cost: standard   Latency: fast
[change]  Capabilities: citations, tools, long context

Field	Rule
Purpose	Let users understand or change model capability when it materially affects outcome, cost, latency, or refusal.
Anatomy	Subtle current-model indicator, capability summary, cost/latency hint, model list, unavailable reason, suggestion after refusal.
States	current, open, changed, unavailable, permission-limited, suggested, degraded.
Motion	Picker open uses `--into-motion-measured`; selection change uses `--into-motion-quick`.
Depth	Dropdown or sheet; never a dominant hero control.
Typography	Mono model IDs; Lexend labels and capability explanations.
Color	Neutral by default; petrol for current selection; Saffron for cost/latency warning; no model-specific brand colors.
Accessibility	Select/listbox semantics; model capabilities are text, not icon-only; unavailable options explain why.
Anti-patterns	Model leaderboard UI, flashy provider branding, hiding cost-impacting swaps, showing model controls to users who cannot act on them.
INTO posture vs generic SaaS	Model awareness is operational disclosure, not AI fandom.

9. Confidence / Uncertainty Indicator

Confidence: Medium
Why: two sources agree, one source is stale.
Next: verify pricing note before export.

Field	Rule
Purpose	Communicate calibrated uncertainty only when it changes user behavior.
Anatomy	Qualitative label by default, optional numeric score when calibrated, explanation, evidence basis, next step.
States	hidden, qualitative, numeric, low, conflicting, stale, not-calibrated.
Motion	No animation by default; state change may use `--into-motion-micro`.
Depth	Inline or source/evidence pane; avoid standalone confidence cards unless it is the decision.
Typography	Mono for score or label; Lexend for explanation.
Color	Do not collapse to red/yellow/green. Use neutral text, petrol for action route, Saffron for caution/milestone, critical only when an unsafe action is blocked.
Accessibility	Label and explanation are text; score is not color-only; numeric confidence states calibration basis.
Anti-patterns	Uncalibrated percentages, traffic-light bars, false precision, hiding uncertainty on client-visible output.
INTO posture vs generic SaaS	Confidence is a decision aid with evidence, not a decorative trust meter.

10. Disclosure Markers

Draft generated by AI  |  Sources attached  |  Human reviewed

Field	Rule
Purpose	Mark provenance and readiness so generated work is not mistaken for approved or source-of-truth content.
Anatomy	AI-generated marker, source-of-truth marker, human-reviewed marker, draft/final marker, timestamp or reviewer when relevant.
States	AI-generated, source-of-truth, human-reviewed, draft, final, client-visible, external-link.
Motion	Static by default; readiness change may use `--into-motion-measured` only when it changes allowed action.
Depth	Inline label, table column, header meta, or approval record; no badge wall.
Typography	IBM Plex Mono compact marker; Lexend explanation when consequence is not obvious.
Color	Neutral markers; petrol for current/approved route; Saffron for draft or needs review when consequence matters.
Accessibility	Marker text is explicit; not icon-only; client-visible/external-link states are announced before export.
Anti-patterns	Tiny unexplained AI sparkle, “verified” without source, final-looking AI drafts, decorative status chips on every field.
INTO posture vs generic SaaS	Disclosure is governance metadata, not compliance theatre.

11. Refusal / Decline

I cannot create the client export yet.
Reason: two required citations are missing.
Next: attach sources or export an internal draft.

Field	Rule
Purpose	Decline unsafe, unsupported, or out-of-scope requests while preserving operator momentum.
Anatomy	Clear refusal, brief reason, safe alternative, escalation route when available, model/tool suggestion when relevant.
States	refused, partial, alternative-offered, escalated, needs-human, retry-after-fix.
Motion	Static or `--into-motion-measured` entry for blocking refusal; no dramatic warning animation.
Depth	Inline or blocking alert based on consequence; use a modal only when the original action was high risk.
Typography	Lexend body; mono reason/source labels if tied to policy or system state.
Color	Neutral for normal refusal; Saffron for blocked prerequisite; critical only for active harm, security, or destructive risk.
Accessibility	Refusal is announced near the triggering control; focus moves only if task is blocked; alternative action is keyboard reachable.
Anti-patterns	Scolding, over-apology, vague “I cannot help”, hiding the next safe route, pretending another model will solve policy.
INTO posture vs generic SaaS	The product says no like an accountable operator: specific, calm, and useful.

12. Evaluation Feedback

Was this useful?  [up] [down]  Add note
Stored with run id, not used for inline retraining.

Field	Rule
Purpose	Capture human judgment about output quality for review and evaluation loops.
Anatomy	Rating control, optional written feedback, run/output identifier, storage disclosure, submit confirmation, undo/edit if supported.
States	neutral, positive, negative, written, submitted, disabled, already-reviewed.
Motion	Rating confirmation uses `--into-motion-micro`; written feedback drawer uses `--into-motion-measured`.
Depth	Inline at output end or in review drawer; do not interrupt the primary workflow.
Typography	Lexend prompt; mono run id when shown.
Color	Petrol for selected feedback action; neutral after submission; critical never used for dislike.
Accessibility	Buttons have names beyond thumbs icons; feedback form has label and submit; confirmation uses polite live region.
Anti-patterns	Claiming inline retraining, hiding where feedback goes, making dislike look destructive, asking for rating before output is inspectable.
INTO posture vs generic SaaS	Feedback is an evaluation artifact, not a dopamine widget.

13. Attachment And Artifact Panel

Sources                    Generated artifacts
+ file.pdf  scanned        + draft.md   v3 reviewed
+ clip.mov  processing     + image.webp v1 needs source

Field	Rule
Purpose	Manage source files and generated outputs with provenance, preview, review, and version history.
Anatomy	Upload zone, file list, scan/progress state, file detail, generated artifact panel, preview, version history, download/export, remove/replace.
States	empty, dragging, uploading, scanned, failed, processing, ready, reviewed, versioned, permission-limited.
Motion	Drag/drop state uses `--into-motion-quick`; upload/progress uses bounded `--into-motion-loop`; preview drawer uses `--into-motion-measured`.
Depth	Full-width exhibit or side panel for previews; dark stage allowed for media. Cards only for peer artifacts.
Typography	Mono file IDs, versions, durations; Lexend filenames and review state.
Color	Petrol for upload/drop target and selected artifact; Saffron for missing source/review; critical for failed scan or unsafe file.
Accessibility	File input is keyboard reachable; progress is text; preview has static summary; download/export names file and sensitivity.
Anti-patterns	Invisible upload scan, final-looking unreviewed artifact, download without sensitivity state, media preview without source notes.
INTO posture vs generic SaaS	Files and artifacts are accountable work objects with review state, not a decorative attachment strip.

Cross-Pattern Rules

Prefer pattern composition over chat sprawl: prompt input, output, evidence, trace, approval, and artifacts are separate zones.
Default all traces and details to collapsed when they are not the main task.
Every high-risk generated action names source, reviewer, consequence, audit, and rollback.
Streaming, tool calls, and long jobs must preserve reduced-motion behavior.
If a pattern needs a new color or dependency, stop and escalate before implementation.

Agent Rule

For any AI-native screen, identify which of the 13 patterns are present before designing. Route each visible surface to this file, then use contexts/web-app-system.html#ai-interface-patterns for the hybrid summary and templates/web-app/style-system.md for implementation mapping.