Approaches for Theme and Component Customization

[origami-z]

To customize Apps at the theme level, there are different ways to achieve through code. We want to gather the how as well as pros and cons.

Scenario 1: I want all my CTA Buttons to be in purple (in both theme/modes)

Approach a: with --saltButton-background

.customTheme .saltButton-cta {
    --saltButton-background: purple;
}

Although --saltButton-background is defined to be used for .saltButton, we can't just provide the color to the theme otherwise all variants (CTA/primary/secondary) would be impacted. So there is a cross-reference shared knowledge between the theme and the component structure.

This approach means the user's code is tied to both classnames (.saltButton-cta) as well as CSS variable API (--saltButton-background)

Approach b: with --salt-actionable-cta-background

.customTheme.saltTheme {
    --salt-actionable-cta-background: purple;
}

This follows how Salt defines theme, where characteristics (actionable in this case) are defined separately than components. However this does mean our consumer needs to fully understand the the structure of the theming system.

This relies on characteristic variable (--salt-actionable-cta-background) alone, which means our components needs to be designed to have such variable exposed/consumed, e.g., button border radius is not at the moment.

Approach c: wrap with custom class

.customButton.saltButton-cta {
    background: purple;
}

Offer a CustomButton by wrapping Salt Button, so it's isolated but no longer tie to the theme anymore.

• makes breaking changes through classname/DOM structure more likely. @libertymayc

Scenario 2: I want additional border at the bottom of my Accordion

Current Accordion only supports top border, so adding a new bottom border can only be done through wrapping with new class name.

.customAccordion.saltAccordion {
  border-bottom: var(--salt-size-border) var(--salt-separable-borderStyle) var(--salt-separable-tertiary-borderColor);
}

Salt won't be offering every properties to be overridable, so addressing unknown requirement purely in theme won't be feasible for all use cases.

Scenario 3: I want additional variants for Button

Additional variants (e.g. foo, bar) on top of CTA, primary and secondary would be only possible through wrapping a component. However, whether how much of the customization should be component specific or at the theme level is a case-by-case consideration.

Approach a: create new actionable characteristics variables and use in Button with new class name

/** Theme.css */
.customTheme {
    --custom-actionable-foo-background: purple;
    --custom-actionable-bar-background: orange;
}

/** CustomButton.css */
.customButton-foo {
  --button-background: var(----custom-actionable-foo-background);
}
.customButton-bar {
  --button-background: var(----custom-actionable-bar-background);
}

Given foo/bar actionable is an extension, prefix are chosen to be not using --salt and it can be scoped without .saltTheme to work. Also note that the use of --button-background v.s. --saltButton-background, where it's likely the result if our user is copying code and structure from Button.css.

Approach b: add button specific overrides

Although Salt button variants are tied to actionable characteristics, that's not necessarily the case for an App needs override.

/** CustomButton.css */
.customButton-foo.saltButton {
  --saltButton-background: purple;
}
.customButton-bar.saltButton {
  --saltButton-background: orange;
}

Potentially --button-background would also work, or even just background. Which one to recommend depends on our recommendation.

Scenario 4: I want border radius for Button

Unlike above scenario, although border radius is not part of theme, Salt Button has --saltButton-borderRadius API available which defaults to 0.

From recent discussion, the choice of which property to have component CSS variable API feels a bit random. We should make it more formal, e.g., one proposal is that only tokens from the theme should have corresponding CSS API.

.customButton.saltButton {
    --saltButton-borderRadius: 8px;
}

From above code, both class name (.saltButton) and component CSS variable API (--saltButton-borderRadius) is used, so both need breaking change management.

Summary

• A lot scenarios have both theme level and component level customization, where only using Salt theme overrides is usually not enough to cover all use cases
• Component customization usually triggers dependencies on class name and CSS variable API, which increases the landscape of breaking change maintenance.

Discussions

• what's the pros and cons of having local variables (e.g. --button-background)?
• which choice(s) of API would make it less error-prone for our consumer to upgrade between theme and/or component versions (and/or is important as they can be updated independently in theory). Is there anything else we can leverage other than API design to help, e.g. leverage TypeScript to have a classes API, so any class name change can be detected.
• in storybook we currently list in the component pages the characteristics used, but the characteristics pages ideally should list what components consume it @libertymayc
• benefit / downside of using border property (short-hand) @Fercas123
• Near term tooling/utils to help consumer manage their theme, e.g. reuse our token naming linting rule. @libertymayc
• Scope of theme, dependency between theme and component specific properties. Example: Ultimate flexibility button token in theme @el-dav
• v1 theme feature, only customisation? with extension in mind? with icon set included? with component as well?
• If any breaking change is needed, is there any possibilities to create breaking change to only theme or only component but not both?

