Carbon: Sass architecture

[elizabethsjudd]

Summary

I'd like to discuss updating the Sass files to be more flexible for extending and white labelling Carbon components. Issues we are currently running into:

• More component specific variables to be available to extend Carbon.
  
  
  
  • e.g. We wanted to create a new scenario for button but the icon size was hard-coded so we had to copy and paste the value. If carbon were to update this we'd have to manually update our code as well. I'd like to see variables like $carbon-button-icon-size so that I can reference a variable in my Sass files.
  
  
• All colors for a component are defined in mixins
  
  
  
  • we need to change colors on a component by component basis, not just global UI tokens to allow for white labelling. Right now most of the colors for a button are defined in a mixin but the disabled, hover, focus states are not always in these mixins. I'd like all colors to be defined in a mixin for a given component/variant of a component so that I can easily define new colors for a component.
  
  

[joshblack]

cc @IBM/carbon-designers if you have thoughts around which parts to theme/configure. Specifically:

All colors for a component are defined in mixins

we need to change colors on a component by component basis, not just global UI tokens to allow for white labelling

@elizabethsjudd something that'd be awesome to learn more about is how the global tokens don't help out for this use-case as I don't think we've encountered that situation before. Would love to learn more about this 😄

[elizabethsjudd]

@joshblack the global tokens work great if the overall feel of the UI is the same as Carbon however when white labeling an application that feel may be completely different. For example, tables may have a different background or border in comparison to other components/page background. Modals or tooltips (dialogs) are another good area where I've seen this commonly. We never know what the design of the white labelled application needs to look like so we need to be flexible enough to allow for them to make as cohesive transition as possible.

WH also allows for inline (sub-application) theming so we need to be able to apply multiple different sets of colors for a component based on a class. The global UI tokens help when creating a global theme but then we don't have a way to reference the colors used for say the gray 90 theme in the white theme so we are forced to copy and paste these values and assign them to our own variables.

[aagonzales]

I open to the concept but I think this would be a big discussion. Maybe making it more white label flexible could be a v11 push?

[aagonzales]

Another concept we're working on is theme zones. So you can target different areas within the page page that calls a different theme (still just a concept). Kind of sounds like what your second comment was about.

[asudoh]

we need to change colors on a component by component basis,

It reminds of something like $accordion-border-color: $ui-03 approach, recalling some past discussions (or my past study) around theme tokens, with some benchmarking efforts. That said, wondering @aagonzales's "theme zone" idea is something like $some-zoned-theme-color: $ui-03 where accordion's border style can refer to $some-zoned-theme-color.

The same discussions/study revealed that the most scenario where something like @mixin button-theme work is components with color/size variants (e.g. danger/small buttons), instead of general-purpose component (or component set)-specific theming.

[elizabethsjudd]

@aagonzales This issue was meant to spark a larger discussion but the work is actually non-breaking so I'd prefer not to wait till a major release to start this process. We are actually blocked from using Carbon X due to these issues.

1. Use more variables instead of hard-coding values. Even if it's only used once in Carbon it may be valuable for a consumer to reference this value as they extend/customize Carbon.
2. Structure code in mixins that could then be called by consuming devs. Currently it looks like the majority of the code is already structured this way and I'm asking that we move the remaining color styles to also be in the mixins. These mixins are already being called by the components so the output wouldn't be changed.

The zoned-theming does sound like it could be similar to what we are currently offering via Watson Health. We although our developer to add a class to a component or a containing element that toggles that component/section to be a different theme. We are able to do this but defining each theme in unique variables so we can reference them separately from the global theme.

• High-level view of how we approach theming
• Global theme setup
• Component theme setup: variables and mixins

Seek preview: I'd like Carbon to offer their responsive views via mixins so we can define them based on the component size vs the view port size. Right now our components are changing sizes when we don't want them too but we have no way to turn off Carbon's default breakpoints

[asudoh]

I think the requirements contain several valid use cases and I'd like the team to discuss it further. Especially curious of what @aagonzales thinks "zoned theme" idea is in more detail.

Meanwhile - Given how close we are toward the v10 release, I don't think we have room for new structural changes esp. whose specification has to be sorted out in the team and the stakeholders, though having to do CSS-level customization (instead of Sass-level) is unfortunate.

[elizabethsjudd]

I understand waiting till the v10 release is done before starting as I know it's coming up very soon. What I'm asking for is not waiting till v11 to actually release these updates. They could be minor/patch fixes and could be done on a per-component basis to make it get in to production sooner while not creating a massive sweeping change to the system.

