Theming isn't really possible using CSS modules

[hugomn]

🐛 Bug Report

After spending hours trying to understand what React Spectrum is built to support theming means on the official docs, I couldn't find the proper way to do any customization to a theme, even a very basic border-radius (I don't want to create a custom component, or to style a specific one using the UNSAFE_ property. We have a design system, and I want to make the components consistent without needing extra config per component).

🤔 Expected Behavior

We should be able to override theme variables or to write a full custom theme overriding the default theme.

😯 Current Behavior

First of all, the Theming docs mentions vaguely that custom themes can be created, but no examples are provided. Trying to create a custom theme object, and passing some of the properties will override all properties. Copying the full theme file doesn't sound like a viable solution.

🔦 Context

I've tried to create a theme object in multiple ways and to pass it to Provider. The code sample below explains the approach and why it doesn't work.

💻 Code Sample

theme.module.css

.theme {
  /* Button overrides */
  --spectrum-button-primary-border-radius: 0.375rem;
}

index.ts

import customTheme from './theme.module.css';
import dark from './spectrum-dark.module.css';
import darkest from './spectrum-darkest.module.css';
import global from './spectrum-global.module.css';
import large from './spectrum-large.module.css';
import light from './spectrum-light.module.css';
import medium from './spectrum-medium.module.css';

const theme = {
  global: global,
  // MERGING DOESN'T WORK
  dark: { ...dark, ...customTheme },
  // WHEN APPLYING CUSTOM THEME FILE, ALL OTHER STYLES ARE IGNORED
  // dark: customTheme,
  darkest: darkest,
  // MERGING DOESN'T WORK
  light: { ...light, ...customTheme },
  medium: medium,
  large: large,
};

// COMPONENTS VARIABLES ARE NOT INCLUDED IN ANY OF THOSE FILES, I.E spectrum-button-primary-border-radius

export default theme;

🌍 Your Environment

Next.js 12.2.25
React 18.2.0
@nrwl/next 14.6.1

What am I missing here? Is it the right way to create a theme to duplicate all files from https://github.com/adobe/react-spectrum/tree/main/packages/%40adobe/spectrum-css-temp/vars? Which other option do we have?

Not being able to change a simple border-radius is frustrating. The theming docs also need to be updated to display some examples or to clarify what theming actually means. I've also based my assumptions on this example from the official storybook: https://github.com/adobe/react-spectrum/blob/main/packages/%40react-spectrum/provider/stories/custom-theme.css, which seems to be misleading as well.

[snowystinger]

Closing with #3370
At this time, this is not possible to support as our token system isn't API. We apologize for any confusion and lost time on this.
The best route to custom theming at the moment is to use our hooks and fully control the rendering of any component you want to style differently.

[squidjam]

Closing with #3370 At this time, this is not possible to support as our token system isn't API. We apologize for any confusion and lost time on this. The best route to custom theming at the moment is to use our hooks and fully control the rendering of any component you want to style differently.

Does it mean that we have to reimplement the whole library just to take out round borders from buttons and define some custom colors?

[albert-schilling-enerparc]

I totally understand your point, @snowystinger , that React-Spectrum does not really support customizing themes currently, but that you can basically rebuild it with React-Aria (and React-CSS). But that approach really does not make any sense. Why should one redo all the great work you put into React-Spectrum just to change the values of a color variable? There must be an easy approach to overwriting or adding additional variables to change the theme.

[snowystinger]

Absolutely, that is a great point. We're working on a proposal right now to make that easier. See #2368 (reply in thread)

[devongovett]

Well that proposal would still be unstyled @snowystinger. I think they're asking to reuse spectrum's css but with some customizations rather than rewriting it.

[snowystinger]

ah, you are correct, i mis-read that. Your proposal will reduce complexity in terms of getting the react-aria correct with the components. From there, it should be easier to style.

Unfortunately we can't easily expose the css variables of React Spectrum as API for customized theming because they are out of our control and have undergone a few major changes already. If and when they become more stable, we could consider revisiting.

[albert-schilling-enerparc]

Thank you for your reply @snowystinger . This sounds somewhat promising. I have no real knowledge about CSS modules, but wouldn't it be sufficient, if devs could view the css modules with the variable names and values in the docs (autogenerated) and then just add their own css module in the correct order that overwrites these variables? Something along these lines:

