Design Systems & Library Authoring

[joshuabaker]

I’ve been tracking this project for a long time now. Congrats on the public launch! 🎉

My interest has been around using StyleX to build a design system foundation. At present, I don’t know that it’s suited for this
case. I’d love to hear your thoughts regarding using StyleX for library authoring.

Component API

I grant there a valid reasons regarding terseness. As it stands, this results in a lot of boilerplate in one-off layouts when compared to alternatives that developers are using.

For instance, we can go from 15 lines in a relatively simple layout to over 40 switching from Tailwind. That’s going to put a lot of people off.

Example using StyleX

import stylex from "@stylexjs/stylex";

const screens = {
  sm: "@media (min-width: 640px)",
  md: "@media (min-width: 768px)",
  lg: "@media (min-width: 768px)",
};

const styles = stylex.create({
  grid: {
    display: "grid",
    gap: 8,
    [screens.sm]: {
      gridTemplateColumns: "repeat(2, 1fr)",
    },
    [screens.md]: {
      gridTemplateColumns: "repeat(3, 1fr)",
    },
    [screens.lg]: {
      gridTemplateColumns: "repeat(4, 1fr)",
    },
  },
  item: {
    paddingLeft: 8,
    paddingRight: 8,
    paddingTop: 4,
    paddingBottom: 4,
    backgroundColor: "#f5f5f5",
  },
});

export default function Example() {
  const names = ["Morty", "Rick", "Summer", "Jerry", "Beth"];

  return (
    <div {...stylex.props(styles.grid)}>
      {names.map((name) => (
        <div key={name} {...stylex.props(styles.item)}>
          {name}
        </div>
      ))}
    </div>
  );
}

Example using Tailwind

export default function Example() {
  const names = ["Morty", "Rick", "Summer", "Jerry", "Beth"];

  return (
    <div
      className={"grid gap-4 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4"}
    >
      {names.map((name) => (
        <div key={name} className={"px-2 py-1 bg-neutral-100"}>
          {name}
        </div>
      ))}
    </div>
  );
}

Concept using an imported design system components

import { Box, Grid } from "ui";

export default function Example() {
  const names = ["Morty", "Rick", "Summer", "Jerry", "Beth"];

  return (
    <Grid columns={{ default: null, sm: 2, md: 3, lg: 4 }} css={{ gap: 8 }}>
      {names.map((name) => (
        <Box
          key={name}
          css={{ paddingX: 4, paddingY: 8, backgroundColor: "#f5f5f5" }}
        >
          {name}
        </Box>
      ))}
    </Grid>
  );
}

^{Note that I’m using custom properties here. I’m guessing that it’s unavoidable to have to handle some form of precompiling to achieve this.}

The Stitches API for overriding styles is roughly the vision I had for a design system foundation using StyleX. Styles are passed as a standard object, which is a lot terser than what StyleX currently allows, but still following the convention of CSS property naming. Several runtime-heavy libraries work in this manner.

<Box css={{ color: "red" }} />

I experimented a bit with a Babel plugin that extracts the CSS prop and nests it directly in a stylex.create call. I haven’t got this to work as of writing, but could be a solution to allow for this.

Is this something you encountered? What are you thoughts on possible solutions for this?

Design tokens

One of the key things that is likely to become an issue — including for Meta — is design token distribution.

Currently only static/local values are allowed inside of stylex.create calls, which makes importing distributed themes and design tokens impossible.

StyleX processes .stylex.js files, which is a nice solution. It reminds me of Vanilla Extract.

I note that you’ve responded to this already, but wanted to ask if there’s consideration for loading/referencing external packages in the future?

One thing that came to mind was resolving static imports and inling them just in .stylex.js.

import stylex from '@stylexjs/stylex';
import { colors, getColor } from "system";

export const tokens = stylex.defineVars({
  accent: colors.accent, // => "#ea580c"
  background: getColor("background"), // => stylex.runtimeVarResolver(() => getColor("background")) _or_ Error
});

Potentially a lot of work, I’ll grant, but this feels like one that’s going to come up a lot.

[nmn]

