Bourbon Neat Sass Grid Framework

4.0.0 · active · verified Sun Apr 19

Bourbon Neat is a lightweight, semantic, and fluid grid framework built with Sass. Currently at stable version 4.0.0, it aims to provide a flexible foundation for responsive layouts while being straightforward to integrate. Its release cadence involves major versions every few years, with more frequent minor and patch updates addressing fixes and enhancements. A key differentiator is its emphasis on semantic markup and a 'fluid first' approach to grid design, offering robust mixins for defining columns, gutters, and media queries without injecting excessive presentational classes into HTML. It is part of the 'Bourbon Family' of Sass tools, which implies good interoperability with other libraries like Bourbon and Bitters.

Common errors

```
Bundler could not find compatible versions for gem "sass"
```
cause The `sass` gem (Ruby Sass) in your Gemfile or system is outdated and conflicts with Neat's requirements.

fix Run `bundle update sass` to upgrade the `sass` gem to a compatible version within your Ruby on Rails project.
```
Neat to not be found when using SassC.
```
cause An issue prevented Neat from being correctly resolved or found by SassC, a LibSass wrapper.

fix This specific issue was fixed in Neat v3.0.1. Upgrade your `bourbon-neat` package to version 3.0.1 or newer. Ensure your `node-sass` `includePaths` are correctly configured if using npm.
```
Neat to not be found within Rails apps.
```
cause A bug in earlier versions of Neat prevented it from being correctly located by Rails' asset pipeline.

fix This issue was fixed in Neat v2.1.0. Upgrade your `neat` gem to version 2.1.0 or newer. Also, ensure your `application.scss` correctly uses `@import "neat";`.

Warnings

breaking Bower support has been entirely removed starting with Neat v4.0.0. Projects still relying on Bower for Neat will need to migrate to npm or RubyGems for package management.
Fix: Migrate your project to use `npm install --save bourbon-neat` or `gem install neat` for installation, updating your build process accordingly.
breaking The Ruby Sass gem (deprecated) is no longer a runtime dependency as of v4.0.0. While this removes a legacy dependency, ensure your Sass compilation environment is updated to use Dart Sass or LibSass-based compilers like `node-sass`.
Fix: Verify your project uses a modern Sass compiler (e.g., Dart Sass, `node-sass`) and update your build scripts if they implicitly relied on the Ruby Sass gem's presence.
breaking Version 2.0.0 introduced significant changes, including the addition of `grid-shift` and `grid-media` functionality, while `grid-collapse` removed its `float` property. These changes might break layouts relying on previous behaviors or expecting the `float` property within `grid-collapse`.
Fix: Review your Sass files for `grid-collapse` usage and adjust layouts that might be affected by the `float` property removal. Explore `grid-shift` for offsetting columns and `grid-media` for managing responsive grids.
deprecated The use of `&&` for boolean 'and' in Sass was deprecated in older versions. Neat fixed this in v1.9.1, but if using an older version or custom mixins, be aware of this Sass warning.
Fix: Update Neat to v1.9.1 or newer. For custom Sass, replace `&&` with the `and` keyword in boolean expressions.
gotcha When using Neat in Ruby on Rails, `@import` rules in `application.scss` are not compatible with Sprockets directives (e.g., `//= require`). You must choose one or the other for your asset management.
Fix: Standardize on `@import` rules for all Sass dependencies, including Neat, and avoid using Sprockets directives in your `.scss` files if you wish to use Sass's `@import` functionality effectively.

Install

npm install bourbon-neat npm
yarn add bourbon-neat yarn
pnpm add bourbon-neat pnpm

Imports

@import 'neat';
wrong:
```
@import 'bourbon-neat';
```
correct:
```
@import 'neat';
```
For npm installations (with `node-sass` and correct `includePaths`) or Rails, 'neat' is the correct path. It resolves directly via `require("bourbon-neat").includePaths`.
@import 'neat/neat';
wrong:
```
@import 'neat';
```
correct:
```
@import 'neat/neat';
```
When installed via RubyGems using `gem install neat` and then `neat install`, the files are typically placed in a 'neat' subdirectory, requiring the full path.
$grid-columns
wrong:
```
$neat-grid-columns: 12;
```
correct:
```
$grid-columns: 12;
```
Configuration variables are typically prefixed with `$grid-` or `$neat-` for global settings like `$grid-columns` or `$neat-gutter`.

Quickstart

This quickstart demonstrates how to set up a basic responsive grid. It shows `outer-container` for overall layout, `column` for defining element widths, `omega()` for clearing floats on the last column, and responsive `media` queries, including using a custom grid.

@import 'neat';

// Configure Neat variables (optional, defaults are fine)
$neat-grid-columns: 12;
$neat-gutter: 20px;

// Define a custom grid for media queries (optional)
$custom-grid: (columns: 6, gutter: 15px);

.outer-container {
  @include outer-container;
}

.main-content {
  @include column(9);

  @include media('max-width', 768px) {
    @include column(12);
  }

  @include media('max-width', 480px) using ($custom-grid) {
    @include column(6);
  }
}

.sidebar {
  @include column(3, omega()); // omega() mixin for the last column in a row

  @include media('max-width', 768px) {
    @include column(12);
  }
}

view raw JSON →