[asudoh]

Got it @elizabethsjudd - We have switched to a process with single branch for features/patches where we make changes non-breaking unless breaking changes is absolutely necessary. That said, the theme structure change should be non-breaking, too, and we can release it any time once we get stable/complete code. Consistency in codebase has become a bigger topic recently among our developers as well as our contributors/users, so I'd like all components covered in a single change, or at least "staged plan" being created.

[elizabethsjudd]

I'd be very interested in working with the team to come up with a staged plan. As I said, this is a blocker for Watson Health using Carbon X styles.

[asudoh]

Cool, please work with @mattrosno so he can connect you and our designers and get a common understanding of what our designers/developers think of the new theming architecture and outline the system design based on it. They as well as @mattrosno are busy with v10 work, and I suspect the substantial collaboration comes after. I understand you feel blocked on this, but I'd like careful work on creating the system design, which may be time-consuming.

[mattrosno]

@elizabethsjudd a couple questions.

Component variables

For whitelabelling, colors yes. Where do we draw the line on what else needs to live in component variables? In your experience building on top of Carbon, or when extending PAL in product, how often have you found yourself wanting to modify box model values as well? (E.g. content sizings, paddings, borders, margins?)

Inline theming

PAL's inline theming supports the default theme and an alternate theme, defined in Sass build. Carbon v10 has 4 themes: https://next.carbondesignsystem.com/guidelines/color/usage. If a product needed more than 2 themes/zones... any ideas on how to accomplish that without needing to define --alt2 and --alt3 in Sass?

[elizabethsjudd]

@mattrosno

Component variables

I totally get how this can become a rabbit hole and I definitely want to avoid that as much as possible. Typically the variables I'm looking for the most are things like icon size, font-sizes, and padding. The issue hasn't really been us wanting to overwrite or change them but instead we are extending what Carbon has to offer and want the extensions to match carbon without having to copy and paste the values.

Inline theming

You're correct that it's possible for someone to want to do more than 3 inline themes, but IMO at that point there might be a reason to look at why a design is having so many different themes within an application? Global themes are a separate matter and I think the likelihood of having more options is greater but within a single application I can't see the need for too many.

The ask isn't for Carbon to define the inline themes but to provide the option for applications to easily build them. Within WH we know that there are 2 common themes for our applications and so we intended to build them out for our offerings because we see the re-use internally. The ask is that Carbon provide the colors in mixins so that it's users can define X number inline themes with minimal code from the user's perspective

.theme-x button {
  @include buttonTheme(...)
}

Because Carbon provides 4 global themes it would be nice if each of those themes were defined as unique variables that could be referenced as well. WH is specifically looking at the white and g90 themes as our bases so we'd want to be able to reference colors from the g90 theme within the white theme when defining the inline-theme.

$white-button-background: #ddd; 
$g90-button-background: #fff;

[shixiedesign]

Hi @elizabethsjudd ! From what I gathered, the global theme variables are not flexible enough to achieve the look you want, so you'd like variables defined at the component level so you can target individual components for more granular control. Is that right? (jee we really should meet or set up a call!) That sounds very reasonable to me.
How about we get together to look at some specific WH use cases, and we explain zoning concept a bit more to you? Would you mind setting up a meeting for the folks involved here? Thanks!

[stale[bot]]

We've marked this issue as stale because there hasn't been any activity for a couple of weeks. If there's no further activity on this issue in the next three days then we'll close it. Thanks for your contributions.

[elizabethsjudd]

Not stale. This issue is blocking us from using Carbon 10.

[stale[bot]]

We've marked this issue as stale because there hasn't been any activity for a couple of weeks. If there's no further activity on this issue in the next three days then we'll close it. You can keep the conversation going with just a short comment. Thanks for your contributions.

[stale[bot]]

As there's been no activity since this issue was marked as stale, we are auto-closing it.

[mattrosno]

Not stale.

[stale[bot]]

We've marked this issue as stale because there hasn't been any activity for a couple of weeks. If there's no further activity on this issue in the next three days then we'll close it. You can keep the conversation going with just a short comment. Thanks for your contributions.

[elizabethsjudd]

Not stale

[stale[bot]]

We've marked this issue as stale because there hasn't been any activity for a couple of weeks. If there's no further activity on this issue in the next three days then we'll close it. You can keep the conversation going with just a short comment. Thanks for your contributions.

[stale[bot]]

As there's been no activity since this issue was marked as stale, we are auto-closing it.

[elizabethsjudd]

not stale