# 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

The engine is analysing the available evidence.

The interface should:

- clearly indicate that reasoning is in progress
- temporarily suspend the workspace
- reassure the user that their input has been accepted
- avoid displaying partial or changing reasoning

The workspace is paused until reasoning completes.

---

### Transition

Every submission follows the same lifecycle:

User submits information
↓
Workspace pauses
↓
Reasoning mode
↓
Updated workspace appears

The interaction should be identical whether the submission is:

- the initial situation
- an investigation answer
- a future uploaded document
- any other evidence

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

---

## Consistent Submission Lifecycle

Every submission follows the same lifecycle regardless of context.

1. User submits → workspace pauses immediately, stale content disappears
2. Reasoning mode appears with loading overlay (spinner, rotating status messages, elapsed timer)
3. Updated workspace returns or error state appears

The loading card must appear before any async request begins and remain visible until the result arrives. 

During reasoning mode:
- The workspace is fully hidden (not just disabled)
- No stale question, response form, or active indicators are visible
- The Investigation Summary Panel shows "Reasoning" rather than "Investigation in progress"
- Recovery states render on top of the loading overlay when applicable

This applies equally to initial analysis and all update submissions.