[plugin-css] Replace custom CSS builder with CSSOM

[davejsdev]

I've been poking around and noticed the way we're generating CSS output is using a lot of custom logic to translate the design tokens into CSS (here).

The main issues I see with this are:

1. It makes the code difficult to read, maintain, and extend. (I noticed this while looking into Feature: Add @property definitions to CSS plugin output #166.)
2. It's prone to errors if there are edge cases we fail to consider.

Replacing this logic with CSS Object Model(CSSOM) entities to build up the generated CSS might allow us to improve the code quality and ensure correctness of the output.

Since CSSOM is a Web API it's not available in Node out of the box, however, there appears to be a community-maintained Node implementation here we could use: https://github.com/jsdom/cssstyle

Open Questions

1. Has this been considered previously?
2. Are there any known blockers/limitations for this approach?
3. Are there other alternatives we should consider?

[drwpow]

This isn’t a bad suggestion. I’m open to a more generic format!

It makes the code difficult to read, maintain, and extend.

The current implementation is 1 file, 66 lines. That’s not that bad IMO, but it’s good to compare apples to apples and see if CSSOM both reduces lines of code and complexity.

One main difference between the Terrazzo CSS plugin and CSSOM is the latter cares deeply about specific syntax. For example there are specific types for individual CSS transforms. The current implementation doesn’t bother with any CSS syntax whatsoever. Individual token types mash together a CSS string on their own. And the code you’re pointing to only takes some key–value string objects and builds them into selector scopes. The inner workings of CSS are opaque to the plugin, and this is only a means of generating scopes. But maybe we will start to care more about actual CSS syntax; it just hasn’t presented itself.

So I think it’s a good approach, but let’s evaluate it based on the goal of whether or not this simplifies things. And if it does, great!

[drwpow]

Oh one other thing, too, is the transform() hook of this plugin lets people write arbitrary CSS strings (for example maybe they have special rules for one token, and they want to modify the generation in a couple of edge cases). So this could potentially make that harder to use, e.g. if they have to use CSSOM syntax.

[davejsdev]

Thanks for the quick response! :)

The current implementation is 1 file, 66 lines.

Yeah, you're right, it's not tough to follow in it's current implementation.

I think what raised this concern for me was when I started prototyping adding the @property rules (#166), some of the logic started getting a bit tricky since there's an implication that selectors starting with @ are media queries. It's a bit unclear if the selector should be narrowed to just check for @media ..., or the intent was to check for any at-rules (@property, @container, @font-face, etc...).

Follow-ups:

1. Is there a known subset of at-rules that need to be handled here?
2. Is the intent of the current code to check for specifically media queries, a subset of at-rules, or all at-rules?

// current
const isMediaQuery = rule.selectors.some((s) => s.startsWith('@'));

// selects for any at-rule
const isAtRule = rule.selectors.some((s) => s.startsWith('@'));

// selects for only media queries
const isMediaQuery = rule.selectors.some((s) => s.startsWith('@media'));

Separately, thanks for the context! I'll start looking into CSSOM to see if it's an improvement while keeping your concerns in mind.

In the meantime, I have a small refactor for this code that I'll open a PR for.