File structure

[MichaelArestad]

I suggest an atomic structure with small self-contained modules. I prefer a version inspired by a Dale Sande article (or video).

Here's how I propose each module is structured:

// Module structure
// 1. main file with styles
// 2. functions used with main file
// 3. mixins used with main file
// 4. variables used with main file

|- typography/
|--- functions.scss  // 2
|--- mixins.scss     // 3
|--- typography.scss // 1
|--- variables.scss  // 4

And how the overall file structure might look:

// 1. _utilities contains global mixins module, normalize, etc
// 2. atoms contains modules like buttons
// 3. molecules contains  modules like nav_horizontal
// 4. organisms contains more complex modules like banner
// 5. views contains individual page/view templates like admin

|- sass/
|--- _utilities/ // 1
|--- atoms/      // 2
|--- molecules/  // 3
|--- organisms/  // 4
|--- views/      // 5
|--- style.scss

Pros

• This method keeps everything pretty tidy. The variables, functions, mixins, extends (dependencies) relevant to a module together rather than scattering them around via a massive variables file, etc.
• The module name is the same as the .base name of the module's rules and components. If the module was calendar, it's rules might be calendar_day.is-today (I'm referencing the BEM naming convention I referenced here. This makes it easy to avoid naming conflicts as it's easy to spot the base elements in use. There is an added benefit of knowing where to find which file a class was declared in by just knowing the class name.
• There are no mystery junk drawer files. For example, there is no giant universal file with a series of placeholder selectors and no way to know which selectors exist and where they are used.
• Because of it's structure, style.css ends up being a pretty rad little table of contents that might look like this:

@import "atoms/colors/colors",  // Global color variables
    "_utilities/mixins/mixins", // Global mixins
    "_utilities/clearings",

    "atoms/typography/typography",
    "atoms/media",
    "atoms/animations",
    "atoms/buttons",
    "atoms/icons/genericons",

    "molecules/nav-horizontal",
    "molecules/nav-off-screen",
    "molecules/alerts",

    "organisms/contact-form",
    "organisms/calendar",

    "views/main",
    "views/settings";

Cons

• Looks weird and scary at first. It's not.
• Can be tricky to figure out whether a module is a molecule or organism. Don't sweat it too much. Just place it where it feels right.

[sfrisk]

Looks interesting. Best I can figure the difference between molecule and organism is an organism might have molecules in it? Or is it more than that?

I definitely could get behind a file organization system like this.

[MichaelArestad]

Best I can figure the difference between molecule and organism is an organism might have molecules in it? Or is it more than that?

That's generally the case.

[cbracco]

I do like this type of organization as well. The next version of Cardinal will have LESS files organized in a similar manner, like so:

|____areas
| |____boxes.less
| |____grids.less
| |____strips.less
| |____wrappers.less
|____base
| |____anchors.less
| |____base.less
| |____blockquotes.less
| |____fonts.less
| |____forms.less
| |____headings.less
| |____horizontal-rules.less
| |____reset.less
| |____selections.less
| |____shared.less
| |____syntax.less
| |____tables.less
|____cardinal.less
|____components
| |____buttons.less
| |____icons.less
| |____lists.less
|____objects
| |____media.less
|____print
| |____print.less
|____settings
| |____mixins.less
| |____variables.less
|____utilities
| |____alignment.less
| |____display.less
| |____layout.less
| |____position.less
| |____spacing.less
| |____text.less
| |____widths.less
| |____z-index.less

Base = normalize, reset, and styling for common elements (aka atoms) Areas = spaces where common elements, components, and objects can live Components = a collection of one or more common elements Objects = a collection of one or more common elements and/or components. Print = print styles Settings = variables and mixins Utilities = helper classes

Not saying we should do it exactly like this, simply sharing some additional thoughts around the subject. I like the suggestions of @MichaelArestad!

[sfrisk]

Also brought up in the January 6, 2015 meeting: Possibility of bundling component styles with components rather than in the sass folder. Example: https://github.com/topcoat/button-bar-template/tree/master/example

[trailofdad]

After much thought, I really like the structure proposed by @MichaelArestad . I do think the documentation would have to make it clear the difference between atoms, molecules and organisms. I feel like some people might be confused otherwise. I do like how in the example that @cbracco had contributed is very obvious where everything goes. I think the best way would be to make sure that everything is as modular as possible and easily readable. I'm going to do some more looking around at other file structures.

[trailofdad]

I've explored a lot of other file structures today and I think the atomic structure is the best option. Some file structures have upwards of 10 folders in the root. I don't know about anyone else but I like to keep my files super tidy. It would be best to have the framework be minimally abrasive and complicated to the user.

[arschmitz]

@sfrisk does it make since to keep this open? We already landed most of whats being covered here. The only thing not already landed is where the html files will go ( I think only because there is nothing in it yet and git wont maintain an empty folder ), but if i'm not mistaken we decided we wanted to keep those in a separate folder ( hence the scss folder name we already landed ). So it seems like this could be closed.

[sfrisk]

I think we're good to close this.

[maikuru]

@arschmitz One can just create the folder with a .gitignore file in it to at least maintain structure while in this early phase

[arschmitz]

@maikuru true just not sure there is a point until we do have something to put it in.

[maikuru]

@arschmitz to stop people from wondering where it's going to go someday ;)