locomotive-boilerplate/docs/grid.md

# Grid system

* [Architectures](#architecture)
  * [Build tasks](#build-tasks)
    * [Configuration](#configuration)
* [Usage](#usage)
  * [Example](#example)

## Architecture

The boilerplate's grid system is meant to be simple and easy to use. The goal is to create a light, flexible, and reusable way to build layouts.
The following styles are needed to work properly:

* [`o-grid`](../assets/styles/objects/_grid.scss) — Object file where the default grid styles are set such as column numbers, modifiers, and options.
* [`u-grid-columns`](../assets/styles/utilities/_grid-column.scss) — Utility file that generates the styles for every possible column based on an array of media queries and column numbers.

### Build tasks

The columns generated by [`u-grid-columns`](../assets/styles/utilities/_grid-column.scss) adds a lot of styles to the compiled CSS file. To mitigate that, [PurgeCSS] is integrated into the `styles` build task to purge unused CSS.

#### Configuration

Depending on your project, you will need to specify all the files that include CSS classes from the grid system. These files will be scanned by [PurgeCSS] to your compiled CSS files.

Example of a Charcoal project:

```jsonc
"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-md {
            @media (min-width: $from-md) {
                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>
```

[PurgeCSS]: https://purgecss.com/