DEV Community

Cover image for scss-helper v5: A Modern SCSS Utility Toolkit for Tailwind's Gaps
Pooya Golchian
Pooya Golchian

Posted on • Originally published at pooya.blog

scss-helper v5: A Modern SCSS Utility Toolkit for Tailwind's Gaps

#scss #css #opensource #tailwindcss

Tailwind CSS handles most styling needs well, but it doesn't cover everything. Fluid typography, CSS container queries, golden ratio layouts, and full 12-column grid control fall outside its scope. I built scss-helper to fill exactly those gaps, a modular toolkit that complements Tailwind without competing with it.

Full Documentation

What's Included

  • 30+ CSS custom property tokens: colors, spacing, typography
  • 12-column CSS grid with responsive breakpoints and auto-fit layouts
  • Fluid clamp() typography: continuous scaling, no breakpoints needed
  • Dark mode: dual strategy: data-theme attribute + prefers-color-scheme
  • CSS container queries for component-level responsiveness
  • Golden ratio typography, spacing, and grid layouts (φ = 1.618)
  • 12 animations + 5 transition presets, all prefers-reduced-motion aware
  • Tailwind CSS v3/v4 plugin to use tokens alongside Tailwind

All classes use the sh- prefix (configurable). Full bundle is 5.1 KB gzipped.

Installation 

pnpm add scss-helper
pnpm add -D sass  # Dart Sass >= 1.60 required
Enter fullscreen mode Exit fullscreen mode

Quick Start

SCSS (recommended) 

@use 'scss-helper';

// Or cherry-pick modules
@use 'scss-helper/src/tokens/index';
@use 'scss-helper/src/typography/fluid';
@use 'scss-helper/src/golden/golden-ratio';
Enter fullscreen mode Exit fullscreen mode

Pre-compiled CSS 

@import 'scss-helper/css';          /* Full bundle, 5.1 KB gzipped */
@import 'scss-helper/css/grid';     /* Grid only, 1.7 KB gzipped */
@import 'scss-helper/css/tokens';   /* Tokens only, 583 B gzipped */
Enter fullscreen mode Exit fullscreen mode

CDN 

<link rel="stylesheet" href="https://unpkg.com/scss-helper@5/dist/style.css">
Enter fullscreen mode Exit fullscreen mode

Design Tokens 

:root {
  --color-primary: #0d6efd;
  --spacing-1: 0.25rem;
  --spacing-4: 1rem;
  --font-size-base: 1rem;
  --line-height-base: 1.5;
}
Enter fullscreen mode Exit fullscreen mode

30+ CSS custom properties generated from Sass variables. Compatible with Tailwind v4 @theme.

CSS Grid System 

<!-- Basic 12-column grid -->
<div class="sh-grid sh-gap-4">
  <div class="sh-col-8">Main</div>
  <div class="sh-col-4">Sidebar</div>
</div>

<!-- Responsive, stacks on mobile, splits on desktop -->
<div class="sh-grid sh-gap-4">
  <div class="sh-col-12 sh-col-6-md sh-col-4-lg">Card</div>
  <div class="sh-col-12 sh-col-6-md sh-col-4-lg">Card</div>
  <div class="sh-col-12 sh-col-12-md sh-col-4-lg">Card</div>
</div>

<!-- Auto-fit: fills available space -->
<div class="sh-grid-auto-md sh-gap-4">
  <div>Card</div>
  <div>Card</div>
  <div>Card</div>
</div>
Enter fullscreen mode Exit fullscreen mode

Breakpoint suffixes: -xs (32rem) · -sm (48rem) · -md (64rem) · -lg (80rem) · -xl (90rem)

Fluid Typography

Continuous font scaling using CSS clamp(), no media queries:

<h1 class="sh-text-fluid-4xl">Headline</h1>
<p class="sh-text-fluid-base">Body text</p>
Enter fullscreen mode Exit fullscreen mode
Class Scale
sh-text-fluid-xs 12px → 14px
sh-text-fluid-sm 14px → 16px
sh-text-fluid-base 16px → 18px
sh-text-fluid-lg 18px → 22px
sh-text-fluid-xl 20px → 28px
sh-text-fluid-2xl 24px → 36px
sh-text-fluid-3xl 30px → 48px
sh-text-fluid-4xl 36px → 64px

Or call the SCSS function for arbitrary ranges:

@use 'scss-helper/src/typography/fluid' as fluid;

h1 { font-size: fluid.fluid-type(1.5rem, 3rem); }
h2 { font-size: fluid.fluid-type(1rem, 2rem, 30rem, 90rem); }
Enter fullscreen mode Exit fullscreen mode

Golden Ratio Layouts

A full design system derived from phi (1.618):

<h1 class="gs-text-3">Display, 4.236rem</h1>
<h2 class="gs-text-2">Section, 2.618rem</h2>
<p  class="gs-text-0">Body, 1rem</p>

<!-- 61.8% / 38.2% layout -->
<div class="gs-grid-golden">
  <main>Content</main>
  <aside>Sidebar</aside>
</div>
Enter fullscreen mode Exit fullscreen mode 
@use 'scss-helper/src/golden/golden-ratio' as golden;

h1 {
  font-size: golden.golden-step(2);      // 2.618rem
  margin-bottom: golden.golden-step(1);  // 1.618rem
}
Enter fullscreen mode Exit fullscreen mode

Dark Mode

Dual strategy, works with JS toggles and prefers-color-scheme simultaneously:

<p class="sh-dark-text-white">White in dark mode</p>
Enter fullscreen mode Exit fullscreen mode 
@use 'scss-helper/src/dark/dark-mode' as dark;

.card {
  background: white;
  @include dark.dark-mode {
    background: #1a1a1a;
    color: white;
  }
}
Enter fullscreen mode Exit fullscreen mode 
document.documentElement.dataset.theme =
  document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark';
Enter fullscreen mode Exit fullscreen mode

Container Queries 

<div class="sh-cq">
  <div class="sh-c-col-12 sh-c-col-6-sm sh-c-col-4-md">
    Responds to container width, not viewport
  </div>
</div>
Enter fullscreen mode Exit fullscreen mode

Animations 

<div class="sh-animate-fade-in">Fades in</div>
<div class="sh-animate-slide-up sh-delay-200">Slides up after 200ms</div>
<button class="sh-transition-colors sh-duration-fast">Smooth color</button>
Enter fullscreen mode Exit fullscreen mode

All 12 animation classes respect prefers-reduced-motion.

Tailwind CSS Plugin 

const scssHelper = require('scss-helper/plugin');
module.exports = { plugins: [scssHelper({ injectTokens: true })] };
Enter fullscreen mode Exit fullscreen mode

Customization 

@use 'scss-helper' with ($prefix: 'my-');
// -> .my-grid, .my-col-6, .my-animate-spin

@use 'scss-helper/src/variables' with (
  $primary: #8b5cf6,
  $grid-columns: 16,
);
@use 'scss-helper';
Enter fullscreen mode Exit fullscreen mode

v5 Migration from v4

v4 v5
.grid .sh-grid
.col-6 .sh-col-6
.text-fluid-lg .sh-text-fluid-lg
.animate-spin .sh-animate-spin
.transition-colors .sh-transition-colors
@import "scss-helper" @use "scss-helper"
-large suffix -lg suffix

GitHub · npm · Full Documentation

Top comments (0)