Gerillass

Gerillass

A Sass mixin library: 55 mixins and 24 functions that emit CSS from semantic declarations. It is Sass source only — there is no runtime and no utility classes, so styles live in your stylesheet and your markup stays clean.

Full documentation: https://docs.gerillass.com Machine-readable API: gerillass.json in this package.

Loading it

Through a bundler (Vite, webpack and most others resolve the package by name):

@use "gerillass" as *;

Calling Dart Sass yourself, with its package importer (new NodePackageImporter() or sass --pkg-importer=node):

@use "pkg:gerillass" as *;

Anything else, by pointing a load path at node_modules/gerillass/scss:

@use "gerillass" as *;

In a Ruby project, from the gerillass gem. Rails with dartsass-rails or dartsass-sprockets, and Jekyll with the gem in its :jekyll_plugins group, need no configuration. Plain Ruby passes the folder to sass-embedded with load_paths: [Gerillass.load_path]. Then:

@use "gerillass" as *;  // the gerillass gem: Rails and Jekyll need no setup; plain Ruby passes Gerillass.load_path

Dart Sass only. LibSass and node-sass are not supported, which rules out sass-rails and sassc-rails in Ruby.

Two names for every mixin

Every mixin exists twice: bare (circle) and prefixed (gls-circle). They are the same mixin. The prefix exists to avoid collisions with other libraries. Pick one and stay with it; do not mix them in a file.

With the module system you can namespace instead, which is usually cleaner:

@use "gerillass" as gls;
.avatar { @include gls.circle(50px); }

Getting arguments right

The conventions are not uniform across the library, so check before guessing. A mixin that wants a string will not take a bare value:

.a { @include after(42) { color: red; } }    // wrong — errors
.a { @include after("→") { color: red; } }   // right

Mixins that reject bad input do so with a message naming what they accept. If you get one, read it: it lists the valid values. Mixins not in the table below mostly pass their arguments through to CSS, so a wrong value there shows up as a dropped declaration rather than an error.

Traps a signature does not show

after

• With no argument no content is emitted, so the pseudo-element does not render unless the block sets content. Pass "" for an empty one.

aspect-ratio

• On an element with a height attribute, such as <img width="1600" height="900"> or an embed code's <iframe>, the attribute height wins and the ratio is ignored. Write height: auto after the include.

before

• With no argument no content is emitted, so the pseudo-element does not render unless the block sets content. Pass "" for an empty one.

breakpoint

• With one argument the query matches exactly that width, (width: 768px), which is a single pixel, and the mixin prints a warning. Write only for that width, or min, max or a range for anything wider.
• Declarations written after the include, in the same rule, are emitted after the @media block and win over it. Write them before the include.

container-query

• A size on its own matches exactly that width, (width: 400px), which is a single pixel, and the mixin prints a warning. Write only for that width, or min, max or a range for anything wider.

container

• An element does not match a @container query that reads its own container, and nothing warns. Put the container-query on a descendant.

counter

• Numbering restarts on every item, each showing the first number, when the items are size containers (container-type: inline-size): containment scopes counters to each item.

except

• An+B with an offset cannot be passed as a number: Sass does the arithmetic, so except(2n+1) becomes 3n and excludes every third element, not the odd ones. Use odd or even, or a coefficient alone such as 3n.

loadify

• init and every call must be in the same module, or the module with the call must @use the one that calls init. Otherwise Sass fails with "The target selector was not found".

motion-safe

• Keep the resting state outside the block. An element hidden in its base rule and revealed by an animation inside the block stays hidden for a user who asked for less motion; put the start state in the keyframes instead.

only

• An+B with an offset cannot be passed as a number: Sass does the arithmetic, so only(2n+1) becomes 3n and selects every third element, not the odd ones. Use odd or even, or a coefficient alone such as 3n.

remove

• With one argument the element is hidden at exactly that width, (width: 768px), which is a single pixel, and the mixin prints a warning. Write only for that width, or min, max or a range for anything wider.
• A display written after the include, in the same rule, is emitted after the @media block and wins over it. Write it before the include.

Mixins

Functions

Called like normal Sass functions, with no @include. They are public API, and camelCase is what tells them apart from the kebab-case mixins above.

Checking your work

Sass evaluates mixin bodies lazily, so a stylesheet that merely loads the library always compiles. Compile the file that actually calls the mixin:

sass --load-path=node_modules/gerillass/scss your.scss

An empty rule in the output means the mixin matched none of its branches — treat that as a bug, not as success.