Re-organize SASS structure

[samikeijonen]

While talking with several developers I sometimes get feedback that sass folder structure is complicated and hard to manage. I tend to agree.

I investigate this more and suggest small tweaks that we might do.

[dingo-d]

It is a bit all over the place. This is the folder structure that we use at the firm I work:

Infinum's wp-boilerplate sass structure

There is a clear separation of util functions and components, as well as of admin side.

[samikeijonen]

@dingo-d At first look I like it:)

[pyronaur]

I made "unstyled" starter theme based on _s and while migrating Sass to Stylus I also refactored the folder structure quite a bit too.

https://github.com/Themetally/unstyled/tree/master/assets/style

Stylus is able to easily take advantage on Globbing, so the main file can look quite simple like this:

// Stylus Configuration & Mixins
@require "_config/*"
@require "_mixins/*"

/*--------------------------------------------------------------
 * Base
 *--------------------------------------------------------------*/
@require "base/reset/*"
@require "base/*"
@require "base/**/*"

/*--------------------------------------------------------------
 * Modules
 *--------------------------------------------------------------*/
@require "modules/*"

/*--------------------------------------------------------------
 * Site
 *--------------------------------------------------------------*/
@require "site/*"
@require "site/**/*"

I like the general idea behind _s folder structure, but the root level has too many folders. My solution was to group everything in 3 parts:

0. /config/ and /mixins/ - before anything gets styled, config files are loaded
1. /base/ - the resets, general element styles, nothing with class-level selectors. Only plain elements here.
2. /modules/ - the common WordPress element styles/resets, like Gallery, Captions, Screen-readers, etc.
3. /site/ - Everything else - this is where the "the real styling" starts

Everything further down in a folder is self-explanatory. This has worked for me personally quite well.

[samikeijonen]

I like the general idea behind _s folder structure, but the root level has too many folders.

I agree that there might be too many folders, and that comes up in conversations.

Your folder is easy to read, I can tell you that:)

[davidakennedy]

I'd be for this. Internally, on the Theme Team at Automattic, we've talked about iterating on the structure, but haven't done so yet. We did it in Components, and it was much simpler. Would love to see a direction like that.

[benoitchantre]

I agree that scss file organization should be reviewed. Personally, I found it better with Components.

Here are as another example, the scss part of 10up Engineering Best Ptractices. The same structure documented in XWP Engineering Best Practices.

|- assets/css/scss/
|  |- global/ ____________________________ # Functions, mixins, placeholders, and variables
|  |- base/
|    |- reset, normalize, or sanitize
|    |- typography
|    |- icons
|    |- wordpress ________________________ # Partial for WordPress default classes
|  |- components/
|    |- buttons
|    |- callouts
|    |- toggles
|    |- all other modular reusable UI components
|  |- layout/
|    |- header
|    |- footer
|    |- sidebar
|  |- templates/
|    |- home page
|    |- single
|    |- archives
|    |- blog
|    |- all page, post, and custom post type specific styles
|  |- admin/ _____________________________ # Admin specific partials
|  |- editor/ ____________________________ # Editor specific partials (leverage placeholders to use in front-end and admin area)
|  |- admin.scss
|  |- project.scss
|  |- editor-styles.scss

I never used it but seems well organized and easy to understand. What are your thoughts on this?

[samikeijonen]

I like where this conversation is going! Based on feedback I think we could go with 4-5 main folders, for example: base, components, global, and layout.

What goes into which folders and how to name folders is next step. I can create suggestion PR next week, it's easier for me actually think while doing.

[brettsmason]

The Sass structure is one area I've always felt needed a rework.

A few nice organisation structures are SMACSS and my personal favourite, the 7-1 pattern: https://sass-guidelin.es/#the-7-1-pattern (with a few tweaks). There's some good info on there to help know where to put things etc.

[samikeijonen]

Thanks @brettsmason! That's pretty much what I had in mind.

I made first suggestion in #1232. I have couple of comments and questions but it's now time for sleep.

@davidakennedy I just noticed that you had assigned this for yourself. Sorry if I stepped on your toes.

[kevinwhoffman]

I have been following an architecture called ITCSS (Inverted Triangle CSS) for the last couple of years and find it to be the best approach I've used to date (after previously using SMACSS and then BEM). It was originally proposed by Harry Roberts, and is based on seven "layers" with specific purposes that get more specific as you move down the triangle.

The ITCSS Architecture

To summarize the seven layers:

Settings – used with preprocessors and contain font, colors definitions, etc. Tools – globally used mixins and functions. It’s important not to output any CSS in the first 2 layers. Generic – reset and/or normalize styles, box-sizing definition, etc. This is the first layer which generates actual CSS. Elements – styling for bare HTML elements (like H1, A, etc.). These come with default styling from the browser so we can redefine them here. Objects – class-based selectors which define undecorated design patterns, for example media object known from OOCSS Components – specific UI components. This is where majority of our work takes place and our UI components are often composed of Objects and Components Utilities – utilities and helper classes with ability to override anything which goes before in the triangle, eg. hide helper class

Flat File Structure

One of the nice things about ITCSS is that the file structure is flat. The files are namespaced, but they all live in one directory so you never have to dig through directories to find what you want.

For more information:

https://www.xfive.co/blog/itcss-scalable-maintainable-css-architecture/ https://youtu.be/1OKZOV-iLj4?t=9m55s

[dingo-d]

I personally don't like flat file structure. It seems messier. The approach seems good, but I don't see what is wrong with logical compartmentalization of files into folders.

[pyronaur]

I agree. Folders were invented for a reason - so that we wouldn't have to namespace files. Flat file structure just seems as a step backward.

I think there is a place for ITCSS and Harry is using it to help companies optimize their CSS. However, I don't think a collaborative open source project is that place. You shouldn't have to learn & understand ITCSS (or any other framework) before you can use _s.

[samikeijonen]

Thanks @kevinwhoffman for the info! I like a lot of things in ITCSS.

In the same time as we are thinking folder structure and how to name folders, we should think about how to organize CSS. It's not just about do we have folders inside folders.

For example links should be in elements, not inside navigation in my opinion.

[brettsmason]

@samikeijonen I'd also suggest a vendor directory. This has the benefit of being able to put all 3rd party code (eg infinite scroll/Jetpack, WooCommerce etc) in its own directory so that it can be easily identified and removed if not needed.

Agree on organising the actual CSS too - could use some changes 👍

ITCSS is indeed also a nice architecture, though details about it are somewhat hard to come by for more details 😄

[kevinwhoffman]

I personally don't like flat file structure. It seems messier. The approach seems good, but I don't see what is wrong with logical compartmentalization of files into folders.

ITCSS could be just as applicable with folders.

I think there is a place for ITCSS and Harry is using it to help companies optimize their CSS. However, I don't think a collaborative open source project is that place. You shouldn't have to learn & understand ITCSS (or any other framework) before you can use _s.

Any decision made here is going to impose an opinionated workflow in some form. Shouldn't _s lead by example with a scalable, modular architecture? If the developer has their own approach, they can always wipe out the styles directory and start fresh as I've done for years.

I'd also suggest a vendor directory.

That's a good point. I often add a vendor layer in ITCSS that sits between Objects and Components. That way any styles that need to extend the vendor styles can be done in their own component.

ITCSS is indeed also a nice architecture, though details about it are somewhat hard to come by for more details.

ITCSS is just the architecture that organizes the SCSS partials. The nuts and bolts of writing CSS are covered in https://cssguidelin.es/ (also by Harry Roberts). I've used ITCSS and CSS Guidelines together to get teams on the same page for years, and I think it could translate just fine to open source.

[m-e-h]

Happy to see this discussion. :smiley: CSS structure is something I've spent a lot of time toying with and what I've learned is that keeping a close eye on specificity is the only way to stay sane.

Following the Inverted Triangle (ITCSS) method of organizing produces predictable front-end styles without worry of unintentionally overriding other styles.

The rules of ITCSS are basically this: Group your stylesheets according to their specificity and then import them in order from least specific(elements) to greatest(utility classes). The file or folder names don't really matter as long as they make sense.

Looking at what @samikeijonen put together, it wouldn't be difficult to organize in this manner. Here's a quick example. I'm sure I've missed some things..

global (or tools)
    variables
    mixins
    normalize
elements (html elements only: no '.classes' here)
    site (general styles- html, body, hr, etc.)
    links
    lists
    tables
    typography
    headings
    images
    forms
    buttons
layouts (or objects)
    comments
    content-sidebar
    sidebar-content    
    widgets
components
    navigation
    media
plugins
    shop
        checkout
        products
        ---
    jetpack
        infinite-scroll
        ---
utilities
    clearings
    alignments
    accessibility

Completed themes and sites will likely have a ton of "component" styles. This being a starter theme, should probably be mostly styled "elements" which will get overridden by components as the theme gets built out.

[samikeijonen]