[libertymayc]

additional thoughts on some of the points in these scenarios:

Scenario 1: I want all my CTA Buttons to be in purple (in both theme/modes)

Approach a: with --saltButton-background

Although --saltButton-background is defined to be used for .saltButton, we can't just provide the color to the theme otherwise all variants (CTA/primary/secondary) would be impacted. So there is a cross-reference shared knowledge between the theme and the component structure.

This approach means the user's code is tied to both classnames (.saltButton-cta) as well as CSS variable API (--saltButton-background)

This is an interesting one on how we have implemented the CSS API. Atm, I have noticed this isn't standardised as much as it should be even though we have tried to, so it needs looking at on a per-component basis once we figure out what solution to take. It differs even in Button itself, where we use --saltButton-background in the root class (.saltButton) as to expose only one token, and our --button-background local token changes value within the variant classnames (e.g. .saltButton-cta).

However, when it then comes to state based classes/pseudoclasses such as .saltButton-disabled, we then expose --saltButton-background-disabled rather than changing the --button-background here like in variants. I believe this is to make sure the attribute defined in the disabled class definitely takes precedence.

One solution to needing the user to tie both to classname and CSS variable is providing e.g., --saltButton-primary-background, --saltButton-cta-background, --saltButton-secondary-background so that users can define that at a top level in .customTheme, but this then bloats up our code with more API tokens for each case. Both seem unideal.

Approach b: with --salt-actionable-cta-background

This follows how Salt defines theme, where characteristics (actionable in this case) are defined separately than components. However this does mean our consumer needs to fully understand the the structure of the theming system.

This relies on characteristic variable (--salt-actionable-cta-background) alone, which means our components needs to be designed to have such variable exposed/consumed, e.g., button border radius is not at the moment.

To emphasise, this will require work from design to extend the theme and provide e.g. a border-radius foundation (which I think is in the pipeline eventually) as well as a concrete decision on the theme being in a stable place - so this would potentially require more thought and dedicated work than approach a
... also, that then begs the question should foundations be customisable when we are going to probably document customising the theme via the characteristics/palette - although spacing would likely also be customised ... although, border-radius is one where it would arguably be added to actionable itself (@pseys ?).

Approach c: wrap with custom class

Offer a CustomButton by wrapping Salt Button, so it's isolated but no longer tie to the theme anymore.

General note: makes breaking changes through classname/DOM structure more likely.

Scenario 2: I want additional border at the bottom of my Accordion

Current Accordion only supports top border, so adding a new bottom border can only be done through wrapping with new class name.

Salt won't be offering every properties to be overridable, so addressing unknown requirement purely in theme won't be feasible for all use cases.

Imo, I think the approach for this scenario is fine and is what we can move forward with. It's almost like adding a new feature to the design, rather than changing an existing style of our component design (color, border width etc) alon.

Scenario 3: I want additional variants for Button

Approach a: create new actionable characteristics variables and use in Button with new class name

Given foo/bar actionable is an extension, prefix are chosen to be not using --salt and it can be scoped without .saltTheme to work. Also note that the use of --button-background v.s. --saltButton-background, where it's likely the result if our user is copying code and structure from Button.css.

Another interesting one, do we allow (encourage) for our local tokens --button-.. to be used when theme/variants are extended? Or should it be that in these classes they create, they actually use the API token?

Plus, if they are extending variant, potentially could cause issues depending on what loads in first, i.e. will they need to be more specific on the default variant, making this actually .saltButton-primary.customButton-foo ?

Approach b: add button specific overrides

Although Salt button variants are tied to actionable characteristics, that's not necessarily the case for an App needs override.

This one will depend on how well we document the theme. Will be important for users to understand what components use actionable/what the actionable characteristic affects (documenting both ways <->, i.e., in storybook we currently list in the component pages the characteristics used, but the characteristics pages ideally should list what components consume it). This education may let the user tie together their customisations (e.g., user wants to change color of ToggleButton and secondary variant Button etc - realising actually changing theme like approach a would be better in this use case, but if they wanted to change only secondary variant Button and ToggleButton not being affected, approach b is better).