I just wanted to start off by sharing a corrected and shortened version of your initial StyleX example. I share this to explain the "idea" behind media queries and pseudo classes in StyleX.

import stylex from "@stylexjs/stylex";

const styles = stylex.create({
  grid: {
    display: "grid",
    gap: 8,
    gridTemplateColumns: {
      default: '1fr',
      "@media (min-width: 640px) and (max-width: 767px)": "repeat(2, 1fr)",
      "@media (min-width: 768px) and (min-width: 1229px)": "repeat(3, 1fr)",
      "@media (min-width: 1230px)": "repeat(4, 1fr)",
    },
    // You should probably just use:
    // gridTemplateColumns: 'repeat(auto-fill, minmax(360px, 1fr))',
  },
  item: {
    backgroundColor: "#f5f5f5",
    paddingBlock: 4,
    paddingInline: 8,
  },
});

export default function Example() {
  const names = ["Morty", "Rick", "Summer", "Jerry", "Beth"];

  return (
    <div {...stylex.props(styles.grid)}>
      {names.map((name) => (
        <div key={name} {...stylex.props(styles.item)}>
          {name}
        </div>
      ))}
    </div>
  );
}

In StyleX, there are no "mobile styles", "tablet styles" and "desktop styles. In StyleX, you just have styles, and some values can adapt to the screen size. This API also encourages you to think about layout holistically and at all screen sizes before you start adding special cases.

---

Regarding terseness, I shared a concept to recreate an experience similar to Tailwind in StyleX on Twitter. https://x.com/naman34/status/1734074956882026894?s=20

This works today but could end up generating a lot of unused CSS. I have some ideas on how this pattern can be optimized.

---

Another approach that people have asked for would be to allow "inline" styles. Some existing solutions have used an API lie this.

export default function Example() {
  const names = ["Morty", "Rick", "Summer", "Jerry", "Beth"];

  return (
    <div
      css={{
        display: "grid",
        gap: 8,
        gridTemplateColumns: 'repeat(auto-fill, minmax(360px, 1fr))',
      }}
    >
      {names.map((name) => (
        <div key={name} css={{
          backgroundColor: "#f5f5f5",
          paddingBlock: 4,
          paddingInline: 8,
        }}>
          {name}
        </div>
      ))}
    </div>
  );
}

We could look into something along these lines, but so far I don't have an API that would work well.

---

Regarding your concept using an imported design system components

This could be implemented in StyleX today, but it would generate less efficient code as it would be dependent on dynamic styles which involve setting inline styles. Since you want to pass in arbitrary values, you need to pass in styles compiled with stylex.create, which is a pattern which is documented.

Also, I'm generally against using shorthands like sm and lg for readability sake. In the Tweet above, these would just be names you've chosen for styles in your codebase, so it would not be public API. I think it's OK in those cases. Using unreadable short names is a bad idea for public API IMO.

[joshuabaker]

All good context and thinking. 👍🏻

It doesn't support this yet, but I have written about how we will support it in the near future. The idea is that you'll be able to define media queries as variables and then be able to import and use them.

Will this be custom media queries?

We want to avoid doing anything that would change the StyleX API. Instead we want to build such features on the tried and true pattern of: Import object. Use Object. No magic strings. No names to remember.

Yeah, I agree with this. All I was asking is how we might implement that on top of StyleX, if we wanted to.

That said, we can consider a pre-processing step for things that would not change the API at some point in the future. We have plans for adding a bunch of new capabilities and optimisations before we get to that.

Sounds great.

[nmn]

Will this be custom media queries?

Conceptually. But they'll be compiled away, so not in practice.

[kevintyj]

It's super cool to see another user form stitches in the StyleX community! After the dev of stitches was no longer maintained, I am supper happy to see StyleX available to the public!

About design tokens & imported vars inside defineVars

I would also like to chime in and agree that support for importing variables would be a very nice addition to see (even if it only supports static objects). Especially if used in conjunction with projects like PurgeCSS, we could automatically purge all unused vars and styles from the project, but I know that this also comes with difficulties with compiled styling systems (as themes and other dynamic styles are introduced). We also use the design token spec at work, and I have been testing StyleX personally to see if we could somehow implement StyleX into our workflow but lack of imported token support has been the biggest bottle neck. Here is what the current workflow looks like:

