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