This guide is intended to help anyone trying to orient themselves with the existing sass in the edX platform as of January 2016. (For a peek into the future, be sure to visit ux.edx.org or UX Pattern Library github project.) This isn't intended to be exhaustive, nor to teach Sass (for that please see Resources for Learning Sass), but to give developers an understanding of what exists, where to start when diving into reading (or editing) Sass in the platform, but should not be taken as the way to write css! This guide also focuses on the LMS since it is more of a jungle to navigate.
Things to remember about Sass/CSS
The most important thing to remember about Sass and CSS is that the rules CASCADE - the last rule (of equal specificity) trumps all previous rules.
CSS = Cascading Style Sheets
CSS rules cascade in two ways:
- Rules get overridden from the top of the first css file imported to the bottom of the last css file (or rule written in the DOM) on the page
- Rules get more specific and powerful as you add selectors (see this article on CSS Specificity for more info)
So just adding a new rule at the bottom of the file is not a great way to add css - make sure you think about what the selectors may affect outside of what you are working on.
Sass = Syntactically Awesome Style Sheets
Sass brings more flexibility (and risk) to css - you can use variables and functions in your Sass that compile into flat css (see this intro to Sass or this simpler intro to Sass/SCSS). All the rules and gotchas of CSS apply to Sass as well.
The anatomy of a SCSS file
Reading the oracle bones of the Sass file structure
Sass partials start with an underscore (e.g. _system-feedback.scss) and are compiled into the final css by the import sass files which do not have an underscore (ex. lms-main.scss).
Key files and directories:
base/ - This directory holds a mix of very old files that are a mess (exhibit A: _base.scss) and central utilities (e.g. _variables.scss)
vendor/ - This directory should only hold original vendor css/sass files; modifications/overrides should be done in the edX sass files.
multicourse/ - This directory holds styles that relate to pages inside the LMS but outside the course experience, including Dashboard and Open edX Onboarding pages.
course/ - This directory holds styles that relate to the course experience.
elements/ - This directory holds styles that relate to particular elements or patterns used throughout the LMS, like buttons/controls, pagination, system feedback.
views/ - This directory holds partials that relate to specific views or sections of the app, such as Teams, Profile, Account Settings.
_variables.scss - The variables file is where most central variables used throughout the Sass files are set up. (Ideally, variables would not be set anywhere else, but you will find them scattered through the LMS - do NOT make new variables outside this file if at all possible.)
_extends.scss - The extends file holds some useful collections of property-value pairs that you may want to use repeatedly (see anatomy above).
_mixins.scss and _mixins-inherited.scss - The mixins files are very similar to the extends, but they generate a rule in the final css file, where extends do not (see anatomy above).
_shame.scss - If you have to do something you're not proud of (and you know it), do it here. Mostly it's overrides for poorly written sass that can't be changed.
_developer.scss - If you don't usually write CSS/Sass, but need somewhere to put stuff while you're developing, do it here. Ideally the FEDs will come in and clean it up occasionally.