How to creating a <Box /> component.

[taylorpreston]

Describe the feature request

I would love if there was some documentation on how to create a component that are often at the root of design systems if it is possible.

We want 0 runtime css with a props driven component api like this.
<Box p={{base: 0, md: "14" }>Hello World</Box>

[zaydek]

@taylorpreston I actually went through a thought evolution like this, but where I ended up is not as generalizable as you're imagining. Instead, if I find myself repeating the same properties over and over again, I can make it a component that accepts the style arguments as component arguments like <Row gap={...}> and I can extend it with arbitrary styles like <Row _styles={...} gap={...}>. Instead of exposing all possible CSS properties to <Row>, I only expose the most relevant ones. And still, <Row> can be arbitrarily extended using _styles.

My overall realization is that a <Box> component is that if it can do too many things, it won't do any one thing well. In general, I heavily rely on StyleX's stylesheet API. I've come to really enjoy it, but every now and then it's good to have general layout components.

Furthermore, the Sx.createComponent is somewhat similar to Styled Components but a little different. The idea is you first declare your styles like you would in StyleX, then, if you need to, you can quickly wrap them up as components that accept style arguments like <Text textAlign="center"> instead of <Text _styles={styles.textAlignCenter}>. I try to solve the 80% use case and just use the stylesheet API for everything else. I find they work really well together.

I don't have enough time to explain how it works right now, but I'll paste some relevant code. If this sparks any interest, just let me know.

https://gist.github.com/zaydek/9dd8746abd26dce5d0044fb329f7e079

[nmn]

@taylorpreston A generic Box component can be created but what is not supported is the configuration on a per-breakpoint basis.

This often becomes an anti-pattern when trying to implement responsive layouts. Your design system should include a set of "values". Those values should change based on the viewport breakpoints internally. You should not be mixing and matching arbitrary values for different viewport breakpoints when using the Box component.

So, I would recommend something like the following instead:

<Box p="sm_fixed">Hello World</Box>
<Box p="sm"_scaling>Hello World</Box>

function Box({p, ...props}) {
  return <div 
    {...stylex.props(styles.base, paddingStyles[p])}
    {...props}
  />;
}

const styles = styles.create({
  base: {boxSizing: 'border-box'},
});

const TABLET = '@media (min-width: 768px) and (max-width: 1279.9px)';
const DESKTOP = '@media (min-width: 1280px)';

const paddingStyles = stylex.create({
  sm_fixed: {padding: 4},
  sm_scaling: {
    padding: {
      default: 4,
      [TABLET]: 8,
      [DESKTOP]: 16,
    },
  },
  md_fixed: {padding: 8},
  ...
});

Basically, you should have an opinion about which values belong together ahead of time in your design system.

For example, sm_scaling above is 4px, 8px and 16px on different breakpoints. This is guaranteed to be consistent. Allowing arbitrary values is error prone and it becomes easier to accidentally forget to provide a value for a certain breakpoint or to not be consistent with the design on how those values fit together.

I think a more locked down design system with named values such as sm are preferrable, but you can allow a larger set of value combinations if you prefer as well:

const TABLET = '@media (min-width: 768px) and (max-width: 1279.9px)';
const DESKTOP = '@media (min-width: 1280px)';

const paddingStyles = stylex.create({
  '2': {padding: 2},
  '2-4-8': {
    padding: {
      default: 2,
      [TABLET]: 4,
      [DESKTOP]: 8,
    },
  },
  '4': {padding: 4},
  '4-8-16': {
    padding: {
      default: 4,
      [TABLET]: 8,
      [DESKTOP]: 16,
    },
  },
  ...
});

This approach is less prescriptive but it still gives you a consolidated place to see all the way the values may be used together and let's the Box component ensure consistency.

---

Combining the values under various breakpoints into a single atomic value can feel restrictive at first. Specially when coming from other styling solutions. But, over time it enforces much better design consistency, encourages good practices for responsive design and makes style composition more predictable and simpler to deal with. (You don't have to manually unset styles for every break point. Setting padding: 0 is enough to set all padding to 0.)

Additionally, this also makes the styling more consistent and reliable across classNames, inline styles and React Native.

[zaydek]

Wait @nmn this is a pattern I haven't really seen or explored before. So instead of using CSS variables defined with defineVars instead you are suggesting you can also export token-level styles like paddingStyles and use them to compose something like a Box component? Is this a pattern you actually use or just something you thought up in service of the OP?

I would think something like this would be a little unwieldy since the stylex.include API is not recommended (from what I can tell) and that means that all styling merging needs to happen in stylex.props and not stylex.create. Not sure, what do you think?

My thinking is token coordination should simply be handled by theme variables like defineVars and in the case of breakpoints or variants you simply define accompanying tokens like theme.paddingInline and theme.paddingInlineMobile or theme.paddingInlineDesktop. Obviously, those tokens need to be implemented in stylex.create but it also gives you the flexibility of only using overrides when you need it (as to forced), which feels more compositional.

[nmn]

CSS variables and what is being asked in this question are separate questions IMO.

We don't really use any component that is this flexible as I think this is just a bad abstraction over being able to just write styles. Yet, I see a lot of questions about doing something like this so I suggested something as close to the original ask as possible that made sense.

IMO, with StyleX, the better solution is to just use Prop types on a Box component and let users pass in styles as needed.

[zaydek]

OK much appreciated. I just wanted to make sure my worldview was mostly aligned.

[taylorpreston]

I know it is kind of opinion territory, but why do you find a <Box /> to be a bad abstraction @nmn?

In my mind as long as you can get type safe tooling in your styles, isn't working as close to the JSX a better experience?

What I find in my work is I want a set of components that don't change much and small set of variants like buttons, form inputs, and typography and then I want a set of really flexible layout components that can take responsive props. For me something like a <Box />, <Flex />, or <Stack /> that take can take props makes it really easy to reason about the UI and handle responsive styling.

What I am also thinking is that maybe these two flavors aren't that different at this level of abstraction and it is more about where you like to define your styles.

<Flex direction="row" gap="12px" width="100%">
or
<Box display="flex" direction="row" gap="12px" width="100%">

Isn't that different from the stylex flavor in practice.

stylex.create({ base: { display: "flex", flexDirection: "row", "gap", width: "100%" }})

I think most engineers would know what is going on in both cases?

[nmn]

@taylorpreston The larger discussion is subjective but there are certain not-so-subjective ways we can discuss this.

isn't working as close to the JSX a better experience?

This is a subjective question, but in the context of StyleX I would say having one way to do styling is generally better than having two ways to do styling.

So even though the JSX form isn't that different from the stylex flavor, I think it adds cognitive overhead to have to learn and use two different syntaxes rather than just one.

why do you find a to be a bad abstraction?

My my main objection to components such as Box, Flex or Stack as described in your example is that they are too flexible to the point that they're just a different syntax around being able to write HTML and styling directly. They don't add value. Components should either have some custom behavior, enforce certain constraints or not exist at all. These components do nothing but change the syntax.