feat: add theming feature to elements

[tjuanitas]

This change adds a new component ThemingStyles to the root of the elements to enable customers to configure theming for components that utilize Blueprint.

• ThemingStyles expands on Blueprint's BrandingStyles implementation and allows developers to overwrite any blueprint tokens using a configuration object.
• Customers can pass a theme object which will be transformed into CSS properties that are scoped to the element:

// Configuration passed into the UI Element
{
    tokens: {
        Label: {
            Bold: {
                fontSize: '0.625rem',
                fontWeight: '700',
                letterSpacing: '0.0375rem',
                lineHeight: '1rem',
                paragraphSpacing: '0',
                textCase: 'none',
                textDecoration: 'none',
            },
            ...
        }
    }
}

// Output inserted in the DOM stylesheet
#bce_[...] {
    --label-bold-font-size: 0.625rem;
    --label-bold-font-weight: 700;
    --label-bold-letter-spacing: 0.0375rem;
    --label-bold-line-height: 1rem;
    --label-bold-paragraph-spacing: 0;
    --label-bold-text-case: none;
    --label-bold-text-decoration: none;
    ...
}

The structure of the passed theme configuration object is not strict and allows for different structured inputs providing the same output. The intended structure is based on how our internal design team defines the levels of the tokens but users can also provide a flattened structure if preferred. DevRel will provide a template theme configuration that customers can modify in order to utilize this feature. In the future, there are goals to build a theme builder that will help developers build a config through a user interface.

Reference: https://www.npmjs.com/package/@box/blueprint-web-assets

• List of CSS properties that can be overwritten can be seen here: /@box/blueprint-web-assets/tokens/tokens-css-vars.scss
• Example of the structured configuration can be found at the bottom of the file: /@box/blueprint-web-assets/tokens/tokens.scss

[greg-in-a-box]

is it safe to delete this https://github.com/box/box-ui-elements/blob/master/src/styles/theme.js or at least remove it from storybook or mark it as deprecated this way the customer is not confused?

[greg-in-a-box]

Is there a way we can have a VRT for this since we know this component should be able to apply a theme. at least we can verify the feature is working at a high level?

[tjuanitas]

yeah I have a separate ticket for adding demos and I can include the VRTs in that

[tjuanitas]

is it safe to delete this https://github.com/box/box-ui-elements/blob/master/src/styles/theme.js or at least remove it from storybook or mark it as deprecated this way the customer is not confused?

no this theming is still used in EUA and I'm guessing Admin console as well. it's how components that haven't been migrated to Blueprint use custom branding in the webapp.

[greg-in-a-box]

is it safe to delete this https://github.com/box/box-ui-elements/blob/master/src/styles/theme.js or at least remove it from storybook or mark it as deprecated this way the customer is not confused?

no this theming is still used in EUA and I'm guessing Admin console as well. it's how components that haven't been migrated to Blueprint use custom branding in the webapp.

I think we should ensure customers dont try to use this one by at least saying its been deprecated or removing the story for it. what do you think?

[tjuanitas]

is it safe to delete this https://github.com/box/box-ui-elements/blob/master/src/styles/theme.js or at least remove it from storybook or mark it as deprecated this way the customer is not confused?

no this theming is still used in EUA and I'm guessing Admin console as well. it's how components that haven't been migrated to Blueprint use custom branding in the webapp.

I think we should ensure customers dont try to use this one by at least saying its been deprecated or removing the story for it. what do you think?

yeah I can remove the storybook and styleguidist related to theming. i'm not sure about deprecation warnings though since it'll also effect EUA developers for however long. we'll probably have to do that closer to when EUA has fully migrated to blueprint. btw this new feature doesn't replace the existing theming stuff in buie, they handle separate use cases. the existing theme work is for internal apps while the new theme work is for ui elements

[greg-in-a-box]

is it safe to delete this https://github.com/box/box-ui-elements/blob/master/src/styles/theme.js or at least remove it from storybook or mark it as deprecated this way the customer is not confused?

no this theming is still used in EUA and I'm guessing Admin console as well. it's how components that haven't been migrated to Blueprint use custom branding in the webapp.

I think we should ensure customers dont try to use this one by at least saying its been deprecated or removing the story for it. what do you think?

yeah I can remove the storybook and styleguidist related to theming. i'm not sure about deprecation warnings though since it'll also effect EUA developers for however long. we'll probably have to do that closer to when EUA has fully migrated to blueprint. btw this new feature doesn't replace the existing theming stuff in buie, they handle separate use cases. the existing theme work is for internal apps while the new theme work is for ui elements

then just removing it from the documentation is enough

[greg-in-a-box]

Approval with the VRTs being done in another pr and testing of the useCustomTheming hook to also be covered by the VRTs and if not there should be a unit test to cover it separately

[JChan106]

lgtm

[mergify]

This pull request has been removed from the queue for the following reason: checks failed.

The merge conditions cannot be satisfied due to failing checks:

• ❌ lint_test_build

You should look at the reason for the failure and decide if the pull request needs to be fixed or if you want to requeue it.

If you want to requeue this pull request, you need to post a comment with the text: @mergifyio requeue

[mergify]

This pull request has been removed from the queue for the following reason: pull request dequeued.

Pull request #3821 has been dequeued. The pull request rule doesn't match anymore

You should look at the reason for the failure and decide if the pull request needs to be fixed or if you want to requeue it.

If you want to requeue this pull request, you need to post a comment with the text: @mergifyio requeue

[mtucker]

@tjuanitas can this new theming support be used to provide custom icons in the ContentExplorer? Our use case, for example, is providing custom icons for folder items.

[tjuanitas]

hello @mtucker! this PR is specific to CSS styles and does not include icons.

however, this is good feedback. few questions:

• why do you want to override the folder icons?
• do you want to override all icons or just this one instance? would it be worth it to provide a custom rendering function instead?
• in your perspective, how would a developer provide their own icons? just as props in a component?

[mtucker]

thanks for your replay @tjuanitas!

• why do you want to override the folder icons?

We're customizing the look and feel of the ContentExplorer in order to better align with our product's design system. We've done this primarily by overriding CSS but replacing icons has been tricky because item icons don't appear to have specific classes we can target.

• do you want to override all icons or just this one instance?

We're currently only interested in overriding the folder icons but a more general solution might come in handy down the road.

would it be worth it to provide a custom rendering function instead?

• in your perspective, how would a developer provide their own icons? just as props in a component?

I like the idea of using the theme to override based on design tokens. We are embedding the ContentExplorer so I imagine a prop (or render prop) solution would involve a lot of prop-drilling in the box-ui-elements components to pass down to the correct icon component. But any solution that's workable form your end would be great!

Love the addition of this theming option!