gerillass 0.0.6 → 2.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb366e2424a9e7c193e6bd1bd2e1cb4003133d681764afdd7dfb2a886346cfe7
-  data.tar.gz: cbdcd153006f1d57db8810532a5aedcd2f9d3bf07cb314783c754ac733218007
+  metadata.gz: 02dd270ee370fad4ffe2c7c923109a817dad1f57ad146c0797f1af0294eed964
+  data.tar.gz: 4b8401c4dcd34999ef807ce113245569ba46851b9681d310013aab6b22ac0aea
 SHA512:
-  metadata.gz: 2554a87240cac4e991e4069819c897bc0a429d4091291d32c78dd8f4966798846dd8d8f330df164323cb1addc05f88b03a607164f6c9a646629a99ec1d4ae893
-  data.tar.gz: e7e76a2e6e0649f975456179f79502e522edf28bbcaa655832611bfcf09f7c60e649dee35b60e8c36aed6776dae9fd3b90d65a20a1f5600f6b83d46b5a8b8b63
+  metadata.gz: 9d4787002cda44ffba63f6bc24b14b0651003e0480d50f361a280c2500deef566c94b351e0207750cb92a059e8cc99e97cd59c63cdd054e9b340692b9e436a5c
+  data.tar.gz: 98c62d1bb1d0d3b04b3eb6529ef9fa74893ca197775633cb57a53229011b1407ac5e30c40126ba4c5bd720f5fdb4bf7ca5060c35a6be61aa7641f52376058aac

data/LICENSE.md

