Creating freeCodeCamp's CSS Style guide

[tomasvn]

I would like to propose freeCodeCamp's CSS Style guide to improve overall maintainability of the codebase. As the FreeCodeCamp has a lot of contributors, and everyone writes the CSS in a different way. And it is hard to keep of track of different ways of writing CSS.

Initial Recommendations:

Comments

• Add comments, when you are starting a new LESS file, so the developers know what are they working with, also add comments when you start new section which is related the code block, it helps with the readability, see EXAMPLES below (I have encountered these style of comments across the code base, therefore I would like to continue writing it, instead of proposing a new style)

• Example 1 - when starting a new LESS file:

//
// Navigation
// --------------------

• Example 2 - when adding a section, related to navigation

//
// Navigation - Mobile Styles
// ------------------------------

Spacings

• Add spaces after a property, it will be much easier to read such a codebase, and maintain. See EXAMPLES below.

• Example 1 - Correct Way

p {
  color: #fff;
}

• Example 2 - Incorrect Way
• What is wrong?
  No space after a colon

p {
  color:#fff;
}

Colors

• Prefer lowercase, instead of uppercase. Now across the CSS, contributors are mixing both. Lower case is faster to write, easier to read. Again improves overall maintainability, if the CSS has consistent convention. Also if possible shorten the hex value. See EXAMPLES below.

• Example 1 - Correct Way

p {
  color: #fff;
}

• Example 2 - Incorrect Way
• What is wrong?
  upper-cased hex value, not shortened

p {
  color: #FFFFFF;
}

RGBA or RGB colors

• Add spaces after values, improves readability. See EXAMPLES below:

• EXAMPLE 1 - Correct Way

p {
  color: rgba(123, 123, 0, 0.1);
}

• EXAMPLE 2 - Incorrect Way
• What is wrong?
  No spaces after values

p {
  color: rgba(123,123,0,0.1);
}

##No unit when declaring 0

• In property such as box-shadow, if you set a 0 value, then you should avoid adding the unit. See EXAMPLE below.

• EXAMPLE 1 - Correct Way

p {
  box-shadow: 1px 1px 0 rgb(0, 0, 0);
}

• EXAMPLE 2 - Incorrect Way
• What is wrong?
  Units after 0

p {
  box-shadow: 1px 1px 0px rgb(0, 0, 0);
}

Avoid floating numbers

• If possible you should avoid floating numbers in CSS for different sizing, as it could render a bit differently. See link attached below.

Browser Rounding

[tomasvn]

@raisedadead What do you think?

[raisedadead]

Thanks, are you aware of any way can lint these? Using any linters?

[vkWeb]

@raisedadead @tomasvn According to me the process of creating a CSS style guide and sticking to it will in long-term not yield useful results. React, Yarn, Babel and lots of other open source projects use Prettier and other similar extensions for their CSS Style formatting.

Instead of creating a style guide. We should tell our contributors to Install Prettier In their IDE/Code editor and we'll be good to go.
@raisedadead Thoughts on this?

[vkWeb]

Thanks, are you aware of any way can lint these? Using any linters?

Prettier works well ;). It warns you when you violate any CSS style rule.

[raisedadead]

Instead of creating a style guide. We should tell our contributors to Install Prettier In their IDE/Code editor and we'll be good to go.

Hiding from problems never helped anyone... 😅 !

I am strongly in favor of avoiding formatters and using linters instead. Automating things sound cool and easy, but they take away the key point of writing standard code.

IMHO, we being the community around learning should not shy away with fixing issues in code style pointed by linters, rather.

Also please note Prettier is an Opinionated Code Formatter

[raisedadead]

According to me the process of creating a CSS style guide and sticking to it will in long-term not yield useful results.

I think, this is is an incorrect argument (feel free to prove me wrong if you have stats).

If you check the Airbnb JS style guide, JS Standard etc. they, have helper write standard code and are being used by thousands of companies, and devs everyday.

[vkWeb]

@raisedadead We're not hiding away from problems...! We can use linters but the same task can be done with a single key binding with Prettier so why we're trying to take a long run on it?

[vkWeb]

I think, this is is an incorrect argument (feel free to prove me wrong if you have stats).
If you check the Airbnb JS style guide, JS Standard etc. they, have helper write standard code and are being used by thousands of companies, and devs every day.

I strongly agree with you on this! Their JS style guides are really very helpful.

[raisedadead]

We're not hiding away from problems...! We can use linters but the same task can be done with a single key binding with Prettier so why we're trying to take a long run on it?

Because, we want to write standard code? Contributors are free to use any tools they like, but that does not dictate we do not need of a guide.

[raisedadead]

Anyways, lets keep this thread for constructive feedback on the guide, we can always have discussions in the chat instead.

@tomasvn RFC looks interesting, and since you are interested in the feedback, do you think it will be possible for you to look up some, established style guides and tooling that we can take inspiration from.

[vkWeb]

Because, we want to write standard code? Contributors are free to use any tools they like, but that does not dictate we do not need of a guide.

I'm with you on this too. Okay, let's go with a style guide and we can use stylelint as our linter.

[tomasvn]

@raisedadead stylelint seems fine 👍 As it would warn the contributor about incosistencies across his document

[QuincyLarson]

@tomasvn We just launched our new curriculum and learning platform. Are you still interested in helping with this?

