AI welcome / first-run screen

patterns specs/patterns/ai-welcome-screen.kmd

First-message hero an AI chat surface renders when the user hasn't sent anything yet — mark + greeting + capability hint + 3-4 starter prompts that pre-fill the composer (do NOT auto-send). Distinct from generic empty-state (#063) by anatomy and intent. Modeled after Ant Design X Welcome + ChatGPT / Claude / Gemini first-run.

When this pattern applies

Primary triggers

Render the empty state of an AI chat in a Koder product

All triggers

Build the first-run view of an AI chat surface
Replace a blank chat with a guided first-message

Pattern — AI welcome screen

Status: v0.1.0 — Draft.

R1 — When to use

Render the AI welcome screen when ALL of:

The current conversation has zero messages.
The AI surface is the primary canvas (not a side panel where the user is mid-task).

For empty side-panel AI assists: use patterns/empty-state.kmd (#063) — simpler, no starter prompts.

R2 — Anatomy

Centered in the chat scroll region, above the Sender:

Element	Required	Notes
AI mark	Yes	Sparkle ⟡ per `patterns/ai-feature-visual-language.kmd` R1, sized 48 dp
Greeting	Yes	One short sentence; identifies the assistant (e.g. "Hi — I'm Kortex Assist") + invites action ("Ask me to summarize, draft, or plan.")
Capability hint	Optional	1-2 lines describing what the assistant knows about the user's current context (e.g. "I can see your open Kortex notes.")
Starter prompts	Yes	3-4 chips, single-tap pre-fills Sender
Disclosure line	Yes	Per `ai-feature-visual-language.kmd` R5 — "AI-generated. Verify before acting." (translatable)

R3 — Starter prompts

3-4 chips, one row (wraps on narrow viewports per specs/app-layout/adaptive-layouts.kmd).
Each chip: short imperative ("Summarize my last 5 notes", "Draft a follow-up email"); ≤ 36 chars per chip.
Tap behavior: fills Sender textarea, focuses it, places cursor at end. Does NOT auto-send. The user always reviews before sending.
After first send: welcome screen disappears for the rest of the conversation; re-appears only on clear() or new conversation.

R4 — Greeting tone

Per specs/content/voice-and-tone.kmd R2 first-run column:

Welcoming, never apologetic.
Identify the assistant by name (Kortex Assist, Talk Helper, Koder Help).
Set expectations briefly. Avoid "I'm an AI" disclaimers (the AI mark
- disclosure line carry that).

R5 — Accessibility

The welcome region uses role="region" with aria-labelledby pointing at the greeting.
Starter prompts: role="list" with each chip a <button>.
Initial focus does NOT move into the welcome region — the Sender retains focus so keyboard users can type directly. (Cmd+/ shortcut per ai-chat-surface.kmd R3 still works.)

R6 — Personalization

The capability hint MAY surface user-specific context (open notes, recent files, active project) but MUST NOT surface anything the user hasn't already approved sharing with AI (per policies/ai-content-disclosure.kmd when published). When in doubt: omit the hint.

R7 — i18n

All strings translatable per specs/i18n/contract.kmd. Keys:

ai.welcome.greeting.{assistant_id}
ai.welcome.capability_hint.{assistant_id} (optional)
ai.welcome.starter.{assistant_id}.{index} (1..4)

Per-assistant keys allow each Koder product to ship its own copy without collision.

Não-escopo

Per-product asset content (starter prompts are owner-curated per surface — KDS sets the anatomy contract, not the prose).
A/B-tested starter variations (consumer concern).

References

specs/patterns/ai-chat-surface.kmd
specs/patterns/ai-feature-visual-language.kmd
specs/patterns/empty-state.kmd