@@ -0,0 +1,13 @@
+Copyright 2020 [Halil İbrahim Çakıroğlu](https://www.linkedin.com/in/selfishprimate/)
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,328 @@
+<p>
+  <a href="https://gerillass.com" target="_blank">
+    <img src="https://gerillass.com/images/github/gerillass_logo_sassy.svg">
+  </a>
+</p>
+
+## _<span><img src="https://gerillass.com/images/github/heart_red.svg"></span> Meet the Coolest Sass Toolset! <span><img src="https://gerillass.com/images/github/heart_red.svg"></span>_
+
+[Gerillass](https://gerillass.com) is a library built on top of [Sass (Syntactically Awesome Style Sheets)](https://sass-lang.com/) to give you flexibility for your projects and accelerate your performance and creativity.
+
+It is also built to be read by coding agents. Every mixin and function ships with a machine-readable manifest, and the test suite compiles every documented example and asserts every documented refusal. So what the manifest says the library does is what the library does. The docs cannot drift away from the code, because a stale manifest fails the build.
+
+Many of the utilities that come with Gerillass are the solutions I have come up with for the challenges I have faced as a frontend developer over the years. These solutions have been shaped by the inspiration of other popular libraries and frameworks like [Bourbon](https://www.bourbon.io/), [Susy](https://www.oddbird.net/), [Scut](https://github.com/davidtheclark/scut), [Bootstrap](https://getbootstrap.com/), etc. over time and helped me create Gerillass.
+
+Hope you’ll enjoy using it!
+
+**Related Links:**
+
+- [Gerillass Website](https://gerillass.com)
+- [Gerillass Documentation](https://docs.gerillass.com)
+- [Gerillass Blog](https://medium.com/gerillass)
+- [Twitter](https://twitter.com/gerillass)
+
+## Table of Contents
+
+- [Dart Sass Upgrade](#dart-sass-upgrade)
+- [Installation](#installation)
+  - [Using with Vite](#using-with-vite)
+  - [Using with webpack](#using-with-webpack)
+  - [Using with Parcel](#using-with-parcel)
+  - [Using with Next.js](#using-with-nextjs)
+  - [Using with Angular](#using-with-angular)
+  - [Using with Gulp](#using-with-gulp)
+  - [Using with Grunt](#using-with-grunt)
+  - [Using with Ruby: Rails, Jekyll, or plain Sass](#using-with-ruby-rails-jekyll-or-plain-sass)
+  - [Cloning the Repository from Github](#cloning-the-repository-from-github)
+  - [Versions these examples were tested with](#versions-these-examples-were-tested-with)
+- [Using Gerillass with an AI coding agent](#using-gerillass-with-an-ai-coding-agent)
+- [Three ways to call the same mixin](#three-ways-to-call-the-same-mixin)
+- [Vendor Prefix Support](#vendor-prefix-support)
+- [Experimenting](#experimenting)
+- [Testing](#testing)
+- [Contribution](#contribution)
+- [License](#license)
+- [Additional Info](#additional-info)
+
+## Dart Sass Upgrade
+_We are saying goodbye to LibSass with version 1.3.0_ :cry:
+
+Because LibSass and the packages built on it, including Node Sass, are deprecated, **Gerillass will no longer support LibSass since version 1.3.0** If you're having a problem running Gerillass v1.3.0 please consider using Dart Sass instead of LibSass. If you are running Dart Sass already, you can install and use Gerillass 1.3.0 and later versions safely. If not, however, please use the earlier versions.
+
+## Installation
+
+    npm install gerillass --save-dev
+
+Or with Yarn:
+
+    yarn add gerillass --dev
+
+Then load it. If your setup resolves packages from **node_modules**, which Vite, webpack, Next.js and most modern bundlers do, this is all you need:
+
+    @use 'gerillass' as *;
+
+If you call Dart Sass yourself rather than through a bundler, turn on its package importer and use a `pkg:` URL:
+
+    @use 'pkg:gerillass' as *;
+
+```js
+// Dart Sass 1.71.0 or later
+import * as sass from 'sass';
+import { NodePackageImporter } from 'sass';
+
+sass.compile('style.scss', { importers: [new NodePackageImporter()] });
+```
+
+Or from the command line:
+
+    sass --pkg-importer=node style.scss style.css
+
+Pointing straight at the file always works too:
+
+    @use '{node_modules_path}/gerillass/scss/gerillass' as *;
+
+The per-tool recipes below were each verified against a real build of Gerillass v1.5.0. The versions used are listed at the end of this section.
+
+
+### Using with Vite
+
+Vite resolves the package by name, so there is nothing to configure. This covers anything built on Vite, including React, Vue, Svelte, SvelteKit and Astro.
+
+    @use 'gerillass' as *;
+
+### Using with webpack
+
+`sass-loader` also resolves the package by name, with no extra options.
+
+    @use 'gerillass' as *;
+
+### Using with Parcel
+
+Parcel resolves the package by name too, so the usual line needs no configuration:
+
+    @use 'gerillass' as *;
+
+**Remove `main` from your project's own `package.json`.** `npm init -y` writes `"main": "index.js"`, and Parcel reads that field as a library build target. With it present an app build fails, and the error names the stylesheet rather than the field: `Can't find stylesheet to import`. No Sass option gets around it. If you need to keep the field, turn that target off instead:
+
+    "targets": { "main": false }
+
+To use a `pkg:` URL, create the importer in a `.sassrc.js`. Setting `pkgImporter` in `.sassrc.json` does not work: Parcel switches Sass to its legacy API for that option, and the import is not found.
+
+    // .sassrc.js
+    const { NodePackageImporter } = require("sass");
+    module.exports = { importers: [new NodePackageImporter()] };
+
+Two more things worth knowing:
+
+- **Pass the font formats you actually have to `font-face`.** It lists five by default, and Parcel resolves every `url()` in the output, so a folder holding only `.woff2` fails with `Failed to resolve './fonts/inter.eot'`. `$file-formats: woff2` fixes it.
+- **`quietDeps` hides the library's own deprecation warnings.** Dart Sass reports its `if()` deprecation from inside the package on every build. A `.sassrc.json` of `{ "quietDeps": true }` silences those and still reports the ones in your own files.
+
+### Using with Next.js
+
+Next.js needs to be told where the library lives. In `next.config.mjs`:
+
+    export default {
+      sassOptions: {
+        loadPaths: ["node_modules/gerillass/scss"],
+      },
+    };
+
+Then, in any `.scss` file:
+
+    @use 'gerillass' as *;
+
+### Using with Angular
+
+Add the library folder to the build target's options in `angular.json`. Angular calls this option `includePaths`, not `loadPaths`:
+
+    "stylePreprocessorOptions": {
+      "includePaths": ["node_modules/gerillass/scss"]
+    }
+
+Then, in `src/styles.scss`:
+
+    @use 'gerillass' as *;
+
+### Using with Gulp
+
+`gulp-sass` hands its options straight to Dart Sass, so the option is **`loadPaths`**. The old `includePaths` name came from Node Sass and no longer resolves.
+
+    const { src, dest } = require("gulp");
+    const sass = require("gulp-sass")(require("sass"));
+
+    function styles() {
+      return src("assets/sass/**/*.scss")
+        .pipe(sass({ loadPaths: ["node_modules/gerillass/scss"] }).on("error", sass.logError))
+        .pipe(dest("assets/css"));
+    }
+
+    exports.styles = styles;
+
+Then:
+
+    @use 'gerillass' as *;
+
+### Using with Grunt
+
+Use `grunt-sass` with Dart Sass as the implementation. The option here is **`loadPaths`** as well, not `loadPath`, and not `includePaths`.
+
+    module.exports = function (grunt) {
+      grunt.loadNpmTasks("grunt-sass");
+      grunt.initConfig({
+        sass: {
+          dist: {
+            options: {
+              implementation: require("sass"),
+              loadPaths: ["node_modules/gerillass/scss"],
+            },
+            files: { "css/main.css": "src/main.scss" },
+          },
+        },
+      });
+    };
+
+Then:
+
+    @use 'gerillass' as *;
+
+### Using with Ruby: Rails, Jekyll, or plain Sass
+
+Gerillass is also a gem. It installs the same Sass files and nothing else: no runtime dependencies, because each kind of project already brings its own Dart Sass. It needs Dart Sass; the LibSass-based `sass-rails` and `sassc-rails` cannot compile it.
+
+    bundle add gerillass
+
+**Rails.** With `dartsass-rails` on Propshaft, the Rails 8 default, or `dartsass-sprockets` on Sprockets, there is nothing to configure: the gem hands the library's folder to Sass, and none of its files end up in `public/assets`. Then, in `app/assets/stylesheets/application.scss`:
+
+    @use 'gerillass' as *;
+
+**Jekyll.** Put the gem in the plugins group of your `Gemfile`:
+
+    group :jekyll_plugins do
+      gem "gerillass"
+    end
+
+Then, in a stylesheet with front matter such as `assets/css/main.scss`:
+
+    ---
+    ---
+    @use 'gerillass' as *;
+
+**Plain Ruby.** Pass the library's folder to `sass-embedded` yourself:
+
+    require "sass-embedded"
+    require "gerillass"
+
+    Sass.compile("style.scss", load_paths: [Gerillass.load_path])
+
+### Cloning the repository from Github
+
+You can clone the repository into your local computer from Github.
+
+    git clone https://github.com/selfishprimate/gerillass.git
+
+Or you can add the library as a submodule into your Git based project ([What is a submodule?](https://git-scm.com/book/en/v2/Git-Tools-Submodules)).
+
+    git submodule add https://github.com/selfishprimate/gerillass.git
+
+Including to the project:
+
+    @use '{folder_path}/gerillass/scss/gerillass' as *;
+
+### Versions these examples were tested with
+
+| Tool | Version |
+|---|---|
+| Dart Sass | 1.103.1 |
+| Vite | 8.2.2 |
+| webpack / sass-loader | 5.110.3 / 17.0.1 |
+| Next.js | 16.3.4 |
+| Angular CLI | 20.3.36 |
+| Gulp / gulp-sass | 5.0.1 / 6.0.1 |
+| Grunt / grunt-sass | 1.6.3 / 4.1.0 |
+| Parcel / @parcel/transformer-sass | 2.16.4 / 2.16.4, with Dart Sass 1.104.1 and Gerillass 2.1.0 |
+| Ruby / Rails | 4.0.1 / 8.1.3.1 |
+| Propshaft / dartsass-rails | 1.3.2 / 0.5.1 |
+| sprockets-rails / dartsass-sprockets | 3.5.2 / 3.2.1 |
+| Jekyll / jekyll-sass-converter | 4.4.1 / 3.1.0 |
+| sass-embedded (Ruby) | 1.104.1 |
+
+## Using Gerillass with an AI coding agent
+
+A library this size has no training data behind it, so an agent asked to use Gerillass will guess at the argument forms and get them wrong. Two files ship with the package to stop that. Both live inside the installed package, so an agent working in your project can read them straight out of `node_modules/gerillass/`, or, in a Ruby project, out of the gem's folder, which `bundle info gerillass --path` prints.
+
+**`gerillass.json`** describes every mixin and function: its signature, what each argument accepts, examples that compile, and inputs that are refused.
+
+    const api = require("gerillass/gerillass.json");
+
+**`SKILL.md`** is a written guide generated from that manifest. It covers how to load the library, the full catalogue, and the argument forms that are easy to get wrong. If your agent supports [Agent Skills](https://code.claude.com/docs/en/skills), copy it into your skills folder:
+
+    mkdir -p .claude/skills/gerillass
+    cp node_modules/gerillass/SKILL.md .claude/skills/gerillass/
+
+In a Ruby project, copy it from the gem instead:
+
+    cp "$(bundle info gerillass --path)/SKILL.md" .claude/skills/gerillass/
+
+Otherwise, point your agent at the file and it will read it as plain Markdown.
+
+### Why you can trust what they say
+
+Neither file is written by hand. Signatures are parsed from the Sass sources, and the semantics come from a separate set of notes, so nobody can describe a mixin that does not exist.
+
+The part that matters is what happens next. The test suite takes every example in the manifest and compiles it. It takes every input the manifest claims is refused and checks that the library really does refuse it, with its own error message rather than an internal Sass one. It runs every example a second time under the `gls-` prefixed name and requires byte-identical CSS. And it fails the build if either generated file is out of date.
+
+So the manifest cannot claim behaviour the library does not have. That is the whole point of it. Documentation drifts away from code in most projects, quietly, and an agent reading stale docs writes code that does not work. Here it cannot happen without turning the test suite red first.
+
+
+## Three ways to call the same mixin
+
+None of them is required. Pick whichever reads best in your project, and stay with it in a given file.
+
+**Bare.** The shortest, and fine unless another library defines the same name.
+
+    @use 'gerillass' as *;
+    .avatar { @include circle(50px); }
+
+**With the `gls-` prefix.** Every mixin also answers to a prefixed name, which avoids collisions with Bootstrap and friends.
+
+    @use 'gerillass' as *;
+    .avatar { @include gls-circle(50px); }
+
+**Through a namespace.** Sass's own mechanism, and the tidiest of the three: nothing enters your global scope at all, so a collision is impossible. The name after `as` is yours to choose.
+
+    @use 'gerillass' as gls;
+    .avatar { @include gls.circle(50px); }
+
+All three produce identical CSS. The prefix predates the Sass module system; if you are starting fresh, the namespace does the same job without the extra name.
+
+## Vendor Prefix Support
+
+Because of the vast usage of bundlers like [Gulp](https://gulpjs.com/), [Grunt](https://gruntjs.com/), [Webpack](https://webpack.js.org/), etc.(these frameworks run some other plugins like Autoprefixer to support vendor prefixes), Gerillass doesn't provide vendor prefix support.
+
+So, feel free to use any tool to support that. My suggestion is Autoprefixer. If you are not using one of the bundlers mentioned above, you can also manually add vendor prefixes using the [Autoprefixer CSS Online](https://autoprefixer.github.io/) tool.
+
+## Experimenting
+
+Experimentation with Gerillass is easy: If you're processing Sass files on your computer already, [download the Gerillass Sass library](https://github.com/selfishprimate/gerillass/archive/main.zip), include it in your project, and start using it. If not, use [Gerillass Play](https://github.com/selfishprimate/gerillass-play)! Gerillass Play is a Gulp based playground, built for you to get started with [Sass](https://sass-lang.com/) and [Gerillass](https://gerillass.com/) quickly.
+
+**Important Note**: Don't forget that you must have [Node.js](https://nodejs.org/en/) and [Gulp CLI](https://gulpjs.com/docs/en/getting-started/quick-start) installed on your machine to work with Gerillass Play.
+
+## Testing
+
+Gerillass comes with a unit-testing module named [True](https://github.com/oddbird/true), which makes Sass unit tests possible (endless thanks to the [OddBird Team](https://github.com/oddbird)).
+
+You can find two test examples under the `test` folder, take your time, examine the codes, and then write your unit tests. After that, run the following command to see if the tests pass.
+
+    npm test
+
+## Contribution
+
+Please read the [contribution details](CONTRIBUTING.md) and feel free to contribute to the library.
+
+## License
+
+Gerillass is licensed under the Apache License, Version 2.0. For more [see the license content](https://github.com/selfishprimate/gerillass/blob/main/LICENSE.md).
+
+## Additional Info
+
+This project is created with the loving music of **Anna German** and dedicated to **James Williamson**: The best web educator ever. For more information about James, please check his legacy blog page at [simpleprimate.netlify.app](https://simpleprimate.netlify.app) or watch his video lectures about **Web** and **Accessibility** on [LinkedIn Learning](https://www.linkedin.com/learning/instructors/james-williamson).

data/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: gerillass
+description: Use the Gerillass Sass mixin library — loading it, the mixin catalogue, and the argument forms that are easy to get wrong. Use when writing SCSS in a project that has gerillass installed.
+---
+
+# Gerillass
+
+A Sass mixin library: 56 mixins and 23 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):
+
+```scss
+@use "gerillass" as *;
+```
+
+Calling Dart Sass yourself, with its package importer
+(`new NodePackageImporter()` or `sass --pkg-importer=node`):
+
+```scss
+@use "pkg:gerillass" as *;
+```
+
+Anything else, by pointing a load path at `node_modules/gerillass/scss`:
+
+```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:
+
+```scss
+@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:
+
+```scss
+@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:
+
+```scss
+.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.
+
+| Mixin | Rejects, for example |
+|---|---|
+| `adaptive` | `.wrap { @include adaptive(auto); }` |
+| `after` | `.a { @include after(42) { color: red; } }` |
+| `all-buttons` | `@include all-buttons(nonsense) { color: red; }` |
+| `all-text-inputs` | `@include all-text-inputs(nonsense) { color: red; }` |
+| `antialias` | `@include antialias(only);` |
+| `aspect-ratio` | `.thumb { @include aspect-ratio("16:9", nonsense); }` |
+| `background-dots` | `.a { @include background-dots(red, 1em, 5em, maybe); }` |
+| `background-image` | `.a { @include background-image("/img/a.png", (red, blue), sideways); }` |
+| `background-stripes` | `.a { @include background-stripes(red, 2em, nonsense); }` |
+| `before` | `.a { @include before(42) { color: red; } }` |
+| `border-box` | `@include border-box(only);` |
+| `border-radius` | `.a { @include border-radius(1px, 2px, 3px); }` |
+| `brand-logo` | `.logo { @include brand-logo(120px, 40px, "/img/a.svg" "/img/b.svg"); }` |
+| `breakpoint` | `.a { @include breakpoint("between", "medium", "large") { color: red; } }` |
+| `breakpointer` | `.a { @include breakpointer(42); }` |
+| `center` | `.modal { @include center(diagonal); }` |
+| `circle` | `.dot { @include circle(huge); }` |
+| `columnizer` | `.grid { @include columnizer(3, 20px, true, 9); }` |
+| `container-query` | `.title { @include container-query("min", 400px, 800px) { color: red; } }` |
+| `container` | `.card { @include container("card", sideways); }` |
+| `ellipsis` | `.a { @include ellipsis(100%, huge); }` |
+| `escape-to-parent` | `.a { @include escape-to-parent(42) { color: red; } }` |
+| `except` | `.a { @include except(#ff0000) { margin: 0; } }` |
+| `focus-ring` | `@include focus-ring;` |
+| `font-face` | `.a { @include font-face("Inter", "/fonts/inter"); }` |
+| `hide` | `.a { @include hide(nonsense); }` |
+| `line-clamp` | `.a { @include line-clamp(0); }` |
+| `linear-gradient` | `.a { @include linear-gradient(sideways, (red, blue)); }` |
+| `loadify` | `@include loadify(nonsense);` |
+| `motion-safe` | `.card { @include motion-safe; }` |
+| `only` | `.a { @include only(#ff0000) { margin: 0; } }` |
+| `position` | `.badge { @include position(absolute, 0, $logical: yes); }` |
+| `radial-gradient` | `.a { @include radial-gradient(42, "center", (red, blue)); }` |
+| `remove` | `.a { @include remove(a, b, c); }` |
+| `reset-css` | `.a { @include reset-css; }` |
+| `resizable` | `.a { @include resizable(huge); }` |
+| `scissors` | `.a { @include scissors(5px 10px); }` |
+| `screen-agent` | `.a { @include screen-agent(var(--density)) { color: red; } }` |
+| `sizer` | `.a { @include sizer(huge); }` |
+| `smartphone` | `.a { @include smartphone(Nokia3310) { display: none; } }` |
+| `sprite` | `.icon { @include sprite("/img/sprite.txt"); }` |
+| `stretched-link` | `.card a { @include stretched-link(middle); }` |
+| `tablet` | `.a { @include tablet(Surface) { display: none; } }` |
+| `text-gradient` | `.a { @include text-gradient(sideways, (red, blue)); }` |
+| `text-image` | `.a { @include text-image(16 9); }` |
+| `text-selection` | `.a { @include text-selection(bogus) { background: yellow; } }` |
+| `text-shadow` | `.a { @include text-shadow(42); }` |
+| `text-stroke` | `.a { @include text-stroke(huge); }` |
+| `tokens` | `:root { @include tokens(#fff); }` |
+| `triangle` | `.caret { @include triangle(sideways); }` |
+
+## 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
+
+| Signature | What it does |
+|---|---|
+| `adaptive($gutter: 30px)` | Centred container whose max-width steps up at every breakpoint. |
+| `after($content: null)` | Styles the ::after pseudo-element. A `data-` argument becomes an attr() content value. |
+| `all-buttons($pseudo: null)` | Targets every button-like element at once, optionally in one pseudo-class state. |
+| `all-text-inputs($pseudo: null)` | Targets every text-like input at once, optionally in one pseudo-class state. |
+| `antialias($value: null)` | Turns on subpixel-antialiased text smoothing. |
+| `aspect-ratio($ratio: null, $fit: cover)` | Holds an element to a ratio and adds what CSS aspect-ratio alone leaves out: object-fit so an image is cropped rather than stretched, and border: 0 so an iframe does not overflow its container by 4px. Apply it to the element itself, not to a wrapper. |
+| `background-dots($color: null, $size: 1em, $gutter: null, $diagonal: true, $image: null)` | Repeating dot pattern as a background, optionally over an image. |
+| `background-image($image-url: null, $filter-color: null, $filter-direction: null)` | Background image with an optional colour or gradient filter laid over it. |
+| `background-stripes($color: null, $thickness: 1em, $rotation: -45deg, $image: null)` | Repeating stripe pattern as a background, optionally over an image. |
+| `before($content: null)` | Styles the ::before pseudo-element. A `data-` argument becomes an attr() content value. |
+| `border-box($value: null)` | Applies box-sizing: border-box. |
+| `border-radius($args...)` | Rounds corners, either all of them, one named corner, or all four individually. |
+| `brand-logo($width, $height, $image-url: null)` | Logo box with an image and an accessible stretched link over it. |
+| `breakpoint($params...)` | Media query built from the breakpoint map, or from raw lengths. |
+| `breakpointer($selector: null)` | Debug helper that prints the active breakpoint name into a pseudo-element. |
+| `center($axis: "both")` | Absolutely centres an element inside its positioned parent. |
+| `circle($size)` | Square element with a fully rounded border, i.e. a circle. |
+| `clearfix` | Clears floated children using an ::after pseudo-element. |
+| `columnizer($params...)` | Flexbox grid of equal columns, with an optional gutter and fill behaviour. |
+| `container-query($params...)` | A @container rule, taking the same argument shapes as breakpoint so the two read alike. Sizes may be a key from $map-for-breakpoints or a raw length, and a length is the common case because a container is usually narrower than the viewport. Nothing matches at all unless an ancestor was declared with the container mixin. |
+| `container($name: null, $type: inline-size)` | Marks an element as a query container, so container-query can ask about its width instead of the viewport's. The rule that asks has to sit on a descendant: an element is never matched by a @container rule reading its own container, and nothing warns you when it is not. |
+| `counter($params...)` | CSS counter for a list, with optional text before and after the number. |
+| `ellipsis($width: 100%, $display: inline-block)` | Truncates a single line of text with an ellipsis. |
+| `escape-to-parent($selector: null)` | Re-roots the current selector under another one using @at-root. |
+| `except($params...)` | Selects every sibling except the ones named. |
+| `focus-ring($width: 2px, $offset: 2px, $color: currentColor)` | Draws a keyboard focus ring with outline on :focus-visible, which survives forced-colors mode where a box-shadow ring disappears. |
+| `font-face($font-family, $file-path, $font-style: normal, $font-weight: 400, $file-formats: eot woff2 woff ttf svg, $font-display: null)` | Emits an @font-face rule for one family across several file formats. Must be called at the root. |
+| `hide($toggle: "hide")` | Visually hides an element while keeping it available to screen readers, or reverses that. |
+| `line-clamp($lines: 3)` | Truncates text after a number of lines, where ellipsis truncates one. It emits five declarations rather than one because -webkit-line-clamp does nothing on its own: without display: -webkit-box or without -webkit-box-orient: vertical the text is not clamped at all and nothing warns you, and without overflow: hidden the clamped text spills out below the box. The unprefixed line-clamp is emitted too, for when it becomes Baseline. |
+| `linear-gradient($direction, $colors)` | Linear gradient background from a direction name or an angle. |
+| `loadify($params...)` | Fades elements in on page load. Call once at the root to set up, then on each element. Under prefers-reduced-motion: reduce the end state is applied directly and no animation runs. Switching the animation off alone would not do, because the element starts invisible and the animation is what reveals it, so the content would stay hidden for good. |
+| `motion-safe` | Wraps its content in @media (prefers-reduced-motion: no-preference), so motion is opt-in: a user who asked their system for less motion gets none of it. |
+| `only($params...)` | Selects only the siblings named. |
+| `placeholder-shown` | Styles an input while its placeholder is visible. |
+| `placeholder` | Styles the placeholder text of an input across vendor prefixes. |
+| `position($position: absolute, $offsets: 0, $logical: false)` | Sets position and offsets in one call, using shorthand order. |
+| `radial-gradient($shape, $position, $colors)` | Radial gradient background from a shape and a position. |
+| `remove($params...)` | Hides an element outright, or within a media query: from a breakpoint up with min, up to it with max, or between two breakpoints. One breakpoint on its own hides the element at exactly that width, a single pixel, and prints a warning: pass only for that. |
+| `reset-css` | Meyer reset. Must be called at the root of the stylesheet. |
+| `reset-figure` | Removes default figure margins and makes the image inside responsive. |
+| `resizable($direction: both, $overflow: auto)` | Makes an element user-resizable. |
+| `responsive-image` | Makes an image fill its container width. |
+| `scissors($corners)` | Cuts the corners off an element with clip-path. |
+| `screen-agent($resolution)` | Media query targeting a screen pixel density. |
+| `sizer($width, $height: $width)` | Sets width and height together; one argument makes a square. |
+| `smartphone($device, $orientation: null)` | Media query targeting a known smartphone by device dimensions. |
+| `sprite($params...)` | Sets up an element as a sprite tile: an image, a background position, or both. |
+| `stretched-link($value: "before")` | Expands a link to cover its positioned parent, so the whole card is clickable. |
+| `tablet($device, $orientation: null)` | Media query targeting a known tablet by device dimensions. |
+| `text-gradient($direction, $colors)` | Applies a linear gradient to the text itself via background-clip. |
+| `text-image($image: null)` | Fills the text with an image via background-clip. |
+| `text-selection($value: null)` | Styles the ::selection pseudo-element. |
+| `text-shadow($params...)` | Layered text shadows built from a direction, a colour and an offset. |
+| `text-stroke($fallback-color: black, $color: transparent, $stroke-color: black, $stroke-width: 1px)` | Outlines text using the webkit text-stroke properties. |
+| `tokens($map, $prefix: null)` | Writes a Sass map out as CSS custom properties, for any kind of token: colours, spacing, sizes, radii, type, shadows, durations. With the prefix space, (4: 1rem) becomes --space-4: 1rem. A null value is skipped, and a quoted string keeps its quotes. |
+| `triangle($direction: "bottom", $color: black, $size: 10px 8px)` | Draws a CSS triangle out of borders, pointing in a given direction. |
+
+## 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.
+
+| Signature | What it does |
+|---|---|
+| `clearUnit($value)` | Strips the unit off a number, returning it unitless. |
+| `clearWhitespace($string)` | Removes every space from a string. |
+| `convertToEm($value)` | Converts a pixel length to em, against a 16px base. |
+| `convertToNumber($value)` | Parses a string of digits into a number. |
+| `fillNulls($value, $seperation: comma, $skip: false)` | Replaces null entries in a list with 0, or drops them. |
+| `fluid($min, $max, $min-viewport: 320px, $max-viewport: 1280px)` | A clamp() value that grows with the viewport between two widths, then stops. The preferred value keeps a rem term rather than being pure vw, because a vw-only value ignores browser text zoom and fails WCAG 1.4.4. It is a function rather than a mixin because the value is the hard part and belongs to any property, not only font-size. |
+| `fontSizer($size, $time)` | Multiplies a size by a factor. Handy for a modular scale. |
+| `fontSource($font-family, $file-path, $file-formats)` | Builds one src entry for an @font-face rule. |
+| `isColor($value)` | Returns the value if every item in it is a colour, and errors otherwise. |
+| `isGutter($value)` | True for anything that can sit where a CSS length is expected: a number, a calculation, or a CSS function such as var(). |
+| `isNumber($value)` | Returns the value if it is a number. |
+| `isTime($value)` | Returns the value if it is a time in s or ms, and errors otherwise. |
+| `mapDeepGet($map, $keys...)` | Reads a value out of a nested map by following a chain of keys. |
+| `pixelify($value)` | Returns the value with a px unit, adding one if it is missing. |
+| `pseudoSelector($elements, $pseudo: null)` | Appends a pseudo-class to every selector in a list. |
+| `remify($value)` | Converts a pixel length to rem, against a 16px root. |
+| `shade($color, $percentage)` | Mixes a colour towards black by a percentage. |
+| `shorthandProperty($value)` | Expands one to four values into the four-value CSS shorthand order. |
+| `tint($color, $percentage)` | Mixes a colour towards white by a percentage. |
+| `validateBreakpoint($value)` | Resolves a breakpoint name to its width, passing a length, a percentage or a CSS function through, and refusing a word that is not a key. |
+| `validateLength($value)` | Returns the value if it is a length or one of auto, inherit, initial, 0. Returns null quietly for null, so a caller can skip a value. |
+| `validateRatio($ratio)` | Turns an aspect ratio into a value for the CSS aspect-ratio property. |
+| `validateScissors($value)` | Normalises corner values for the scissors mixin, adding px where missing. |
+
+## 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:
+
+```bash
+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.