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

252 lines
11 KiB
Markdown
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:
```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)
Reference in New Issue View Git Blame Copy Permalink