confidence-engine/.claude/ux-guidelines.md

# UX Guidelines

## Main principle

The user should see the next useful step clearly.

The system may retain considerable complexity underneath, but the primary
workspace should remain calm and understandable.

## Main user view

Prioritise:

1. Your situation
2. Current understanding
3. What we are working out
4. Why it matters
5. Next question
6. Answer field
7. Reasoning progress

## Developer view

Keep technical details behind a collapsed `Developer details` disclosure.

This may contain:

- complete situation graph;
- graph counts;
- nodes and edges;
- affected and resolved nodes;
- diagnostics;
- proposal details;
- raw JSON;
- prompt and model details;
- technical confidence data.

Do not remove the developer view. It remains important while the product is
being tested.

## Language

Use plain language.

Prefer:

- `areas that still need investigation`
- `what we are working out`
- `why this matters`
- `what we understand so far`
- `next question`

Avoid in the main view:

- unknown nodes;
- unresolved candidates;
- activeUnknownNodeId;
- graph references;
- proposal compatibility;
- candidate count;
- internal enum values;
- raw IDs.

Never display an unexplained count such as:

`3 remaining`

Explain what the count represents, or omit it.

Do not imply that one unresolved graph node always equals one remaining user
question.

## Loading experience

Analysis and update requests can take around a minute with the current local
model.

A disabled button is not sufficient feedback.

Show a visible processing card immediately.

Recommended initial-analysis messages:

- 0–10 seconds: `Reading your situation`
- 10–25 seconds: `Building a structured understanding`
- 25–45 seconds: `Identifying what is known and still unclear`
- 45+ seconds: `Selecting the next useful question`

Recommended update messages:

- 0–10 seconds: `Considering your answer`
- 10–25 seconds: `Updating the situation`
- 25–45 seconds: `Checking what changed`
- 45+ seconds: `Choosing the next question`

These messages are time-based reassurance only.

Do not claim that a backend stage has completed unless the backend explicitly
reports it.

Show elapsed time.

Do not show fake progress percentages.

Disable duplicate submission while a request is active.

## Visual character

Aim for:

- calm;
- professional;
- spacious;
- accessible;
- suitable for business, consultancy and government users.

Prefer:

- clear hierarchy;
- restrained colour;
- generous whitespace;
- readable line lengths;
- consistent cards;
- accessible contrast;
- responsive layouts.

Avoid:

- visual clutter;
- excessive badges;
- neon colour;
- unnecessary gradients;
- glassmorphism;
- distracting animation;
- dashboard-style density.

The next question should be the strongest visual element.

## TL;DR Workspace Rules

The newest state is the most important state.

The primary focus of every screen should be the user's next action, not the history of how they arrived there.

### Information hierarchy

1. Current investigation
2. Why this matters
3. Response
4. Current understanding
5. Investigation history
6. Original situation
7. Developer details

### Progressive disclosure

Show only the information needed for the current decision.

Everything else should be collapsible or secondary.

### Cognitive load

The user should never need to scan an entire page to discover:

- what is happening
- what they need to do next
- why they are being asked

These should always be immediately visible.

### Investigation history

History exists to provide confidence and traceability, not to compete with the current investigation.

History should remain collapsed unless the user chooses to inspect previous reasoning.

### Original situation

Once an investigation has started, the original scenario becomes reference material rather than the primary focus.

## Interaction Modes

The Confidence Engine operates in two distinct modes.

### Workspace Mode

The user is reading, thinking, and providing information.

The interface should:

- present the current investigation
- allow the user to answer
- show the current understanding
- provide investigation history

The workspace is interactive.

---

### Reasoning Mode (initial analysis)

The engine is constructing the first investigation from nothing.

A full primary loading state appears:

- prominent overlay with spinner, rotating status messages, elapsed timer;
- the entire workspace is replaced until reasoning completes;
- no partial or changing content is visible during processing.

---

### Reasoning Mode (subsequent answers — localised)

The investigation already exists.

Only the active response panel is replaced by the loading card:

- Current investigation question remains visible for context;
- Current understanding, Original situation, and Investigation history persist;
- Terminal state cards are suppressed during loading;
- The workspace layout remains stable and recognisable;
- Recovery states appear in place of the loading card if reasoning fails.

The interface should:

- clearly indicate that reasoning is in progress via the response-panel overlay;
- reassure the user that their answer has been accepted;
- avoid displaying partial or changing reasoning outside the response panel.

---

### Transition

Every submission follows the same lifecycle:

User submits information
↓
Loading card appears (full-page for initial analysis, localised for updates)
↓
Updated workspace returns

The interaction is consistent in intent — both modes confirm input acceptance and pause the active response area — but the page-level behaviour differs because one constructs from nothing while the other refines existing context.

Users should never wonder whether their input has been accepted or whether the engine is still reasoning.