138 lines
2.7 KiB
Markdown
138 lines
2.7 KiB
Markdown
# 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.
|