Automatically build your grid design’s CSS Grid code, CSS Flexbox fallback code, Sketch artboards, and Chrome extension.

  • By International Business Machines
  • Last update: Dec 31, 2022
  • Comments: 17

CSS Gridish

CSS Gridish Logo

CSS Gridish takes design specs of your product’s grid and builds out several resources for your team to use:

  • Sketch file with artboards and grid/layout settings for designers
  • CSS/SCSS code using CSS Grid with a CSS Flexbox fallback for developers
  • Google Chrome extension for anyone to check a webpage’s alignment

This tool is not a grid system with a grid already designed for you. Instead, CSS Gridish builds all of the resources for the grid your team designed.

We hope it helps teams adapt CSS Grid sooner and enables more complex layouts. To show how versatile the tool is, we have examples of grids from Bootstrap, Carbon Design System, and Material Design.

The truth is that many enterprise projects can’t afford to drop support for browsers that do not support CSS Grid Layout yet. This tool takes your grid’s design specs and builds a slim CSS Grid Layout implementation and a fallback to CSS Flexbox support.

Build your grid code

Requires Node v8.2.0 or higher, which includes npm and npx.

  1. Create a file called css-gridish.json in your project root. See the config documentation or an example config for help.
  2. Determine how you want your grid built:
    • If you want to build once, run command npx css-gridish.
    • If you want to add the grid building to your project’s build process:
      1. Run command npm install css-gridish.
      2. Add scripts: {build: "css-gridish"} in your package.json.
      3. Run command npm run build.

Your CSS and README.md with class documentation will be built into ./css-gridish/.

Config file

CSS Gridish takes design redlines and makes developer-friendly code

The config file is where all of your design system specs live. See this example for help. Edit your css-gridish.json to have all generated grid content match your design system:

{
  "prefix": "gridish", // Custom prefix for all classes and filenames
  "breakpoints": {
    // Class name for a breakpoint
    "sm": {
      "breakpoint": 20, // Min-width for media query (number in rem)
      "columns": 4, // Quantity of columns (number)
      "gutter": "2rem", // Space between columns (rem string, px string, vw string or 0)
      "margin": "3vw" // Horizontal margin of grid container (rem string, px string, vw string or 0)
    },
    ...
    "max": {
      "breakpoint": 100,
      "columns": 12,
      "gutter": "4rem",
      "margin": "5vw"
    }
  },
  "extraArtboards": {
    "xlg": 100 // Additional breakpoint for the Sketch file (number in rem)
  },
  "rem": 16, // Base rem unit for all measurements (number in px)
  "rowHeight": 0.5, // Height of a fixed row (number in rem)
  "rows": 30, // Quantity of row variables (number)
  "paths": {
    "route": "css-gridish", // Route that files save in from project root (optional, use `""` for project root, `"css-gridish"` is default)
    "intro": "intro.md" // Path to any markdown you want inserted at the top of your README.md documentation (optional)
  }
}

Tip: For the best results in Sketch, we recommend you make your grid breakpoints, margin, and gutter divisible by the row height.

Required: Even if your design specs do not change between breakpoints, you need to list the max-width breakpoint in the breakpoints object.

The first breakpoint min-width media query is not used to save kilobytes, but we recommend stating it anyways for future artboard-making tools.

Legacy support

If you are supporting browsers that lack CSS Grid Layout support, you can use css-gridish/yourPrefix-legacy.min.css and the legacy classes detailed in the README.md. With the legacy file and classes, the browsers that do not support the final CSS Grid Legacy spec will fallback to a CSS Flexbox alternative. The CSS Flexbox alternative supports embedded subgrids that still reflect the overall grid system’s column structure.

User-defined breakpoints

One of the best parts about CSS Grid Layout is that your users can rearrange the layout at any width in their own media query. Your grid will also support rearranging layout at custom breakpoints for the legacy implementation when the user compiles their own Sass. Just have them define the following map of rem widths before they import in your Sass file:

$extraBreakpoints: (
  xsm: 10,
  whatever: 78,
  superxlarge: 1000,
  ...
);
@import './css-gridish/scss/yourPrefix-legacy.scss;

Transitioning from Legacy

Once your experience can drop support for browsers like IE 11 and Edge <15, you can simply remove all legacy classes and switch over to the non-legacy files. This is a great progressive-enhancement for your performance when it happens.

Future Updates

  • Once Edge and Safari gain display: subgrid support, we can remove our dependence on vw units.
  • Once a solution in the CSS Grid spec is given for one item to ignore grid-gap, we can utilize grid-gap by default instead of opting in to padding classes.

FAQs

Why does none of the CSS Grid code use grid-gap for gutters?