Thanks @m-e-h for stepping in! I 110% agree everything you said. I'll try to create 1-2 different PR so we get ideas tested out.

[kevinwhoffman]

Regarding ITCSS, I should also note that the main stylesheet which imports the partials can function as inline documentation that goes a long way towards teaching the developer how the architecture is meant to be used. As an example, here is a template that I start every project with.

/**
 * Main stylesheet for the {THEME_NAME} theme.
 *
 * Theme styles follow http://cssguidelin.es/ and are organized according to
 * Inverted Triangle CSS (ITCSS) principles put forth by Harry Roberts. In
 * short, each layer of CSS gets more specific as you move down this page.
 */

/*--------------------------------------------------------------
# Settings - Global variables, config switches.
--------------------------------------------------------------*/

// Import Settings partials here.

/*--------------------------------------------------------------
# Tools - Default mixins and functions.
--------------------------------------------------------------*/

// Import Tools partials here.

/*--------------------------------------------------------------
# Generic - Ground-zero styles (resets, box-sizing, etc.).
--------------------------------------------------------------*/

// Import Generic partials here.

/*--------------------------------------------------------------
# Elements - Unclassed HTML elements (type selectors).
--------------------------------------------------------------*/

// Import Element partials here.

/*--------------------------------------------------------------
# Objects - Cosmetic-free design patterns.
--------------------------------------------------------------*/

// Import Object partials here.

/*--------------------------------------------------------------
# Vendors - Third-party styles or extensions thereof.
--------------------------------------------------------------*/

// Import Vendor partials here.

/*--------------------------------------------------------------
# Components - Designed components, chunks of UI.
--------------------------------------------------------------*/

// Import Component partials here.

/*--------------------------------------------------------------
# Utilities - Helpers and overrides.
--------------------------------------------------------------*/

// Import Utility partials here.

[samikeijonen]

Okay second version is up in PR #1234 which uses ITCSS approach. I probably broke something even if I tested it couple of times.

Note that I broke away from the current style.css sync on purpose. If we're going to remove that anyway it's not going to be a problem. If we're going to keep it, I'll fix it.

I'm not sure if it's best to comment this approach only in the PR #1234. @kevinwhoffman Would love to have your comment is it even close what you had in mind. Couples of folders are named differently but that's not that important at the moment.

[rilwis]

In addition to keep some root folder, I think some of them can be flatten to files, such as:

variables.scss # All variables, there's no need to keep them in separated files. We usually don't have > 100 variables.
base.scss      # All basic styles for HTML elements, including typography, lists, tables, forms, etc. Only basic styles (global styles)

Also, I suggest combine these folders into one (components, modules, objects). They serve very similar purpose (for reusable components), even sometimes confusing in differentiating them. I've been using ITCSS for a while, and still confused using these terms. Let's pick a general name for them. I think what @samikeijonen proposed on using components is good.

I also think WordPress utilities (screen reader text, caption, gallery) or other frameworks' utilities (alert box, tabs, etc.) can also be added in this folder.

Final thing is layout. I think it's a good name, since I always have to put all styles for footer, header, sidebar, ... in the current site folder (which I think is a bad name). In general, I'd like this folder to be a container of styles for all specific parts of the website.

So my suggestion is having these:

variables.scss
base.scss
components/
layout/

[samikeijonen]

@rilwis You were referring to PR #1234, right?

variables.scss # All variables, there's no need to keep them in separated files. We usually don't have > 100 variables.

It could be like this also. I'm fine with both.

variables.scss base.scss components/ layout/

I disagree on this one. It would not be clear how important the specificity and order of styles are.

[m-e-h]

I kind of like the idea of a single variables.scss file in the top-level of the sass folder. If that happens, should probably follow suit with the mixins.scss since it's already a single file. No sense in making people guess which folder contains these files if we don't have to: "tools? settings? generic?".

@rilwis the utility classes in the utilities/ folder are very different than components. These are single use classes that can be added to a component to perform a single function or change a single attribute. They should, in all cases, override any style in the components/ folder.

I also think a general "catch all" file like base.scss is nice. I usually use one called page.css. It's a good place for more opinionated global element styles that normalize.css leaves out. A lot of the styles in the current elements.scss would go here like the html, body, hr, and border-box.

And I agree that it's better to use naming because it generally makes sense, rather than because a trending framework or methodology uses it.

Another common ITCSS name which I think isn't so intuitive is generic/. What about naming that something like base/? We could maybe even throw the general file mentioned above in there.

[samikeijonen]

