Feature Proposal: createThemedVariant

[joe-bell]

Is your feature request related to a problem? Please describe.

One thing I find myself doing regularly with stitches is mapping through themed values to generate my variants

For example, let's look at this demo grid style which reduces theme.space into a gap variant:

import type * as Stitches from '@stitches/core';
import { css, config } from "./stitches.config";

const { space } = config.theme;

const gap = Object.keys(space).reduce(
  (acc, cv) => ({
    ...acc,
    [cv]: { $$gridGap: `$space$${cv}` },
  }),
  {}
) as { [key in keyof typeof space]: Stitches.CSS };

export const grid = css({
  display: "grid",
  gap: "$$gridGap",
  variants: {
    gap,
  },
  defaultVariants: {
    gap: 4,
  },
});

Which can then be used like so:

interface IGridProps
  extends React.HTMLAttributes<HTMLDivElement>,
    Stitches.VariantProps<typeof grid> {}

const Grid: React.FC<IGridProps> = ({ className, gap, ...props }) => (
  <div className={grid({ className, gap })} {...props} />
);

This solution's OK for one or two components, but it can become tedious and might not be immediately obvious for those expecting Stitches to offer "dynamic variants" from other run-time styling libraries.

Describe the solution you'd like

I'm not super keen on this exact proposed API, but I think something like this could enable users to roll their own themed variants (without having to worry about some of the runtime concerns that come with dynamic themed variants)

import type * as Stitches from "@stitches/core";
import { css, config, createThemedVariant } from "./stitches.config";

export const grid = css({
  display: "grid",
  gap: "$$gridGap",
  variants: {
    gap: createThemedVariant(
      // theme key
      "space", 
      // variant style (with themed value)
      (spaceKey) => ({
      $$gridGap: `$space$${spaceKey}`,
    })),
  },
  defaultVariants: {
    gap: 4,
  },
});

Describe alternatives you've considered
An alternative approach to #721

Additional context
This issue was raised following an informal chat of ideas with @peduarte

[lukemorales]

The only thing I don't like about this solution is that it limits the usage to theme keys, while cases where you want property values are not covered, like in this example #721 (comment).
Obviously, your proposal is already a better stage than what we have today, but #721 seems like a more complete solution to dynamic variants

[joe-bell]

This is absolutely the intention! Restricting to themed values is a feature (from both performance and design consistency perspectives)

If a consumer wants to break away from themed values, then it's probably best they create their own use-case variant on-top of these

[joe-bell]

Worthy mention: @pleunv's createScaleVariant API does a stellar job of providing this functionality

[peduarte]

This comment is a response to @pleunv's createScaleVariant API.

Commenting here as #721 is more about dynamic variant.

---

If we offer an API for this, we're saying "it's a good idea", and I'm not yet convinced it is.

Variants were not designed to be "CSS Properties". They were designed to be true variation of a component, like a primary/secondary button.

I understand if you're coming from styled-system/theme-ui/chakra-ui it feels natural to pass CSS properties as prop, but that's not the goal with Stitches.

That's why Stitches offers the css prop, where all CSS are supposed to be colocated. If you accept that CSS Properties are passed in via the css prop, do we agree that the need to map tokens to variant names is almost rare? In which case, doing it manually is acceptable?

(and possibly also maintenance) effort.

I'd like to understand more about the maintenance here. In design system worlds, changing tokens is an enormous breaking change. And something that rarely happens (if ever). Personally I think repetition and manual fixes are good!

[peduarte]

We did it manually though 😄

[joe-bell]

@peduarte if I'm totally honest, I'm really struggling to see how this isn't a good idea

I can see where you're coming from; there's absolutely variants that make more sense to be self-contained (e.g. a Button), but there's also a common use-case for themed variants too (e.g. type sizing, layout components, containers)

Most importantly though; not all design systems/component libraries are equal

I like Stitches because it's fairly unopinionated and flexible when it comes to variants – it's ultimately down to the component library authors to decide what works best

I'm not saying you're wrong, just that I think this stance should be subjective to Modulz's Design System rather than Stitches 🤔

[peduarte]

Thanks for letting me know your thoughts, I get it 🙏 For the record, I'm not saying it's a bad idea. I mean, I had even drafted this API months ago before suggesting it as "less powerful dynamic variants" when we were chatting about it.

But I hope we can agree that when a tool offers a 1st-class API for something, it's almost the same as promoting its usage. Some features can be easily abused. So, we must think carefully before implementing something.

This proposal is not rejected, it's under consideration. And as soon as we get the more critical issues out of the way, we'll be able to dedicate more time to it.

[joe-bell]

🙏

[lukemorales]

We did it manually though 😄

Yeah, but mainly because there isn't a way to automate this through stitches, right? If stitches had something like #721 I believe you'd have used that instead of creating all those variants manually.

