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.