Theme customizability with SvelteKit migration

[aabounegm]

Problem

With the new packaging functionality in SvelteKit, we get the benefit of being able to use TypeScript in the component source code without requiring the users to also install TypeScript (or any preprocessing we might want to do to improve Developer Experience). However, we cannot selectively apply preprocessing to some features (i.e.: TypeScript) and not others (i.e.: SCSS) without also breaking our docs since they are part of one project and the same preprocessing must be applied to all. This breaks our current schema of theme customization using SCSS.

This is currently blocking #349.

Inspiration

We can take a look at how some of the other UI libraries do styling/theming to see possible ways of going around this limitation.

Svelte UI:

• Needs the SvelteUIProvider wrapper around whole app
• Uses createStyles function (accepts a function with default theme that returns overridden values) in JS

Svelte Material UI:

• Bare CSS (subset of the theme options)
• SCSS (@use '@material/theme/index' as theme with ();) + building theme with smui-theme and including as a <link>

Carbon components:

• Provides 5 themes only, no customization

Smelte:

• JS object passed to Rollup plugin (no Vite) overriding TailWind's defaults

Sveltestrap:

• No customization, uses Bootstrap CSS file

Svelte Materialify (deprecated):

• Uses includePaths, but @imports vars instead of @use "..." as vars so scope leaks.

All of the above seem to have very different solutions than ours except for the last, which wouldn't work post SvelteKit migration.

Possible solutions

• Remove SCSS altogether, just use CSS vars everywhere: This is probably the simplest solution in the long run, but we will not be able to use Sass's utilities for color manipulation and such (to base one property on the value of another using just one variable). It will likely require a lot more variables than with SCSS. Relevant to Improvement: use css custom properties instead of scss variables for themeing #181.
• Use SCSS internally and as the default value of the CSS vars: Has the same benefits as removing SCSS from the user's perspective, but it might make it more difficult to customize inter-dependent values.
• "Unpreprocess" the files when packaging only (would require dirty hacks/workarounds) and keep SCSS always required: Since the SCSS files will be copied anyway and the src attribute remains on the <style> tag, we can simply postprocess the output to remove the resulting CSS from this tag and keep SCSS required and everything as it was before the SvelteKit migration. We can also ship this "unpreprocessor" with the library instead of doing it ourselves so that users satisfied with the default styles don't need to install SCSS or preprocess anything.
• Something else?

Personally, I'm more inclined towards the first solution, but I want to know the opinions of others who use the library.

[aabounegm]

After some exploration, I decided to move on with the first option, but inspired by the second one. All variables will be moved to pure CSS (custom properties), we will get rid of Sass entirely, but we can keep some of its useful features as PostCSS plugins (such as nesting and mixins), meaning we will still ship pure CSS. This solution has the benefit of making theming much easier due to the differences in the nature of CSS custom properties as compared to Sass variables.

About how the migration process, there are 2 main issues to tackle:

1. What to do with the properties that depend (at least in the default value) on other variables. This can be further split into 2:
   1.1) Variables whose default value is exactly the value of another variable
   1.2) Properties that are directly defined as some transformation of a variable (using color.adjust or similar)
2. How to define the default styles (since CSS vars don't have an equivalent to !default. The var() function does support a default value, but it's not the same)

About the first, it's worth noting the following:

• We only import 2 sass utilities: math and color
• The math one is used in only 4 instances, all of which seem easily replaceable with calc or hard-coding.
• The color one is used 109 times, of which:
  • color.adjust: 85 times
  • color.scale: 22 times
  • color.mix: 2 times
• Some other sass function without imports are used:
  • darken: 1 time
  • Not sure if there is anything else
• 15 mixins are defined, 3 of which are parametrized

Without much further analysis, I think we can tackle them as follows:
1.1) Straightforward: just use var(--other-var) as the default value of the second variable.
1.2) There are 2 possible solutions. Either add another variable especially for this property/variable (easier from our side, but worse experience for the users), or figure out a way to represent the same transformation in plain CSS (can prove a lot more difficult, but is the desirable solution).
2) This is the simplest: Just write them all in one CSS file and require users to import 'attractions/variables.css'; (or however it might be called) in their entry point (ex: the root +layout.js in SvelteKit), or @import in a CSS file that will then override the variables.

The following sources may be relevant to the conversion of Sass function to CSS:

• https://blog.jim-nielsen.com/2020/sass-color-functions-in-css/
• https://una.im/css-color-theming/