AI feature visual language

patterns specs/patterns/ai-feature-visual-language.kmd

Canonical visual lexicon for distinguishing AI-driven surfaces from deterministic UI: AI mark (sparkle ⟡), AI accent token, animated border on AI-generated content, progressive-reveal cursor on streamed text, mandatory non-determinism disclosure microcopy. Modeled after MongoDB LeafyGreen AI branding, GitLab Pajamas Duo, Atlassian Rovo.

When this pattern applies

Primary triggers

All triggers

Pattern — AI feature visual language

Status: v0.1.0 — Draft. Sets the cross-cutting visual vocabulary; companion specs in specs/ai-ui/ cover specific surfaces (chat-message-bubble, citations, code-block, etc.).

R1 — The AI mark

  • Single canonical icon: the sparkle ⟡ (4-point star, asymmetric). Vector lives in meta/brand/koder-design/icons/sparkle.svg.
  • Used wherever an affordance opens an AI surface or labels AI output.
  • Size scale: 12 / 16 / 20 / 24px (matches icon-system).
  • Color: --kds-color-ai-accent (see R2).

Never substitute generic gear / brain / robot / chip icons.

R2 — The AI accent token

  • New Verge token: --kds-color-ai-accent.
    • Light theme: #7c3aed (violet — distinguishable from primary blue / success green).
    • Dark theme: #a78bfa (lifted violet).
  • Used for: AI mark color, AI surface accent border, AI-stream cursor.
  • Never used for: regular UI primary actions, status colors.

Tokens are added to internal/kinds/verge.go + cascaded through assets/css/presets.css + emitted in dist/tokens/tokens.* (see #059).

R3 — AI surface (panel, card, cell)

When a surface contains AI-generated content:

  • Border: 1px solid; in prefers-reduced-motion: no-preference, animate a subtle linear-gradient(--kds-color-ai-accent → transparent) along the border. Period: 3s. Otherwise: static 1px --kds-color-ai-accent border.
  • Mark position: top-right corner, 12px inset, 16px size.
  • Background: unchanged from surrounding surface (no tint — the border + mark carry the signal).

R4 — AI-streamed text

  • During streaming: append a 2px-wide pulsing block-cursor in --kds-color-ai-accent, attached to the end of the streamed text.
  • After stream ends: no special tint, no leftover cursor. The text reads as regular body text once complete.

R5 — Mandatory non-determinism disclosure

Every AI surface MUST include a one-line disclosure beneath the AI- generated content:

Surface typeRequired microcopy (en-US)
AI chat assistant messageAI-generated. Verify before acting.
AI suggestion / autocompleteAI suggestion — review.
AI-edited contentAI-edited from your input. Diff available.
AI summaryAI summary. May omit details.
  • Translatable per specs/i18n/contract.kmd — keys ai.disclosure.<surface>.
  • Rendered with the AI mark inline + --kds-color-text-muted style.
  • Cross-link to specs/ai-ui/ai-disclaimer.kmd for the full risk- tiered disclaimer system (when present, this spec defers to that).

R6 — Specific anti-patterns

  • ❌ Rainbow gradients
  • ❌ Glowing halos around AI surfaces
  • ❌ Anthropomorphic icons (robot face, avatar with eyes)
  • ❌ Loud "✨ AI POWERED" badges
  • ❌ Bouncing dots that imply emotion

Não-escopo

  • AI-chat-surface primitives (specs/patterns/ai-chat-surface.kmd).
  • AI citations / source attribution UX (specs/ai-ui/citations.kmd).
  • Per-product branding overrides of the AI mark (deferred to product decisions; Koder Stack default is the sparkle).

References