[Feature Request]: Facilitate non-SCSS usage of Carbon tokens and mixins

lee-chase commented 3 months ago

The problem

Carbon uses SCSS to generate it's CSS. Use of CSS in JS, Less or other technique to apply Carbon is not always possible. This is a block to Carbonisation in some cases.

Currently some Carbon tokens can be accessed as Custom CSS properties, but this does not include all values e.g. motion easings.

The custom properties are not well documented including the mechanisms for instantiating them. For example type mixins make use of custom css properties, but it is not clear how these are instantiated in CSS.

Mixins can be discovered through inspection of the Javascript imports, and recreated. These mixins could be available as CSS classes e.g. .productive-heading-04.

The solution

Document how each set of CSS custom properties are instantiated.
Publish a table of CSS tokens/mixins to Custom Properties or utility classes.
Provide Javascript utilities to parse/utilise the custom properties in JS.

Examples

No response

Application/PAL

No response

Business priority

Medium Priority = upcoming release but is not pressing

Available extra resources

No response

Code of Conduct

[X] I agree to follow this project's Code of Conduct

github-actions[bot] commented 3 months ago

Thank you for submitting a feature request. Your proposal is open and will soon be triaged by the Carbon team.

If your proposal is accepted and the Carbon team has bandwidth they will take on the issue, or else request you or other volunteers from the community to work on this issue.

tay1orjones commented 3 months ago

Hey! Thanks for writing this down, there are some interesting ideas here. Some quick thoughts:

Getting motion token/easings into CSS Custom properties is definitely worth exploring
Improving docs on CSS Custom Properties and how they're emitted is a great idea
Despite their popularity, I'm not sold on utility classes when there is already an extensive api of mixins available for use.

Since interoperable css isn't on a standards track and isn't supported by sass, I think the only available way to get tokens and mixins into a js environment is by using the sass javascript api directly. We have some tests that do this actually:

https://github.com/carbon-design-system/carbon/blob/36685a0be5e62db11a60d938c76b1c49a402c99a/packages/type/__tests__/scss-test.js#L19-L46

lee-chase commented 3 months ago

Hey @tay1orjones assuming all values are output, then suitable documentation ticks most boxes for either JS in CSS and direct access to custom css properties ticks most boxes for non-SASS users. That does need to include, how to instantiate custom css properties like --cds-productive-01-font-size.

Not sold on utility classes myself, too easy to accidentally override, but do provide an non-sass way of collecting multiple CSS settings.

carbon-design-system / carbon