Welcome document

structure

# Architecture

    sass/
    |
    |– base/
    |   |– _reset.scss       # Reset/normalize
    |   |– _typography.scss  # Typography rules
    |   |– _all.scss         # To be imported
    |   ...                  # etc…
    |
    |– globals/
    |   |– _colors.scss      # Color variable objects
    |   |– _buttons.scss     # Buttons variable objects
    |   |– _all.scss         # To be imported
    |   ...                  # etc…
    |
    |– components/
    |   |– _buttons.scss     # Buttons
    |   |– _carousel.scss    # Carousel
    |   |– _cover.scss       # Cover
    |   |– _dropdown.scss    # Dropdown
    |   |– _navigation.scss  # Navigation
    |   |– _all.scss         # To be imported
    |   ...                  # etc…
    |
    |– helpers/              # Can be breaked in more folders /funcions /mixins
    |   |– _functions.scss   # Sass Functions
    |   |– _mixins.scss      # Sass Mixins
    |   |– _helpers.scss     # Class & placeholders helpers
    |   |– _all.scss         # To be imported
    |   ...                  # etc…
    |
    |– partials/
    |   |– _grid.scss        # Grid system
    |   |– _header.scss      # Header
    |   |– _footer.scss      # Footer
    |   |– _sidebar.scss     # Sidebar
    |   |– _forms.scss       # Forms
    |   |– _all.scss         # To be imported
    |   ...                  # etc…
    |
    |– pages/
    |   |– _home.scss        # Home specific styles
    |   |– _contact.scss     # Contact specific styles
    |   |– _all.scss         # To be imported
    |   ...                  # etc…
    |
    |– themes/
    |   |– _theme.scss       # Default theme
    |   |– _admin.scss       # Admin theme
    |   |– _all.scss         # To be imported
    |   ...                  # etc…
    |
    |– vendors/
    |   |– _bootstrap.scss   # Bootstrap
    |   |– _jquery-ui.scss   # jQuery UI
    |   |– _all.scss         # To be imported
    |   ...                  # etc…
    |
    |– _shame.scss           # Temporary fix/hacks. All code here is a shame
    |– main.scss             # primary Sass file

## Base

The `base/` folder holds what we might call the boilerplate stuff for your project.
In there, you might find the reset (or Normalize.css, or whatever), probably some stuff dealing with typography, and, depending on the project, maybe some other files.

## Globals

The `globals/` folder holds all the global stuff, mostly variables and config files.

## Partials

The `partials/` directory usually contains a number of files, each of them setting some styles for the main sections of the layout (header, footer, and so on).

## Components

For smaller components, there is the `components/` folder. While `partials/` is kind of macro (defining the global wireframe), `components/` is more micro.
It can contain all kinds of specific modules like a slider, a loader, a widget, or anything along those lines.
There are usually a lot of files in `components/` since your site is should be mostly composed of tiny modules.

## Pages

For any page-specific styles, you have the `pages/` folder and in a file named after the page.
For example, it’s not uncommon to have very specific styles for the home page, so you’d have a `_home.scss` file in `pages/` dealing with this.

## Themes

If you are working on a large site with multiple themes like I do, having a `themes/` folder can make sense.
You can stuff all your theme/design related styles in there. This is definitely project-specific so be sure to include it only if you feel the need.

## Vendors

And last but not least, you will probably have a `vendors/` folder containing all the CSS files from external libraries and frameworks – Bootstrap, jQueryUI, FancyCarouselSliderjQueryPowered, and so on.
Putting those aside in the same folder is a good way to tell “Hey, this is not from me, not my code, not my responsibility”.
Any change on default vendor behavior should also be placed here too.

## `_shame.scss`

The idea of shame.css is that you have a totally new stylesheet reserved just for your hacky code.
The code you have to write to get the release out on time, but the code that makes you **ashamed**.

#### The rules

Obviously you need some kind of rules and criteria:

1. If it’s a hack, it goes in `_shame.scss`.
1. Document all hacks fully:
  1.1. What part of the codebase does it relate to?
  1.1. Why was this needed?
  1.1. How does this fix it?
  1.1. How might you fix it properly, given more time?
1. Do not blame the developer; if they explained why they had to do it then their reasons are probably (hopefully) valid.
1. Try and clean `_shame.scss` up when you have some down time.
  1.1 Even better, get a tech-debt story in which you can dedicate actual sprint time to it.
1. Should **always** be imported lastly

##### E.g.
    /**
     * Nav specificity fix.
     *
     * Someone used an ID in the header code (`#header a {}`) which trumps the
     * nav selectors (`.site-nav a {}`). Use !important to override it until I
     * have time to refactor the header stuff.
     */
    .site-nav a {
      color: #BADA55 !important;
    }