AI UX Patterns

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

Use When

UX design patterns for AI-powered features — loading states, streaming display, confidence indicators, progressive disclosure, error recovery, human-in-the-loop controls, usage/budget display, and feedback collection. Invoke during UI design for...
The task needs reusable judgment, domain constraints, or a proven workflow rather than ad hoc advice.

Do Not Use When

The task is unrelated to ai-ux-patterns or would be better handled by a more specific companion skill.
The request only needs a trivial answer and none of this skill's constraints or references materially help.

Required Inputs

Gather relevant project context, constraints, and the concrete problem to solve.
Confirm the desired deliverable: design, code, review, migration plan, audit, or documentation.

Workflow

Read this SKILL.md first, then load only the referenced deep-dive files that are necessary for the task.
Apply the ordered guidance, checklists, and decision rules in this skill instead of cherry-picking isolated snippets.
Produce the deliverable with assumptions, risks, and follow-up work made explicit when they matter.

Quality Standards

Keep outputs execution-oriented, concise, and aligned with the repository's baseline engineering standards.
Preserve compatibility with existing project conventions unless the skill explicitly requires a stronger standard.
Prefer deterministic, reviewable steps over vague advice or tool-specific magic.

Anti-Patterns

Treating examples as copy-paste truth without checking fit, constraints, or failure modes.
Loading every reference file by default instead of using progressive disclosure.

Outputs

A concrete result that fits the task: implementation guidance, review findings, architecture decisions, templates, or generated artifacts.
Clear assumptions, tradeoffs, or unresolved gaps when the task cannot be completed from available context alone.
References used, companion skills, or follow-up actions when they materially improve execution.

Evidence Produced

Category	Artifact	Format	Example
UX quality	AI UX pattern audit	Markdown doc covering loading states, streaming display, confidence indicators, and progressive disclosure findings per AI surface	`docs/ai/ux-pattern-audit.md`

References

Use the links and companion skills already referenced in this file when deeper context is needed.

Purpose

AI features fail the user more often than traditional software. They are slow, sometimes wrong, and opaque. These patterns manage user expectations, build trust, and reduce frustration — without making the AI feel like a gimmick.

Core principle: AI should feel like a capable colleague, not a magic button.

Pattern 1: Progressive Reveal Loading

AI responses take 2–8 seconds. Never show a blank screen.

Immediate (0ms):   Show skeleton placeholder with "Analysing your data..."
Early (500ms):     Animate a progress indicator specific to the task
Mid (2s):          If streaming: show first tokens as they arrive
Complete:          Replace skeleton with result; fade in smoothly

Android (Jetpack Compose):

when (uiState) {
    is AIState.Idle    -> AIPromptButton(onClick = { vm.generate() })
    is AIState.Loading -> AISkeletonCard(label = "Analysing sales data...")
    is AIState.Streaming -> AIStreamingText(text = uiState.partial)
    is AIState.Success -> AIResultCard(result = uiState.result, onFeedback = vm::submitFeedback)
    is AIState.Error   -> AIErrorCard(message = uiState.message, onRetry = vm::retry)
    is AIState.Gated   -> AIUpgradePrompt(tier = uiState.requiredTier)
}

Web (PHP/Blade + Alpine.js):

<div x-data="aiFeature()" x-init="init()">
    <template x-if="state === 'idle'">
        <button @click="generate()" class="btn-ai">Generate Summary</button>
    </template>
    <template x-if="state === 'loading'">
        <div class="ai-skeleton animate-pulse">Analysing your data...</div>
    </template>
    <template x-if="state === 'done'">
        <div class="ai-result" x-text="result"></div>
    </template>
    <template x-if="state === 'gated'">
        <div class="ai-upgrade-banner">Upgrade to AI Growth to use this feature.</div>
    </template>
</div>

Pattern 2: Streaming Text Display

Stream responses token-by-token for chat and long-form output. Eliminates the "waiting for a response" problem.

Rules:

Stream whenever output > 100 tokens.
Show a blinking cursor at the end of partial text.
Allow the user to stop streaming mid-response.
Do not let the user submit again while streaming.
Scroll to follow the latest token automatically.

Key UX detail: Label the result clearly as AI-generated. Use a subtle AI badge (✦ or a model icon), never pretend the output is from a human.

Pattern 3: Confidence Indicator

Show confidence level when the AI makes a prediction or recommendation.

┌─────────────────────────────────────────┐
│ ✦ AI Risk Assessment                    │
│ Student: Aisha Nakato                   │
│                                         │
│ Risk Level:  ████████░░  HIGH           │
│ Confidence:  ███████░░░  Medium         │
│                                         │
│ Reason: Attendance below 60% in last    │
│ 4 weeks; 3 missed assignments.          │
│                                         │
│ [Review] [Dismiss] [Send Alert]         │
└─────────────────────────────────────────┘

