locomotive-boilerplate/docs/grid.md

Grid system

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

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 — Object file where the default grid styles are set such as column numbers, modifiers, and options.
• u-grid-columns — 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 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:

"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>