Common Dark Mode Rendering Bugs in Doctor Appointment Apps: Causes and Fixes

All of these stem from mixing static design assets with dynamic theming APIs and from not testing the full user journey under a true dark‑mode environment.

1. What causes dark‑mode rendering bugs in doctor‑appointment apps

All of these stem from mixing static design assets with dynamic theming APIs and from not testing the full user journey under a true dark‑mode environment.

---

2. Real‑world impact

• User complaints – Support tickets for “can’t read the doctor’s name” or “buttons are invisible” spike after a dark‑mode release. In one case, a clinic’s support inbox received 42 tickets within 48 hours, each requiring manual clarification of the selected time slot.
• Store ratings – Apps that ship with glaring contrast issues see a 0.5‑point drop in Google Play rating within two weeks, often accompanied by “UI broken in dark mode” reviews.
• Revenue loss – A 2 % conversion dip on the “Confirm appointment” screen translates to ≈ $12 K/month for a mid‑size telehealth provider (average revenue per booking ≈ $30). The loss is directly traceable to users abandoning the flow when they cannot see the “Confirm” button in dark mode.

---

3. Concrete manifestations in doctor‑appointment apps

1. Invisible “Book” button on the time‑slot screen – Light‑colored text (#FFFFFF) on a dark surface (#121212).
2. Calendar dates rendered as white squares with no contrast – The native Android MaterialCalendarView inherits the system dark theme, but custom day‑cell backgrounds remain #FFFFFF.
3. Doctor avatar icons appear as solid white blobs – PNG assets without a dark‑mode counterpart.
4. Form field placeholders disappear – android:hint color set to @color/white while the background switches to dark, making the hint invisible.
5. Bottom navigation bar icons lose their tint – The navigation component uses app:itemIconTint="@color/colorPrimary" where colorPrimary is a bright blue that blends into the dark background.
6. Payment SDK overlay shows a light‑theme credit‑card form – Users see white input fields on a black backdrop, breaking the visual flow and causing data‑entry errors.
7. Accessibility contrast failures – WCAG 2.1 AA requires a 4.5:1 contrast ratio for normal text. Dark‑mode screenshots often fall to 2.1:1, triggering automated audit failures.

---

4. How to detect dark‑mode rendering bugs

---

5. Fixes for each example (code‑level guidance)

1. Invisible “Book” button

Android (XML)

<Button
    android:id="@+id/btnBook"
    style="?attr/materialButtonStyle"
    android:text="@string/book"
    android:backgroundTint="?attr/colorPrimary"
    android:textColor="?attr/colorOnPrimary"/>

*Define colorOnPrimary in values-night/colors.xml*

<color name="colorOnPrimary">#FFFFFF</color> <!-- light text on dark primary -->

Web (CSS)

button.book {
  background: var(--color-primary);
  color: var(--color-on-primary);
}

/* dark theme */
@media (prefers-color-scheme: dark) {
  :root {
    --color-primary: #1E1E1E;
    --color-on-primary: #E0E0E0;
  }
}

2. Calendar dates with white background

Android (Kotlin)

val calendar = MaterialCalendarView(this)
calendar.setDayViewDecorator(object : DayViewDecorator {
    override fun shouldDecorate(day: CalendarDay) = true
    override fun decorate(view: DayViewFacade) {
        view.addSpan(object : ForegroundColorSpan(
            ContextCompat.getColor(this@MainActivity, R.color.calendarDayText))
        )
        view.setBackgroundDrawable(
            ContextCompat.getDrawable(this@MainActivity, R.drawable.bg_day_dark))
    }
})

Create bg_day_dark.xml with a semi‑transparent dark drawable.

Web (Playwright test snippet generated by SUSA)

await expect(page.locator('.day-cell')).toHaveCSS('background-color', 'rgb(30,30,30)');

3. Doctor avatar icons

*Convert PNGs to vector assets (.svg or Android VectorDrawable) and provide a dark‑mode tint.*

Android

<ImageView
    android:src="@drawable/ic_doctor"
    android:tint="?attr/colorOnSurface"/>

Define colorOnSurface in values-night/colors.xml (#CCCCCC).

Web

img.avatar {
  filter: invert(80%); /* fallback for raster assets */
}
@media (prefers-color-scheme: dark) {
  img.avatar { filter: none; } /* use SVG with proper fill */
}

4. Missing placeholder text

Android

<EditText
    android:id="@+id/etSymptoms"
    android:hint="@string/hint_symptoms"
    android:textColorHint="?attr/colorOnSurface"/>

Add colorOnSurface dark variant.

Web

input::placeholder {
  color: var(--color-placeholder);
}
@media (prefers-color-scheme: dark) {
  :root { --color-placeholder: #AAAAAA; }
}

5. Bottom navigation icon tint

Android (using Material Components)

<com.google.android.material.bottomnavigation.BottomNavigationView
    android:id="@+id/bottomNav"
    app:itemIconTint="@color/bottom_nav_icon_tint"
    app:itemTextColor="@color/bottom_nav_icon_tint"/>

bottom_nav_icon_tint.xml (color state list) with night variant:

<?xml version="1.0" encoding="utf-8"?>
<selector xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:color="?attr/colorOnSurface" android:state_checked="true"/>
    <item android:color="?attr/colorOnSurface" android:state_checked="false"/>
</selector>

6. Light‑theme payment SDK

*Most SDKs expose a theme setter.*

PaymentSdk.initialize(this)
PaymentSdk.setTheme(PaymentSdk.Theme.DARK) // force dark

If the SDK lacks a dark mode, wrap it in a DialogFragment with a dark background and apply a custom style:

<style name="DarkPaymentDialog" parent="Theme.MaterialComponents.DayNight.Dialog">
    <item name="android:windowBackground">@color/black</item>
    <item name="android:textColor">@color/white</item>
</style>

7. Accessibility contrast failures

Run SUSA’s WCAG audit; it returns element selectors and the computed contrast ratio. Fix by adjusting the color token in the design system:

$primary-dark: #0A84FF; // meets 4.5:1 on $surface-dark (#121212)

Regenerate both light and dark token files (design-tokens-light.json, design-tokens-dark.json) and commit them to the repo.

---

6. Prevention: catching dark‑mode bugs before release

1. Design‑system enforcement

• Store every color in a token file (colors.json).
• Use a lint rule (e.g., stylelint for CSS, detekt for Kotlin) that forbids raw HEX values.

1. Persona‑driven automated testing with SUSA

• Upload the build to SUSA, enable the *elderly* and *accessibility* personas in dark mode.
• SUSA will automatically generate Appium (Android) and Playwright (Web) scripts that exercise the full booking flow, capture screenshots, and produce a coverage analytics report highlighting any untapped elements.

1. Night‑mode CI gate

• Add a GitHub Actions step:

   - name: Run SUSA dark‑mode regression
     uses: susatest/susa-action@v1
     with:
       apk-path: app/build/outputs/apk/release/app-release.apk
       theme: dark

• Fail the pipeline if SUSA returns any “FAIL” verdicts for critical flows (login, search, checkout).

1. Static resource audit

• Run grep -r "#FFFFFF" src/ as part of the pre‑commit hook.
• Fail if any hard‑coded light colors are found outside values-night.

1. Third‑party SDK compliance checklist

• Before adding a new SDK, verify it supports prefers-color-scheme or provides a dark‑theme API.
• Document the required initialization code in a shared sdk-initializer.kt/sdk-initializer.js file.

1. Continuous accessibility monitoring

• Integrate SUSA’s WCAG report into the pull‑request comment bot.
• Any contrast ratio below 4.5:1 is flagged, and the PR cannot be merged until the token is adjusted.

1. User‑feedback loop

• Export SUSA’s “untapped element list” to a bug‑tracking board (Jira, GitHub Issues).
• Prioritize any dark‑mode element that never receives interaction during the automated runs.

By embedding theme‑aware resource management, persona‑driven autonomous testing, and CI gate enforcement, a doctor‑appointment app can ship with confidence that dark‑mode users—whether they are a *curious* teenager checking a pediatrician or an *elderly* patient scheduling a follow‑up—will see a fully functional, accessible UI.