Mapping Verse Connections: Designing a Cross-Reference UI

Visualizing the relationship between two distinct pieces of data is a common software challenge, but in the context of a scripture-based application like Alif2Ayah, the complexity scales exponentially. The Quran is not structured as a linear narrative; instead, themes, linguistic patterns, and historical contexts interweave across different chapters (surahs) and verses (ayahs). When a user reads a verse about patience, they might benefit from seeing other verses that provide further context on that same theme, even if those verses are hundreds of pages apart. Designing a UI that allows for this non-linear exploration without cluttering the screen or confusing the reader requires a deliberate balance of information density and cognitive load.

At AIA Innovations, our experience building tools like ShariahSignal taught us that users handle complex data best when it is tiered. Just as a financial analyst needs to see high-level compliance ratios before diving into balance sheet line items, a reader needs to see the existence of a connection before they are plunged into the full text of a cross-reference. In Alif2Ayah, we approached the cross-reference UI not as a simple list of links, but as a dynamic map of relationships.

The Problem: The Cognitive Penalty of Context Switching

The primary technical hurdle in cross-referencing is context switching. In a standard reading app, clicking a reference often takes the user to a new screen. This breaks the flow of reading. The user must remember why they clicked the link, process the new information, and then navigate back to their original position. If they follow a chain of three references, they are often "lost" in the stack.

We identified three specific UX risks during the prototyping of Alif2Ayah:

1. 1.Spatial Disorientation: Users losing their place in the primary text.
2. 2.Information Overload: Seeing a wall of "Related Verses" that makes the primary verse harder to focus on.
3. 3.Ambiguity of Relationship: Why is this verse linked? Is it a thematic match, a linguistic similarity, or a historical continuation?

To solve these, we looked at how we managed attention in Mindful Assistant. That app prioritizes "protecting" the user's focus. We applied the same philosophy here: the cross-reference UI should be invisible until requested, and non-destructive once activated.

Architectural Strategy: The Relational Schema

Before designing the UI, we had to structure the data. A cross-reference in Alif2Ayah is more than just a (SourceID, TargetID) pair. We developed a schema that classifies the nature of the link. This allows the UI to group references meaningfully rather than just listing them chronologically.

By categorizing these links, we can use a "Peek and Pop" interaction pattern. Instead of a hard navigation, we use a bottom sheet or an expandable inline card. This keeps the primary verse visible in the background, maintaining the user’s spatial anchor.

Designing the Peek Interaction

We settled on a three-tier visibility strategy for cross-references. This is a lesson we carried over from Designing Financial UI: Displaying Shariah Data without Overload.

1. 1.The Indicator: A subtle count or icon adjacent to the verse. It signals that "more is available" without demanding attention.
2. 2.The Preview (The Peek): A gesture-based expansion (tap or long-press) that shows a summary of the connected verse and the reason for the connection.
3. 3.The Full View (The Pop): A dedicated view for deep study, where the user can see both verses side-by-side or in a vertical stack.

In Jetpack Compose, we implemented this using an AnimatedVisibility wrapper around a LazyColumn. When a user taps a connection icon, the list of references slides in below the verse. This animation is crucial; it provides a visual cue that the new information is a child of the current verse, rather than a new top-level page.

The Challenge of Non-Linear Navigation Paths

What happens when a user is reading Verse A, opens a cross-reference to Verse B, and then finds a cross-reference in Verse B that leads to Verse C? This is where standard back-stack navigation fails.

Our solution was to implement a "Breadcrumb Trail" within the reference sheet itself. Instead of pushing new fragments to the Android navigation controller, we maintain a local stack within the bottom sheet. This allows the user to explore a deep web of connections and then close the sheet with a single swipe to return exactly where they were in their primary reading session.

We also had to account for performance. Fetching 20 related verses from an SQLite database every time a user scrolls could lead to frame drops. We utilized the strategies discussed in Optimizing SQLite for Speed, specifically using indexed lookups for the link_type and source_id columns to ensure that the "Peek" UI feels instantaneous.

Visualizing Semantic Similarity

In our previous work on Mapping Semantic Search: The Alif2Ayah Concept Index, we discussed how we index concepts. The UI for cross-references is the visual manifestation of that index.

We experimented with a "Graph View"—a nodes-and-lines visualization—but found it too chaotic for mobile screens. Users felt like they were looking at a complex map rather than a book. We reverted to a "Connection Thread." We use a vertical line (a "thread") that visually connects the source verse to the reference cards. This mimics the feeling of a margin note in a physical book, which is a mental model users already understand and feel comfortable with.

Checklist for Implementing Complex Cross-References

When building these types of non-linear UI components, we follow this technical checklist to ensure stability and usability:

• State Preservation: If the user minimizes the app while viewing a reference, does the app return to the reference or the primary text? (We recommend returning to the reference to avoid data loss).
• Gesture Conflicts: Ensure that swiping to close a reference doesn't trigger a "swipe to next chapter" gesture.
• Text Contrast: Use distinct background shades for the "Reference Card" vs. the "Main Text" to avoid visual blending. Refer to Dark Mode Done Properly for color ratio guidelines.
• Memory Management: Clear the reference stack when the main view changes surahs to prevent the app’s memory footprint from creeping up during long sessions.
• Accessibility: Ensure screen readers describe the connection ("Connection to Surah 2, Verse 255 regarding Divine Knowledge") rather than just reading the text.

Conclusion

Mapping the connections in Alif2Ayah was not just a database task; it was a design task. By respecting the user's focus and providing clear visual hierarchies, we turned a potentially overwhelming web of data into a guided journey. The goal of focused software is to make complex information feel simple, not by removing the complexity, but by organizing it so that the user is always in control of what they see and when they see it.

Engineering a cross-reference UI is an exercise in restraint. Every time we wanted to add a new feature—like a spider-web graph or a massive list of related topics—we asked ourselves: "Does this help the user understand the verse they are currently reading, or does it pull them away from it?" By prioritizing the primary reading experience, the cross-references become a support system rather than a distraction.

What to do next

1. 1.Audit your navigation: Open your current project and identify any "hard" navigations (full screen changes) that could be replaced with a "peek" (bottom sheet or overlay) to preserve user context.
2. 2.Categorize your links: If you have a "Related Content" section, create a simple schema to label why the content is related, and use those labels as headers in your UI.
3. 3.Test for spatial awareness: Ask a user to navigate two levels deep into your cross-references and then ask them to return to the starting point. If they struggle, consider adding a breadcrumb trail or a "Close All" gesture.