Using design tokens within StyleX vars

Currently we have a design token spec defined like so:

{
    "colors": {
        "indigo": {
            "type": "color",
            "0": {
                "value": "#ebedfb",
            },
            ...
            "9": {
                "value": "#0b003d"
            }
        },
        "indigoDark": {
            "type": "color",
            "0": {
                "value": "#16171f",
            },
            ...
            "9": {
                "value": "#e4e5fb"
            }
        },
    }
}

Since all variables used inside defineVars must be in the same file, I currently use a simple script to generate a file like so:

  const colorTokens = {
      indigo0: '#ebedfb',
      ...
      indigo9: '#0b003d'
  }

const colorDarkTokens = {
    indigo0: '#16171f',
    ...
    indigo9: '#e4e5fb'
}

Then I can copy and past the contents into a colors.stylex.ts file which will include the above generate constants plus:

export const colorTokens = defineVars(colorTokens)
export const darkTheme = createTheme(colorTokens, colorDarkTokens)

Up until this point, there is a not a lot of problems with migrating from tokens to StyleX, only that when the design token gets updated (let's say indigo color was updated), the colorTokens will have to be regenerated or else the global or core design tokens from the design team will be out of sync with the codebase using StyleX. Previously, when using the design token spec, or just using exported objects we would publish these constants in a shared package ie @acme/color which is all the design tokens that are in sync with the design team which also automatically generates the necessary js files (common js object export) plus css/scss files (for projects using css/scss variables). Ie for use with Unocss the workflow looked like below:

//uno.config.ts
import { indigo } from '@acme/color';

export default defineConfig({
  // ...
  theme: {
    colors: {
      indigo,
      indigoDark
    },
  },
  // ...
});

and use with scss looked like below:

// Indigo Colors
@import '../../../../node_modules/@acme/color/scss/indigo';

And all the colors would be in sync with the design token spec defined in the color package for the entire organization and or project. Since imports are not supported with StyleX, this syncing process is not done on the package level, rather has to be done manually. Just wanted to know if anyone has thought of possible workarounds to use cases like this?
As the design token spec gets more and more specific, with the use of semantic tokens, and component layer tokens beyond the global layer, managing the sync between absolute truth & StyleX defined vars will become more and more difficult as project sizes grow.
However, once the global tokens are defined, since StyleX allows imports of other vars defined using defineVars, a nested var from the use of indigo0 as acme-s-color-primary-0 in the semantic layer and acme-c-color-background-button-primary-default wouldn't be too difficult to keep in sync.
Also, support for sharing media queries across the project will be a huge plus to helping maintain consistency for larger projects.
A solution like the following would be super neat:

// colors.stylex.ts
import { indigo } from '@acme/color'

const convertToStyleX = (colorObject: Record<string, string>, name: string) => {
    const colorTokens = {};
    
    colorObject.foreach([key, hex], () => {
        colorTokens[`${name}${key}`] = hex;
    })
    
    return colorTokens;
}

const colors = {...convertToStyleX(indigo, 'indigo')}

export const colorTokens = defineVars(colors)

or something like this:

import { indigo } from '@acme/color/stylex'

export const colorTokens = defineVars(...indigo)

[nmn]

Just wanted to know if anyone has thought of possible workarounds to use cases like this?

It should be possible to create a code generation script that reads the design tokens and generates the file with defineVars in it. It's what we do internally as well.

About being able to support imports, it is technically possible but it can cause a lot of caching issues which will make large build untenable. For that reason we are not going to officially support it for the time being.

[joshuabaker]

I think the code generation route makes sense. It does make the adoption friction a bit higher, but I grant there’s good reason for things to work the way they do.

[mryechkin]

Great topic for discussion! Very curious to hear the suggested patterns.

For inline style overrides, have you seen CSS Hooks? It looks quite promising.

[nmn]

I have seen CSS Hooks. Sadly it's a runtime lib which uses inline styles heavily. So it's going to be slow.

It also does media queries and pseudo classes IMO. (As is evident by first response!)

[mryechkin]

In StyleX, there are no "mobile styles", "tablet styles" and "desktop styles. In StyleX, you just have styles, and some values can adapt to the screen size. This API also encourages you to think about layout holistically and at all screen sizes before you start adding special cases.

I respect the decision to go this route, but IMO this will result in much more refactoring work than otherwise would be needed for existing projects - should they wish to migrate to StyleX - if their styles have been defined using those pretty common patterns already. I can see that being a pretty hard selling point for someone considering to adopt StyleX.

[nmn]

Most existing styling solutions aren't very good at merging styles and so codebases don't rely on merging styles much. When this is the case, it's easy to translate the code automatically, rather than by hand.

Example: I wrote a script that can transform JSX code using Tailwind to code using StyleX automatically: https://github.com/nmn/tw-to-stylex

My short term plan is to create a VS Code plugin with it so that developers can type Tailwind, hit save and get StyleX. IMO, this gives you the best of both worlds. Quick to type, easy to read and maintain. And, obviously, the other benefits of using StyleX.

[mryechkin]

That sounds awesome! Look forward to trying it out

[shawngustaw]

@nmn know you're super busy (thanks for all your help!!), but do you have steps to run the tw-to-stylex script?

[nmn]

It's a very barebones script that takes stdin and outputs on to stdout. I'm not sure how to use it on Windows (or if it would even work). But on mac/linux it's as simple as:

cat input-file.js | node ./tw-to-stylex/lib/index.js > output-file.js

[MtDalPizzol]

Regarding this approach mentioned by @nmn :

export default function Example() {
  const names = ["Morty", "Rick", "Summer", "Jerry", "Beth"];

  return (
    <div
      css={{
        display: "grid",
        gap: 8,
        gridTemplateColumns: 'repeat(auto-fill, minmax(360px, 1fr))',
      }}
    >
      {names.map((name) => (
        <div key={name} css={{
          backgroundColor: "#f5f5f5",
          paddingBlock: 4,
          paddingInline: 8,
        }}>
          {name}
        </div>
      ))}
    </div>
  );
}

I wrote a POC as a plugin for Vite + Vue. I'm not an expert on static analysis, bundlers nor anything on those lines, so I took the easy/dangerous route for me: good old Regex matching.

So, basically, I've introduced a :stylex="" or :css="" attribute on my components that can receive anything that you can normally pass as props. When Vite runs, it scans the files for those attributes and, if there are any object literals on that attribute, it creates a UUID as the style name and appends them to the stylex.create({}) definition. After that, I replace the object literals with references to that UUID style name and replace the :stylex="" for an :class="stylex(...)" one.

I haven't used it extensively yet, but it's doing its job for now and you can even mix inline with predefined styles. If anyone with deeper knowledge of Vite's compiler could try this approach, I thing it can be a good direction to follow.

// The Vite plugin

    {
      name: 'vite:stylex-attr',
      enforce: 'pre',
      transform: (code, id) => {
        const attrMatchRegex = /:(stylex|css)="([^"]*)"/g
        const attrMatches = code.match(attrMatchRegex)

        if (!attrMatches) {
          return code
        }

        let styles = ''

        // Handle :stylex attributes
        code = code
          .replace(attrMatchRegex, (attrMatch, attrName, contents) => {
            let newContents = contents.replace(/\{[\s\S]*?\}/g, (objMatch) => {
              const styleName = uuid()

              // Create a new stylex variable
              styles += `'${styleName}': ${objMatch},`

              // Replace object literals with stylex calls
              return `styles['${styleName}']`
            })

            // Unwrap array
            if (/^\[/.test(newContents)) {
              newContents = newContents.replace(/^\[|\]$/g, '')
            }

            // Replace :stylex attributes with :class attributes
            return `:class="stylex(${newContents})"`
          })

        const stylexDefinitionRegex = /<script(?![^>]*\bsetup\b)[^>]*>([\s\S]*?stylex\.create\(\{([\s\S]*?)\}\)[\s\S]*?)<\/script>/g

        if (!stylexDefinitionRegex.test(code)) {
          return (code += `
            <script>
              const styles = stylex.create({${styles}})
            </script>
          `)
        }

        // Modify the object passed to stylex.create()
        return code.replace(stylexDefinitionRegex, (scriptTag, scriptContents, stylesObject) => {
          const modifiedScriptContent = scriptContents.replace(/(stylex\.create\(\{)([\s\S]*?)(\}\))/, (match, start, props, end) => {
            const newProps = (props)
              ? `${props}, `
              : ''

            return `${start}${newProps}${styles}${end}`
          })

          // Replace the original script content in the SFC
          return scriptTag.replace(scriptContents, modifiedScriptContent)
        })
      }
    }

