@taraskucherenko/scss-kit

🇺🇦 Українська | 🇬🇧 English

Українська

Про проєкт

scss-kit — персональний SCSS-фреймворк для швидкого старту нових проєктів. Містить:

• CSS reset
• SCSS-змінні (кольори, шрифти, розміри сітки) — усі !default, перевизначаються
• Функції (oklch, oklab, px-to-rem, img-url, …)
• Міксини (медіа-квері, стани, псевдо, fonts, тема, сітка, типографіка, …)
• Атоми — статичні утиліти-класи + %placeholder-селектори

Встановлення

yarn add @taraskucherenko/scss-kit
# або
npm install @taraskucherenko/scss-kit

Вимоги: Sass >= 1.97.2 (peerDependency)

Підключення

Рекомендований сучасний підхід — через pkg: URL. Один і той самий рядок працює з будь-якої глибини файлу:

@use 'pkg:@taraskucherenko/scss-kit' as *;

Щоб це запрацювало, у твоєму збірнику треба ввімкнути Node Package Importer.

Налаштування під різні збірники

Sass CLI:

sass --pkg-importer=node main.scss main.css

Vite:

// vite.config.js
import { defineConfig } from 'vite';
import { NodePackageImporter } from 'sass';

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        importers: [new NodePackageImporter()]
      }
    }
  }
});

Gulp + gulp-sass:

// gulpfile.js
const gulp = require('gulp');
const sass = require('sass');
const { NodePackageImporter } = sass;
const gulpSass = require('gulp-sass')(sass);

gulp.task('styles', () =>
  gulp.src('src/**/*.scss')
    .pipe(gulpSass({ importers: [new NodePackageImporter()] }).on('error', gulpSass.logError))
    .pipe(gulp.dest('dist/css'))
);

Webpack + sass-loader (≥ 13.3):

// webpack.config.js
const { NodePackageImporter } = require('sass');

module.exports = {
  module: {
    rules: [
      {
        test: /\.scss$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              sassOptions: {
                importers: [new NodePackageImporter()]
              }
            }
          }
        ]
      }
    ]
  }
};

Fallback (без pkg: importer)

Якщо ввімкнути pkg: importer неможливо (старіший Sass або обмеження тулінгу) — можна імпортувати через відносний шлях. Кількість ../ залежить від глибини файлу:

@use '../../../node_modules/@taraskucherenko/scss-kit/src/main' as *;

Перевизначення дефолтних змінних

Усі публічні змінні позначені !default. Перевизначай їх через with (...) при імпорті:

@use 'pkg:@taraskucherenko/scss-kit' as * with (
  // обов'язково для img-url() — без цього функція кине @error
  $img-path: '/assets/img',

  // обов'язково для @include font() — без цього міксин кине @error
  $font-path: '/assets/fonts',

  // сітка
  $page-width-max: 1280,
  $page-width-min: 320,
  $col-gutter:     24,
  $cols:           8,

  // кольори
  $col-black: #111111,
  $col-white: #FAFAFA,

  // шрифти (списки — щоб мати fallback)
  $font-family-default: ('Inter', system-ui, sans-serif),
  $font-plain:          ('Inter',           system-ui, sans-serif),
  $font-titles:         ('Playfair Display', Georgia,  serif),

  // тривалість анімації для атома .anim
  $anim-duration: 0.3s,

  // z-index шкала (доступно: $z-ind-background, $z-ind-backward, $z-ind-0..3,
  //                          $z-ind-select, $z-ind-tooltip, $z-ind-high,
  //                          $z-ind-overlay, $z-ind-modal)
  $z-ind-modal: 9999
);

Що далі

• Згенерувати кольорову палітру: :root { @include generate-colors($yourMap); }
• Підключити кастомні шрифти: @include font('Inter-Regular', 400, 'Inter') (шлях береться з $font-path); для italic — @include font('Inter-Italic', 400, 'Inter', $style: italic)
• Використовувати атоми (.bg-white, .round-8, .gap-1) або плейсхолдери (@extend %fg-current)
• Ставити медіа-квері: @include media-t-768 { ... }

English

About

scss-kit is a personal SCSS framework that bootstraps new projects with:

• CSS reset
• SCSS variables (colors, fonts, grid sizes) — all !default, overridable
• Functions (oklch, oklab, px-to-rem, img-url, …)
• Mixins (media queries, states, pseudo, fonts, theme, grid, typography, …)
• Atoms — static utility classes + %placeholder selectors

Installation

yarn add @taraskucherenko/scss-kit
# or
npm install @taraskucherenko/scss-kit

Requires: Sass >= 1.97.2 (peerDependency)

Usage

The recommended modern approach is via pkg: URL. The same line works from any file depth:

@use 'pkg:@taraskucherenko/scss-kit' as *;

For this to work, your build tool needs the Node Package Importer enabled.

Build tool configuration

Sass CLI:

sass --pkg-importer=node main.scss main.css

Vite:

// vite.config.js
import { defineConfig } from 'vite';
import { NodePackageImporter } from 'sass';

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        importers: [new NodePackageImporter()]
      }
    }
  }
});

Gulp + gulp-sass:

// gulpfile.js
const gulp = require('gulp');
const sass = require('sass');
const { NodePackageImporter } = sass;
const gulpSass = require('gulp-sass')(sass);

gulp.task('styles', () =>
  gulp.src('src/**/*.scss')
    .pipe(gulpSass({ importers: [new NodePackageImporter()] }).on('error', gulpSass.logError))
    .pipe(gulp.dest('dist/css'))
);

Webpack + sass-loader (≥ 13.3):

// webpack.config.js
const { NodePackageImporter } = require('sass');

module.exports = {
  module: {
    rules: [
      {
        test: /\.scss$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              sassOptions: {
                importers: [new NodePackageImporter()]
              }
            }
          }
        ]
      }
    ]
  }
};

Fallback (without pkg: importer)

If you cannot enable the pkg: importer (older Sass or tooling limitations), you can import via a relative path. The number of ../ depends on file depth:

@use '../../../node_modules/@taraskucherenko/scss-kit/src/main' as *;

Overriding defaults

All public variables are marked !default. Override them via with (...) at import time:

@use 'pkg:@taraskucherenko/scss-kit' as * with (
  // required for img-url() — otherwise it throws @error
  $img-path: '/assets/img',

  // required for @include font() — otherwise it throws @error
  $font-path: '/assets/fonts',

  // grid
  $page-width-max: 1280,
  $page-width-min: 320,
  $col-gutter:     24,
  $cols:           8,

  // colors
  $col-black: #111111,
  $col-white: #FAFAFA,

  // fonts (lists — keep fallbacks)
  $font-family-default: ('Inter', system-ui, sans-serif),
  $font-plain:          ('Inter',           system-ui, sans-serif),
  $font-titles:         ('Playfair Display', Georgia,  serif),

  // animation duration for the .anim atom
  $anim-duration: 0.3s,

  // z-index scale (any of: $z-ind-background, $z-ind-backward, $z-ind-0..3,
  //                        $z-ind-select, $z-ind-tooltip, $z-ind-high,
  //                        $z-ind-overlay, $z-ind-modal)
  $z-ind-modal: 9999
);

What's next

• Generate a color palette: :root { @include generate-colors($yourMap); }
• Register custom fonts: @include font('Inter-Regular', 400, 'Inter') (path comes from $font-path); for italic — @include font('Inter-Italic', 400, 'Inter', $style: italic)
• Use atoms (.bg-white, .round-8, .gap-1) or placeholders (@extend %fg-current)
• Apply media queries: @include media-t-768 { ... }

Author

Taras Kucherenko GitLab: gitlab.com/teekeydev/scss-kit

License

MIT