Simplify styles architecture

[filipsobol]

When working on the new installation methods, @pszczesniak and I had an opportunity to have a high-level look at how we deal with styling the editor. We noticed some areas where with small effort we could modernize our setup and reduce the complexity of working on the editor.

This issue is meant to document some of these ideas and to start a discussion which of them (if any) are worth implementing.

Fix

Let's start with a fairly simple fix that can be implemented at any time.

Use @media (hover: hover)

As suggested in this comment, we should consider using @media (hover: hover), to prevent certain mobile browsers from applying the hover styles on “tap”.

Architecture improvements

Now the difficult part. The improvements listed below could be introduced after we deprecate the src folder for the legacy installation method to avoid introducing unnecessary breaking changes.

Remove theme-lark

As suggested by @oleq, we should consider removing theme-lark. The original idea for it was that at some point we could have multiple editor themes, so we should place all styles that could be considered a part of such a theme into a theme-lark package. However, the idea never took off — we didn't introduce any alternative themes, but maintaining theme-lark introduces complexity and edge cases that we must remember about when working with styles.

To reduce the complexity, styles from theme-lark could be moved directly to the plugins that these styles affect.

If we implement it after deprecating the src folder, then this change will only impact projects that optimize editor build size. Fortunately, this will only require removing one line of code. This change will not impact those using the default installation methods, nor projects using DLLs.

What to do with the few mixins that we have is an open question.

Separate CSS from JavaScript

Currently, the CSS files are imported individually in different JavaScript files throughout each package. This was done to make the webpack load them in proper order and to only import styles that are required at a given moment.

However, this doesn't guarantee proper order in every bundler, which we learned the hard way when migrating from webpack to Rollup. Additionally, in new installation methods, all packages are bundled, so it's not possible to import individual files from the source, nor is it possible to only import individual styles. All JavaScript code is bundled into one file, and all CSS is bundled into another file.

To ensure that styles are built in proper order, we should consider creating a CSS entry file in each package that will import other, existing style sheets (think index.ts, but for CSS). That entry CSS files could then be imported into the main index.ts files in packages.

Separate editor- and content-only styles in source code

To make the content produced in the editor look the same as in the editor, the pages displaying it must include the same content styles. However, because the content styles only make a tiny part of all editor styles, it doesn't make sense to load all of them.

For this reason, in the legacy installation methods, we had a script that generated a content-only stylesheet that was displayed in the docs. In the new installation methods, we decided to generate these stylesheets together with the “regular” stylesheets and include them in the npm package.
This works alright, but extracting editor- and content-only styles is tricky, as there are many rules and exceptions to extract exactly what we want in both stylesheets. However, separating editor and content styles on the source code level should be fairly simple and allow us to remove the tooling necessary to split them at the build time. Following the idea from above, we could have two entry CSS files:

• editor.css that will import existing style sheets in proper order.
• content.css that will contain only the content styles.

Because the entire editor has very few content-only styles, the content.css will likely be flat and won't have any dependencies / imports.

---

Here's the visual representation of the current architecture:

This is the proposed architecture:

[Witoso]

One thing that would be great to have is if plugins could record in metadata what CSS variables could be changed. This way, the Builder could consume it when we have a UI step for "templating".