ibm / css-gridish

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

CSS Gridish

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

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.

css-gridish's Issues

Rem unit is not defined in resulting CSS

Font size for root element (<html>) is not defined, it's mistakenly defined for <body>.

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.

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.

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.

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.

Activate `--fluid-rows` at a breakpoint

.yourPrefix--fluid-rows has been really helpful on tablet and desktop. However, on mobile I tend to want content to not have white space below it from the fluid rows because it usually is a one-column layout.

It would be great if there were also fluid row classes for starting fluid rows at a specific breakpoint. (.yourPrefix--fluid-rows--yourBreakpoint)

No legacy class for last breakpoint

Hi @seejamescode

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

Thanks!

css-gridish/src/scss/_mixins.scss

Line 43 in c5f16a5

// Do not make class if last media query

[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.

On Google Chrome uses shortcuts which does not show up in chrome://extensions/shortcuts

Looking at page chrome://extensions/shortcuts in chrome, does not show that this extensions using shorcuts like RAlt + L.

Add CLI support to specify output options

Hi there! 👋

This is just a suggestion for an enhancement 😄 Would be nice to update this to a CLI that supports flags like:

# Displays capabilities
npx css-gridish --help 

# Creates necessary files in the current directory for
# css-gridish to work, then runs css-gridish
npx css-gridish create <path-to-dir>

# Updates files with newest css-gridish version
npx css-gridish update <path-to-config>

# Updates files in config path directory
npx css-gridish sync <path-to-config> [...options]

Options for sync could be ones that help determine what files need to be output, the biggest ones would be:

• Whether to output a Sketch file or not
• Whether to output a README file or not

Let me know if you'd be open to these kinds of changes or not! Can try and see what kind of effort would be involved if so 😄

Margin bottom on last-child

Hi there,

This selector seems to be causing some strange behaviour for elements on my site - it looks like it has a high specificity level that's overriding margins on my own components.

Wondering if you have any ideas or suggestions for this?

Cheers!

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?

Publish the chrome extension to npm?

Hey guys it would be nice if could also publish the chrome extension as a npm package.. (of course would require some tweaking) to make it work as a package that can be imported "installed" via the main bundler..

i currently face a situation where i have two projects with slight different grids.. and i have to swap configs constantly... it would be a much nicer workflow if i could have like a devOnly.js file that imports this extension.. and initialize it with the current projects config...

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!

Use `display: unset` instead of `display: block` for dealing with the `--0` utility selectors.

There is a set of utility classnames that you can add to an element that just tells the element how many columns to span at a given breakpoint so you don't have to declare explicit grid positioning for the element (e.g. ibm-grid__col--lg--2).

This includes the ability to hide a column with --0 which uses display: block. To override this at higher breakpoints, the selectors use display: block but display: unset should achieve the same thing without offering an opinion about just which type of display the element should be add.

Use `grid-column-end` instead of `grid-column` for the `grid__col` selectors.

There is a set of utility classnames that you can add to an element that just tells the element how many columns to span at a given breakpoint so you don't have to declare explicit grid positioning for the element (e.g. ibm-grid__col--lg--2).

The selectors for these use grid-column (e.g. grid-column: span 2;) which really means grid-column-start. It's more likely that someone using these classes to expect the spanning to begin at a starting column and span forward the given number of columns. Doing that would mean using grid-column-end instead of grid-column-start (or grid-column).

I suspect this is only an issue if anyone wants to set both grid-column-start and grid-column-end at the same time (perhaps even if not all the cells in a row do).

Uses RAlt + L on Windows instead of LAlt + L only

With such settings, I cannot enter polish characters like ł.

Look how uBlock origin does it: LAlt + Z to select element. RAlt + Z does not trigger anything.

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.

Offset classes

Do you plan on including offset classes, similar to Bootstrap, or Foundation?

This could be achieved by modifying .col--[x] helper classes to use:

grid-column-end: span 6;

And then using grid-column-start to specify an offset.

What do you reckon? Happy to help out with this!

css-gridish requires xcodebuild on macOS

When I ran npx css-gridish I got this error:

xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance

macOS 10.13.2
node v 8.9.2

Fallback properties being generated on .gridName-grid class for non-legacy grid

When generating a grid, a display: flex property and an align-items: flex-start property are being generated on the .gridName-grid class on the non-legacy grid.

.gridName-grid {
  align-items: flex-start;
  box-sizing: border-box;
  display: flex;
  display: grid;
  flex-wrap: wrap;
  position: relative;
}

Transform column and unit finding into functions

@jendowns, are you down to move those functions you worked on internally into Gridish?

sketch file will not open when gutter and margin are set as vw units