Potentially --button-background would also work, or even just background. Which one to recommend depends on our recommendation.

See above comment on approach a

Scenario 4: I want border radius for Button

From recent discussion, the choice of which property to have component CSS variable API feels a bit random. We should make it more formal, e.g., one proposal is that only tokens from the theme should have corresponding CSS API.

Agreed. Ideally need designers to look on per-component basis on what can be customised which will require potentially a lot of research/effort. cc @bhoppers2008

From above code, both class name (.saltButton) and component CSS variable API (--saltButton-borderRadius) is used, so both need breaking change management.

I don't think .saltButton classname would be needed here (think you mentioned why in meeting, can't remember if you could add why it's necessary?)

[Fercas123]

Notes from current POC implementation, which will benefit and probably change from this conversations.

Scenario 1

For this scenario , we are currently overriding at a theme level (option b).
About the non exposed variables (like border-radius), we are only using component level variables for cases in which overriding a theme level variable would not be enough, like --saltIcon-size when --icon-base-size is not enough for us to go below 12px.
The way we are currently addressing values that are not in theme, is adding a variable in our theme and using it in the CSS prop

--customTheme-border-radius: 20px;

and adding it to the component

 border-radius: var(--customTheme-border-radius);

having this as a variable would be useful but it doesn't represent a lot of benefit as it would mean a lot of variables would need to be declared.

Scenario 2

For this one, I think it would be beneficial to think on how we use CSS shorthands. In the case of borders, where we declare a border

  border: var(--salt-size-border) var(--salt-container-borderColor-style) var(--salt-container-primary-borderColor);

splitting this to having border-width and border-color would allow the width to swap the position of the border without having to tie the custom theme to a salt class.

[libertymayc]

following @Fercas123 comment

About the non exposed variables (like border-radius), we are only using component level variables for cases in which overriding a theme level variable would not be enough, like --saltIcon-size when --icon-base-size is not enough for us to go below 12px.

This is quite a unique one where it's the local token --icon-size enforcing a max on the multiplier*theme variable. Thinking about this a bit, we could actually change the 12px to be a minimum icon size in the theme (--salt-icon-size-minimum), otherwise, even when teams create new themes, the component is going to give a limitation on that token based on what we are saying is minimum, so customising the theme would be pointless and it seems a bit unclean.

The way we are currently addressing values that are not in theme, is adding a variable in our theme and using it in the CSS prop

--customTheme-border-radius: 20px;

We would have a lint rule in Salt for this to convert it to -borderRadius (CSS attributes always camel case). I wonder if we should document the rules (doc'd in confluence) for consumers when creating their tokens, so that they appear more similar to ours, which could make code look cleaner overall?

and adding it to the component

 border-radius: var(--customTheme-border-radius);

I think this is ok for now in what we don't have in the theme, and when we eventually have border radius foundation (or e.g. ..--salt-actionable-borderRadius characteristic), users can replace this with the tokens we provide

having this as a variable would be useful but it doesn't represent a lot of benefit as it would mean a lot of variables would need to be declared.

do you mean having a border radius API token on the component or as you've done above?

For this one, I think it would be beneficial to think on how we use CSS shorthands. In the case of borders, where we declare a border

  border: var(--salt-size-border) var(--salt-container-borderColor-style) var(--salt-container-primary-borderColor);

splitting this to having border-width and border-color would allow the width to swap the position of the border without having to tie the custom theme to a salt class.

that's interesting too - I think it depends on how strict we want to be with the design being the border at the bottom. I see this as one that highlights why it's important for design to look on a per-component basis and decide whether we would want to go this way as is, or to provide the border width token for users to place it in different positions.
In general, it probably is better to not use shorthands where we can to provide more flexibility. That being said, could it just be border-width set here regardless if that's the only thing changing?

 border-width: var(--salt-size-border) 0 0 0;

[el-dav]

Thanks for putting this together

My view is that if we can allow theming/component customisation primarily through css variables, this in theory provides the most flexibility and the easiest change management. However the caveat is that to do this effectively requires many more css variables which would be unmanageable without investment in tooling.

With regards to the proposed scenarios:

Scenario 1: I want all my CTA Buttons to be in purple (in both theme/modes)

Prefer Approach B, but there is an additional approach which is we could provide an additional variable in our theme:

--salt-button-cta-background: var(--salt-actionable-cta-background);

This would allow consumers to target cta buttons without affecting other actionable components, if this is something we wanted to support for ultimate flexibility.

Scenario 2: I want additional border at the bottom of my Accordion

Could be simplified with an additional variable e.g. we provide an extra variable such as:

--salt-accordion-border: var(--salt-size-border) var(--salt-separable-borderStyle) var(--salt-separable-tertiary-borderColor);

Then consumers could use:

.customAccordion.saltAccordion {
  border-bottom: var(--salt-accordion-border);
}

Again this would increase the amount of variables.

Scenario 3: I want additional variants for Button

Probably prefer Approach B which feels more inline to how we add variants ourselves, and I see consumer variants as extending our theme/styling

Scenario 4: I want border radius for Button

Worth mentioning that with the approach of only including overrides for theme variables, we can still support things like border-radius on button, but it means taking a view that border-radius: 0 is actively part of our theme and we should therefore have characteristics/tokens for it.

[libertymayc]

some thoughts in reply to @el-dav :)

