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.

## Workspace Layout Philosophy

The Confidence Engine is a workspace, not a document.

Documents optimise for reading from top to bottom.

Workspaces optimise for allowing related information to be visible simultaneously.

As investigations become larger, users should not be forced into unnecessary
vertical scrolling simply because horizontal space is available.

Layout decisions should always ask:

> "How much useful investigation context can be seen at one time?"

rather than:

> "How narrow can the content column be?"

### Principles

- **Active investigation remains the primary focus.** The current question and response form are always fully visible first.
- **Frequently referenced information should remain visible.** Understanding and Investigation Map should be scannable without scrolling away from the active question.
- **Reference material may share horizontal space on larger displays.** Situation and History can sit side-by-side when there is room.
- **Layout should adapt to available space without changing the investigation flow.** The same information is always present; only its arrangement changes.
- **Mobile and tablet continue to use a stacked single-column layout.** No progressive disclosure at small sizes — every section remains accessible by scrolling, just as it always has been.
- **Desktop progressively exposes more simultaneous context.** Instead of simply adding whitespace, wider screens reveal horizontal relationships between related panels.

### Desktop layout model (wide screens)

```
┌───────────────────── full-width ─────────────────────┐
│  Investigation Summary                                │
├───────────────────────────────────────────────────────┤
│  Active Workspace   │  Working Memory                │
│  (full width)       │  Understanding     Map        │
│  Current Investigation                      │         │
│  Response           └─────────────────────────────────┘
├───────────────────────────────────────────────────────┤
│  Reference: Situation    │    History                 │
├───────────────────────────────────────────────────────┤
│  Developer Details (always below)                     │
└───────────────────────────────────────────────────────┘
```

### Visual goal

The page should feel less like a long report and more like an investigator's
workspace. The eye should be able to compare Understanding alongside Investigation Map without scrolling, and Situation alongside History in the same way.

### What this phase does NOT include

- No card redesigns.
- No new navigation.
- No account management or top bar.
- No tabs, collapsing layouts, resizable panes, floating panels, or masonry.
- No typography or colour changes.

This is a layout-only phase. The reasoning engine should remain completely unaware of presentation decisions.

## 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.

## Workspace Polish (v0.7)

The workspace should feel calm. Every visible element must justify its presence.

Unknown values should usually be hidden rather than represented with placeholders.

Whitespace is preferred over decorative UI.

Prefer removing over adding. Prefer consistency over cleverness.

Every section group should feel visually connected — spacing within a group is tighter than between groups.

Labels should be brief. "Investigation History" → "History". "Your response" → "Response". The context already makes the meaning clear.

Headings should be clean. Remove unnecessary subheadings that duplicate context. Remove uppercase labels from headings where they add visual noise without adding information.

Cards should have consistent border radius, padding, and heading treatment across the workspace.

An Investigation Map Preview should look provisional — lighter borders, muted text, subtle background — so the user knows it is a preview rather than completed content.

## Entry Experience

The landing page is not the investigation workspace.

The landing page welcomes the user.

The landing page explains what will happen.

Complexity appears progressively.

Users begin with observations rather than conclusions.

The Confidence Engine behaves like a facilitator introducing a workshop — calm, patient, and focused on understanding before acting.

## Facilitator Behaviour

Orientation should support work, not interrupt it.

The facilitator is present by invitation, not obligation.

Returning users should control repeated guidance.

The workspace should remain the primary visual focus.

Information should naturally flow from left to right.