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.