A modern SCSS/CSS utility toolkit — fills the gaps in Tailwind CSS v3/v4 and pure-SCSS projects with design tokens, fluid typography, container queries, dark mode, golden ratio layouts, animations, and a 12-column CSS grid.

📖 Full Documentation & Interactive Demos →

• Design Tokens — 30+ CSS custom properties for colors, spacing & typography
• 12-Column CSS Grid — responsive breakpoints, gap utilities, auto-fit layouts
• Fluid Typography — smooth clamp()-based scaling, no breakpoints needed
• Dark Mode — dual strategy: data-theme attribute + prefers-color-scheme
• Container Queries — component-level responsive design
• Golden Ratio — φ-based typography, spacing, and grid layouts
• Animations & Transitions — 12 animations + 5 transition presets, all prefers-reduced-motion aware
• Tailwind CSS Plugin — use tokens and utilities alongside Tailwind v3
• Modern Sass — 100% @use/@forward, zero deprecation warnings
• Namespaced — sh- prefix on all classes, configurable via $prefix
• Tiny — 5.1 KB gzipped (full bundle), 1.7 KB grid-only, 583 B tokens-only

Removed modules: flexbox grid (.sg-row/.sg-col-*), px-based margin/padding helpers, font-size helpers (.fs-*), modifier classes (.text-*, .bg-*), clearfix, border-radius/box-shadow wrapper mixins.

1. Update imports: replace @import with @use "scss-helper"
2. Find & replace class names: add sh- prefix (e.g. .grid → .sh-grid)
3. Update breakpoint suffixes: -large → -lg, -medium → -md, etc.
4. Update keyframe references: spin → sh-spin, bounce → sh-bounce
5. Remove references to deleted modules (see table above)
6. Test dark mode — class format changed from .dark\:* to .sh-dark-*

• Installation
• Quick Start
• Design Tokens
• CSS Grid System
• Golden Ratio Layouts
• Fluid Typography
• Dark Mode
• Container Queries
• Animations & Transitions
• Mixins
• Tailwind CSS Plugin
• Build Outputs
• Customization
• Browser Support
• Contributing
• License

npm install scss-helper
# or
pnpm add scss-helper
# or
yarn add scss-helper

Peer dependency: Dart Sass ≥ 1.60

npm install -D sass

// Import everything
@use "scss-helper";

// Or cherry-pick individual modules
@use "scss-helper/src/tokens/index";
@use "scss-helper/src/typography/fluid";
@use "scss-helper/src/golden/golden-ratio";

/* Full bundle */
@import "scss-helper/css";

/* Grid only */
@import "scss-helper/css/grid";

/* Tokens only (CSS custom properties) */
@import "scss-helper/css/tokens";

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

CSS custom properties generated from Sass variables. Drop into any project — Tailwind v4 @theme, vanilla CSS, or SCSS.

:root {
  /* Colors */
  --color-primary: #0d6efd;
  --color-secondary: #6c757d;
  --color-success: #28a745;
  /* ... 30+ color tokens */

  /* Spacing (0.25rem steps) */
  --spacing-1: 0.25rem;
  --spacing-2: 0.5rem;
  --spacing-4: 1rem;
  /* ... 30 steps */

  /* Typography */
  --font-size-base: 1rem;
  --font-weight-bold: 700;
  --line-height-base: 1.5;
}

Standalone build: @import "scss-helper/css/tokens" — just the :root custom properties, nothing else.

A 12-column CSS Grid with responsive breakpoints and gap utilities.

<div class="sh-grid sh-gap-4">
  <div class="sh-col-8">Main content</div>
  <div class="sh-col-4">Sidebar</div>
</div>

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

<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>

<!-- Cards that auto-fit to fill available space -->
<div class="sh-grid-auto-md sh-gap-4">
  <div>Card</div>
  <div>Card</div>
  <div>Card</div>
</div>

Auto-fit sizes: sh-grid-auto-xs (8rem), sh-grid-auto-sm (10rem), sh-grid-auto-md (15rem), sh-grid-auto-lg (20rem), sh-grid-auto-xl (25rem).

<div class="sh-grid sh-gap-4">...</div>     <!-- 1rem gap -->
<div class="sh-grid sh-gap-x-2 sh-gap-y-4">...</div> <!-- different axes -->

Scale: sh-gap-0 through sh-gap-16 (0 to 4rem).

All column utilities support responsive suffixes: sh-col-6-md, sh-col-start-1-lg, etc.

A complete design system derived from φ (1.618). Typography scales, spacing, grid layouts, and aspect ratios — all mathematically harmonious.

<h1 class="gs-text-3">Display heading</h1>   <!-- 4.236rem -->
<h2 class="gs-text-2">Section heading</h2>   <!-- 2.618rem -->
<p class="gs-text-0">Body text</p>            <!-- 1rem (base) -->
<small class="gs-text--1">Caption</small>     <!-- 0.618rem -->

<div class="gs-p-5 gs-m-4">
  <!-- padding: 1.618rem, margin: 1rem -->
</div>

<!-- 61.8% / 38.2% two-column layout -->
<div class="gs-grid-golden">
  <main>Content</main>
  <aside>Sidebar</aside>
</div>

<!-- Reversed: 38.2% / 61.8% -->
<div class="gs-grid-golden-reverse">...</div>

<!-- Three-column golden spiral -->
<div class="gs-grid-golden-3">...</div>

@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
}

.layout {
  @include golden.golden-columns;           // 61.8% / 38.2% grid
}

