UI Approachability Improvements #82
Description
Iterative plan to make the existing align-app more welcoming to new users, non-technical stakeholders, and evaluators who aren't familiar with the research internals.
Existing Plans (Already Identified)
1. Remove Jargon Terminology
The current UI surfaces internal/research terminology that means nothing to someone outside the team.
| Current Term | Problem | Suggested Replacement |
|---|---|---|
| Decider | Unclear — sounds like a person | AI Model / Decision Model |
| Probe | Research jargon | Scenario / Scene |
| LLM | Acronym, assumes ML literacy | AI Model / Language Model |
Pipeline names (e.g. phase2_pipeline_zeroshot_compa...) |
Internal identifiers, truncated, unreadable | Human-readable labels ("Zero-shot Baseline", "Few-shot Comparison") |
| KDMA | Acronym nobody outside ITM knows | Values / Decision Values |
| ADM | Another acronym | AI Decision Maker / Decision Model |
| Alignment | Overloaded term in AI | Value Alignment / Value Tuning |
July2025-PS-train, June2025-AF-train |
Dataset codes | Descriptive names ("July 2025 - Public Safety", "June 2025 - Armed Forces") |
Approach: Create a display-name mapping layer so internal IDs stay in the code but the UI shows readable labels. Start with the highest-visibility items (table columns, section headers, dropdown labels).
2. Readability Pass
- Truncated text everywhere — pipeline names, scenario descriptions, and scene IDs are cut off with
... - Small text in dropdowns makes scanning hard
- Section headers (Run, Scenario, Decider, Alignment, System Prompt, LLM, Decision, Choice Info) are stacked vertically with no visual hierarchy to indicate which are most important
- The left table columns are too narrow for their content
Quick wins:
- Use tooltips on truncated text so hovering reveals the full value
- Widen the left panel or allow resizing
- Add subtitle/description text under section headers where the label alone isn't enough
- Use chips or tags instead of raw text for values like alignment attributes
3. Info Icons / Contextual Help
Add (i) info icons next to every non-obvious label. On hover or click, show a short plain-English explanation.
Priority targets (what a new user would ask "what is this?"):
- Decider → "The AI model configuration used to make triage decisions"
- Alignment → "Value dimensions that steer the AI's reasoning (e.g., fairness, risk aversion)"
- System Prompt → "The instructions sent to the AI before it sees the scenario"
- LLM → "The underlying language model (e.g., Mistral, GPT-4)"
- Decision / CHOOSE → "Click to have the AI make a decision for this scenario"
- Choice Info → "Details about the available choices and the AI's selection"
- Compare → "View multiple runs side-by-side to see how different settings change decisions"
Implementation: A reusable InfoIcon(text="...") component that renders a small mdi-information-outline icon with a Vuetify tooltip or dialog.
4. Onboarding App Tour
A guided walkthrough for first-time users that highlights key areas of the UI and explains the workflow.
Tour stops (in order):
- Welcome — "ALIGN helps you see how AI decisions change when you adjust human values."
- Load Experiments — "Start by loading pre-computed experiment results, or create a new run."
- Runs Table — "Each row is one AI decision on a specific scenario. Filter and sort to find what you need."
- Run Detail Panel — "Select a run to see its full configuration — the scenario, AI model, values, and decision."
- Scenario & Scene — "The situation the AI is responding to. Change the scene to see how context affects the decision."
- Values / Alignment — "These are the value knobs. Adjust them to steer the AI toward different priorities."
- Decision — "Click CHOOSE to have the AI decide. Compare different value settings to see what changes."
- Compare View — "Open the comparison view to see multiple runs side-by-side."
Implementation options:
- Vuetify Tour or Vue Tour
- Custom stepper with a Vuetify overlay/dialog that highlights elements sequentially
- Store a "tour completed" flag in localStorage so it only shows once (with a "Restart Tour" button in a help menu)
5. Progressive Disclosure
The right panel currently shows everything at once: Run, Scenario, Decider, Alignment, System Prompt, LLM, Decision, Choice Info. Most users only care about the scenario and the decision.
Restructure into tiers:
- Always visible: Scenario summary, Decision result, Value settings
- Expandable: System Prompt, LLM details, Decider internals, Choice Info
- Advanced: Pipeline name, raw probe ID, cache keys
This reduces cognitive load on first impression from 8 sections to 3.
6. Landing Page / Mode Selector
Instead of dropping users directly into the research workbench, show a landing screen with two paths:
- "Explore Decisions" → Guided mode with preset scenarios and value controls (demo-friendly)
- "Research Workbench" → The current full UI for power users
This lets casual visitors and PMs get value without navigating the full interface. The demo brainstorm docs describe this as a "separate front door" — the full app stays as-is for internal work, but first-time visitors and stakeholders get a streamlined experience that tells a story in minutes.
Implementation Priority
| Priority | Improvement | Effort | Impact |
|---|---|---|---|
| 1 | Jargon removal (#1) | Low-Medium | High — immediate readability boost |
| 1 | Progressive disclosure (#5) | Medium | High — reduces overwhelm, simplifies first impression |
| 1 | Landing page / mode selector (#6) | Medium | High — gives newcomers a guided entry point |
| 1 | Info icons (#3) | Low | High — self-service answers to "what is this?" |
| 2 | Readability pass (#2) | Low-Medium | Medium — polish that compounds |