Frontend Guidelines (HTML/CSS/JS)

CSS/SCSS Architecture (system structure)

The foundations of a solid CSS architecture can uphold the project as it begins to scale and grow. If these foundations have not been constructed properly, your project could likely fall over in the future.
CSS will not likely break the system as a JavaScript error might. However, it can create different issues that make working on the project very difficult. If you have a team of engineers who are not confident in adding or changing CSS in the project, they are more likely to introduce bugs. These bugs will find their way to your end-users, and the project’s success may be affected because of this.
It is essential to begin a project with a solid CSS architecture because writing lousy CSS is much easier than removing it.
Basic CSS Library Structure
The projects should have two main files: configuration and content styles files. The configuration file, called _config.scss, references all configuration files, and the content styles file, called _local.scss, references all folders & files inside the local folder.
The main.scss connects both those files.
Main SASS Folder:
|- framework/
|- _config.scss
|- _local.scss
|- main.scss
main.scss file:
@use "config";
@use "local";
Configuration Level (_config.scss)
The configuration level defines all my SASS/CSS variables and some main root definitions. To achieve a well-constructed project, I divide the configuration into smaller files according to their logical function.
CDN variables
Colors Variables
Responsive Design Breakpoints Variables
Language Support Variables
Main Z-Index levels
Other variables don’t fit into the other parts.

|- config/
| |- _common.scss
| |- _cdn.scss
| |- _colors.scss
| |- _directions.scss
| |- _breakpoints.scss
| |- _layers.scss
|- local/
| |- Folders and Files
|- _config.scss
|- _local.scss
|- main.scss
Content Level (_local.scss)
The content level, located in _local.scss, is your styles' main content, i.e., this is where you should place all your styles. This level should include SASS mixins, CSS Normalize & CSS Resets, fonts, icons, CSS utility classes, standard grids, and partials.
|- config/
| |- config files
|- local/
| |- _mixins.scss
| |- _resets.scss // normalize + resets + typography
// in the case of the large proj we can have these files separate
| |- _fonts.scss
| |- _icons.scss // font icons/SVG icons
| |- _utilities.scss
| |- _grids.scss // common layouts
| |- _partials.scss // elements/components/entities/pages
|- _config.scss
|- _local.scss
|- main.scss
The content level contains styles belonging to many logical parts, such as resets, fonts, icons, etc. Even if we divide it into the minimum number of files, we could get to 7 or 8 files. In some cases, it’s better to divide them into even smaller parts so that the .sass files never get too big, i.e., not more than 50 rows if you write your style definitions in one row per selector, and no more than 200 rows if each definition takes a whole row.
An examples:
Mixins level
Folder structure:
|- local/
|- |- mixins/
| | |- _trim.scss
| | |- _rotation.scss
| | |- _prevent-select.scss
| | |- _break-word.scss
| | |- _scrollbar.scss
| | |- _screen-reader.scss
| |- _mixins.scss
_mixins.scss file
@use "mixins/trim";
@use "mixins/rotation";
@use "mixins/prevent-select";
@use "mixins/break-word";
@use "mixins/scrollbar";
@use "mixins/screen-reader";
Reset level
Folder structure:
|- local/
|- |- resets/
| | |- _normalize.scss
| | |- _reset.local.scss
| | |- _typography.scss
| |- _resets.scss
_resets.scss file
@use "resets/normalize";
@use "resets/reset.local";
@use "resets/typography";
Multi-Platform CSS Library Architecture
application 1 Global CSS Library Base Level application 2 application 3 subApplication 2.0 sub Application 2.2 subApplication 2.1
The base level should be light, only containing CSS resets, base SASS mixins, shared icons, general font, utility classes, flex-box, and shared grids. For the _partials.scss layer (elements, components, etc.), you will primarily use the _elements.scss level, which has partials like modals, standard forms, and standard titles. You only add styles shared by all.
Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
) instead.