@ryanknutson/pattern-hero

Tree-friendly Sass SVG pattern library built from Hero Patterns.

Apply lightweight, customizable SVG background patterns using Sass—only the patterns you use get emitted.

✨ Features ✨

• 🎨 SVG-based background patterns
• 🌗 Built-in light/dark support
• 🧩 Tree-friendly (no unused CSS output)
• 🎯 Flexible sizing (single value or 2D)
• 🌈 Supports hex, rgb/rgba, and named colors

Installation

These install methods have been tested in both Node.js and Deno.

Option 1: npm

Install the package:

npm install @ryanknutson/pattern-hero

Using the Dart Sass CLI

1. Import the library in your Sass:

@use '@ryanknutson/pattern-hero/PatternHero.scss' as p;

2. Compile your Sass with the node_modules load path:

sass --load-path=node_modules main.scss

Using the Sass JS API

import * as sass from 'sass';

const result = sass.compileString(`
  @use '@ryanknutson/pattern-hero/PatternHero.scss' as p;

  .hero {
    @include p.pattern('architect', #b0e1e3);
  }
`, {
  loadPaths: ['node_modules'],
});

console.log(result.css);

Option 2: git clone (no npm required)

Clone the repository into your project Sass directory:

git clone https://gitlab.com/ryanknutson/pattern-hero.git sass/pattern-hero

Then import it directly in your Sass:

@use 'pattern-hero/PatternHero.scss' as p;

Compile normally (no extra config needed):

sass input.scss output.css

Examples

Basic example

.hero {
  @include p.pattern('architect', #b0e1e3);
}

Light / Dark Mode

.hero {
  @include p.pattern-dual('architect', #b0e1e380, #333);
}

Uses prefers-color-scheme: dark.

Complex usage example

.card {
  @include p.pattern('zig-zag', rgba(255,255,255,0.08), 80px, #111);
  border-radius: 12px;
  padding: 2rem;
}

Size Options

The $size argument supports:

• null or _ → default size
• single value → 120px, 25%, etc.
• keywords → auto, cover, contain
• 2-value list → (120px 80px)

.card {
  @include p.pattern('zig-zag', limegreen, (120px 60px));
}

Full API

@include pattern(...)

@include pattern(
  $name,
  $color,
  $size: null,
  $bg: null
);

Applies a pattern as a background.

@include pattern-dual(...)

@include pattern-dual(
  $name,
  $light,
  $dark,
  $size: $default-size,
  $bg: null
);

Applies different pattern colors for light/dark mode.

Color Support

You can pass:

@include p.pattern('architect', #b0e1e3);
@include p.pattern('architect', #b0e1e380);
@include p.pattern('architect', rgba(176, 225, 227, 0.4));
@include p.pattern('architect', limegreen);

Supported formats:

• hex (#rgb, #rrggbb, #rrggbbaa)
• rgb / rgba
• named colors

Notes

• Pattern names must be strings:

  "architect" or 'architect'

• Colors are automatically normalized for SVG use
• Only used patterns generate CSS (tree-friendly)

Structure

• PatternHero.scss → public API
• PatternLibrary.scss → generated pattern map

Custom Patterns

Generating custom patterns

You can generate your own patterns from SVG files using the included Perl script:

chmod +x convert.pl
./convert.pl *.svg > MyPatterns.scss

This converts SVG files into encoded data URLs in a Sass map and saves them as MyPatterns.scss.

Using custom patterns

1. Create a file (eg. MyPatterns.scss) containing your generated patterns:

// MyPatterns.scss
$pattern-svg: (
  'my-pattern': "data:image/svg+xml,..."
);

The easiest way is to generate this file with the included convert.pl.

2. Create a small wrapper file (eg. patterns.scss) to merge your patterns with the built-in library:

// patterns.scss
@use './MyPatterns' as custom;

@forward '@ryanknutson/pattern-hero/PatternHero.scss' with (
  $custom-patterns: custom.$pattern-svg
);

3. Use your combined patterns anywhere like usual:

// any file in your project
@use './patterns' as p;

.hero {
  @include p.pattern('my-pattern', limegreen);
}

License/Attribution

This project is MIT licensed and includes SVG patterns derived from:

Hero Patterns
https://heropatterns.com/

Licensed under Creative Commons Attribution 4.0
https://creativecommons.org/licenses/by/4.0/

Modifications have been made to the original works.