UI Approachability Improvements

[PaulHax]

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):

1. Welcome — "ALIGN helps you see how AI decisions change when you adjust human values."
2. Load Experiments — "Start by loading pre-computed experiment results, or create a new run."
3. Runs Table — "Each row is one AI decision on a specific scenario. Filter and sort to find what you need."
4. Run Detail Panel — "Select a run to see its full configuration — the scenario, AI model, values, and decision."
5. Scenario & Scene — "The situation the AI is responding to. Change the scene to see how context affects the decision."
6. Values / Alignment — "These are the value knobs. Adjust them to steer the AI toward different priorities."
7. Decision — "Click CHOOSE to have the AI decide. Compare different value settings to see what changes."
8. 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