# 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:
```bash
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`)
```html
<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`)

```html
<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`)

```html
<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

- [Explanation API](../advisory-ai/guides/explanation-api.md)
- [Policy Studio API](../advisory-ai/guides/policy-studio-api.md)
- [SCM Connector Plugins](../advisory-ai/guides/scm-connector-plugins.md)