StyleXStyles and Developer Experience / Documentation

[BMCwebdev]

My use case: maintainer of a Design System and Component Library that is only used internally.

Specific workflow: A consumer of my library is expected to create a Stylex object and pass it back to the component. In this workflow, using StyleXStyles, the CSS properties would always be constrained. Their values may or may not be. We would not be looking to use this as a way for consumers to pass any arbitrary CSS property they wish back to the component.

Example Code:

export interface AcmeBoxProps {
  userStyles?: StyleXStyles<{
    backgroundColor: 'red' | 'blue' | 'green' | 'yellow' | 'purple';
  }>
}

export function AcmeBox({userStyles}: AcmeBoxProps) {
  return (
    <div
      {...stylex.props(
        userStyles,
      )}
    >
     ...
    </div>
  );
}

And the consumer of my library may use it like this

import { AcmeBox } from '@acme';

const styles = stylex.create({
  base: {
    backgroundColor: 'yellow',
  }
});

function App() {
  return (
    <AcmeBox userStyles={styles.base} />
  );
}

Why use StyleXStyles & stylex.create this way:

• I’m trying to avoid dynamic styles for obvious reasons. Additionally a company-wide Content Security Policy may be enacted that will disallow inline styles.
• The component may be something that is constrained to accept only a width CSS property, but the value can be anything the consumer needs. It can’t be constrained to pre-defined choices.
• Example Component: CSS Grid Layout Component. The grid-template-columns CSS property needs to accept any value from the consumer.

Where I run into a potential blocker in this flow is documentation, demonstrations, and developer experience. Conditional and Variant styles work great. They are just props, with typed options, and will get picked up automatically by Storybook. A consumer of my library can refer to the Storybook to see all the options (variants) available to them. They can also select one of the typed values from an auto-generated dropdown to see the resulting UI. While writing their app code, and using my component, consumers will get auto-complete and suggestions in their IDE for variant names and typed value options.

However, if I am expecting the consumer to pass in a Stylex style object, this won’t get picked up by Storybook automatically. There will be no developer experience of auto-complete or suggestions in the IDE. Even if I constrain my Stylex CSS properties and values (as in the first code snippet above). Rather the autocomplete/suggestions will just suggest (I believe) every CSS property that exists, and there is no feedback for the values.

The user will have to know that a style object is expected. They have to know what properties are allowed. They have to know what values are allowed if any. They will have to look back and fourth between wherever this is documented and their own code. And if that place is something like a Storybook, there should also be a way for them to input the value they want to use to see the resulting UI. (Again, the CSS properties would always be constrained.)

This is where I am at right now. I’m moving forward with trying to only use Conditional and Variant styles. However I feel that at some point I will hit this wall and will need to figure out a solution.

I am very curious as to what people working at Meta have been doing. I assume you roll your own documentation solution? When you use StyleXStyles with constrained options, how do you communicate that with the developers? Do you use StyleXStyles with constraints often? Or is it more of an open door to allow any CSS?

Thank you for all the insight and advice! I really hope seeing my user name pop up isn’t becoming a thorn in your side 😛

[BMCwebdev]

PS I am going to see what I can get Storybook to do. It will be ugly I'm sure, but it could be the start of something. Interesting how it looks out of the box

[nmn]

I don't see anything problematic or hard to read about that type definition.

[nmn]

I’m trying to avoid dynamic styles for obvious reasons. Additionally a company-wide Content Security Policy may be enacted that will disallow inline styles.

Use StaticStyles instead of StyleXStyles and it will disallow dynamic styles and hence inline styles.

The component may be something that is constrained to accept only a width CSS property, but the value can be anything the consumer needs.

You can use string | number as the value type.

export interface AcmeBoxProps {
  userStyles?: StaticStyles<{
    width: string | number;
    gridTemplateColumns: string;
  }>
}

(You can add null if you want the ability to unset default styles as well)

The user will have to know that a style object is expected. They have to know what properties are allowed.

You can export object types from your component and lean on Typescript's satisfies keyword to help the users of the component.

Component File:

export type AcmeStyleOverride = {
  backgroundColor: 'red' | 'blue' | 'green' | 'yellow' | 'purple';
};
export interface AcmeBoxProps {
  userStyles?: StaticStyles<AcmeStyleOverride>
}

export function AcmeBox({userStyles}: AcmeBoxProps) { ... }

Usage:

import type { AcmeStyleOverride } from '@acme';
import { AcmeBox } from '@acme';

const styles = stylex.create({
  base: {
    backgroundColor: 'yellow',
  } satisfies AcmeStyleOverride
});

function App() {
  return (
    <AcmeBox userStyles={styles.base} />
  );
}

As long as the users of the component type {} satisfies AcmeStyleOverride first, they should get help from Typescript.
Based on my testing using satisfies (and not as) may also error on extra properties.
However, since TypeScript doesn't support exact object types, using on it to catch extra properties is not reliable. We had to use some complex hacks in StyleXStyles and StaticStyles to error on extra properties.

I am very curious as to what people working at Meta have been doing...When you use StyleXStyles with constrained options, how do you communicate that with the developers?...

We don't constrain what styles can be passed in the general case, but there are many components that do. We don't have any special tooling for these types and we also use types that look like this:

  StyleXStyles<{ 
    backgroundColor: 'red' | 'blue' | 'green' | 'yellow' | 'purple'
  }>

This has never come up as a problem, and is generally easy to understand. We use the same types in our component documentation and it has not been a concern for us.