A series of CSS conventions to architect scalable, maintainable CSS.
Note: the rules are meant for code review, so they are written as if a mistake was made against the convention.
-
S1 Accord to internal component structure
Follow the prescribed component structure. You should use the correct component structure, with the right block level comments.
-
S2 Use
editorconfig
logic for file indentationEditorconfig is a way to get rid of the spaces vs tabs discussion. It sets up your editor automatically based on conventions in an .editorconfig config file contained in the project. When this rule is called, your code does not accord to whatever is set up in editorconfig.
-
S3 Every component should start with its component name
Every SCSS component should start with its own component name.
-
S4 Use correct block level comments
Use the correct block level comments as defined in the project conventions
-
S5 Don’t nest BEM child selectors
Don’t nest BEM child selectors for CSS specificity reasons. Also, because of the way CSS parsing works, this has performance benefits.
-
S6 Multiple components called in single
class=""
statementThis problem occurs in the HTML, not in the CSS. It is best to not mix up components and write things separately, as this can cause override problems, since ITCSS components have the same level of CSS specificity.
-
S7 Component cannot contain other component code references
Component cannot contain other component code references - unless dependency is explicitly listed in top level description
-
S8 Components should be namespaced
A component should be namespaced. Please adhere to ITCSS's or the project-specific namespacing.
-
S9 Prefer rems for element sizing
Use rem units across the board to size elements. Percentages or vh/vw units can work for size relations. Use pixels for media query statements.
-
S10 Don’t put CSS conventions in the main CSS file, only imports
Use _trash.scss for whatever you are ashamed of. Try to keep the _trash.scss empty.
-
S11 Don’t use
!important
in regular component filesRespect the ITCSS logic of having more specificity the later a rule occurs in the stylesheet.
-
S12 Use
!important
for utility classes to make them immutableFor the logic concerning this, I would like to refer to Harry Robert’s “forcing immutability in CSS” logic as explained in this article.
-
S13 Imports in main file should be ordered alphabetically
Every SCSS partial in a main SCSS file should be ordered alphabetically.
-
S14 0 values should be unitless
Don’t write 0rem, just write 0.
-
S15 Only load components that are actually being used in the HTML
Only load components in the CSS that will end up being used in the HTML.
-
S16 No BEM grandchildren
Do not attempt to to recreate HTML structures in CSS; the HTML structure can be nested whereas the CSS structure will be flat.
-
S17 Incorrect BEM usage: no usage of BEM children
Please use
__
for any div that is a child of a BEM component. -
S18 Multiple BEM components specified in a single CSS file
Multiple top-level BEM components are specified in a single CSS file. Please split into multiple files.