Light-Dark() Linear Gradients Break on iPadOS, Here’s the Fix

iPad OS 26.2 fixes this issue. You only need to do this if you want to have backwards compatibility.

Modern CSS has made building light and dark themes dramatically easier, especially with the introduction of the light-dark() color function.

Paired with Automatic CSS (ACSS) and its Color Scheme (Light/Dark) settings, creating a fully themed website with automatic color switching becomes almost effortless.

That’s exactly how I built my personal website using Etch:

• Light & dark themes
• A theme switcher
• Automatic color conversions
• Clean, modern CSS

Everything worked beautifully… until I tested it on an iPad Pro.

The Setup: Light & Dark Mode the Easy Way

On my site, I’m using:

• The CSS light-dark() color function
• ACSS Color Scheme (Light/Dark) settings
• ACSS Auto Scheme, which converts all colors and shades automatically
• A theme switcher (toggling the color scheme)

If you’re not familiar with light-dark(), it allows you to define both light and dark values directly in CSS:

:root {
  color-scheme: light dark;
}

color: light-dark(#111, #eee);

:root {
  color-scheme: light dark;
}

color: light-dark(#111, #eee);

You can read more about it on MDN:

Visit Website

With ACSS handling variables and scheme switching, building light/dark themes becomes a breeze.

Or so I thought.

The Problem: Background Linear Gradients Not Updating on iPad

After testing my website on:

• Desktop
• Mobile
• Chrome
• Firefox
• Safari

Everything looked perfect.

But when I opened the site on an iPad Pro (both Safari and Chrome), I noticed something strange:

• All colors switched correctly when toggling the theme
• Except sections using linear-gradient() backgrounds

Even stranger:

• If I refreshed the page, the gradients updated correctly
• The issue only appeared when switching themes
• It only happened on iPad
• It happened across multiple browsers on iPad

At first, I thought it might be an ACSS issue. It wasn’t.

Here is an example when switching from light to dark:

https://pv21design.pt

The top card is using the original background: linear-gradient(); while the bottom one is using the fix. Now check from dark to light, the same problem.

https://pv21design.pt

Confirming the Bug: It’s Not Just Me

I tested:

• Other websites using light-dark()
• Sites using background linear gradients
• Different CSS variable setups

Every single one showed the same issue on iPad:

When switching color schemes, background: linear-gradient() does not repaint correctly.

This appears to be a bug on iPadOS, not specific to WordPress, ACSS, or Etch.

And as of now, I haven’t seen this documented anywhere.

The Original (Broken) Code

This is the kind of gradient I was using:

background: linear-gradient(
  45deg,
  transparent 0%,
  var(--bg-light) 100%
);

background: linear-gradient(
  45deg,
  transparent 0%,
  var(--bg-light) 100%
);

It works everywhere, except when switching themes on iPad.

The Fix: Use Masked Gradients Instead

After a lot of experimentation, I found a workaround that works perfectly.

Instead of applying the gradient to the background itself, I:

1. Set a normal background color
2. Used a mask with a linear gradient
3. From transparent to black
4. transparent hides the background color, black reveals it

✅ The Working Solution

background: var(--bg-light);

-webkit-mask: linear-gradient(
  45deg,
  transparent 0%,
  black 100%
);

mask: linear-gradient(
  45deg,
  transparent 0%,
  black 100%
);

background: var(--bg-light);

-webkit-mask: linear-gradient(
  45deg,
  transparent 0%,
  black 100%
);

mask: linear-gradient(
  45deg,
  transparent 0%,
  black 100%
);

Why This Works

• The background color updates correctly when the theme switches
• The gradient is handled via masking, not background repainting
• iPadOS browsers correctly recalculate the mask when the color scheme changes
• The visual result is identical to a background gradient

And most importantly:
✅ It works everywhere
✅ It works when switching themes
✅ No page refresh needed

Why This Matters

If you’re:

• Using light-dark()
• Building light/dark themes
• Using gradients for section backgrounds
• Testing mostly via desktop breakpoints

You might never notice this issue.

That’s why this is such an important reminder:

Always test your websites on real devices.

Breakpoints are not devices. Emulators are not browsers!

Final Thoughts

Modern CSS is incredibly powerful, but browser quirks still exist, especially on iPadOS.

If you’re building light and dark themes with gradients and notice strange behavior on iPad:

• It’s not your setup
• It’s not ACSS
• It’s not Etch

It’s a WebKit issue. And now you have a clean, reliable workaround.

If this saves you even an hour of debugging, then this post has done its job 🙌