I kind of like the idea of a single variables.scss file in the top-level of the sass folder. If that happens, should probably follow suit with the mixins.scss since it's already a single file. No sense in making people guess which folder contains these files if we don't have to: "tools? settings? generic?".

We also need to think what happens when the actual theming starts based on _s. If variables.scss and mixins.scss are on top-level of the sass folder then where would developer put functions.scss file. Or similar files. I don't think top-level folder is the place for additional files, it would not guide developers how to actually organize and structure CSS.

In short I'm still confident that having style.scss should be the only file in top-level sass folder.

One option is having base folder like this:

base
--- variables.scss // All variables.
--- mixins.scss
--- functions.scss // And other base stuff developer might want to add. Not in _s at the moment.

--- normalize.scss
--- box-sizing.scss

This would leave out folders settings, tools, and generic. And they would become folder base or whatever it's called.

Also note that we are never going to find names for folders that everyone agree on. Renaming folders in own theme is OK.

But naming folders is not the most important thing. Educating and guiding developers to scalable, modular, hierarchical CSS architecture is more important. Naming the folders is only one part of it.

[m-e-h]

where would developer put functions.scss file. Or similar files.

Good point. Also real world projects could outgrow the single variables or mixins files.

I don't know if it's the best thing to mix the tool files and the style files in base/ like that though.

As long as the user can find a file within the first or even second guess as to which folder it's in, I think the structure will be considered intuitive and uncomplicated. For that, steering clear of ambiguous folder and file names can make a big difference.

But you're right, everyone isn't going to agree on naming and I do tend to overthink things. :smile:

[rilwis]

@samikeijonen #1234 is still too complicated to me. I think we should make a simple structure with a good & detailed guidelines. ITCSS seems to be a complex standard. I brought some idea from it, but don't use everything.

Regarding the base folder, it makes sense to keep a folder for all the general files. Perhaps the top-level file is a good idea only when the number of files small.

@m-e-h I understand the difference between utilities and components. I actually started to use utility frameworks like Tachyon. However, the way we build WordPress website lacks of those utilities. In reality, I often keep all of them in 1 file. So perhaps, put it in base folder?

[samikeijonen]

@rilwis Can you give an example how would you structure folders and all the files?

Edit: Sorry I missed it's already in this comment.

I also probably don't follow 100% how we define and name things in here. So it's totally fine to fine tune them in your own work.

But we are aiming for the solution that helps developers to have a rock solid base structure based on all the things we have discussed here.

[rilwis]

Guys, is there any update on this issue? I'd love to cleanup the sass folder, but don't want to maintain that on my own. A common practice is appreciated.

[samikeijonen]

No update on this. I have personally moved pretty much to ITCSS structure.

[rilwis]

Too bad. I think this issue is a critical thing on how to code well.

[samikeijonen]

Absolutely agree, it's the most important thing in my opinion too.

I'm sure _s maintainers pick this up at some point.

[kevinwhoffman]

I think ITCSS is still the way to go. I've been using it for 2 years now and recently presented it at WordCamp San Diego where I showed how it can be leveraged in Gutenberg blocks as well as standard themes. The audience seemed to grasp the key concepts in a 45-minute talk, and I'm confident we could distill that down to written documentation--one doc for the overall approach and then a doc for each layer in the triangle with examples.

I understand the urge to remove layers from the triangle in an effort to simplify the architecture, but in my experience every one of those layers has a purpose and they appear in a specific order to ensure the most specific styles (e.g. utilities) appear last.

I have limited availability right now but I will gladly assist if someone wants to take the lead here.

Here are my slides for Blocks & Triangles: Front-end Architecture in the Gutenberg Era.

[samikeijonen]

I understand the urge to remove layers from the triangle in an effort to simplify the architecture, but in my experience every one of those layers has a purpose and they appear in a specific order to ensure the most specific styles (e.g. utilities) appear last.

Agreed.

Here are my slides for

I looked them before, super good overview!

---

I can proceed with this if there is green light from _s maintainers. Or they can pick this for their own architecture.

Anyways SASS/CSS structure would need to be re-written from to ground up and put it on priority.

[rilwis]

I found a similar implementation from 10up.com's best practice website, which is kind of following the ITCSS principle.

I think we can make a fork to _s and propose the new structure. Until now, we have discussions, but no real propose. I'm happy to contribute to do that.

[samikeijonen]

@rilwis Go for it. There are some work done in #1234.

[Ismail-elkorchi]

To move this issue forward I have created a PR ( https://github.com/Automattic/_s/pull/1425 ) which includes much of the feedback that we have got so far. Your thoughts are welcome!