Suggestion: Create a utility/debug class to display a phantom of the grid

[Xavier Zalawa]

The intention

Draw a phantom representing the columns and the gutters of the used grid in the background of a .grid element.
The main will is to avoid the debug of each cell (with the help of a background-color for exemple) and to debug really the grid itself.
For that, I propose to simplify/popularise the debug operation at its maximum. It could be done by adding a CSS class (e.g.: <div class="grid debug"> ... </div>) or setting a variable (e.g.: $grid-debug: true;).
The objective with these propositions is to carry out all external dependencies (e.g.: #grid or Compass Grid Backgrounds) and
to be able to answer the project's characteristics:

• Not changing the first aim of the project and using the Griddle environment (Sass and CSS).
• Drawing a template which can be composed by two different units.
• Modifying the debugging phantom (number of columns, color, ...) to adjust it in different contexts (e.g.: --desktop).
• Being able to apply more than one phantom to debug nested or adjacent grids.

Here is some debug's phantoms tests to present the expected working.

The proposal

Naming convention for the use of phantom(s)

debug - The core phantom grid class
debug-ofY (numerous) - Specify the number of drawn columns. Y must be an integer and represents the same unit as in .unit-XofY
debug-ofY--C - The optional modifier to describe different contexts (e.g. viewport dimensions)

$grid-debug global variable

During development, you can switch this variable to:

• load the needed CSS in _griddle.scss partial
• use the griddle-debug mixin
• apply .debug-ofY[--C] classes in your markup

@import "griddle-debug";

...

$grid-debug: false !default; // can be switch to 'true'

...

// Check if you are in "debug mode"
// and if your grids use any gutters
@if not not $grid-debug and $grid-gutter > 0 {

    /* Grid debug
       ========================================================================== */

    /**
     * Grid phantom
     * Must only apply on an component with `.grid` class.
     *
     * Note :
     * According to this test case http://7studio.fr/github/griddle/test-debug-phantoms/bg-size/,
     * the column width should be rounded as follows:
     * ceil(W * 100) / 100
     *
     * 1. Draw (left to right) a linear gradient of colors
     *    representing the gutter follow by the column.
     * 2. Move to a half-gutter to the left,
     *    the initial position of background image.
     * 3. Set the width of column (including gutters) as with
     *    of the background image (e.g.: `8.34% 100%`).
     *    By default, drawn a no background.
     */

    .grid[class*='debug-of'] {
        background-image: -webkit-linear-gradient(left
           ,transparent $grid-gutter
           ,rgba(230, 36, 153, .15) $grid-gutter
        ) !important; /* 1 */
        background-image: linear-gradient(to right
           ,transparent $grid-gutter
           ,rgba(230, 36, 153, .15) $grid-gutter
        ) !important; /* 1 */
        background-position: -0.5 * $grid-gutter 0 !important; /* 2 */
        background-size: 0 0; /* 3 */
    }
}

Optional $debug argument to pass to griddle-build

The $debug argument is set by default with the $grid-debug value firstly the backward compatibility.
If this argument value is true, the mixin will ask to create phantoms for each of its units.
In the case, it should not, you can set this argument to false and (if you need) use the griddle-debug mixin with your own units.

@mixin griddle-build($units, $modifier: '', $debug: $grid-debug) {

    ...

    @if not not $debug {
        @include griddle-debug($units, $modifier);
    }
}

Here is how to override the default working:

$grid-debug: true !default;

...

// Create 2, 4, 5, 6, and 12 column grids (wider screens)
@include griddle-build(2 4 5 6 12, '--desktop', false);

// Create 4, 6, and 12 column grid phantoms (wider screens too)
@include griddle-debug(4 6 12, '--desktop');

griddle-debug mixin

To respect the project organisation, all the code below will be write in an independant file _griddle-debug.scss.

// =============================================================================
// Griddle debug functions
// =============================================================================

// Fluid debug's phantoms of grid

// USAGE: provide a space-separated list of integers, each of which represents
// the number of columns that make up phantoms of grid component. Optionally provide a
// modifier suffix that can be used to adjust grid phantoms in different contexts (e.g.
// viewport dimensions).

@mixin griddle-debug($units, $modifier: '') {
    // Don't write rules without the needed CSS
    @if not not $grid-debug and $grid-gutter > 0 {
        /* Proportional phantoms
          ========================================================================== */

        /*
         * Specify the proportional column width of a grid phantom.
         * Limited to, use with `.grid` components.
         */

        @each $n in $units {
            // Avoid creating rules like `.debug-of1 {}`
            @if $n > 1 {
                .debug-of#{$n}#{$modifier} {
                    background-size: (ceil(percentage(1 / $n) * 100) / 100) 100% !important;
                }
            }
        }
    }
}

Browser support

Google Chrome (latest)
Opera 12.1+
Firefox 24.1.0+ (esr version)
Safari 5+
Internet Explorer 10+

What do you think?
I will be happy to have your feedbacks on the suggested feature and also on the way how I presented it.

Thanks!