Smooth font scaling using CSS clamp() — no breakpoints, no JavaScript.

<h1 class="sh-text-fluid-4xl">Headline</h1>
<p class="sh-text-fluid-base">Body text</p>

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

h1 {
  font-size: fluid.fluid-type(1.5rem, 3rem);           // default viewport range
  font-size: fluid.fluid-type(1rem, 2rem, 30rem, 90rem); // custom viewport range
}

Dual-strategy dark mode — works with both JavaScript toggles and OS preferences.

Semantic color tokens automatically shift in dark mode:

/* Light mode */
--color-primary: #0d6efd;

/* Dark mode (automatic) */
--color-primary: #60a5fa;

<!-- Works under [data-theme="dark"] AND prefers-color-scheme: dark -->
<p class="sh-dark-text-white">White text in dark mode</p>
<div class="sh-dark-bg-gray-900">Dark background in dark mode</div>

@use "scss-helper/src/dark/dark-mode" as dark;

.card {
  background: white;
  @include dark.dark-mode {
    background: #1a1a1a;
    color: white;
  }
}

// Toggle dark mode
document.documentElement.dataset.theme =
  document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark';

Component-level responsive design using CSS 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>

@use "scss-helper/src/container/container-query" as cq;

.card {
  @include cq.container-bp('card', sm) {
    font-size: 1.25rem;
  }
  @include cq.container-bp(none, md) {
    // unnamed container query
    display: grid;
  }
}

Pre-built animations with prefers-reduced-motion guard. All prefixed with sh- to avoid Tailwind collisions.

<div class="sh-animate-fade-in">Fades in</div>
<div class="sh-animate-slide-up sh-delay-200">Slides up after 200ms</div>
<div class="sh-animate-spin">Loading spinner</div>

<div class="sh-animate-fade-in sh-delay-300 sh-animate-once">
  Fades in once after 300ms
</div>

Delays: sh-delay-75 through sh-delay-1000. Iteration: sh-animate-once, sh-animate-twice, sh-animate-infinite. Fill: sh-animate-fill-both, sh-animate-fill-forwards.

<button class="sh-transition-colors sh-duration-fast">
  Smooth color transition
</button>

Duration: sh-duration-fast (100ms), sh-duration-slow (400ms). Easing: sh-ease-in, sh-ease-out, sh-ease-bounce.

<div class="sh-transition" style="--duration: 500ms; --easing: ease-in-out">
  Custom timing via CSS custom properties
</div>

@use "scss-helper/src/animation/transitions" as tr;

.button {
  @include tr.transition(opacity transform, 200ms, ease-out);
}

All animations and transitions are automatically disabled for users with prefers-reduced-motion: reduce.

@use "scss-helper/src/mixin" as mx;

.card {
  @include mx.border-stroke(light);          // 1px solid black
  @include mx.border-stroke(medium, red);    // 3px solid red
  @include mx.border-stroke(heavy, #333);    // 6px solid #333
}

@use "scss-helper/src/mixin" as mx;

$sizes: (sm: 0.875rem, md: 1rem, lg: 1.25rem);

.text {
  @include mx.modifiers($sizes, "font-size");
}
// → .text-sm { font-size: 0.875rem; }
// → .text-md { font-size: 1rem; }
// → .text-lg { font-size: 1.25rem; }

@use "scss-helper/src/variables" as vars;

.sidebar {
  display: none;
  @include vars.breakpoint(md) {
    display: block;
  }
}

Use scss-helper's design tokens and utilities alongside Tailwind CSS v3.

// tailwind.config.js
const scssHelper = require('scss-helper/plugin');

module.exports = {
  plugins: [scssHelper],
  // or with options:
  plugins: [scssHelper({ injectTokens: true })],
};

1. Design tokens as :root CSS custom properties (colors, spacing, typography)
2. Dark mode token overrides under [data-theme="dark"] and prefers-color-scheme
3. Fluid typography utilities: sh-text-fluid-xs through sh-text-fluid-4xl
4. Container query utilities: sh-cq, sh-cq-size, sh-cq-normal
5. Transition utilities: sh-transition-colors, sh-transition-shadow
6. Animation utilities: sh-animate-fade-in, sh-animate-spin, etc.
7. Theme extensions: text-primary, bg-danger, text-fluid-lg, etc.

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

@use "scss-helper/src/variables" with (
  $primary: #8b5cf6,
  $font-size-base: 1.125rem,
  $grid-columns: 16,
);
@use "scss-helper";

$fluid-type-scale: (
  sm: (1rem, 1.25rem),
  lg: (1.5rem, 2.5rem),
) !default;

$dark-palette: (
  "brand": #a78bfa,
  "surface": #1e1e2e,
) !default;

# Install dependencies
pnpm install

# Build all outputs
pnpm build

# Watch mode
pnpm watch

# Build expanded (readable) CSS
pnpm build:dev

1. Fork the repo
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit changes: git commit -m 'Add my feature'
4. Push: git push origin feature/my-feature
5. Open a Pull Request

• Modern Sass @use/@forward module system (zero @import deprecation warnings)
• sh- namespaced utility classes with configurable $prefix
• Removed ~25 KB of legacy helper modules
• DRY CSS grid, prefixed keyframes, dark mode fixes
• Updated Tailwind plugin & documentation

• Design tokens, fluid typography, container queries, golden ratio layouts
• Tailwind CSS v3 plugin
• Dark mode with dual strategy

MIT © Pooya Golchian