Proposal: Semantic and contextual size / spacing tokens

[janhassel]

Related: #10616, #10617, #7701

Motivation

As of right now, the different size variants of components are implemented on a per component basis. Each component that offers different sizes accepts a size prop which the consumer can set to one of the supported size options (mostly sm, md and lg). The component then adds a css class depending on the selected size, e.g. cds--text-input--lg, to define the specific styles (in most cases just setting the component's height).

This approach has some considerable drawbacks:

1. Duplicate code. Each component needs to implement their own...
   1.1 prop to accept a size
   1.2 logic to add a css class to the container
   1.3 css rules to apply the correct styles
2. Sizes are not standardized by code. Last year, the sizes have been manually standardized (Update Size Prop across components #8370) to ensure lg in Component A matches lg in component B. The sizes are however defined in rem for each component (e.g. .cds--text-input--lg { height: rem(48px); }). This means if size definitions were to change it would need to be updated in all occurances. Adding new size variants throughout the system is a good amount of work.
3. Wrapping components need to handle passing on the size prop accordingly. Reference: v11 Beta 3 #10247

Approach

While creating semantic size tokens like var(--cds-size-lg) would mitigate point 2 already, there is more potential in combining this with a contextual token system (similar to how color layering works in v11 now).
Most of the time, a consumer doesn't just need to adjust the size of one specific component but of a few adjacent components (as components in one group should always match in height).

When the sizing responsibility is outsourced to a utility component, points 1 and 3 could also be mitigated while reducing redundancy in the consumer's code.

Current implementation	Proposal
<Stack> <TextInput size="lg" ... /> <TextInput size="lg" ... /> <NumberInput size="lg" ... /> <Dropdown size="lg" ... /> </Stack>	<Layout size="lg"> <Stack> <TextInput ... /> <TextInput ... /> <NumberInput ... /> <Dropdown ... /> </Stack> </Layout>

At the same time, components would no longer need to individually support a size prop, handle the logic to add css classes and define their own styles. It would happen through contextual tokens:

Current implementation	Proposal
.cds--text-input { ... } .cds--text-input--sm { height: 2rem; } .cds--text-input--md { height: 2.5rem; } .cds--text-input--lg { height: 3rem; }	.cds--text-input { height: var(--cds-height); }

Design

All size tokens would be defined in :root (or wherever the theme is emitted) and the contextual token would be redefined by the utility component (<Layout> in the examples above though I'm not at all attached to the name).

:root {
  --cds-height-sm: 2rem;
  --cds-height-md: 2.5rem;
  --cds-height-lg: 3rem;

  /* setting a default */
  --cds-height: var(--cds-height-md);
}

.cds--layout--sm {
  --cds-height: var(--cds-height-sm);
}

.cds--layout--md {
  --cds-height: var(--cds-height-md);
}

.cds--layout--lg {
  --cds-height: var(--cds-height-lg);
}

This would solve the redundancy in code for individual components as well as making it easier for development teams to create custom components and compositions that adapt automagically to the rest of the UI.

Advancing the approach to spacing tokens

Since most components use the same spacing / padding logic to achieve alignment throughout the UI, these values would be an interesting candidate for semantic, contextual tokens as well. Instead of defining padding-left and padding-right to var(--cds-spacing-05) for each component, there could be a semantic alias like --cds-padding-x.

If this semantic token is now made contextual, building out a condensed zoning component (#10617) would be quite easy.

In the theme:

:root {
  --cds-padding-x-condensed: .5rem;
  --cds-padding-x-normal: 1rem;

  /* or even:
   *  --cds-padding-x-condensed: var(--cds-spacing-03);
   *  --cds-padding-x-normal: var(--cds-spacing-05);
   * */

  /* setting a default */
  --cds-padding-x: var(--cds-padding-x-normal);
}

.cds--layout--condensed {
  --cds-padding-x: var(--cds-padding-x-condensed);
}

In the component:

.cds--text-input {
  height: var(--cds-height);
  padding-left: var(--cds-padding-x);
  padding-right: var(--cds-padding-x);
}

As a consumer:

<Layout size="xs" breadth="condensed">
  <Stack>
    <TextInput ... />
    <TextInput ... />
    <NumberInput ... />
    <Dropdown ... />
  </Stack>
</Layout>

This design also leaves room for a potential wide layout mode as all it would take is one additional css custom property and css rule handling it. All components would support it out of the box.

padding-x is only one of many opportunities to standardize the way components are rendered and each one will make it easier for development teams to implement custom components and compositions that strictly follow Carbon components.

Demo

Here is a quick codepen of how it could work: https://codepen.io/janhassel/pen/gOXryGZ/87b8dd253d26231bfa573d4a6c90f93e?editors=1100

Potential issues

1. What about components that have different default sizes (think of TextInput with md vs. Button with lg for example)?
2. Could wrapping your component inside a <Layout> component be too confusing or verbose for some developers when they actually only need to adjust the size of one component?
3. How to limit some size variants to components that shouldn't support them (e.g. TextInput probably shouldn't exist as 2xl where a Button needs to when they're in a modal)

---

Overall, as a consumer of the Carbon Design System and someone that regularily develops custom components this would be such a big help to ensure my components and application will always be aligned with the standard Carbon ones and they would grow together with the system (refering to the example above with condensed or wide UI zones) without me actively needing to add support.

I'm very excited about the amount of opportunities for a truly adaptive and smart design system a technology like css custom properties actually opens and I'd love y'alls thoughts and feedback on this.

[tw15egan]

I love this idea. I think adding size tokens would go a long way in terms of the maintainability of components that use the size prop, as well as future components or sizes we will need to implement.

[tay1orjones]

Very very into this idea. The potential issues you describe seem to point to still needing size props on the components, but I'd love to not have to go that route.

[joshblack]

@janhassel thanks for taking the time to write this up! I really appreciate the proposal and the level of detail that went into it.

Parts of this sound similar to the idea of container tokens, in a way, which may be worth resurrecting. If I remember that concept right it was a sequential scale: container-01, container-02, etc. that could also be extended to semantic names like container-input or t-shirt sizes container-sm.

Another similar idea in this space was if we could ever want to "inline theme" the spacing scale, but that always seems to impact more things than we would like 🤷 . The idea was that this could make it easy to have different "modes" like condensed, default, cozy.

Anyways, I definitely want to read more into this and more notes next week but just wanted to leave some thoughts on some of the questions or concerns that you brought up in the interim 👀

---

Could wrapping your component inside a component be too confusing or verbose for some developers when they actually only need to adjust the size of one component?

I do think that we need to be able to support:

• Being able to set the value for all components that care about it (like size), great for layouts
• Being able to set the value for an individual component for a prop, great for one-offs
• Being able to override the contextual value on an individual component through a prop, great for overrides

Here's a quick codesandbox that models this idea: https://codesandbox.io/s/exciting-clarke-ebr0q?file=/src/App.js

How to limit some size variants to components that shouldn't support them

Totally get what you mean. Since components have different size domains, we also can run into a situation where:

• Given an "xlg" layout
• And a component, A, with sizes: [sm, md, lg] (default md)
• And a component, B, with sizes: [sm, md, lg, xlg] (default md)

Component B can map to xlg, but component A may need to map to the "largest" size (lg)

padding-x is only one of many opportunities to standardize the way components are rendered and each one will make it easier for development teams to implement custom components and compositions that strictly follow Carbon components.

Super small note, I think we'll align to the CSS logical properties naming scheme as we invest more into CSS Custom Properties / component tokens. Specifically inline and block.

[janhassel]

Thank you for your feedback, @joshblack!

---

I think bringing back / introducing the container tokens would be a good first step and seems like a low-hanging fruit. Was there a reason to not pursue them before?

---

Another similar idea in this space was if we could ever want to "inline theme" the spacing scale...

Funny, this is exactly what @tw15egan, @aagonzales and I have discussed for #10617 👀
If there is any way in which I can help figuring these problems out, please let me know!

---

In regards to your two points about the size value propagation and size limits: I would love to see this being a CSS-only implementation.

I guess the first one could be treated as a useful utility component for framework users while vanilla users could still set the css class (e.g. cds--layout--lg) manually.

Assuming the supported sizes are always consecutive, could we use clamp to implement the size limits?

.cds--text-input {
  height: clamp(var(--cds-height-sm), var(--cds-height), var(--cds-height-lg));
}

---

Super small note, I think we'll align to the CSS logical properties naming scheme...

Yes, 100% agree! I still forget about the logical properties way too often. Thanks for pointing that out!

[tay1orjones]

Just want to update - the initial PR is up here: #13287