Recommended approach for component theming that uses base tokens

[jonathanj]

In the theming docs there's a hint of a components key, but this pattern isn't explored anywhere else in the docs.

In my case, the design has a set of base tokens ("primary background", "secondary background", "accent background", etc.) and then components are styled according to these. However, if you simply define the stylesheet as "secondary buttons have a background of tokens.background.secondary" then you can't style secondary buttons differently to the secondary background, or if you want to change the secondary background then secondary buttons are forced to change too, which may not always be the relationship you want.

const tokens = {
  colors: { background: { primary: …, secondary: … }, … },
  …,
} as const;

const theme = {
  tokens,
  components: {
    button: { secondary: { background: tokens.colors.background.secondary }, … },
    …,
  },
} as const;

However, if theme.components is defined in terms of theme.tokens then using UnistylesRuntime.updateTheme to modify the tokens, won't update the use of tokens in theme.components (for cases where a second tier token isn't being modified.)

I realise this has some conceptual overlap with variants, but variant styles are not defined near the theme, and can't be directly modified by updateTheme.

My initial thought on this was to provide some kind of factory for component tokens:

function updateComponents(name, componentsFn) {
  UnistylesRuntime.updateTheme(name, (current) => {
    return {...current, merge({}, current.components, componentsFn(current.tokens))};
  });
}

Do you have any advice or suggestions?

Edit: Some other theme systems allow the use of special identifiers like background: '$tokens.colors.background.other'. This solves my immediate issue but is not good from a types/reliability point of view because of strings (even if you build fancy interpolated string types). Some kind of ref function that explicitly describes the hierarchical relationship in a way that Unistyles knows to resolve things would be better than magic strings. background: ref(current => current.tokens.colors.background.other)

[jpudysz]

Hello 👋

components is not a reserved word. It's just an example. It's not handled by Unistyles by any mean.

I would simply create a base button component, and then use variants to change desired style keys. You can also define anything in the theme and simply spread it in the button. Unistyles is flexible, you can do the same what is supported in JavaScript eg.;

const stylesheet = createStyleSheet(theme => ({
      baseButton: {
           // variants
           variants: {},
           // or usage with theme
           ...theme.components.button
      }
}))

or mix with dynamic function:

const stylesheet = createStyleSheet(theme => ({
      baseButton: (someExternalParamsFromJSX) => ({
           ...theme.components.button(someExternalParamsFromJSX)
      })
}))

I would need some example to see what you're trying to achieve

[jonathanj]

Sorry, didn't mean to imply it's reserved just that it seems like an interesting pattern to explore but isn't mentioned again.

So in my case I think I want to do something like this:

const stylesheet = createStyleSheet(theme => ({
  variants: {
    type: {
      secondary: theme.components.button.type.secondary,
      …
    }
  }
});

I want the variants to be defined by the theme, so that it's possible to modify what "secondary button" looks like by modifying the theme, without the implicit assumption that "secondary button uses background secondary token". (Sorry if I'm explaining this poorly.)

But I'm not sure if this is is a good way to go about it, it feels a bit like I'm finding myself between "theme" and "variants", so just looking for some confirmation.

[jpudysz]

Oh then that's easy 😎

Define variant in your theme:

const theme = {
    // other keys
    variants: {
         button: {
             type: {
                  // if you want to use color from theme, then move colors above the theme
                  secondary: 'red'
             }
         }
    }
}

component:

const stylesheet = createStyleSheet(theme => ({
    button: {
         variants: theme.variants.button
    }
})

[jonathanj]

Thanks, that does seem like a good approach!