stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
b4fc66feb6f1c992cf5f0de8925698a9c89e17f6
git.stella-ops.org/docs/modules/web/ai-ux-patterns.md

11 KiB
Raw Blame History

AI UX Patterns

Sprint: SPRINT_20251226_020_FE_ai_ux_patterns Tasks: AIUX-43, AIUX-44

This document defines the design patterns for AI assistance in StellaOps, ensuring AI is helpful without being intrusive.

Core Principles

1. Deterministic Verdict First, AI Second

AI is never shown above evidence. The visual hierarchy is:

  1. Verdict Panel (authoritative) - policy outcome
  2. Evidence Panel (authoritative) - reachability, runtime, VEX
  3. AI Panel (assistant) - explanations, suggestions

2. Progressive Disclosure

AI is an overlay, not a layer. Users click to expand:

  • Default: 3-line summary + chips
  • Click: Full explanation with citations
  • Drill-down: Evidence node details

3. The 3-Line Doctrine

AI text is constrained to 3 lines by default:

  • Line 1: What changed or what is it
  • Line 2: Why it matters here
  • Line 3: Recommended next action

Users can expand for more details, but the default is always 3 lines.

4. Compact Chips

AI chips are action-oriented, 3-5 words maximum:

  • "Reachable Path" (not "A reachable path exists from...")
  • "Fix in 1 PR" (not "A fix is available that can be applied...")
  • "Needs: Runtime" (not "Runtime evidence is needed to confirm...")

5. Authority Labels

All AI output must have a clear authority label:

  • Evidence-backed (green): Claims supported by citations
  • Suggestion (amber): AI inference without direct evidence

6. Opt-in in CI/CLI

No AI text appears in logs unless explicitly requested:

stella scan --ai-summary  # Opt-in for AI summary

7. State-Change PR Comments

Only comment when materially useful (state changes, new fixes available).

Component Library

AI Chips

Base Chip (stella-ai-chip)

<stella-ai-chip
  [label]="'Reachable Path'"
  [icon]="'\u2192'"
  [variant]="'status'"
  (onClick)="handleClick()"
/>

Variants:

  • action: Blue, clickable action
  • status: Neutral, informational
  • evidence: Purple, links to evidence

Specialized Chips

Chip Use Case Max Words
stella-ai-explain-chip Trigger explanation 3
stella-ai-fix-chip Fix available/PR ready 4
stella-ai-vex-draft-chip Draft VEX 3
stella-ai-needs-evidence-chip Evidence gap 4
stella-ai-exploitability-chip Reachability/exploitability 4

AI Summary (stella-ai-summary)

<stella-ai-summary
  [line1]="'libfoo 1.2.3 introduced CVE-2025-1234'"
  [line2]="'Vulnerable function called via main\u2192parse_input'"
  [line3]="'Fastest fix: bump to 1.2.5'"
  [authority]="'evidence-backed'"
  [hasMore]="true"
  [expandLabel]="'details'"
  (expanded)="onExpand()"
/>

AI Authority Badge (stella-ai-authority-badge)

<stella-ai-authority-badge [authority]="'evidence-backed'" />
<stella-ai-authority-badge [authority]="'suggestion'" />

Visual Design:

  • Evidence-backed: Green badge, checkmark icon
  • Suggestion: Amber badge, lightbulb icon

Finding Detail Layout

3-Panel Structure

\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
\u2502 VERDICT PANEL (authoritative)                             \u2502
\u2502 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502
\u2502 \u2502 Critical \u2502 BLOCK \u2502 SLA: 3 days \u2502 Reachable: Confirmed   \u2502 \u2502
\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502
\u2502                                                             \u2502
\u2502 EVIDENCE PANEL (authoritative, collapsible)          [\u25BC]  \u2502
\u2502 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502
\u2502 \u2502 Reachability: main\u2192parse_input\u2192vulnerable_fn (3 hops) \u2502 \u2502
\u2502 \u2502 VEX: vendor=affected, distro=not_affected \u2192 affected  \u2502 \u2502
\u2502 \u2502 Runtime: loaded in api-gw (observed 2025-12-25)       \u2502 \u2502
\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502
\u2502                                                             \u2502
\u2502 AI ASSIST (non-authoritative)              [Evidence-backed]\u2502
\u2502 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502
\u2502 \u2502 libfoo 1.2.3 introduced CVE-2025-1234 in this build.  \u2502 \u2502
\u2502 \u2502 Vulnerable function called via path main\u2192parse_input. \u2502 \u2502
\u2502 \u2502 Fastest fix: bump libfoo to 1.2.5 (PR ready).         \u2502 \u2502
\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502
\u2502 [Explain] [Fix] [Draft VEX] [Show evidence]                 \u2502
\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518

Visual Hierarchy

  1. Verdict Panel: Bold border (2px), full opacity, largest header
  2. Evidence Panel: Standard border (1px), full opacity, normal header
  3. AI Panel: Dashed border, 50% opacity background, smaller italic header

Findings List Integration

Chip Display Rules

Severity Policy State Chips Shown (max 2)
Any BLOCK Reachable Path + Fix Available
Any WARN Exploitability + Fix Available
Critical/High Any Reachable Path + Needs Evidence
Medium/Low Any Exploitability only (1 chip)

Hard Rules

  1. Maximum 2 chips per row - prevents visual clutter
  2. No paragraphs in list view - chips only
  3. Hover for preview - 3-line tooltip on hover
  4. Click to detail - chip click opens finding detail with AI panel

Ask Stella Command Bar

Layout

\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
\u2502 Ask Stella                       [CVE-2025-1234] [prod] \u2502
\u2502 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2502
\u2502 [Explain why exploitable]  [Show minimal evidence]      \u2502
\u2502 [Draft VEX]  [What test closes Unknown?]                \u2502
\u2502 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2502
\u2502 Or type your question...                          [Ask] \u2502
\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518

Features

  • Auto-scoped context: CVE, service, environment shown as chips
  • Suggested prompts: Prominent buttons for common questions
  • Freeform secondary: Text input available but not emphasized
  • Not a chatbot: One question at a time, not conversational

User Preferences

Settings

Setting Options Default
Verbosity Minimal / Standard / Detailed Standard
Show in UI On/Off On
Show in PR Comments On/Off Off
Show in Notifications On/Off Off
Per-team notifications Opt-in per team Off

Verbosity Levels

  • Minimal: Action chips only, no explanations
  • Standard: 3-line summaries with expand option
  • Detailed: Full explanations shown by default

Dashboard Integration

Executive Dashboard Rules

  1. No generative narrative - No AI-generated prose paragraphs
  2. Top 3 risk drivers - Evidence-linked, grounded in data
  3. Top 3 bottlenecks - Actionable gaps (missing runtime, etc.)
  4. Deterministic trends - Risk trend from policy, not AI

Risk/Noise Metrics

  • Risk Trend: Deterministic calculation from policy outcomes
  • Noise Reduction: % of findings confirmed "not exploitable"

Testing Requirements

Unit Tests

  • All chip components render correctly
  • Authority badge shows correct color
  • Summary respects 3-line limit
  • Expand/collapse toggles work

E2E Tests

  • Ask Stella flow: button \u2192 panel \u2192 response
  • Finding detail: all 3 panels visible in order
  • Chip click opens finding with AI panel

Visual Regression

  • Chips don't overflow list rows
  • 3-line summary doesn't exceed container
  • Authority badges visible in all contexts

Related Documentation