How to use Spectrum CSS theme awareness?

In UXP docs it states:

with Spectrum controls your plugin gets theme awareness essentially for free. So when the user changes from light to dark, you don’t have to wire up all those appearance changes yourself

In Spectrum docs it states:

make sure you’ve included the relevant classes to choose which scale and colorstop you want:
<html class="spectrum spectrum--medium spectrum--light">

So how this auto theme switching should be handled? I’m hesitant to even start refactoring some stuff until I understand how it should work. Do we still have to catch some event and dynamically add classes to plugin HTML?


Also was going through components and I see lots of them use CSS that’s not even supported on UXP. Is it even worth digging into Spectrum CSS at this point?

Hi @Karmalakas

The plugin’s theme is determined based on the user’s setting (from Photoshop → Preferences → Interface → Color Theme).
You dont have to anything special to catch the theme change event. You have 2 options to make your UI theme-friendly:

  1. Use UXP spectrum widgets. They will automatically adapt to the theme. Try out <sp-label>Any text</sp-label>
  2. Use the HTML elements by managing theme awareness yourself. You can do this by using the theme-specific css variables in this guide. For example: <div class="text-theme-friendly"> Any text </div> along with .text-theme-friendly: { color: var(--uxp-host-text-color); } will adjust the text color automatically.

I specifically want to avoid Spectrum UXP (like <sp-button> and other <sp-..> elements). So my confusion lies with the advice in UXP docs to use not Spectrum UXP, but specifically Spectrum CSS, which requires theme CSS class on a wrapper. From your suggested options I suspect it’s not really possible to use Spectrum CSS and make it theme aware so easily as described in the docs.

@Karmalakas Are these the docs you are referring to? Like Padma mentioned, the best way to make your plugin theme-aware is to use the CSS variables that respond to match the plugin user’s host app theme automatically. These are different from Spectrum UXP components, and should be easier to implement than Spectrum CSS used alongside a wrapper.

Basically yes

And yes, I know how to use CSS vars. Also I know how to use Spectrum UXP components. The problem is, they are almost non-customizable. So I was looking for solutions to easy implement UI as similar as Ps itself and have theme awareness out of the box, but also be able to change components styles as I see fit.

I appreciate Adobe team gives us the option to use components that match host style, but I will never understand why they are made as difficult to customize as possible. I want to have a starting point and then do whatever I want (reasonably) with the components.

To workaround some issues, as an example, @kerrishotts suggested to use <div> instead of a proper button, because again - we cannot customize buttons properly. And I believe you can imagine what that means to get that div to a starting point with all the theme awareness and visually match the host app. Makes not much sense.

That being said, I’ll get back to my question. Is there a way to use Spectrum CSS (not Spectrum UXP) out of the box with theme awareness without having to manually add CSS vars to each component, because Spectrum CSS supposed to support it already (according to the docs)?

I spent so much time trying to customize sp-picker blue color. I tried using css vars from spectrum docs with no success, also tried to use inspector to see what vars are defined in the DOM, still got nothing new.

from my test I know that we can’t override the CSS variables for sp-* element (I guess because of css specificity?)

a perfect solution would be overriding the variable once in the root element and not worrying about anything else.

exposing the blue accent color would be great too

@Karmalakas Thanks for clarifying what you’re trying to accomplish. We currently don’t support as much customization as the docs suggest. @Maher Thanks for your feedback as well. You’re right that you cannot override the CSS vars for Spectrum UXP components. We apologize for not being clear there, and will work on updating those asap. There’s no direct way to tie in Spectrum CSS – 1) it has a lot of CSS that UXP doesn’t support, and 2) it isn’t set up to use media queries for theme detection. Kerri’s alternative seems to be the best alternative at this moment (using a div and customizing it using Spectrum CSS).

Then docs should be updated to not confuse, that Spectrum CSS is an option if it really isn’t :thinking: