@winstonblewup/sass-utils

@winstonblewup/sass-utils is a mini SCSS utility framework inspired by Tailwind. It enables you to easily generate classes for grid, spacing, sizing, colors, border-radius, animations and more. The framework relies on Sass and offers a modular, responsive-first approach to building interfaces.

Table of Contents

• Installation
• Usage
• Project Structure
• Documentation
  • Grid System
  • Spacing, Margins and Paddings
  • Widths and Heights
  • Colors and Border Radius
• License

Installation

1. Install Sass

   The framework depends on Sass. In your project, install it with:

   npm install --save-dev sass

2. Install the framework

   npm install @winstonblewup/sass-utils

3. Add the setup script manually

   In your project’s package.json, add the following script:

   "scripts": {
     "setup": "node node_modules/@winstonblewup/sass-utils/setup-project.cjs"
   }

4. Run the setup

   Then initialize the project using:

   npm run setup

   This will:

   • Copy generate-safelist.cjs and postcss.config.cjs to your project root
   • Inject the script build:css into your package.json if not already present

5. Compile the CSS

   npm run build:css

Usage

In your src/styles/main.scss file, import the framework:

@use "@winstonblewup/sass-utils" as *;

After editing your styles or HTML structure, run:

npm run build:css

Then include the compiled file (typically dist/assets/index.min.css) in your HTML pages.

Project Structure

The framework is structured as follows:

sass-utils/
├── _index.scss
├── scss/
│   ├── abstracts/
│   │   ├── _functions.scss
│   │   ├── _mixins.scss
│   │   └── _variables.scss
│   ├── base/
│   │   └── _reset.scss
│   └── utilities/
│       ├── _colors.scss
│       ├── _flex.scss
│       ├── _grid.scss
│       ├── _radius.scss
│       ├── _sizing.scss
│       └── _spacing.scss
├── generate-safelist.cjs
├── postcss.config.cjs
├── setup-project.cjs
└── package.json

Documentation

1. Grid System

• .col-1 to .col-12 define widths as fractions (e.g., .col-6 = 50%)

• Responsive variants like .col-sm-6, .col-md-4, etc., are auto-generated

• Breakpoints:

  $breakpoints: (
    "xs": 360px,
    "sm": 480px,
    "md": 768px,
    "lg": 1024px,
    "xl": 1280px,
    "2xl": 1536px
  );

2. Spacing, Margins and Paddings

• Classes like .mt-16, .p-20, .mx-8, etc.
• Pixel values converted to rem() automatically

3. Widths and Heights

• .w-100, .h-50, etc. define width/height in percentage
• Responsive versions also available

4. Colors and Border Radius

• Colors defined via a SCSS map
• Utilities generated: .bg-*, .text-*, .border-*
• Border radius: .radius-4, .radius-8, .sm-radius-12, etc.

License

This project is licensed under the ISC License.