added claude context files

2026-08-03 15:51:46 +01:00
parent 44aad69e12
commit e2960853ba
5 changed files with 415 additions and 0 deletions
@@ -0,0 +1,137 @@
+# 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.