gerillass 1.6.2 → 2.0.1

package/README.md

@@ -8,6 +8,8 @@
 
 [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!
@@ -32,7 +34,7 @@ Hope you’ll enjoy using it!
   - [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)
-- [Namespace Usage](#namespace-usage)
+- [Three ways to call the same mixin](#three-ways-to-call-the-same-mixin)
 - [Vendor Prefix Support](#vendor-prefix-support)
 - [Experimenting](#experimenting)
 - [Testing](#testing)
@@ -53,7 +55,7 @@ Or with Yarn:
 
     yarn add gerillass --dev
 
-Then load it. If your setup resolves packages from **node_modules** — Vite, webpack, Next.js and most modern bundlers do — this is all you need:
+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 *;
 
@@ -79,7 +81,6 @@ Pointing straight at the file always works too:
 
 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.
 
-> **A note on eyeglass.** Gerillass still ships eyeglass module metadata, but eyeglass has not been released since June 2022 and its importer is broken with current Dart Sass — any `@import` fails with `doneImporting is not a function`, whether Gerillass is involved or not. It also relies on the legacy JS API, which Dart Sass removes in 2.0.0. Use the `pkg:` importer above instead; it is the built-in equivalent.
 
 ### Using with Vite
 
@@ -140,7 +141,7 @@ Then:
 
 ### Using with Grunt
 
-Use `grunt-sass` with Dart Sass as the implementation. The option here is **`loadPaths`** as well — not `loadPath`, and not `includePaths`.
+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");
@@ -189,25 +190,48 @@ Including to the project:
 
 ## Using Gerillass with an AI coding agent
 
-Gerillass ships two files that let a coding agent use the library correctly instead of guessing at it. Both are inside the installed package, so an agent working in your project can read them straight out of `node_modules/gerillass/`.
+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/`.
 
 **`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 — 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:
+**`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/
 
 Otherwise, point your agent at the file and it will read it as plain Markdown.
 
-Neither file is generated by hand: signatures are parsed from the Sass sources, and every example and refusal in the manifest is executed by the test suite. What the manifest says the library does is what the library does.
+### 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.
 
-## Namespace Usage
+    @use 'gerillass' as gls;
+    .avatar { @include gls.circle(50px); }
 
-You can use Gerillass with or without `gls-` namespace. It is optional, but I strongly recommend you to use it to prevent having conflicts with other Sass libraries or frameworks like Bootstrap.
+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
 

package/SKILL.md

@@ -5,7 +5,7 @@ description: Use the Gerillass Sass mixin library — loading it, the mixin cata
 
 # Gerillass
 
-A Sass mixin library: 51 mixins and 22 functions that emit CSS from
+A Sass mixin library: 50 mixins and 22 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.
 
@@ -37,7 +37,7 @@ Dart Sass only. LibSass and node-sass are not supported.
 
 ## Two names for every mixin
 
-Every mixin exists twice: bare (`ratio-box`) and prefixed (`gls-ratio-box`).
+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.
 
@@ -45,17 +45,17 @@ With the module system you can namespace instead, which is usually cleaner:
 
 ```scss
 @use "gerillass" as gls;
-.hero { @include gls.ratio-box("16/9"); }
+.avatar { @include gls.circle(50px); }
 ```
 
 ## Getting arguments right
 
 The conventions are not uniform across the library, so check before guessing.
-The single most common mistake is passing a ratio as a list:
+A mixin that wants a string will not take a bare value:
 
 ```scss
-.hero { @include ratio-box(16 9); }    // wrong — errors
-.hero { @include ratio-box("16/9"); }  // right
+.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
@@ -69,6 +69,7 @@ a dropped declaration rather than an error.
 | `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); }` |
@@ -86,10 +87,8 @@ a dropped declaration rather than an error.
 | `loadify` | `@include loadify(nonsense);` |
 | `only` | `.a { @include only(#ff0000) { margin: 0; } }` |
 | `radial-gradient` | `.a { @include radial-gradient(42, "center", (red, blue)); }` |
-| `ratio-box` | `.hero { @include ratio-box(16 9); }` |
 | `remove` | `.a { @include remove(a, b, c); }` |
 | `reset-css` | `.a { @include reset-css; }` |
-| `responsive-video` | `.video { @include responsive-video(16 9); }` |
 | `scissors` | `.a { @include scissors(5px 10px); }` |
 | `smartphone` | `.a { @include smartphone(Nokia3310) { display: none; } }` |
 | `sprite` | `.icon { @include sprite("/img/sprite.txt"); }` |
@@ -109,6 +108,7 @@ a dropped declaration rather than an error.
 | `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: $size * 5, $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. |
@@ -135,13 +135,11 @@ a dropped declaration rather than an error.
 | `placeholder` | Styles the placeholder text of an input across vendor prefixes. |
 | `position($position: absolute, $offsets: 0)` | Sets position and offsets in one call, using shorthand order. |
 | `radial-gradient($shape, $position, $colors)` | Radial gradient background from a shape and a position. |
-| `ratio-box($ratio: null)` | Container that holds a fixed aspect ratio. Its single direct child is stretched to fill it. |
 | `remove($params...)` | Hides an element outright, or only within a breakpoint range. |
 | `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. |
-| `responsive-video($ratio: null)` | Wrapper that keeps an embedded video at a fixed aspect ratio. |
 | `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. |
@@ -158,33 +156,33 @@ a dropped declaration rather than an error.
 
 ## Functions
 
-Called like normal Sass functions. The two leading underscores mark them as
-functions rather than mixins; they are public API.
+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. |
-| `__darken($color, $percentage)` | Mixes a colour towards black by a percentage. |
-| `__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. |
-| `__lighten($color, $percentage)` | Mixes a colour towards white by a percentage. |
-| `__mapDeepGet($map, $keys...)` | Reads a value out of a nested map by following a chain of keys. |
-| `__null($value, $seperation: comma, $skip: false)` | Replaces null entries in a list with 0, or drops them. |
-| `__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. |
-| `__shorthandProperty($value)` | Expands one to four values into the four-value CSS shorthand order. |
-| `__validateBreakpoint($value)` | Resolves a breakpoint name to its width, passing other values through. |
-| `__validateLength($value)` | Returns the value if it is a length or one of auto, inherit, initial, 0. |
-| `__validateRatio($ratio)` | Turns an aspect ratio into the padding-top percentage that holds it. |
-| `__validateScissors($value)` | Normalises corner values for the scissors mixin, adding px where missing. |
+| `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. |
+| `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 other values through. |
+| `validateLength($value)` | Returns the value if it is a length or one of auto, inherit, initial, 0. |
+| `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