import {defaultTheme} from '@adobe/react-spectrum';
import custom-light-theme from '../css/custom-light-theme.css';

<Provider 
  theme={{...defaultTheme
    , light: [defaultTheme.light, custom-light-theme] }
>
  <YourApp />
</Provider>

Now, it should be sufficient, that React-Spectrum imports the css-module in the correct order as placed in the array, shouldn't it?

[devongovett]

Yeah the main problem is actually stabilizing the variable names themselves. So far they have been an implementation detail, and the names have changed several times. If we wanted to officially support this, we'd need to treat them as public API that followed semver.

[albert-schilling-enerparc]

Ah, I see. That gives hope that this is only a matter of time. I hope you come up with good future-proof var names and get rid of the cumbersome spectrum prefix :)
I think there is some nice inspiration out there regarding naming like the tokens from the IMB Carbon System or the utility classes from Tailwind CSS.

[squidjam]

Maybe if customizing was left to the user by having undefined vars in the css of the elements and all your current values as fallbacks?
You are already kind of doing it, so is something like this possible?

background-color:var(---spectrum-custom-background-color-transparent, var(--spectrum-fieldbutton-quiet-background-color-disabled,var(--spectrum-alias-background-color-transparent)))

Variable names can still be changed on your side, while we would be still be able to customize things by keeping the custom ones more or less static.

[snowystinger]

I agree that things could be better. I'm not sure we currently have the bandwidth to implement such a system at the moment.

I think there are a lot of questions about what would be supported in terms of variables. Would it only be colors? or would it also be dimensions? What about in cases of shorthand properties? or positioning or psuedo elements or properties we don't use? or places where we use the same value, but someone customizing would want two separate values?

I'm also not so sure that allowing them to be component specific is the best idea. Our color scale is specifically built to meet contrast a11y requirements and all our components work together. That said, it's a big undertaking to make a new color scale if you're a third party and you just want to tweak a couple of things and are aware of the dangers.

All I'm really saying is that this is something that isn't simple. This would be a huge API surface area. It needs time and people to think through, make a proposal, implement, document, and maintain.

What you've outlined is a good starting place. I think starting from the Tailwind angle could also be worthwhile.

[squidjam]

I agree that things could be better. I'm not sure we currently have the bandwidth to implement such a system at the moment.

I think there are a lot of questions about what would be supported in terms of variables. Would it only be colors? or would it also be dimensions? What about in cases of shorthand properties? or positioning or psuedo elements or properties we don't use? or places where we use the same value, but someone customizing would want two separate values?

I'm also not so sure that allowing them to be component specific is the best idea. Our color scale is specifically built to meet contrast a11y requirements and all our components work together. That said, it's a big undertaking to make a new color scale if you're a third party and you just want to tweak a couple of things and are aware of the dangers.

All I'm really saying is that this is something that isn't simple. This would be a huge API surface area. It needs time and people to think through, make a proposal, implement, document, and maintain.

What you've outlined is a good starting place. I think starting from the Tailwind angle could also be worthwhile.

Making it all optionally customizable for the user could be interesting. Not easy or fast, but interesting.

Now, if this is not the vision of this implementation, maybe stating it clearly how strict this implementation is in the documentation would be a great time saver.

P.S. Your color palettes won't match corporative branding colors, so doing it at the component level would allow someone to control this without redefining any palette you provide.
P.P.S Going the Tailwind way seems to me like more work, and might not allow users to customize the design system implementation with their own style requirements.

[albert-schilling-enerparc]

@snowystinger Thank you for your explanation. Your points are absolutely valid. It is definitely the right way to have a clear concept regarding feature set, implementation and maintenance.

On the other hand, I think it is sometimes smarter to start the conceptual work simultaneously with the implementation and improve both incrementally. For example, you could start with a very small API offering only the most important feature for customers, let's say for example adding new color variants. This would offer your users a huge benefit and your team a lot of insights regarding further steps for the implementation and overall concept.

It might also help in evaluating reasonable css variable names.

(Just a side note regarding implementation, maybe an npx script that properly modifies or appends to the existing CSS modules according to the package version might be a first foot in the door. The script might also warn or throw an error if the reference color by the user is not suitable for a color scale.)