// Component

<template>
  <q-banner
    rounded
    :css="[
      {
        backgroundColor: 'var(--bg-color, #000000)'
      },
      styles[type]
    ]"
  >
    <template #avatar>
      <i-mdi-information
        :css="{
          fontSize: '2rem',
          opacity: 0.3
        }"
      />
    </template>
    <template #action>
      <q-btn
        flat
        color="white"
        label="Dismiss"
        @click="$emit('dismiss')"
      />
    </template>
    <template
      v-for="(slot, index) of Object.keys($slots)"
      :key="index"
      #[slot]
    >
      <slot :name="slot" />
    </template>
  </q-banner>
</template>

<script setup>
import { colors } from '../assets/tokens.stylex.js'

defineProps({
  type: {
    type: String,
    default: 'info'
  }
})

defineEmits(['dismiss'])
</script>

<script>
const styles = stylex.create({
  success: {
    '--bg-color': colors.success_500
  },
  info: {
    '--bg-color': colors.info_500
  },
  warning: {
    '--bg-color': colors.warning_500
  },
  error: {
    '--bg-color': colors.danger_500
  }
})
</script>

[nmn]

I'm working on a system to make writing simple Babel transforms like this easier.

[tounsoo]

I'm trying to build a scaffolding of UI library using Vite and StyleX too but without success just yet. Can anyone share link to a repo that is working?
Mine isn't working and probably a lot of it is wrong but if anyone is interested or have ideas to make it work, feel free to take a look and share your thoughts in thread. Thanks!

