Designing for Compliance: Real-Time Filter States in Shariah Signal

When a user opens Shariah Signal to check a stock's compliance status, they are looking for a definitive answer. However, compliance is rarely a static boolean. It is the result of applying specific financial filters—such as debt-to-market-cap ratios or interest-income thresholds—against a shifting dataset. If a user changes their preferred screening standard (such as AAOIFI versus DJIM) or if the underlying market data refreshes, the UI must reflect these state changes immediately. The challenge in engineering this experience lies in preventing "UI flicker" while ensuring the user understands exactly which rules are currently determining their investment verdict.

The Anatomy of a Compliance State

In our development of Shariah Signal, we categorize compliance states into three distinct phases: the Input State (the raw financial data), the Logic State (the selected screening methodology), and the Result State (the visual verdict). Most financial apps fail by treating the Result State as a simple text label. To build a robust system, we must treat the indicator as a dynamic component that reflects the health and source of the data.

When designing these indicators, we avoid hardcoding logic into the UI layer. Instead, we use a state machine that handles transitions between "Compliant," "Non-Compliant," and "Doubtful." Because these states rely on real-time calculations, we also have to account for a fourth, often overlooked state: "Recalculating." A user who switches a filter toggle shouldn't see an old verdict for 200ms while the new one loads; they should see a transient state that acknowledges the change.

Designing the Filter Feedback Loop

Financial screening requires high cognitive load. If a user adjusts a debt-ratio threshold, they need to see how that specific adjustment affected the final result. In Shariah Signal, we implemented a real-time feedback loop using Jetpack Compose to manage these UI transitions. This ensures that every time a filter parameter is touched, the downstream components react in a predictable hierarchy.

We prioritize these three design pillars for compliance indicators:

1. 1.Persistence of Methodology: The user should never have to guess which screening standard is active. The indicator is always paired with a methodology badge.
2. 2.Granular Detail on Demand: While the primary indicator is a simple pass/fail, the secondary UI must reveal the exact ratios (e.g., Debt/Market Cap) that led to that result.
3. 3.Visual Consistency: Colors must remain consistent with the established design system to avoid confusion. We previously explored this in our guide on visualizing financial purity, which details our specific palette choices.

Technical Implementation: The State Table

To ensure the engineering team and design team are aligned, we use a state-indicator matrix. This table defines how the UI responds to various data and filter combinations. This prevents edge cases where a stock might appear compliant simply because the data failed to load.

Handling Asynchronous State Transitions

One of the most difficult parts of building real-time filter indicators is managing the lag between a user action and the backend calculation. In Shariah Signal, we use Kotlin Flows to stream these updates. When a user clicks a toggle to switch from a standard 33% debt threshold to a 30% threshold, the UI immediately emits a ComplianceState.Loading event.

This is where many apps go wrong by using a generic spinning wheel. In a productivity-focused app, a spinning wheel feels like a breakdown. Instead, we use a "shimmer" effect on the specific ratio card that is being recalculated. This tells the user: "The app is working, and only this specific part of the data is changing."

We also implement a debounce on filter inputs. If a user is sliding a percentage bar, we don't want to trigger fifty API calls or heavy local calculations per second. We wait for a 300ms pause in user activity before committing to a new state. This keeps the UI responsive and prevents the battery drain often associated with heavy financial apps.

The Role of Transparency in Compliance UI

A verdict is only as good as the data behind it. We learned during the beta phase of Shariah Signal that users distrusted a "Non-Compliant" verdict if they couldn't see the math. To build trust, the indicator component must be "tappable." Tapping the compliance badge opens a bottom sheet that breaks down the calculation:

• Total Debt / Market Capitalization: The raw numbers used.
• Methodology Threshold: The limit defined by the selected standard.
• Variance: How close the stock is to failing or passing.

By providing this level of detail, we move the UI from being a "black box" to a transparent tool. This is similar to how we handle complex timing calculations in Salah Companion, where we allow users to see the exact angles used for Fajr and Isha calculations rather than just providing a time. Clarity beats simplicity every time in high-stakes environments.

Checklist for Designing Compliance Components

If you are building an app that requires filtering based on strict rules or compliance standards, use this checklist to evaluate your UI:

• [ ] Immediate Acknowledgement: Does the UI react within 100ms of a filter change (even if just to show a loading state)?
• [ ] Source Attribution: Is the name of the active filter set (e.g., "AAOIFI Standard") visible near the result?
• [ ] Non-Binary States: Have you designed for "Missing Data" and "Stale Data" rather than just Pass/Fail?
• [ ] Accessibility: Does the indicator rely on more than just color? (e.g., using icons like checkmarks or crosses for color-blind users).
• [ ] Audit Trail: Can the user click the indicator to see the logic that produced the current state?

Balancing Speed and Accuracy

In the beta of Shariah Signal, we faced a trade-off: do we update the UI instantly using cached data that might be 15 minutes old, or do we force a fetch that takes two seconds? We settled on a hybrid approach. The UI displays the cached verdict immediately but adds a subtle "Syncing" indicator. Once the fresh data arrives, if the verdict changes, we don't just snap the new color into place. We use a cross-fade animation to draw the user’s eye to the change, ensuring they don't miss a critical update to their investment's status.

This approach respects the user's attention, a principle we also apply in Mindful Assistant, where we avoid jarring UI transitions that could break a user's focus. In financial apps, a jarring change isn't just a distraction; it can lead to costly errors if a user acts on outdated information.

Practical Example: The Debt-Ratio Filter

Consider a user looking at a tech stock. The current screening standard allows for 33% total debt. The stock is at 31%. It shows a Green "Compliant" badge. The user then switches to a more conservative custom filter of 30%.

1. 1.User Action: User toggles the 30% filter.
2. 2.Immediate UI Response: The Green badge desaturates to a neutral grey, and a small loading pulse appears.
3. 3.Logic Layer: The app compares the 31% actual debt to the new 30% limit.
4. 4.Result State: The badge turns Red. A small "!" icon appears next to the Debt Ratio line item in the breakdown.
5. 5.User Education: A toast or tooltip briefly explains: "Verdict changed based on new 30% Debt Threshold."

This sequence ensures the user is a participant in the compliance process, rather than just a passive observer of a changing screen.

What to do next

1. 1.Audit your current app's empty and loading states. Ensure that every filter change has a corresponding "working" state so the user never feels the app has frozen.
2. 2.Implement a 'Logic Breakdown' view. For any pass/fail metric in your app, create a secondary view that shows the raw data and the threshold used to reach that conclusion.
3. 3.Review your color-blind support. Check your compliance indicators in a grayscale filter mode to ensure that the difference between 'Pass' and 'Fail' is distinguishable by shape or iconography alone.