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.
- Create a file called
css-gridish.json
in your project root. See the config documentation or an example config for help. - 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:
- Run command
npm install css-gridish
. - Add
scripts: {build: "css-gridish"}
in yourpackage.json
. - Run command
npm run build
.
- Run command
- If you want to build once, run command
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 onvw
units. - Once a solution in the CSS Grid spec is given for one item to ignore
grid-gap
, we can utilizegrid-gap
by default instead of opting in to padding classes.
FAQs
grid-gap
for gutters?
Why does none of the CSS Grid code use 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.
How does css-gridish work with container having max-width?
As css-gridish using
100vw / 12 = 8.3333vw
for each column width, rather than using8.3333%
for each one, how to make it work like a grid system that has container hasmax-width
with auto margin on left and right side?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.
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.
Setting margin at smallest breakpoint applies same margin at larger breakpoints when larger breakpoints' margins are set to zero
css-gridish.json:
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.
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 thevw
unit differently. It applies to any browser that supports CSS Variables and MutationObserver.Thoughts, @joshblack?
[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's
README.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.
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
bin/src/scss/_utilities.scss
, which contains the following utility functions:map-deep-get
- for traversing deeply nested maps like the generated$grid-values
mapgetBreakpointValue
- returns a breakpoint value in rems when passed a breakpoint name (example use:@media
queries)getFluidSize
- returns acalc()
expression that represents a fluid length (example use:min-width
rule)getFixedSize
- returns a length in rems when passed a fixed nondimensional unitnpm 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()
orgetBreakpointValue()
, you will run into trouble because the Material example is using different breakpoint names ("small" instead of "sm") & themap-get()
ormap-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
bin/src/scss/_utilities.scss
:cd examples/bootstrap
node ../../bin/index.js
to run just the Bootstrap exampleview the compiled CSS and check for
.awesome-test-element
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'scss-gridish.json
file: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.[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
feat(css): minimal css file for native css grid sizing
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 rulesPinging @jendowns, @diego-codes, @joshblack, and @electrostaticfleece for feedback
docs(utilities): fix example scss in get-fluid-size documentation
Proposed Changes
@media screen and (min-width: 20rem) {
from example SCSS forget-fluid-size()
function (The line is not meant to be there and doesn't reflect a correct example, in that context.)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.
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.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, itrepeat()
s using theauto-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 userepeat($columnCount)
for each breakpoint, ensuring that the column quantity is preserved? At the moment I'm doing this to achieve the desired behaviour:Thanks!
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
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
ExtraBreakpointWidth index out of bounds
Here's the error I've been getting:
Relevant code: _variables.scss
_functions.scss
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.