Improve theming docs

🙋 Documentation Request

Hey folks, I’m struggling to understand how to customize the themes. The docs say

React Spectrum is built to support theming.

But it’s very hard to find information on how to practically change how things look. Like, for example how do I change the default styles of the inputs?

It seems like the theme you pass to the provider points to the classes and then you need to make sure the classes are present in your CSS, but what do you actually put in these classes to start meaningfully customizing Spectrum’s appearance? For example I’m using emotion, but I’d recon you can do this with any styling solution.

// spectrum.ts
import { Theme } from '@react-types/provider'
import { darkTheme } from '@adobe/react-spectrum'

export const spectrumTheme: Theme = {
  ...darkTheme,
  global: {
    spectrum: 'spectrum-global',
// Should I put anything else here?
  },
}


const spectrumGlobalStyles: Style = (theme) => ({
  '.spectrum-global': {
    backgroundColor: theme.backgroundColors.primary,
    // Do I just shove all my overrides here?
    // Should I just manually comb through this file to find what I need? https://github.com/adobe/react-spectrum/blob/main/packages/%40adobe/spectrum-css-temp/vars/spectrum-dark.css
  },
})

My app that has a lot of existing styling already.

import React from 'react'
import { Global } from '@emotion/react'
import { Provider as SpectrumProvider } from '@adobe/react-spectrum';

import globalStyles from '../../style/globalStyles'
import { spectrumGlobalStyles, spectrumTheme } from "../../style/themes/spectrum";


const App: React.FC = () => {
  return (
    <SpectrumProvider theme={spectrumTheme} locale="en-GB">
        <Global styles={[globalStyles, spectrumGlobalStyles]} />

        <h1>Hello, world!</h1>
    </SpectrumProvider>
  )
}

export default App

I’d be down to make a PR if I figure out how to do it properly. Essentially, I’m trying to “normalize” spectrum so that its default styles behave with my styles.

[LFDanLu]

Your hunch is correct, creating your own custom theme would require reproducing the set of variables/tokens that our Spectrum themes have and replacing the values with your own colors (e.g. you could set --spectrum-global-color-gray-800: red in your own css file and set that file as your ‘light’ theme object that your provide to our Provider). We don’t recommend that users do so since many of the color and size choices were made with color contrast and mobile + desktop accessibility in mind.

Since you are building your own app that has its own styling in place, it may be easier to create the components with the aria/stately hooks instead so that you have full control over the styling yourself

[hugomn]

@LFDanLu if I understand you correctly, does that mean that my components will always have the blue-400 as the primary color, and if I want a button with a different primary color, I need to create a new one, reimplement all the logic using aria/stately? Something like <MyCustomGreenButton />? And all the other components will still be blue-400? How about increasing the default font-sizes and input-heights?

After struggling for some hours setting up Spectrum, I’m shocked that theming is ~NOT~ customizable at all, which is quite the opposite of what you can find in the homepage and in the docs.