feat: add experimental contextual layout token system

[janhassel]

Implementation of #10619

Closes #10318
Closes #10617
Closes #13423

Contributes to #6202
Contributes to #7704
Contributes to #10616

---

This PR adds an experimental system for contextual layout tokens. These allow for layout contexts to change specific rendering settings that are applied to all components within a context. At the moment, these settings are size and density.

The system consists mainly of the sass module, but also offers a convenience component in React which can be used to create a new layout context.

The following example will set both Button as well as TextInput to use size = lg

<Layout size="lg">
  <Button />
  <TextInput />
</Layout>

The system is backwards compatible and components accepting a size prop will still render in the appropriate size. In addition, any component explicitly setting a size will use that over the layout context's setting:

The following example will render Button as sm and TextInput as lg.

<Layout size="lg">
  <Button size="sm" />
  <TextInput />
</Layout>

"Density" is an experimental new layout setting which can be set to condensed (defaults to normal). It will provide a preferred padding-inline value which is spacing-05 for normal and spacing-03 for condensed.

---

Components can use the sass functions to more easily access the layout context settings:

.cds--component {
  @include layout.use('size', $default: 'md');
  @include layout.use('density', $default: 'normal');

  height: layout.size('height');
  padding-inline: layout.density('padding-inline');
}

Components that use non-standard sizes can still participate in layout contexts by locally overriding the tokens. An example can be seen in the Tag styles.

See the updated packages/styles/docs/sass.md document for the full details.

In order to apply specific constraints to children components that might differ from their own preference, the <LayoutConstraint> utility component can be used. Like <Layout> all it does is setting class names.

An example of this use case is the icon-only content switcher. It uses IconButton under the hood which supports all sizes and defaults to lg. The ContentSwitcher though should only support sm->lg and defaults to md.

<div className="cds--component">
  <LayoutConstraint size={{ default: 'md', min: 'sm', max: 'lg' }}>
    {/* IconButton is now locked to the sizes sm->lg and defaults to md */}
    <IconButton … />
  </LayoutConstraint>
</div>

---

This PR includes migration for the following components:

• Accordion
• Button
  • percy highlights a bunch of visual differences between this PR and the current button implementation. This is because the current button implementation was actually differing from the visual specs (most noticeable the padding-inline was changing for each step below lg)
• ContainedList
• ContentSwitcher
• Tag
• TextInput

[netlify]

✅ Deploy Preview for carbon-components-react ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	d1f4291
🔍 Latest deploy log	https://app.netlify.com/sites/carbon-components-react/deploys/6479e4e7e4e11500086dc981
😎 Deploy Preview	https://deploy-preview-13287--carbon-components-react.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[netlify]

✅ Deploy Preview for carbon-elements ready!

Name	Link
🔨 Latest commit	d1f4291
🔍 Latest deploy log	https://app.netlify.com/sites/carbon-elements/deploys/6479e4e73d69ec0008356a49
😎 Deploy Preview	https://deploy-preview-13287--carbon-elements.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[alisonjoseph]

I'm seeing some visual breaking changes with this PR in Percy 👀

Tag

Copy Button

Button in File Uploader

Also in the icon content switcher, but looks like you confirmed above with Anna that is correct. 👍

[janhassel]

@alisonjoseph

• Tag
  • The default size for <Tag /> is md, but the default story was showing them in sm. This PR removed the explicit size override which is why they render in md now.
• CopyButton
  • Do you remember if CopyButton used to be md in v10 as well or is this also a regression by the difference in size for IconButton ([Bug]: IconButton size prop default should be lg #13423)?
• Button in FileUploader
  • The implementation of buttons in main currently differ from the visual spec: the padding-inline decreases for sizes sm and md. This PR includes a fix for these defects. Percy shows it in this story as the button in FileUploader is set to md

[alisonjoseph]

Thanks for clarifying @janhassel! Makes sense 😄
Looks like copy button was also md in v10 --> https://v7-react.carbondesignsystem.com/?path=/story/components-copybutton--default

[janhassel]

@alisonjoseph Ok, I wrapped CopyButton in a LayoutConstraint. Let me know if this works for you!

[andreancardona]

reviewed on my end and looks good - would just want a last pass / visual review

[janhassel]

@alisonjoseph @aagonzales Let me know if you have any questions!

[aagonzales]

Approved! Awesome work Jan!!! 🚀 🎉

[janhassel]

@alisonjoseph @aagonzales I think one of you still need to approve the changes in percy for all tests to pass