All of our CSS is in need of a good refactor, and this would be a good opportunity to not only create a style guide but to turn around and immediately apply it to the project, and make sure all our repos are in accordance with it.

[tomasvn]

@QuincyLarson Sure, I can take some of my time and help you with refactoring the CSS, as the freecodecamp is quite a large codebase, just point me where should I start

[QuincyLarson]

@tomasvn That would be amazing!

freeCodeCamp doesn't have all that much CSS. freeCodeCamp's CSS is mainly located in "main.less". And we're using Bootstrap 3.0.

We may eventually move to Bootstrap 4.0 or just rewrite our CSS to use Flexbox. But for the time being, we're using React Bootstrap on several of our applications, and that is currently locked to Bootstrap 3.0. So I recommend just going in and cleaning up the existing custom CSS in main.less and making it less redundant and more logically arranged.

[tomasvn]

@QuincyLarson got it, and the main.less is located in client/less/main.less, is this the correct file?

[QuincyLarson]

@tomasvn Thanks for your patience - I just saw this. Yes - client/less/main.less should be the right file.

[borisyordanov]

@tomasvn Need help with this? I'll be happy to contribute

[QuincyLarson]

@tomasvn have you had a chance to start working on this yet? If not, @borisyordanov Yes - we would welcome your contributions with this.

[tomasvn]

@borisyordanov sorry for delay, sure go ahead I have some problems running dev env on windows, so you can start, when I fix my stuff I can help you refactor it

[borisyordanov]

@tomasvn I sent you an email, lets meet up in a chat and plan this. If you have trouble running the project i'd recommend going through the guide if you haven't already or ask for help on Gitter

[Jgriebel1990]

If there is still need I can help with this

[borisyordanov]

@Jgriebel1990 i couldn't get in touch with tomasvn so no progress has been done as far as i know. Feel free to take over

[tomasvn]

@Jgriebel1990 feel free to take over, i wasnt able to get my copy working on windows machine, all i can do is a code review once you are done

[tomasvn]

@QuincyLarson I will try to make it work on windows, I still have issues of running it, If I won't be able to set my environment, just close the thread.

[QuincyLarson]

@tomasvn No worries - any luck getting it to run locally?

[raisedadead]

Related: #35081

[tomasvn]

@QuincyLarson No luck, running it locally

[Nirajn2311]

@tomasvn what issues did you come across when setting up locally.

[borisyordanov]

@tomasvn Please read this - https://github.com/freeCodeCamp/freeCodeCamp/blob/master/docs/how-to-setup-freecodecamp-locally.md

[RandellDawson]

@raisedadead With the updates to https://github.com/freeCodeCamp/design-style-guide, is this issue needed?

[raisedadead]

Its more on the roadmap. Eventually it will be the central resource for our UI components.

[ManasMahanand]

Hey! What's the progress on this? I am available to help!

[ahmaxed]

@ManasMahanand, thank you for your interest.
It would be great if you could look into the available css linters, compare them and see if there is anything better than stylelint.
Then, add the linter to our repo and change the CSS files to make sure the repo is linting error free.

[ManasMahanand]

@ahmadabdolsaheb Will do!

[ManasMahanand]

@ahmadabdolsaheb Wait what do you mean add to repo?

Do you want me to install the linter as a dependency, like eslint is already?

Or is there a way of installing tests on github itself, so it won't allow merging unless the style guide is followed?

[ManasMahanand]

Ok, looks like stylelint is a good option itself. I am installing that.

For experimenting, I will set rules as suggested by OP. I will then remove all rules and open a pr. We can then discuss and set rules

[ManasMahanand]

https://stylelint.io/user-guide/rules/about

You can have a look at this link to see the types of rules that can be set

[ManasMahanand]

currently there is already a lint:css command that uses prettier. We can change it to use stylelint.

Any how, I have installed it, and it successfully detects errors based on rules set. Shall I open a PR?

[tomasvn]

No need to remove prettier, prettier has config for stylelint rules that you can use to extend prettier config file

[ManasMahanand]

Awesome. Will work on it tomorrow.

[ManasMahanand]

I didn't find prettier config for stylelint rules (or how to do that), but currently I have installed another package stylelint-config-prettier that will check for conflicts and will turn off any rules that does conflict.

What I am thinking is in lint:css command we can also run the stylelint command as well along with prettier

[ManasMahanand]

(Opinion) I feel that we can write all custom stylelint rules based on what makes sense for fcc, and even completely remove prettier. This is just an opinion, it is left to you guys to decide.

[ahmaxed]

Thanks @ManasMahanand on your progress. I am tagging @ojeytonwilliams for a second opinion.

[ojeytonwilliams]

I think prettier does a good job with formatting, so I'd rather keep that. If we use https://github.com/prettier/stylelint-prettier then prettier is used as a plugin of stylelint and we get the best of both worlds.

This mirrors the approach we already use for JavaScript linting.

[ahmaxed]

@ManasMahanand I was wondering about your progress with your solution. let me know if I could be of any help.

[ahmaxed]

Since we are moving away from custom css and leaning towards our component libraries's tailwind for most of our styling, adding CSS style guide would not be necessary; However, I added a note to add a CSS linter to our component library which should address this issue.

I will go ahead and close this issue accordingly. Let me know if this issue has been closed by mistake or if it needs further discussion. Thank you.