Some ideas for improving OFN CSS

Tech
1

This is a set of ideas how the frontend CSS code of OFN could be improved over time, as well as help with the overall design of the app. There are a few drivers for this:

  • A growing team of devs
  • Mobile support needs improving
  • More general UX improvements, as this thread suggests
  • Potentially scenarios where new themes need to be developed

1: Build a style guide

There are a bunch of good reasons to use a style guide - see Creating Style Guides – A List Apart for a good explanation. http://styleguides.io/ has loads more resources if interested. It could help specifically with OFN in a few ways:

  • Encourage more consistent, modular, smaller CSS
  • Help with fixing the backlog of UX and mobile issues
  • Provide a prototyping tool for new UI development, that then gets built into the app

I’ve started a proof-of-concept here:

https://pmackay.github.io/ofn-styleguide/index.html

Note: this is copied from OFN, some images are missing. The intent is to have a “living style guide” that is based on the live OFN CSS.

2: Convert all SASS files to .scss format

(or at least a consistent format if possible)

There is a mix of sass and scss files in /assets/stylesheets. It would be great to know the backstory why if someone could post a response. However, having 2 formats makes the overall codebase harder to manage, particularly for new devs.

This article lists a number of reasons why to use SCSS over SASS (several of which I have found to be important).

3: Adopt BEM as a format

See http://getbem.com/naming/:

It is a known fact that the right styleguide can significantly increase development speed, debugging, and the implementation of new features in legacy code.

There are a number of naming formats in CSS. I’ve been using BEM recently and found it pretty solid. What is really useful (beyond the naming conventions) is the focus on modular components (blocks).

4: Structure CSS files using atomic design principles

Read Atomic Design | Brad Frost for more info.

This is strongly related to 3 and about building a modular UI system. The CSS files could be structured into something like this:

/atoms (or base)
/components
/templates
/pages

Note: I’ve compressed the atomic design “molcules” and “organisms” into “components” as the former can create confusion as to what goes where.

While building the styleguide prototype, I’ve noticed the OFN CSS is quite heavily nested. It should be possible to display a product component without being nested under .darkswarm products for example - what if there was a need to show a sidebar promotion for example? This also might be factor in the 6000+ selectors the app CSS file has. With refactoring it might be possible to reduce this and remove the need for the css_splitter gem.

5: Add stylelint as a CSS linter tool

http://stylelint.io/ seems to be a strong tool of choice currently. This is just about also increasing consistency and helping with the other points.

How could this be done?
This might be approached thus:

  • Setup a live styleguide that can be built within the project (very happy to continue with my start on this)
  • Add new /base and /components directories. Potentially do some initial moving of CSS files for base.
  • Setup stylelint to scan the files just within those new directories and agree on a basic set of rules to use.
  • When components are edited, aim to move the CSS into a new file under /components at the same time, adjusting for BEM style.
  • If new components are needed, e.g. a card layout for products, build these intially using the styleguide as a design/review tool.

All feedback much appreciated. Also, this is a bunch of fairly bold points (all in the name of future improvement!), so please give any historical reasons why things are a certain way, or if there are strong preferences for other kinds of conventions, tech, etc.

Ping @Kirsten @lin_d_hop @RohanM @maikel @oeoeaio @sstead @stveep @Arthur @elf-pavlik

1 Like
2

Thanks @pmackay, I am happy with all of these suggestions.

Others could have more information but I don’t think there is any particular reason for using a mixture of SASS and SCSS, we just never decided on a standard, and so things got into a bit of a mess. Same goes for file structure.

3

Thank you! I always struggle with the vast amount of code in the OFN including styles. It’s too much to know it all.

Build a style guide

Good idea. Would that live within the OFN code and use the same CSS?

Convert all SASS files to .scss format

Yes, I’m always happy about consistency. I just got caught on this last week. I copied a .sass file name, but then tried to put scss content in it. Didn’t work. :wink:

Adopt BEM as a format

I’m not convinced yet. Why is .block__elem better than .block .elem? And if I move the element? Do I have to rename the class to .blockb__elem? I probably overlooked something.

Structure CSS files using atomic design principles

This sounds interesting. I like this view of designing re-usable components. I sometimes use the heavy nesting just to avoid breaking something else. And that doesn’t make it better…

Add stylelint as a CSS linter tool

Very good. As always, it’s good to start with really relaxed rules so that the linter is not annoying. Then we can become stricter over time.

4

I am suggesting that it could be in the OFN code, because its then easier to use the OFN styles in-place, and its available for anyone to build prototype UI components as examples before building data driven versions.

Why is .block__elem better than .block .elem?

It helps with these things (as that naming page describes):

Use class name selector only
No tag name or ids
No dependency on other blocks/elements on a page

It flattens selector hierachies as well.

By reducing dependencies, it decouples the CSS from the element structure. So say you have a button inside a component. If its been styled with .component button then changing the button to a <a> link would break the CSS. If the button has the class .component__link on it, the <a> element could retain that and the CSS does not need to change.

Some expanded, very useful points about BEM here:

I also learnt a few other well-explained benefits of BEM from these slides:

5

Thanks Paul. Regarding BEM I found an answer to my question this morning. I was wondering which advantage BEM has even if you already use only class names. I thought, .product .name is easier than .product__name. But then I realised that .product .name can be ambiguous if you have another component within the product component. .product__name and .fee__name are unambiguous even if the fee component is within the product component. If you used .product .name, it would apply to .product .fee .name as well. So yes, I would give that a try.

6

We are currently doing 1.

also exploring tailwind as a CSS framework.

i’m closing this discussion and moving it to the tech category: let’s reopen when needed!