UX Interaction Redesign — Research Notes

Problem Statement

The app has grown to 10 views, 30+ keyboard shortcuts, and multiple interaction surfaces (popups, sidebars, drawers). Adding commentaries makes this worse. The current interaction model is keyboard-first with implicit mouse support — fast for power users but undiscoverable for everyone else.

Key pain points:

Discoverability is near-zero — users must know shortcuts exist; the bottom hint bar is easy to miss
Doesn't scale — running out of memorable single-letter keys
Not touch/mobile-friendly — keyboard shortcuts don't translate to mobile
Developer mindset — vim-style J/K navigation is niche, not mainstream UX

The goal: keep the speed and depth, but surface it through patterns normal users understand.

Design Principles

Drawing from Apple's HIG, Dieter Rams, and modern productivity apps:

Progressive disclosure — show the simple thing; reveal complexity on demand
Recognition over recall — clickable actions > memorized shortcuts
Context is king — show relevant actions for what the user is looking at right now
One way in, many ways through — one obvious entry point, shortcuts as accelerators
Consistency — same gesture/pattern works everywhere

Current Interaction Inventory

Global shortcuts

Key	Action
F11	Fullscreen
F10	Atmospheric mode
F3	FPS counter

ReaderView shortcuts (the busiest view)

Key	Action
Esc	Back to menu
G	Go to chapter
P	Pericope list
X	Cross-ref graph
F	Font size cycle
T	Translation cycle
B	Bookmark
N	Notes drawer
/	Search
J/K	Scroll
H/L	Chapter nav
Click word	Greek/Hebrew popup
Right-click verse	Cross-ref sidebar

That's 14 shortcuts in one view. A new user sees a page of text and has no idea any of this exists.

Mouse/click actions (already exist)

Click word → popup
Right-click verse → cross-ref sidebar
Click menu item → navigate
Click chapter grid → open chapter
Mouse wheel → scroll

These work well. The app already has a click vocabulary — it just needs to be extended and made more visible.

Proposed Patterns

1. Verse Context Menu

What: Right-click (desktop) or long-press (mobile) on a verse opens a contextual action menu.

Why: The verse is the atomic unit of the Bible app. Every feature connects to a verse. A context menu answers "what can I do with this verse?" without memorizing anything.

Actions in menu:

Commentary (Matthew Henry / John Gill / Kanttekeningen)
Cross-references
Greek/Hebrew word analysis
Add/edit note
Copy verse
Bookmark

Behavior:

Appears near the click position (popup, not fullscreen)
Single click on action → opens that feature (e.g. commentary in right panel)
Esc or click elsewhere → dismiss
Keyboard shortcut shown next to each action (teaches shortcuts passively)

Current state: Right-click already opens cross-ref sidebar. This would expand that into a menu with cross-refs as one option.

Design considerations:

Keep it minimal (6-8 items max)
Group by type: Study (commentary, cross-refs, words), Personal (note, bookmark), Utility (copy)
Icon + label for each item
Could use pixel-art style icons to match aesthetic

Mobile mapping: Long-press → same menu. Natural gesture.

2. Command Palette

What: A single shortcut (Ctrl+K, :, or Ctrl+P) opens a searchable list of every action in the app.

Why: Replaces memorizing 30+ shortcuts with one pattern. Users type what they want. Power users discover new features. New users always have an escape hatch.

Examples of what you'd type:

"commentary" → Toggle commentary panel
"font" → Cycle font size
"bookmark" → Toggle bookmark
"search" → Open search
"dutch" → Switch to Dutch translation
"notes" → Open notes drawer
"genesis 3" → Navigate to Genesis 3
"atmospheric" → Toggle atmospheric mode

Behavior:

Overlay centered on screen, dark background, text input at top
Fuzzy matching (type "comm" matches "Commentary panel")
Each result shows: icon + action name + shortcut key (if any)
Enter → execute action
Esc → dismiss
Recent/frequent actions bubble to top

Design considerations:

This is additive — all existing shortcuts keep working
Teaches shortcuts passively by showing them
Can also serve as a "Go to chapter" replacement (type book name + chapter)
Fits the pixel aesthetic: monospace font, minimal chrome

Mobile mapping: Swipe-down or tap search icon → same palette. Works as search + command in one.

