AI feature visual language

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.

Pattern — AI feature visual language

*tatus* v0.1.0 — Draft. Sets the cross-cutting visual vocabulary; companion specs in specs/ai-ui/ cover specific surfaces (chatmessagebubble, citations, code-block, etc.).

R1 — The AI mark

  • Single canonical icon: the *parkle ⟡*(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:

  • *order* 1px solid; in prefers-reduced-motion: no-preference, animate

    a subtle lineargradient(kdscoloraiaccent → transparent) along the border. Period: 3s. Otherwise: static 1px --kds-color-ai-accent border.

  • *ark position* top-right corner, 12px inset, 16px size.
  • *ackground* unchanged from surrounding surface (no tint — the

    border + mark carry the signal).

R4 — AI-streamed text

  • During streaming: append a 2pxwide pulsing blockcursor 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 oneline disclosure beneath the AI generated content:

Surface type Required microcopy (en-US)
AI chat assistant message AI-generated. Verify before acting.
AI suggestion / autocomplete AI suggestion — review.
AI-edited content AI-edited from your input. Diff available.
AI summary AI 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.
  • Crosslink to `specs/aiui/aidisclaimer.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

  • AIchatsurface 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).

Source: ../home/koder/dev/koder/meta/docs/stack/specs/patterns/ai-feature-visual-language.kmd