Confidence levels:

High — show action buttons prominently.
Medium — show action buttons, add "Please verify before acting."
Low — do not show action buttons. Show "Insufficient data — manual review recommended."

Do not display raw probability scores to end users. Map to High / Medium / Low.

Pattern 4: Human-in-the-Loop Controls

Match control level to action severity.

Action	Control Pattern
View summary / report	Auto-display. No confirmation needed.
Accept recommendation	"Accept" / "Dismiss" buttons. One click.
Send alert to user	Confirmation dialog: "Send risk alert to Aisha's guardian?"
Approve/reject financial action	Full review screen + typed confirmation ("Type CONFIRM to approve")
Irreversible action	Disabled by AI — human must initiate separately.

Anti-pattern: Never let AI take any action that cannot be undone without a confirmation step.

Pattern 5: AI Error Recovery

Design error states that feel helpful, not broken.

Error	User-Facing Message	Action
Timeout	"Analysis is taking longer than expected."	Auto-retry once; then show retry button
Invalid output	"We couldn't generate a result this time."	Retry button + "Report issue" link
Budget exceeded	"Your AI usage limit for this month has been reached. Contact your administrator to increase your limit."	Link to admin panel
Module not active	"This feature requires the AI add-on. Contact your system administrator."	No upgrade link (admin decides)
API provider down	"AI analysis is temporarily unavailable. Your request has been queued."	Show queue confirmation

Rules:

Never expose technical errors (HTTP codes, stack traces) to end users.
Never say "AI error" — say "analysis unavailable."
Always provide a next step (retry / contact admin / queue).

Pattern 6: AI Budget / Usage Display

Tenants that pay for AI want visibility into what they are spending.

User-Level Display (compact, in-app)

✦ AI Usage this month
████████░░  82% of your allocation used
[18% remaining — resets in 11 days]

Show this in user settings or profile. Not on every screen.

Admin-Level Dashboard (tenant admin)

Columns:

User name / email
Total AI calls this month
Input tokens used
Output tokens used
Estimated cost (UGX)
Top feature used

Show a tenant-level totals row. Include a trend chart (this month vs last month).

Super-Admin Dashboard (your SaaS ops)

Columns:

Tenant name
AI tier (Starter / Growth / Enterprise)
Budget (UGX)
Tokens used this month
Raw cost (USD)
Revenue (UGX)
Margin (%)

Alert row: tenants at > 80% budget consumption.

Pattern 7: Feedback Collection

AI improves with feedback. Collect it unobtrusively.

┌─────────────────────────────────────────┐
│ ✦ AI Sales Summary — Today             │
│ Total sales UGX 2,450,000. Top item:   │
│ Maize flour (340 units). 3 stockouts   │
│ flagged for reorder.                    │
│                                         │
│ Was this useful?  👍  👎               │
└─────────────────────────────────────────┘

Collect thumbs up / down per response. No form required.
For 👎: optionally show "What was wrong?" (one-tap options: "Inaccurate / Irrelevant / Too long / Other").
Log feedback to ai_feedback_log(response_id, user_id, rating, reason, created_at).
Review 👎 responses weekly to improve prompts.

Pattern 8: AI Feature Discoverability

AI features are invisible until users know they exist.

Use a consistent ✦ AI badge or icon on every AI-powered element.
On first activation, show a 3-step onboarding card: "What this does / How it works / What it costs."
Show AI features in a dedicated "AI Insights" section in the nav, not buried in menus.
For admin: show a setup checklist when AI module is first activated.

AI UX Anti-Patterns

Anti-Pattern	Problem	Fix
Blank white screen while AI loads	User thinks app crashed	Show skeleton + loading message immediately
Raw JSON shown to user	Confusing; breaks trust	Always transform output before display
"AI says to do X" with no explanation	No trust basis	Always show reason + data points used
One-click irreversible AI actions	Catastrophic if wrong	Add confirmation gate
AI badge on non-AI features	Misleading	Only badge genuine AI-generated content
Hiding AI errors silently	User doesn't know result is missing	Always show a graceful error state
Prompt text visible to users	Confusing	Keep prompts server-side only

See also:

ai-feature-spec — Output schema that drives these UX states
ai-architecture-patterns — Gate state that triggers upgrade prompt
ai-metering-billing — Data behind the usage dashboard
ux-for-ai — Deeper AI trust and transparency principles
ai-slop-prevention — Avoiding low-quality AI output in UI

ai-ux-patterns