Obviously, I'm more advocating towards #721 than just scale/theme variants. My point by using the Modulz team's work as an example is that even though stitches was not designed with using CSS properties as variants in its core, the creators themselves have used that pattern and a lot of people are already creating utils and abstractions in order to be able to do the same in a more automated way. I don't think anyone will be crazy enough to recreate some clone of Chakra-UI with stitches, but there are some components, especially layout components, that can definitely benefit from that (again, Radix-UI is a great example of that usage).

My main argument is: there's a lot of examples of this pattern being used manually and workarounds of users wanting to create this in a more automated way. Whether stitches was created with this pattern in mind or not, this is how users are using it. If one of stitches' greatest strengths is providing one of the best DX ever and users are creating workarounds to a feature stitches does not provide yet, doesn't it make sent to provide that in stitches itself? Because, from what we are seeing, users are using it this way, whether it was intended or not.

[pleunv]

It was not immediately clear to me when I first started tinkering with Stitches, but I do understand now that a prop API is not one of its goals. Which is fine, tooling can be (should be?) opinionated to some extent. It's then up to us to decide whether we want to adopt it or not.

Just to give you some perspective on what I was trying to achieve with that createScaleVariant() and why: When starting out from an existing, substantial codebase built on top of something that heavily favors a prop API such as styled-system, the migration effort of switching to a different styling library is quite frankly, huge. Running them side-by-side and doing an incremental migration is in theory possible but in practice a massive pain due to style conflicts and priority issues, different APIs in turn complicating adoption and onboarding, mental overhead, bundle impact, and of course simply the work involved in migrating everything over and eliminating technical debt.

Being able to swap out the underlying styling library without the need to change thousands of lines of JSX and styles is of course a massive benefit, while definitely also having its drawbacks. The library you're adopting might have a different philosophy and core principles which you are deliberately ignoring because you just want your code to run, while it has to provide this compatibility layer that might cause friction in its ecosystem and a maintenance burden moving forward. I agree that providing this functionality as part of Stitches' core when you haven't figured out yet if and how it fits into Stitches' core design is not a good idea. One possible solution here could be to provide it as some sort of separate compat layer, or give the community a way to plug one in (i.e. preact compat).

I'm sure there are patterns in our codebase we've adopted over the past few years that can be done differently and/or better today, which is one of the points I see being made here and there. The difficulty is that detecting and adapting these is an effort that takes time. Time to familiarise yourself with a new library and gain new insights, time to transform these insights into actionable changes, and time to actually apply all these changes throughout your code.

I believe you when you say that doing X in Stitches is better than how we used to do Y instead before Stitches, and I think it's important to share these insights in order to share experiences, push better practices and improve everyone's quality of life. But, you are only realistically able to apply these immediately when you're starting a project from scratch or have a smallish project and/or a small team that can be easily adjusted. Any other scenario will be almost impossible to tackle.

This is basically where I was coming from. We have a large codebase built on top of styled-system and emotion. Styled-system has since become unmaintained, and we have adopted TypeScript. Both of these changes make styled-system rather annoying and painful to use. Having a way to swap out both styled-system and emotion without requiring a massive migration effort would of course be the prefered scenario here, but that is only feasible when the styling library we switch to can offer a similar prop API that the scale values can slot into. Again, not telling you to go this or that direction, just giving you one use-case which I'm sure also applies to other teams out there (if so, let yourselves be heard 😄).

When it comes to styled() vs prop API, I'm a bit torn. On one hand I understand the direction you have laid out for Stitches, but on the other hand I have found us to be a lot more productive with a (restrictive) prop API since it makes it a lot more straightforward to build restritive primitives but also richer reusable components that hook straight into the theme scales. When it comes to passing arbitrary css properties in addition to theme scales I'm a bit less convinced and I tend to agree that Stitches' variant approach feels more intuitive, as css properties tend to be a bit too verbose for many use-cases, i.e. <Text fontSize={16} fontFamily="Arial" /> vs <Text size={16} font="Arial" /> to give a rather silly example. The latter one is easily achievable with Stitches and makes everything feel a bit more "purposefully made", rather than just a small API on top of CSS with little flexibility.

To briefly touch the "prop API vs css prop" topic: I still definitely favour the prop API because it allows you to completely lock down the styling of the component. Personally I would even discourage the use of a css prop since it means that either your component is not flexible enough or people are using and customizing ComponentA while they should be using ComponentB or building a new one for their particular use-case. Also worth mentioning are the ergonomics of sprinking inline objects throughout your JSX and the perf impact of it. That said, prop APIs also have downsides. When it comes to responsive theme values for example it's hard to avoid inline objects (i.e. mt={{ '@initial': '2x', '@bp1': '4x' }}).

All of that said, Sprinkles is definitely one of the most exciting libraries I have run into in recent years, and you're all doing a stellar job 😄

[peduarte]

Thanks for that. I agree with everything you said. And I appreciate you can see how from our side making these decisions isnt as straight forward.

I'm curious about something. Is it possible for you to create this helper locally? I'm asking because one thing is Stitches "limiting" people from achieving something, and the other is Stitches not offering an API for it.

Sprinkles is definitely one of the most exciting libraries I have run into in recent years

Excuse me? 🤣