A lot of times, you will want an item to break out of the gutters for background color, to extend media, or for another reason. Until the CSS Grid spec has a way to ignore that gutter, we use the padding classes (.yourGrid-padding) to opt-in to respecting the gutter. The padding classes are always half the size of a gutter for alignment.

Why are columns using vw units and sometimes the calc function?

Until Edge and Safari support display: subgrid, it will be difficult for you to write semantic HTML with CSS Grid Layout. We are able to take advantage of vw units and the calc function so you can embed your .yourPrefix-grid class inside of itself as much that is needed for you.

Why are there no row classes for the legacy implementation?

Thanks to flexbox’s wrapping functionality, nodes that specify rows are not necessary. Only create a node for a row if it has semantic or accessibility significance. You can keep embedding .yourPrefix-grid as necessary to accomplish this.

What happens in the legacy implementation if I specify the column width for one breakpoint, but not the next larger breakpoint?

To maintain a mobile-first opinion, column widths will scale to the next breakpoint if not specified. This means that a .yourPrefix__col--sm--3 (with 6 total columns) would automatically grow into a .yourPrefix__col--md--6 (with 12 total columns) if no md class was declared to maintain half of the screen size.

Github

https://github.com/IBM/css-gridish

Comments(17)

  • 1

    How does css-gridish work with container having max-width?

    As css-gridish using 100vw / 12 = 8.3333vw for each column width, rather than using 8.3333% for each one, how to make it work like a grid system that has container has max-width with auto margin on left and right side?

  • 2

    feat(scss): add modern css grid support to legacy column classnames

    This update adds modern css grid support to legacy column classnames for easier transition from flexbox.

    Action required to end users of your CSS Gridish grid would be that they are about to have all width behaviors attached to legacy classes also take affect in modern browsers. This means they would need to eliminate their excess CSS Grid code or make sure to overwrite the rules they did not mean to transfer over from legacy.

    We are in a weird place by using semver for a build tool. This has no breaking changes for the grid-creating users of Gridish, but is a breaking change to our users’ users.

    Thanks to @nilesh-chavan for starting this initiative.

  • 3

    Add scss for css grid-layout

    I was working on css-gridish. I face an Issue a grid-layout the fallback is only for flex but not for grid layout. I am working on it please help with grid-layout.

  • 4

    Setting margin at smallest breakpoint applies same margin at larger breakpoints when larger breakpoints' margins are set to zero

    css-gridish.json:

    {
      "prefix": "dnno",
      "breakpoints": {
    
        "sm": {
          "breakpoint": 20,
          "columns": 2,
          "gutter": "30px",
          "margin": "15px"
        },
        "md": {
          "breakpoint": 48,
          "columns": 12,
          "gutter": "32px",
          "margin": 0
        },
        "lg": {
          "breakpoint": 63.125,
          "columns": 12,
          "gutter": "32px",
          "margin": 0
        }
      }, 
      "extraArtboards": {
        "md": 48,
        "lg": 62,
        "xl": 75
      },
      "rem": 16,
      "rowHeight": 0.5,
      "rows": 30,
      "paths": {
        "route": "styles/base/grid",
        "intro": "grid-intro.md"
      }
    }
    

    When 'sm' margin is set to 15px with other breakpoints set to 0 (or also '0px'), .dnno-container receives

    padding-left: 15px; padding-right: 15px;

    I can confirm that if 'lg' breakpoint is set to '12px', the padding is applied properly to the container.

  • 5

    feat(js): optional javascript file to adjust grid to scrollbar width

    Comes after #38

    Adds an optional JavaScript file included at js/yourGrid-grid.js. This will adjust the grid to not go behind browser scrollbars since different browsers handle the vw unit differently. It applies to any browser that supports CSS Variables and MutationObserver.

    Thoughts, @joshblack?

  • 6

    [docs] Improve class name readability and add common definitions to help first-time users

    After talking to some first-time users, there are two small things we can change to make this documentation more readable and more easy to digest.

    1. Split up the "Classes" table by "parent" and "child" classes

    The class name table in the Grid'sREADME.md was a lot for a new user to take in. One user wanted to know, at a glance, which classes were suited for parent elements and which were for children.

    2. Define common terms

    The following terms sparked some confusion, so it might help to have a section of definitions to make sure everyone is one the same page:

    • Breakpoint -- One first-time user didn't realize that this was the same thing as the values in an @media query, so they kept thinking it was a new concept/vocab unique to Gridish that they needed to understand.

    • Artboards -- One first-time user was a developer who didn't seem familiar with Sketch or terminology used by designers.

    Note: while these are the only 2 terms that came up, we can be on the lookout for other terms that are worth defining explicitly.

  • 7

    feat(utilities): Add scss utility functions to find fixed and fluid sizes.

    Summary

    Resolves #21 This PR adds utility functions to helps consuming developers calculate and use fixed and fluid sizes within their scss. Notably, the fluid sizing is based on the breakpoint values that the consuming developer set in their css-gridish.json.

    An example use case would be a consuming developer using getFluidSize() to set a component's width to be a fluid size, relative to their grid configuration (see example below in the "Test" section).

    Proposed Changes

    • Adds bin/src/scss/_utilities.scss, which contains the following utility functions:
      • map-deep-get - for traversing deeply nested maps like the generated $grid-values map
      • getBreakpointValue - returns a breakpoint value in rems when passed a breakpoint name (example use: @media queries)
      • getFluidSize - returns a calc() expression that represents a fluid length (example use: min-width rule)
      • getFixedSize - returns a length in rems when passed a fixed nondimensional unit
    • Updates Examples (scss & Sketch files) after running npm run build-examples

    Testing with the Examples

    I suggest testing with the examples individually. If you try to test them all at once by adding some sample rules that use getFluidSize() or getBreakpointValue(), you will run into trouble because the Material example is using different breakpoint names ("small" instead of "sm") & the map-get() or map-deep-get() in each of those functions won't be able to find the breakpoint names you are using. If you test them all individually, you can modify the breakpoints names in your test scss rules as appropriate.

    Bootstrap & Carbon

    1. Add the following the bottom of the new bin/src/scss/_utilities.scss:
    @media screen and (min-width: getBreakpointValue('sm')){
      .awesome-test-element {
        max-width: getFixedSize(10);
        min-width: getFluidSize('sm', 1);
      }
    }
    
    1. cd examples/bootstrap

    2. node ../../bin/index.js to run just the Bootstrap example

    3. view the compiled CSS and check for .awesome-test-element

    4. repeat for Carbon

    Material

    The Material css-gridish.json is using different breakpoint names ("small" instead of "sm", for example). So the steps to test are the same as above, but modify the breakpoint names to match the full words in that example's css-gridish.json file:

    @media screen and (min-width: getBreakpointValue('small')){
      .awesome-test-element {
        max-width: getFixedSize(10);
        min-width: getFluidSize('small', 1);
      }
    }
    
  • 8

    Stretching rows for variable content

    As a developer with an unknown paragraph length, I want to not have to specify a specific row count for that paragraph’s DOM element.

    Currently, the default rows are grid-auto-rows: $rowHeight * 1rem.

    I think the behavior should be grid-auto-rows: minmax($rowHeight * 1rem, auto). However, this affects the situation when two subgrids are placed next to each other. The smaller of the two grids will stretch all of it’s children to fill the height of the larger subgrid.

  • 9

    [ImgBot] Optimize images

    Beep boop. Your images are optimized!

    Your image file size has been reduced by 57% 🎉

    Details

    | File | Before | After | Percent reduction | |:--|:--|:--|:--| | /src/sketch/files/previews/preview.png | 6.54kb | 0.34kb | 94.84% | | /graphics/gridish.png | 25.62kb | 6.18kb | 75.88% | | /extension/icons/icon128.png | 1.08kb | 0.38kb | 65.13% | | /graphics/configDiagram.png | 92.93kb | 47.02kb | 49.40% | | /extension/icons/icon64.png | 0.65kb | 0.42kb | 35.40% | | /extension/icons/icon48.png | 0.58kb | 0.40kb | 31.99% | | /extension/icons/icon32.png | 0.48kb | 0.39kb | 18.85% | | /extension/icons/icon19.png | 0.36kb | 0.36kb | 1.88% | | | | | | | Total : | 128.24kb | 55.47kb | 56.74% |


    📝docs | :octocat: repo | 🙋issues | 🏅swag | 🏪marketplace

  • 10

    feat(css): minimal css file for native css grid sizing

    • Adds a yourPrefix-minimal.css file that contains no column or height classes. This saves lots of kilobytes if the dev is only concerned with native CSS Grid rules
    • Updated documentation to close #36 and share difference in normal, legacy, and minimal css files

    Pinging @jendowns, @diego-codes, @joshblack, and @electrostaticfleece for feedback

  • 11

    docs(utilities): fix example scss in get-fluid-size documentation

    Proposed Changes

    • Remove stray line @media screen and (min-width: 20rem) { from example SCSS for get-fluid-size() function (The line is not meant to be there and doesn't reflect a correct example, in that context.)
    • Update documentation and examples to reflect change
  • 12

    A plea for simple installation instructions

    A gentle request: At the risk of revealing my ignorance, is there a step-by-step setup guide and further is there a guide for integrating this Visual Studio Code? Thank you.

  • 13

    fix(prefix): make use of -- as a prefix standard

    It adds an extra - to the prefixing of class name so it is consistent with Carbon's prefixing standards. This is so that the $prefix value is respected in the building of sass code for Carbon users.

  • 14

    Fixed column grid doesn't behave as expected

    Hi,

    I've just started using Gridish and it seems like a great tool! One thing though, when selecting --fixed-columns, I expected my Grid would stick to the specified number of columns in the config file. However, it repeat()s using the auto-fill property, which results in a behaviour which doesn't conform to Material Design's definition of a fixed grid because between breakpoints the grid keeps to the maximum width but the column count changes (Chrome 67, OSX 10.13.5).

    Not that MD is the definitive style-guide, but I think this is more or less a universal standard for an 'adaptive' or 'fixed' grid.

    If that isn't a bug, would it be possible to provide a config option in css-gridish.json to use repeat($columnCount) for each breakpoint, ensuring that the column quantity is preserved? At the moment I'm doing this to achieve the desired behaviour:

    
    @import "../grid/scss/core";
    
    /*
      Override Gridish fixed column behaviour to preserve number of columns
      at all breakpoints while centering the grid. Without this, fixed columns
      will repeat to fill the space, rather than stick to the 'columns' config
      setting in css-gridish.json
    */
    
    .bl-grid.bl-grid--fixed-columns {
      // Horizontally centre grid within container
      justify-content: center;
    
      @each $name, $size in $breakpoints {
        $break: map-get($size, 'breakpoint');
        $cols: map-get($size, 'columns');
    
        // Breakpoint for 320px devices. Between this and 360px wide, columns flex using vw units
        @if $name == 'xxsmall' {
          grid-template-columns: repeat($cols, #{100/$cols}vw);
        } @else {
          @include media-query($name) {
            grid-template-columns: repeat($cols, #{$break/$cols}rem);
          }
        }
      }
    }
    
    

    Thanks!

  • 15

    V2.1.0

    This has been released on NPM as a beta release for several months now. See the beta release for notes: https://github.com/IBM/css-gridish/releases/tag/v2.0.0-beta.1

  • 16

    No legacy class for last breakpoint

    Hi @seejamescode

    Wondering why we don't create a class for the last breakpoint?

    Thanks!

    https://github.com/IBM/css-gridish/blob/c5f16a541df485fa833f8f50299bd6a3f290a142/src/scss/_mixins.scss#L43

  • 17

    ExtraBreakpointWidth index out of bounds

    Here's the error I've been getting:

    events.js:183
    [0]       throw er; // Unhandled 'error' event
    [0]       ^
    [0] Error: src/scss/_functions.scss
    [0] Error: index out of bounds for `nth($list, $n)`
    [0]         on line 24 of src/scss/_functions.scss, in function `nth`
    [0]         from line 24 of src/scss/_functions.scss, in function `all-breakpoints`
    [0]         from line 21 of src/scss/_variables.scss
    [0]         from line 3 of src/scss/_core.scss
    [0]         from line 2 of src/scss/gridish-grid-legacy.scss
    [0] >>     $extraBreakpointWidth: nth($currentBreakpoint, 2);
    [0]
    [0]    ---------------------------^
    

    Relevant code: _variables.scss

    // Merge standard and custom breakpoints into list
    @function all-breakpoints($breakpoints, $extraBreakpoints, $first, $last) {
      $allBreakpoints: $breakpoints;
      @each $currentBreakpoint in $extraBreakpoints {
        $extraBreakpointName: nth($currentBreakpoint, 1);
        $extraBreakpointWidth: nth($currentBreakpoint, 2);
    

    _functions.scss

    $prefix: gridish !default;
    @if map-get($grid-values, "prefix") and $prefix == "gridish" {
      $prefix: map-get($grid-values, "prefix");
    }
    $extraBreakpoints: () !default;
    $breakpoints: add-padding(map-get($grid-values, "breakpoints"));
    $first: nth(nth($breakpoints, 1), 2);
    $last: nth(nth($breakpoints, -1), 2);
    $includeFlexFallback: false !default;
    $rowHeight: map-get($grid-values, "rowHeight");
    $rows: map-get($grid-values, "rows");
    $extraArtboards: map-get($grid-values, "extraArtboards");
    $allBreakpoints: all-breakpoints(
      $breakpoints,
      $extraBreakpoints,
      $first,
      $last
    );
    

    Looking through it and using some debug statements, I've found that $extraBreakpoints is empty, which isn't surprising considering the definition is $extraBreakpoints: () !default; and it isn't referenced anywhere else.

    I'm not super well versed with sass script though, so I might be missing something here.