locomotive-boilerplate/docs/grid.md

Grid system

• Architectures
  • Styles
  • Build tasks
    • Config file
• Usage
  • Example
• Limitations

Architectures

The Grid System is meant to be simple and easy to use. To goal is to create a light, flexible and reusable way to build layouts.

Styles

Some styles are needed to make it work properly :

• o-grid.scss: Object file where the default grid styles are set. Column numbers, modifiers, options.
• u-grid-columns.scss: Utility file where it generates every possible column styles based on an array of media queries and column numbers.

Build tasks

The generation of columns adds a lot of styles in the css output file. To solve that, a build task is set up to purge unused css generated by u-grid-columns.scss using PurgeCSS.

Config file

Depending on your project, you will need to specify all the files that will include the Grid System classes. These files will be parsed by PurgeCSS and then a "cleaned" css file will be generated. The styles should also compile everytime the following listed files are changed.

Example of a Charcoal project:

"purgeCSS": {
    "content": [
        "./views/app/template/**/*.mustache",
        "./src/App/Template/*.php",
        "./assets/scripts/**/*" // use case: `el.classList.add('u-gc-1/2')`
    ]
}

## Usage

The first step is to set intial SCSS values in the following files :

- [`settings/_config.scss`](../assets/styles/settings/_config.scss)

    ```scss
    // Grid
    // ==========================================================================
    $base-column-nb: 12;
    $base-column-gap: $unit-small;
    ```

    You can create multiple column layouts depending on media queries.

- [`objects/_grid.scss`](../assets/styles/objects/_grid.scss)

    ```scss
    .o-grid {
        display: grid;
        width: 100%;
        margin: 0;
        padding: 0;
        list-style: none;

        // ==========================================================================
        // Cols
        // ==========================================================================
        &.-col-#{$base-column-nb} {
            grid-template-columns: repeat(#{$base-column-nb}, 1fr);
        }

        &.-col-4 {
            grid-template-columns: repeat(4, 1fr);
        }

        &.-col-#{$base-column-nb}\@from-medium {
            @media (min-width: $from-medium) {
                grid-template-columns: repeat(#{$base-column-nb}, 1fr);
            }
        }
        // …
    ```

### Example

The following layout has 4 columns at `>=999px` and 12 columns at `<1000px`.

```html
<div class="o-container">
    <h1 class="c-heading -h1">Hello</h1>

    <div class="o-grid -col-4 -col-12@from-medium -gutters">
        <div class="o-grid_item u-gc-1/8@from-medium">
            <h2 class="c-heading -h2">This grid has 4 columns and 12 columns from `medium` MQ</h2>
        </div>

        <div class="o-grid_item u-gc-1/5@from-medium">
            <p>Lorem, ipsum dolor sit amet consectetur adipisicing elit. Expedita provident distinctio deleniti eaque cumque doloremque aut quo dicta porro commodi, temporibus totam dolor autem tempore quasi ullam sed suscipit vero?</p>
        </div>

        <div class="o-grid_item u-gc-5/9@from-medium">
            <p>Lorem, ipsum dolor sit amet consectetur adipisicing elit. Expedita provident distinctio deleniti eaque cumque doloremque aut quo dicta porro commodi, temporibus totam dolor autem tempore quasi ullam sed suscipit vero?</p>
        </div>

        <div class="o-grid_item u-gc-9/13@from-medium">
            <p>Lorem, ipsum dolor sit amet consectetur adipisicing elit. Expedita provident distinctio deleniti eaque cumque doloremque aut quo dicta porro commodi, temporibus totam dolor autem tempore quasi ullam sed suscipit vero?</p>
        </div>
    </div>
</div>