3. Contextual Icon Bar

What: Replace the current text-only bottom hint bar with a slim strip of clickable icons. Icons change per view to show only what's relevant.

Why: Makes features visible without reading documentation. Clickable for mouse/touch users. Shows shortcuts on hover for keyboard users who want to learn.

ReaderView icon bar example:

[search] [bookmark] [notes] [font] [translation] [commentary] [cross-refs] [go-to]

Behavior:

Fixed at bottom of screen (like current hint bar, but richer)
Icons are small pixel-art symbols (16x16 or similar)
Hover → tooltip with action name + shortcut
Click → execute action
Active state for toggles (bookmark ON, notes drawer OPEN)
Subtle, doesn't compete with content

Per-view icon sets:

View	Icons
Reader	search, bookmark, notes, font, translation, commentary, cross-refs, go-to
Search	Jesus-only filter, clear
Parallel	translation, go-to
CrossRef	zoom controls, strength filter, back
Notes	new note, link, search

Design considerations:

Keep to 6-8 icons max per view
Icons must be readable at small pixel-art sizes
Consider generating icons via AI or hand-drawing pixel sprites
Background band matches current hint bar styling (semi-transparent)

Mobile mapping: Bottom tab bar / toolbar. Standard mobile pattern.

4. Commentary Panel (specific to this feature)

What: Commentary content displayed in a right-side panel (reusing the drawer/sidebar pattern from notes and cross-refs).

Entry points:

Verse context menu → "Commentary"
Icon bar → commentary icon
Command palette → "commentary"
Future: dedicated keyboard shortcut if demand warrants it

Panel layout:

┌─────────────────────────────────────────────────────┐
│ Commentary — John 3:16                              │
├─────────────────────────────────────────────────────┤
│ [Matthew Henry] [John Gill] [Kanttekeningen]        │  ← tabs or stacked
│                                                     │
│ "God so loved the world — Here is the great         │
│ gospel mystery: God's love to man. This is           │
│ the fountain whence flowed..."                      │
│                                                     │
│ ─────────────────────────────────────                │
│ (scroll for more)                                   │
└─────────────────────────────────────────────────────┘

Behavior:

Opens for the verse you right-clicked / selected
Tabs or vertically stacked sections for each commentary source
Scrollable within the panel
Updates when you click a different verse (or stays pinned — user choice?)
Same drawer mechanics as notes drawer (N key)

Design considerations:

Commentary text can be long (especially John Gill) — need good scroll + truncation
Kanttekeningen is in Dutch — show alongside Dutch translation mode?
Could combine with existing cross-ref sidebar? Or keep separate to avoid overloading one panel
Tab labels: short names ("Henry", "Gill", "Kantt.") to save space

Implementation Priority

Recommended order based on impact vs effort:

#	Pattern	Impact	Effort	Notes
1	Verse context menu	High	Medium	Organizes existing features + commentary. One new UI component.
2	Commentary panel	High	Low	Reuses existing drawer pattern. Data layer already built.
3	Contextual icon bar	Medium	Medium	Replaces hint bar. Needs icon assets.
4	Command palette	Medium	Medium-High	Needs action registry, fuzzy search, overlay. Big payoff long-term.

The context menu + commentary panel together give users a way to access commentaries (and everything else) without learning any new shortcuts, while preserving all existing keyboard shortcuts for power users.

Open Questions

Icon style: Generate pixel-art icons via AI, hand-draw, or use a pixel icon set?
Panel stacking: Can cross-ref sidebar, notes drawer, and commentary panel coexist? Or mutual exclusion (only one right panel at a time)?
Mobile timeline: How soon does mobile matter? If soon, prioritize click/tap patterns now.
Shortcut overlay: Alternative to command palette — a single key (e.g. ?) shows a full-screen shortcut cheat sheet. Simpler to build, less powerful.
Context menu trigger: Right-click is taken by cross-ref sidebar. Options: (a) right-click becomes context menu with cross-refs as one option, (b) use a different trigger for context menu.

References

Apple Human Interface Guidelines — Progressive disclosure
VS Code command palette pattern
Figma's contextual toolbar approach
Hyper Light Drifter — pixel-art UI with minimal text, icon-driven