https://github.com/tounsoo/stylex-ui-lib-template

[tounsoo]

Ohhh I see. I'll definitely try it out.
Also, I'm I understanding this correct that the project that imports the UI library with stylex also needs to install stylex?

[nmn]

We have also have a few examples on the StyleX ecosystem page with hand-rolled Vite plugins that work for narrow use-cases.

[tounsoo]

@nmn @BMCwebdev Thank you for your helps! I got everything working now and have updated the repo 👍

Next step for me will be adding themes

[tounsoo]

One thing I am trying to find information on while setting up the theme and tokens is how to let the DS consumers also access the tokens. But I believe per this doc we need the extension to be *.stylex.(js|ts|...) for it to work. Below is what seems ideal in my head for end result.

Ideal in my head

import { Button, ButtonTokens } from '@my-lib';
import { palette } from '@my-lib/token'

const overrideStyles = stylex.createTheme(buttonTokens, {
    defaultBackgroundColor: palette.blue600.,
    defaultColor: palette.gray50,
    defaultBackgroundColorHover: palette.blue300
});

const SampleCode = () => {
    return <Button theme={overrideStyles}>Custom Themed</Button>;
};

Is this currently possible? Let me know if there is another discussion around this and I'll move this post. Thank you!

[nmn]

@tounsoo No this is not possible. Variables can only be exported from and imported from .stylex.(js|ts|...) files.

But something like this is possible:

import { Button, ButtonTokens } from '@my-lib';
import { palette } from '@my-lib/tokens/palette.stylex'

const overrideStyles = stylex.createTheme(buttonTokens, {
    defaultBackgroundColor: palette.blue600.,
    defaultColor: palette.gray50,
    defaultBackgroundColorHover: palette.blue300
});

const SampleCode = () => {
    return <Button theme={overrideStyles}>Custom Themed</Button>;
};

Note: the import ends with a .stylex.

This is important for the compiler to know that palette is an object of variables and should be treated as such.