PoC: Use CSS modules for the Agama components

[lslezak]

CSS modules

When working with Docusaurus I learned about the CSS modules.

With the current implementation it is very hard to find the CSS related to the component code. For example the FirstUserForm component defines its CSS style in assets/styles/app.scss file somewhere in the middle. That's quite difficult to find.

Pros and cons

CSS modules have several advantages:

• It allows using simple and short CSS names. To avoid conflicts we use agama- prefix or long names like first-username-dropdown. That's not nice.
• It has local scope, it avoids conflicts in CSS rules. You can decrease the chance for a conflict using a prefix but you cannot completely avoid it. Webpack generates unique names for the CSS modules which guarantees that a conflict can never happen.
• The CSS and the JS code live next to each other, it is easy to find the related CSS. If you delete a component it is easy to delete the related CSS.

Of course, there also some disadvantages

• When inspecting the page elements you see CSS classes like Iv3X764_hcFfxZFNQLEm from which is not obvious what was the original name. Fortunately CSS modules support source mapping properly so you can get the original name and the exact location in the source file quite easily in the browser devtools.
• That might be problematic for the future Agama plugins. On the other hand I expect that the CSS modules will mostly contain layout fixes. Color theming, etc... will be still defined in the global CSS with known names. So I guess you should not need to change the base CSS modules from plugins.

Notes

• The HMR (Hot Module Replacement) works fine as with normal CSS or JS files. After changing the CSS module file in editor the webpage is automatically updated when using the Webpack development server.
• CSS modules should be used only for the components. The global styles, PatternFly overrides, theming, etc... should be done as it is now.

Proof of concept

In this example I moved the the CSS for the FirstUserForm component to separate FirstUserForm.module.scss file. We could do the same for the other components as well.

[lslezak]

Oh, the unit tests fail, it probably misses the CSS loader...

[dgdavid]

Honestly, I don not have a clear view on this yet. Sorry for that, but IMHO we have to think a bit more about it before moving ahead. But, of course, great someone else invest some time PoC for improving the UI at both levels, UX and DX 🎉

That said, it is completely true that the way we are dropping CSS rules right now it is FAR from ideal. And we now it, but because of priorities we are always postponing the "HTML & CSS" infrastructure. Admittedly, it is difficult to find the right one.

About priorities, I have one after we decided to avoid creating yet another UI library: to reduce custom CSS as much as possible.

Also, think about small utils css rules that are valid for more than one component. Of course, they could live in a "utils module", but I'd like to have it into account.

I'm now migrating to PF v6, which has started to use tokens for the design and CSS, which I expect help us a lot with theming thing.

So, If you don't mind, we can still postponing this decision a bit more in order to have time to finish the migration and explore other techniques 🙏

BTW, thanks a ton for working in this proposal

[lslezak]

I'm fine with postponing the CSS refactoring. Let's see what PF6 brings to the table. This was rather an idea or suggestion how to solve some of the current problems.

Reducing custom CSS is a good idea, but I'm a bit afraid that you cannot reduce that to zero as you probably always need to fine tune or tweak something here or there... For that few tweaks we could use CSS modules.

For sharing/extending CSS between more components you can use the composes keyword: https://css-tricks.com/css-modules-part-1-need/#aa-the-composes-keyword