Prefer Approach B, but there is an additional approach which is we could provide an additional variable in our theme:

--salt-button-cta-background: var(--salt-actionable-cta-background);

This would allow consumers to target cta buttons without affecting other actionable components, if this is something we wanted to support for ultimate flexibility.

I (and I can probably speak for design) would be against tying components to the theme. It's good to have the theme as a standalone that could be used even for another set of components thats not Salt, a product in its own right. Though, this is basically the local token --button-background, I think it may make more sense to change how we implement the local tokens if we want to go via css api, to add more flexibility, i.e. having either an API token overriding all the locals (I feel this would be easier to track tokens ourselves, although it makes it pretty messy: token: var(token, var(token)) potentially isnt so easy to read

.saltButton-cta { --button-background: var(--saltButton-cta-background, var(--salt-actionable-cta-background); }

or directly defining the background in each class itself and getting rid of the local token

.saltButton-cta { background: var(--saltButton-cta-background, var(--salt-actionable-cta-background); }

it would increase API tokens, but decrease local...

Worth mentioning that with the approach of only including overrides for theme variables, we can still support things like border-radius on button, but it means taking a view that border-radius: 0 is actively part of our theme and we should therefore have characteristics/tokens for it.

agreed - and I think that is designs POV too (see above comments)

[lukeac123]

additional thoughts on some of the points in these scenarios:

Scenario 1: I want all my CTA Buttons to be in purple (in both theme/modes)

Approach a: with --saltButton-background

Although --saltButton-background is defined to be used for .saltButton, we can't just provide the color to the theme otherwise all variants (CTA/primary/secondary) would be impacted. So there is a cross-reference shared knowledge between the theme and the component structure.
This approach means the user's code is tied to both classnames (.saltButton-cta) as well as CSS variable API (--saltButton-background)

This is an interesting one on how we have implemented the CSS API. Atm, I have noticed this isn't standardised as much as it should be even though we have tried to, so it needs looking at on a per-component basis once we figure out what solution to take. It differs even in Button itself, where we use --saltButton-background in the root class (.saltButton) as to expose only one token, and our --button-background local token changes value within the variant classnames (e.g. .saltButton-cta).

However, when it then comes to state based classes/pseudoclasses such as .saltButton-disabled, we then expose --saltButton-background-disabled rather than changing the --button-background here like in variants. I believe this is to make sure the attribute defined in the disabled class definitely takes precedence.

One solution to needing the user to tie both to classname and CSS variable is providing e.g., --saltButton-primary-background, --saltButton-cta-background, --saltButton-secondary-background so that users can define that at a top level in .customTheme, but this then bloats up our code with more API tokens for each case. Both seem unideal.

Approach b: with --salt-actionable-cta-background

This follows how Salt defines theme, where characteristics (actionable in this case) are defined separately than components. However this does mean our consumer needs to fully understand the the structure of the theming system.
This relies on characteristic variable (--salt-actionable-cta-background) alone, which means our components needs to be designed to have such variable exposed/consumed, e.g., button border radius is not at the moment.

To emphasise, this will require work from design to extend the theme and provide e.g. a border-radius foundation (which I think is in the pipeline eventually) as well as a concrete decision on the theme being in a stable place - so this would potentially require more thought and dedicated work than approach a ... also, that then begs the question should foundations be customisable when we are going to probably document customising the theme via the characteristics/palette - although spacing would likely also be customised ... although, border-radius is one where it would arguably be added to actionable itself (@pseys ?).

Approach c: wrap with custom class

Offer a CustomButton by wrapping Salt Button, so it's isolated but no longer tie to the theme anymore.

General note: makes breaking changes through classname/DOM structure more likely.

• Approach A&C here are component level overrides and both require wrapping of the Button.

• Approach C I think this is the fastest for users to implement, but is the least scalable / reusable across an application.

• Approach A is a good middle ground for a user to add these to theme and not have to wrap the component.

• Approach B is the most scalable and can be extracted to a higher level theme and styling changes can occur in a single place and cascade down through multiple components. Although this is potentially the most susceptible to theme changes and has the longest learning curve for users i think it's the best approach.

• @libertymayc Regarding exposing --saltButton-background-disabled and not overwriting --button-background isn't this to enable us to have a fallback style, or am i misunderstanding ?

Scenario 2: I want additional border at the bottom of my Accordion

Current Accordion only supports top border, so adding a new bottom border can only be done through wrapping with new class name.
Salt won't be offering every properties to be overridable, so addressing unknown requirement purely in theme won't be feasible for all use cases.

Imo, I think the approach for this scenario is fine and is what we can move forward with. It's almost like adding a new feature to the design, rather than changing an existing style of our component design (color, border width etc) alon.

Scenario 3: I want additional variants for Button

Approach a: create new actionable characteristics variables and use in Button with new class name

Given foo/bar actionable is an extension, prefix are chosen to be not using --salt and it can be scoped without .saltTheme to work. Also note that the use of --button-background v.s. --saltButton-background, where it's likely the result if our user is copying code and structure from Button.css.

Another interesting one, do we allow (encourage) for our local tokens --button-.. to be used when theme/variants are extended? Or should it be that in these classes they create, they actually use the API token?

Plus, if they are extending variant, potentially could cause issues depending on what loads in first, i.e. will they need to be more specific on the default variant, making this actually .saltButton-primary.customButton-foo ?

Approach b: add button specific overrides

Although Salt button variants are tied to actionable characteristics, that's not necessarily the case for an App needs override.

This one will depend on how well we document the theme. Will be important for users to understand what components use actionable/what the actionable characteristic affects (documenting both ways <->, i.e., in storybook we currently list in the component pages the characteristics used, but the characteristics pages ideally should list what components consume it). This education may let the user tie together their customisations (e.g., user wants to change color of ToggleButton and secondary variant Button etc - realising actually changing theme like approach a would be better in this use case, but if they wanted to change only secondary variant Button and ToggleButton not being affected, approach b is better).

Potentially --button-background would also work, or even just background. Which one to recommend depends on our recommendation.

See above comment on approach a

Approach A - I'd recommend this If an additional variant or validation status is needed across multiple components
Approach B - for simplicity if it's just for one if only a single component needs an extra variant. I'd also just override using background: 'purple'. I see no reason to link this to the theme.

Scenario 4: I want border radius for Button

From recent discussion, the choice of which property to have component CSS variable API feels a bit random. We should make it more formal, e.g., one proposal is that only tokens from the theme should have corresponding CSS API.

Agreed. Ideally need designers to look on per-component basis on what can be customised which will require potentially a lot of research/effort. cc @bhoppers2008

From above code, both class name (.saltButton) and component CSS variable API (--saltButton-borderRadius) is used, so both need breaking change management.

I don't think .saltButton classname would be needed here (think you mentioned why in meeting, can't remember if you could add why it's necessary?)

[libertymayc]

@libertymayc Regarding exposing --saltButton-background-disabled and not overwriting --button-background isn't this to enable us to have a fallback style, or am i misunderstanding ? - @lukeac123

you're right, I confused myself because we treat variants and state slightly differently - I guess what I meant to say is the bit below that comment I made (the thought it eluded to 😄 )

[mark-tate]

this was a maintainers discussion, closing due to inactivity

[mryechkin]

Hi there. Just curious if the team landed on one particular pattern from this discussion? We are going through something similar in our component library, and I'd love to know if you had any user feedback or found one pattern to work better over another. Appreciate any insight!

[origami-z]

Not yet. It will discussed and documented in the next few months