Seed Spacing Utilities

0.4.3 · maintenance · verified Sun Apr 19

Seed Spacing is a Sass (SCSS) utility pack that provides a comprehensive set of classes and a helper function for managing consistent margins and padding within projects built with the Seed CSS framework. It offers granular control over spacing values, directions, and responsive breakpoints. Currently at version 0.4.3, its release cadence is tied to updates in its core dependencies, particularly `seed-breakpoints`, making releases somewhat infrequent but purposeful. A key differentiator is its modular design, allowing developers to configure namespaces and define their own spacing scales via Sass variables, reducing unnecessary CSS output. It emphasizes functional CSS principles and integrates seamlessly into Sass build pipelines, generating utility classes and a `spacing($size)` function for use in custom SCSS. This approach ensures design consistency and optimizes stylesheet size.

Common errors

```
Error: File to import not found or unreadable: seed-spacing/__all
```
cause Attempting to import the `seed-spacing` pack using the deprecated `__all.scss` filename and path after upgrading to v0.1.0 or later.

fix Update your SCSS `@import` statement to `@import "pack/seed-spacing/_index";`.
```
CSS class `u-mrg--at-lg-5` does not apply expected styles, or `u-pad--at-sm-2` is not recognized.
```
cause Using the old `--at-size` breakpoint class naming convention (e.g., `--at-md`) after upgrading to v0.2.0 or later, where the convention changed to `@size` (e.g., `@md`).

fix Locate and update all instances of responsive utility class names in your HTML and SCSS to use the new `@size` format (e.g., `u-mrg@lg-5`, `u-pad@sm-2`).
```
Undefined variable or function named 'spacing'.
```
cause The `seed-spacing` SCSS pack is not correctly imported into your main stylesheet, or the `spacing()` function is called with a key not defined in the `$seed-spacing-sizes` Sass map.

fix Ensure `seed-spacing` is correctly imported via `@import "pack/seed-spacing/_index";` in your SCSS. Also, verify that the argument passed to `spacing()` (e.g., `spacing(3)`) corresponds to a valid key in your `$seed-spacing-sizes` map.

Warnings

breaking The `xl` responsive size was entirely removed, and the default `1-5em` sizes were eliminated from the configuration map. Projects relying on these specific defaults or the `xl` breakpoint will need to adjust their SCSS configurations and class usage accordingly.
Fix: Review your `$seed-spacing-sizes` and `seed-breakpoints` configurations. If you require `xl` or default `1-5em` sizes, you must explicitly define them in your project's Sass configuration.
breaking The naming convention for breakpoint/responsive classes changed significantly. Previously, suffixes like `--at-size` (e.g., `u-mrg--at-md-3`) were used; these have been updated to use an `@size` suffix (e.g., `u-mrg@md-3`). This change was inherited from `seed-breakpoints` v0.3.0.
Fix: Update all instances of responsive utility classes in your HTML and SCSS from the `prefix--at-size` format to the new `prefix@size` convention (e.g., `u-mrg--at-md-3` becomes `u-mrg@md-3`).
breaking The primary SCSS entry file was renamed from `__all.scss` to `__index.scss`, and the recommended `@import` path changed to include a `pack/` namespace. Using old import paths will result in compilation errors.
Fix: Update your SCSS `@import` statements from `@import "seed-spacing/__all";` to the new standard: `@import "pack/seed-spacing/_index";`.
gotcha Version 0.3.1 introduced `!important` to auto classes for margin (e.g., `u-mrg--h-auto`). While intended to enable responsive auto classes to work with non-auto classes, this can increase CSS specificity, potentially overriding other styles unexpectedly.
Fix: Be mindful of increased specificity when using `auto` margin classes. If specificity conflicts arise, consider refining your selectors, adjusting the order of your CSS imports, or providing more specific overrides where necessary.

Install

npm install seed-spacing npm
yarn add seed-spacing yarn
pnpm add seed-spacing pnpm

Imports

seed-spacing SCSS import
wrong:
```
@import "seed-spacing/__all";
```
correct:
```
@import "pack/seed-spacing/_index";
```
This is the primary way to include `seed-spacing` in your Sass project. The import path changed in v0.1.0, introducing the `pack/` namespace and renaming the main file from `__all` to `_index`.
Gulp includePaths
wrong:
```
import seedSpacingPack from 'seed-spacing';
```
correct:
```
const seedSpacingPack = require('seed-spacing'); // in Node.js/Gulpfile
// ... .pipe(sass({ includePaths: seedSpacingPack }))
```
When integrating with Node.js build tools like Gulp (specifically `gulp-sass`), `require()` is used to obtain the package's include path. This package does not export a JavaScript API for direct consumption outside of its build-tooling context.
spacing() function
wrong:
```
body { margin: $seed-spacing-sizes-3; }
```
correct:
```
body { margin: spacing(3); }
```
The `spacing()` Sass function should be used to apply predefined spacing values from the `$seed-spacing-sizes` map within your custom SCSS, ensuring consistency and adherence to the defined scale. Directly accessing internal Sass map values or generating ad-hoc values is discouraged.

Quickstart

Demonstrates how to integrate `seed-spacing` into a Gulp build pipeline using `gulp-sass`, showing both JavaScript configuration and illustrative SCSS usage of utility classes, the `spacing()` function, and responsive modifiers.

const gulp = require('gulp');
const sass = require('gulp-sass')(require('sass')); // Using dart-sass for modern Node.js
const seedSpacingPack = require('seed-spacing');

gulp.task('compile-sass', function () {
  return gulp.src('./sass/**/*.scss')
    .pipe(sass({
      includePaths: seedSpacingPack // Provides the path to seed-spacing's SCSS files
    }))
    .pipe(gulp.dest('./css'));
});

// --- In your main.scss file (e.g., './sass/main.scss'): ---
// Packs
@import "pack/seed-spacing/_index";

// Example usage of generated utility classes:
.my-component {
  @extend .u-mrg--a-3; // Applies margin-all: 12px; (based on default config)
  padding-bottom: spacing(5); // Applies padding-bottom: 20px; (using the Sass function)
}

.responsive-element {
  @extend .u-pad--v-2; // Vertical padding 8px
  @extend .u-pad--v@md-4; // Vertical padding 16px at medium breakpoint
  margin-left: spacing(auto); // Horizontal auto margin for centering
}

// Customizing variables (optional, typically in a config file before import):
$seed-spacing-sizes: (
  sm: 4px,
  md: 8px,
  lg: 16px
) !default;

view raw JSON →