gerillass 2.1.0 → 2.2.0

package/gerillass.json

@@ -1,6 +1,6 @@
 {
   "name": "gerillass",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Gerillass is an open-source toolkit that contains a set of Sass mixins to help designers and developers to create better, faster and consistent user interfaces.",
   "homepage": "https://gerillass.com",
   "documentation": "https://docs.gerillass.com",
@@ -42,17 +42,23 @@
           "accepts": [
             "a string used as the content value",
             "a data- attribute name, rendered as attr()",
-            "null to write content yourself"
+            "null to write content yourself",
+            "var(), attr(), counter() or counters(), written as they are"
           ]
         }
       ],
       "file": "scss/library/_after.scss",
       "signature": "after($content: null)",
       "summary": "Styles the ::after pseudo-element. A `data-` argument becomes an attr() content value.",
+      "caveats": [
+        "With no argument no `content` is emitted, so the pseudo-element does not render unless the block sets `content`. Pass `\"\"` for an empty one."
+      ],
       "examples": [
         ".a { @include after(\"→\") { color: red; } }",
         ".a { @include after(\"data-label\") { color: red; } }",
-        ".a { @include after { content: \"x\"; } }"
+        ".a { @include after { content: \"x\"; } }",
+        ".a { @include after(var(--label)) { color: red; } }",
+        ".a { @include after(attr(data-label)) { color: red; } }"
       ],
       "rejects": [
         ".a { @include after(42) { color: red; } }",
@@ -100,6 +106,8 @@
             "invalid",
             "required",
             "disabled",
+            "focus-visible",
+            "user-invalid",
             "null for the plain state"
           ]
         }
@@ -109,7 +117,9 @@
       "summary": "Targets every text-like input at once, optionally in one pseudo-class state.",
       "examples": [
         "@include all-text-inputs { border: 1px solid; }",
-        "@include all-text-inputs(\"focus\") { outline: 2px solid; }"
+        "@include all-text-inputs(\"focus\") { outline: 2px solid; }",
+        "@include all-text-inputs(\"focus-visible\") { outline: 2px solid; }",
+        "@include all-text-inputs(\"user-invalid\") { border-color: crimson; }"
       ],
       "rejects": [
         "@include all-text-inputs(nonsense) { color: red; }"
@@ -151,7 +161,8 @@
             "a slash separated string, such as \"16/9\"",
             "a colon separated string, such as \"16:9\"",
             "a number, where 1.5 means 1.5 / 1",
-            "null for the 16/9 default"
+            "null for the 16/9 default",
+            "var(), written as it is"
           ]
         },
         {
@@ -170,17 +181,22 @@
       "file": "scss/library/_aspect-ratio.scss",
       "signature": "aspect-ratio($ratio: null, $fit: cover)",
       "summary": "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.",
+      "caveats": [
+        "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."
+      ],
       "examples": [
         ".thumb { @include aspect-ratio(\"16:9\"); }",
         ".video { @include aspect-ratio(\"16/9\"); }",
         ".tile { @include aspect-ratio(\"1:1\", contain); }",
         ".plain { @include aspect-ratio(1.5, null); }",
-        ".default { @include aspect-ratio; }"
+        ".default { @include aspect-ratio; }",
+        ".a { @include aspect-ratio(var(--ratio)); }"
       ],
       "rejects": [
         ".thumb { @include aspect-ratio(\"16:9\", nonsense); }",
         ".thumb { @include aspect-ratio(16 9); }",
-        ".thumb { @include aspect-ratio(\"sixteen/nine\"); }"
+        ".thumb { @include aspect-ratio(\"sixteen/nine\"); }",
+        ".a { @include aspect-ratio(url(a.png)); }"
       ]
     },
     {
@@ -199,14 +215,15 @@
           "name": "$size",
           "default": "1em",
           "accepts": [
-            "dot radius"
+            "dot radius: a length, or var(), env() or a calculation such as calc() or clamp()"
           ]
         },
         {
           "name": "$gutter",
-          "default": "$size * 5",
+          "default": "null",
           "accepts": [
-            "spacing between dots"
+            "spacing between dots, in the same forms as $size",
+            "null, the default, for five times $size"
           ]
         },
         {
@@ -221,21 +238,27 @@
           "name": "$image",
           "default": "null",
           "accepts": [
-            "an image path to sit behind the dots"
+            "an image path to sit behind the dots",
+            "var(), url(), image-set() or a gradient, written as they are rather than wrapped in url()"
           ]
         }
       ],
       "file": "scss/library/_background-dots.scss",
-      "signature": "background-dots($color: null, $size: 1em, $gutter: $size * 5, $diagonal: true, $image: null)",
+      "signature": "background-dots($color: null, $size: 1em, $gutter: null, $diagonal: true, $image: null)",
       "summary": "Repeating dot pattern as a background, optionally over an image.",
       "examples": [
         ".a { @include background-dots; }",
         ".a { @include background-dots(red); }",
-        ".a { @include background-dots(red, 1em, 5em, false); }"
+        ".a { @include background-dots(red, 1em, 5em, false); }",
+        ".a { @include background-dots(red, var(--dot), calc(var(--dot) * 6)); }",
+        ".a { @include background-dots(red, clamp(2px, 0.5vw, 6px)); }",
+        ".a { @include background-dots(red, $image: var(--photo)); }"
       ],
       "rejects": [
         ".a { @include background-dots(red, 1em, 5em, maybe); }",
-        ".a { @include background-dots(red, 1em, 5em, true, 42); }"
+        ".a { @include background-dots(red, 1em, 5em, true, 42); }",
+        ".a { @include background-dots(red, nonsense); }",
+        ".a { @include background-dots(red, 1em, nonsense); }"
       ]
     },
     {
@@ -247,7 +270,8 @@
           "default": "null",
           "accepts": [
             "an image path",
-            "null to filter the element itself instead"
+            "null to filter the element itself instead",
+            "var(), url(), image-set() or a gradient, written as they are rather than wrapped in url()"
           ]
         },
         {
@@ -272,10 +296,14 @@
       "examples": [
         ".a { @include background-image(\"/img/a.png\"); }",
         ".a { @include background-image(\"/img/a.png\", rgba(0,0,0,0.5)); }",
-        ".a { @include background-image(\"/img/a.png\", (red, blue), \"top\"); }"
+        ".a { @include background-image(\"/img/a.png\", (red, blue), \"top\"); }",
+        ".a { @include background-image(var(--hero), rgba(0,0,0,0.5)); }",
+        ".a { @include background-image(image-set(\"/img/a.png\" 1x, \"/img/a@2x.png\" 2x)); }"
       ],
       "rejects": [
-        ".a { @include background-image(\"/img/a.png\", (red, blue), sideways); }"
+        ".a { @include background-image(\"/img/a.png\", (red, blue), sideways); }",
+        ".a { @include background-image(\"/img/a.png\", rgba(0,0,0,0.5), sideways); }",
+        ".a { @include background-image(null, rgba(0,0,0,0.5), sideways); }"
       ]
     },
     {
@@ -294,7 +322,7 @@
           "name": "$thickness",
           "default": "1em",
           "accepts": [
-            "stripe thickness"
+            "stripe thickness: a length, or var(), env() or a calculation such as calc() or clamp()"
           ]
         },
         {
@@ -308,7 +336,8 @@
           "name": "$image",
           "default": "null",
           "accepts": [
-            "an image path to sit behind the stripes"
+            "an image path to sit behind the stripes",
+            "var(), url(), image-set() or a gradient, written as they are rather than wrapped in url()"
           ]
         }
       ],
@@ -317,11 +346,14 @@
       "summary": "Repeating stripe pattern as a background, optionally over an image.",
       "examples": [
         ".a { @include background-stripes; }",
-        ".a { @include background-stripes(red, 2em, -30deg); }"
+        ".a { @include background-stripes(red, 2em, -30deg); }",
+        ".a { @include background-stripes(red blue, var(--stripe)); }",
+        ".a { @include background-stripes(red, 2em, -30deg, var(--photo)); }"
       ],
       "rejects": [
         ".a { @include background-stripes(red, 2em, nonsense); }",
-        ".a { @include background-stripes(red, 2em, -45deg, 42); }"
+        ".a { @include background-stripes(red, 2em, -45deg, 42); }",
+        ".a { @include background-stripes(red, nonsense); }"
       ]
     },
     {
@@ -334,16 +366,21 @@
           "accepts": [
             "a string used as the content value",
             "a data- attribute name, rendered as attr()",
-            "null to write content yourself"
+            "null to write content yourself",
+            "var(), attr(), counter() or counters(), written as they are"
           ]
         }
       ],
       "file": "scss/library/_before.scss",
       "signature": "before($content: null)",
       "summary": "Styles the ::before pseudo-element. A `data-` argument becomes an attr() content value.",
+      "caveats": [
+        "With no argument no `content` is emitted, so the pseudo-element does not render unless the block sets `content`. Pass `\"\"` for an empty one."
+      ],
       "examples": [
         ".a { @include before(\"→\") { color: red; } }",
-        ".a { @include before(\"data-label\") { color: red; } }"
+        ".a { @include before(\"data-label\") { color: red; } }",
+        ".a { @include before(var(--label)) { color: red; } }"
       ],
       "rejects": [
         ".a { @include before(42) { color: red; } }"
@@ -384,6 +421,7 @@
           "accepts": [
             "one length for every corner",
             "a corner name plus a length",
+            "a logical corner or edge plus a length: start-start, start-end, end-start, end-end, inline-start, inline-end, block-start or block-end",
             "four lengths: top-left, top-right, bottom-right, bottom-left"
           ]
         }
@@ -394,7 +432,9 @@
       "examples": [
         ".a { @include border-radius(8px); }",
         ".a { @include border-radius(\"top\", 8px); }",
-        ".a { @include border-radius(1px, 2px, 3px, 4px); }"
+        ".a { @include border-radius(1px, 2px, 3px, 4px); }",
+        ".tab { @include border-radius(\"inline-start\", 8px); }",
+        ".bubble { @include border-radius(\"end-end\", 12px); }"
       ],
       "rejects": [
         ".a { @include border-radius(1px, 2px, 3px); }",
@@ -423,7 +463,8 @@
           "name": "$image-url",
           "default": "null",
           "accepts": [
-            "an image path"
+            "an image path",
+            "var(), url(), image-set() or a gradient, written as they are rather than wrapped in url()"
           ]
         }
       ],
@@ -431,7 +472,8 @@
       "signature": "brand-logo($width, $height, $image-url: null)",
       "summary": "Logo box with an image and an accessible stretched link over it.",
       "examples": [
-        ".logo { @include brand-logo(120px, 40px, \"/img/logo.svg\"); }"
+        ".logo { @include brand-logo(120px, 40px, \"/img/logo.svg\"); }",
+        ".logo { @include brand-logo(120px, 40px, var(--logo)); }"
       ],
       "rejects": []
     },
@@ -443,7 +485,8 @@
           "name": "$params",
           "variadic": true,
           "accepts": [
-            "one breakpoint name, for exactly that width",
+            "one breakpoint name, for exactly that width, which prints a warning: write only instead",
+            "only plus a breakpoint, for exactly that width",
             "min or max plus a breakpoint",
             "between plus two breakpoints",
             "a start and an end value"
@@ -453,12 +496,24 @@
       "file": "scss/library/_breakpoint.scss",
       "signature": "breakpoint($params...)",
       "summary": "Media query built from the breakpoint map, or from raw lengths.",
+      "caveats": [
+        "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. 3.0.0 will refuse the one-argument form.",
+        "Declarations written after the include, in the same rule, are emitted after the `@media` block and win over it. Write them before the include."
+      ],
       "examples": [
-        ".a { @include breakpoint(\"medium\") { color: red; } }",
+        ".a { @include breakpoint(\"only\", \"medium\") { color: red; } }",
         ".a { @include breakpoint(\"min\", \"medium\") { color: red; } }",
         ".a { @include breakpoint(\"between\", \"medium\" \"large\") { color: red; } }"
       ],
-      "rejects": []
+      "rejects": [
+        ".a { @include breakpoint(\"between\", \"medium\", \"large\") { color: red; } }",
+        ".a { @include breakpoint() { color: red; } }",
+        ".a { @include breakpoint(\"min\", var(--wide)) { color: red; } }",
+        ".a { @include breakpoint(\"between\", var(--start) \"large\") { color: red; } }"
+      ],
+      "warns": [
+        ".a { @include breakpoint(\"medium\") { color: red; } }"
+      ]
     },
     {
       "name": "breakpointer",
@@ -579,7 +634,7 @@
           "name": "$params",
           "variadic": true,
           "accepts": [
-            "a size",
+            "a size, for exactly that width, which prints a warning: write only instead",
             "two sizes for a range",
             "one of min, max, only or between followed by a size",
             "$name as a keyword, to query one named container"
@@ -589,9 +644,13 @@
       "file": "scss/library/_container-query.scss",
       "signature": "container-query($params...)",
       "summary": "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.",
+      "caveats": [
+        "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. 3.0.0 will refuse the one-argument form."
+      ],
       "examples": [
         ".title { @include container-query(\"min\", 400px) { font-size: 2rem; } }",
         ".title { @include container-query(\"max\", 399px) { font-size: 1rem; } }",
+        ".title { @include container-query(\"only\", 400px) { color: red; } }",
         ".title { @include container-query(\"between\", 300px 500px) { color: red; } }",
         ".title { @include container-query(300px, 500px) { color: red; } }",
         ".title { @include container-query(\"min\", \"medium\") { color: red; } }",
@@ -599,7 +658,16 @@
       ],
       "rejects": [
         ".title { @include container-query(\"min\", 400px, 800px) { color: red; } }",
-        ".title { @include container-query(\"min\", 400px, $name: 42) { color: red; } }"
+        ".title { @include container-query(\"min\", 400px, $name: 42) { color: red; } }",
+        ".title { @include container-query(\"min\", var(--wide)) { color: red; } }",
+        ".title { @include container-query(\"min\", 400px, $name: var(--container)) { color: red; } }",
+        ".title { @include container-query(\"min\", 400px, $name: \"none\") { color: red; } }",
+        ".title { @include container-query(\"min\", 400px, $name: \"not\") { color: red; } }",
+        ".title { @include container-query(\"min\", 400px, $name: \"my card\") { color: red; } }",
+        ".title { @include container-query(\"min\", 400px, $name: \"1card\") { color: red; } }"
+      ],
+      "warns": [
+        ".title { @include container-query(400px) { color: red; } }"
       ]
     },
     {
@@ -627,6 +695,9 @@
       "file": "scss/library/_container.scss",
       "signature": "container($name: null, $type: inline-size)",
       "summary": "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.",
+      "caveats": [
+        "An element does not match a `@container` query that reads its own container, and nothing warns. Put the `container-query` on a descendant."
+      ],
       "examples": [
         ".card { @include container(\"card\"); }",
         ".panel { @include container; }",
@@ -647,17 +718,22 @@
           "accepts": [
             "a counter style name",
             "a prefix and/or suffix string",
-            "a prefix, a counter style and a suffix"
+            "a prefix, a counter style and a suffix",
+            "var(), attr(), counter() or counters() in place of a prefix or suffix, written as they are"
           ]
         }
       ],
       "file": "scss/library/_counter.scss",
       "signature": "counter($params...)",
       "summary": "CSS counter for a list, with optional text before and after the number.",
+      "caveats": [
+        "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."
+      ],
       "examples": [
         ".list { @include counter(\"decimal\"); }",
         ".list { @include counter(\".\"); }",
-        ".list { @include counter(\"(\", \"decimal\", \")\"); }"
+        ".list { @include counter(\"(\", \"decimal\", \")\"); }",
+        ".list { @include counter(var(--prefix), \"decimal\"); }"
       ],
       "rejects": []
     },
@@ -738,6 +814,43 @@
         ".a { @include except(#ff0000) { margin: 0; } }"
       ]
     },
+    {
+      "name": "focus-ring",
+      "kind": "mixin",
+      "arguments": [
+        {
+          "name": "$width",
+          "default": "2px",
+          "accepts": [
+            "an outline width, such as 2px"
+          ]
+        },
+        {
+          "name": "$offset",
+          "default": "2px",
+          "accepts": [
+            "a length; negative draws the ring inside the element"
+          ]
+        },
+        {
+          "name": "$color",
+          "default": "currentColor",
+          "accepts": [
+            "any CSS colour, including currentColor and var()"
+          ]
+        }
+      ],
+      "file": "scss/library/_focus-ring.scss",
+      "signature": "focus-ring($width: 2px, $offset: 2px, $color: currentColor)",
+      "summary": "Draws a keyboard focus ring with outline on :focus-visible, which survives forced-colors mode where a box-shadow ring disappears.",
+      "examples": [
+        ".button { @include focus-ring; }",
+        ".card-link { @include focus-ring(3px, 4px, var(--focus)); }"
+      ],
+      "rejects": [
+        "@include focus-ring;"
+      ]
+    },
     {
       "name": "font-face",
       "kind": "mixin",
@@ -776,19 +889,39 @@
           "accepts": [
             "any of eot, woff2, woff, ttf, svg"
           ]
+        },
+        {
+          "name": "$font-display",
+          "default": "null",
+          "accepts": [
+            "auto, block, swap, fallback or optional",
+            "null, the default, to leave font-display out"
+          ]
         }
       ],
       "file": "scss/library/_font-face.scss",
-      "signature": "font-face($font-family, $file-path, $font-style: normal, $font-weight: 400, $file-formats: eot woff2 woff ttf svg)",
+      "signature": "font-face($font-family, $file-path, $font-style: normal, $font-weight: 400, $file-formats: eot woff2 woff ttf svg, $font-display: null)",
       "summary": "Emits an @font-face rule for one family across several file formats. Must be called at the root.",
       "examples": [
         "@include font-face(\"Inter\", \"/fonts/inter\");",
-        "@include font-face(\"Inter\", \"/fonts/inter\", italic, 700, woff2 woff);"
+        "@include font-face(\"Inter\", \"/fonts/inter\", italic, 700, woff2 woff);",
+        "@include font-face(\"Readex Pro\", \"/fonts/readex\", $font-weight: 160 700, $file-formats: woff2, $font-display: swap);",
+        "@include font-face(\"Inter\", \"/fonts/inter\", \"italic\", $font-weight: \"bold\", $file-formats: woff2);"
       ],
       "rejects": [
         ".a { @include font-face(\"Inter\", \"/fonts/inter\"); }",
         "@include font-face(42, \"/fonts/x\");",
-        "@include font-face(\"Inter\", 42);"
+        "@include font-face(\"Inter\", 42);",
+        "@include font-face(\"Inter\", \"/fonts/inter\", $file-formats: otf);",
+        "@include font-face(\"Inter\", \"/fonts/inter\", $file-formats: woff2 wof);",
+        "@include font-face(\"Inter\", \"/fonts/inter\", $file-formats: null);",
+        "@include font-face(\"Inter\", var(--font-path));",
+        "@include font-face(\"Inter\", \"/fonts/inter\", $file-formats: woff2, $font-display: fast);",
+        "@include font-face(\"Inter\", \"/fonts/inter\", $file-formats: woff2, $font-display: var(--display));",
+        "@include font-face(var(--font-family), \"/fonts/inter\", $file-formats: woff2);",
+        "@include font-face(\"Inter\", \"/fonts/inter\", var(--font-style), $file-formats: woff2);",
+        "@include font-face(\"Inter\", \"/fonts/inter\", $font-weight: var(--font-weight), $file-formats: woff2);",
+        "@include font-face(\"Inter\", \"/fonts/inter\", $font-weight: 100 var(--max-weight), $file-formats: woff2);"
       ]
     },
     {
@@ -824,7 +957,8 @@
           "default": "3",
           "accepts": [
             "a whole number of lines, at least 1",
-            "none, to undo a clamp"
+            "none, to undo a clamp",
+            "var(), written as it is"
           ]
         }
       ],
@@ -835,13 +969,15 @@
         ".excerpt { @include line-clamp(3); }",
         ".title { @include line-clamp(2); }",
         ".full { @include line-clamp(none); }",
-        ".default { @include line-clamp; }"
+        ".default { @include line-clamp; }",
+        ".a { @include line-clamp(var(--lines)); }"
       ],
       "rejects": [
         ".a { @include line-clamp(0); }",
         ".a { @include line-clamp(2.5); }",
         ".a { @include line-clamp(3px); }",
-        ".a { @include line-clamp(\"three\"); }"
+        ".a { @include line-clamp(\"three\"); }",
+        ".a { @include line-clamp(url(a.png)); }"
       ]
     },
     {
@@ -892,6 +1028,9 @@
       "file": "scss/library/_loadify.scss",
       "signature": "loadify($params...)",
       "summary": "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.",
+      "caveats": [
+        "`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\"."
+      ],
       "examples": [
         "@include loadify(init);\n.a { @include loadify; }",
         "@include loadify;\n.a { @include loadify(0.4s, 1s); }"
@@ -900,6 +1039,24 @@
         "@include loadify(nonsense);"
       ]
     },
+    {
+      "name": "motion-safe",
+      "kind": "mixin",
+      "arguments": [],
+      "file": "scss/library/_motion-safe.scss",
+      "signature": "motion-safe",
+      "summary": "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.",
+      "caveats": [
+        "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."
+      ],
+      "examples": [
+        ".card { @include motion-safe { transition: transform 0.2s ease; } }",
+        "@include motion-safe { .spinner { animation: spin 1s linear infinite; } }"
+      ],
+      "rejects": [
+        ".card { @include motion-safe; }"
+      ]
+    },
     {
       "name": "only",
       "kind": "mixin",
@@ -966,7 +1123,8 @@
           "name": "$offsets",
           "default": "0",
           "accepts": [
-            "one to four lengths in shorthand order, or auto/inherit/initial/0"
+            "one to four lengths in shorthand order, or auto/inherit/initial/0",
+            "null in any position to leave that edge out"
           ]
         }
       ],
@@ -975,7 +1133,9 @@
       "summary": "Sets position and offsets in one call, using shorthand order.",
       "examples": [
         ".a { @include position(absolute, 0); }",
-        ".a { @include position(fixed, 0 10px); }"
+        ".a { @include position(fixed, 0 10px); }",
+        ".a { @include position(absolute, null 16px 16px 16px); }",
+        ".a { @include position(absolute, 0 null null 0); }"
       ],
       "rejects": []
     },
@@ -1026,7 +1186,8 @@
           "variadic": true,
           "accepts": [
             "nothing, to hide it always",
-            "one breakpoint",
+            "one breakpoint, for exactly that width and no other, which prints a warning: write only instead",
+            "only plus a breakpoint, for exactly that width",
             "min or max plus a breakpoint",
             "a start and an end breakpoint"
           ]
@@ -1034,14 +1195,24 @@
       ],
       "file": "scss/library/_remove.scss",
       "signature": "remove($params...)",
-      "summary": "Hides an element outright, or only within a breakpoint range.",
+      "summary": "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.",
+      "caveats": [
+        "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. 3.0.0 will refuse the one-argument form.",
+        "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."
+      ],
       "examples": [
         ".a { @include remove; }",
-        ".a { @include remove(\"medium\"); }",
-        ".a { @include remove(\"min\", \"medium\"); }"
+        ".a { @include remove(\"min\", \"medium\"); }",
+        ".a { @include remove(\"max\", \"medium\"); }",
+        ".a { @include remove(\"only\", \"medium\"); }",
+        ".a { @include remove(\"small\", \"large\"); }"
       ],
       "rejects": [
-        ".a { @include remove(a, b, c); }"
+        ".a { @include remove(a, b, c); }",
+        ".a { @include remove(\"max\", var(--narrow)); }"
+      ],
+      "warns": [
+        ".a { @include remove(\"medium\"); }"
       ]
     },
     {
@@ -1154,7 +1325,9 @@
       "examples": [
         ".a { @include screen-agent(\"2x\") { background-image: url(\"/img/a@2x.png\"); } }"
       ],
-      "rejects": []
+      "rejects": [
+        ".a { @include screen-agent(var(--density)) { color: red; } }"
+      ]
     },
     {
       "name": "sizer",
@@ -1337,7 +1510,8 @@
           "name": "$image",
           "default": "null",
           "accepts": [
-            "an image path"
+            "an image path",
+            "var(), url(), image-set() or a gradient, written as they are rather than wrapped in url()"
           ]
         }
       ],
@@ -1345,7 +1519,8 @@
       "signature": "text-image($image: null)",
       "summary": "Fills the text with an image via background-clip.",
       "examples": [
-        ".a { @include text-image(\"/img/t.png\"); }"
+        ".a { @include text-image(\"/img/t.png\"); }",
+        ".a { @include text-image(var(--texture)); }"
       ],
       "rejects": []
     },
@@ -1438,6 +1613,48 @@
       ],
       "rejects": []
     },
+    {
+      "name": "tokens",
+      "kind": "mixin",
+      "arguments": [
+        {
+          "name": "$map",
+          "required": true,
+          "accepts": [
+            "a map of names to values, where a value is any CSS value: a colour, a length, a font stack, a shadow, a duration, calc() or clamp()",
+            "a value of null, which is skipped",
+            "a value that references another token, such as var(--blue-500)"
+          ]
+        },
+        {
+          "name": "$prefix",
+          "default": "null",
+          "accepts": [
+            "null, the default, for no prefix",
+            "a name, joined to each property name with a hyphen"
+          ]
+        }
+      ],
+      "file": "scss/library/_tokens.scss",
+      "signature": "tokens($map, $prefix: null)",
+      "summary": "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.",
+      "examples": [
+        ":root { @include tokens((1: 0.25rem, 2: 0.5rem, 4: 1rem), space); @include tokens((md: 8px, full: 9999px), radius); }",
+        ":root { @include tokens((md: 0 4px 12px rgba(24, 24, 27, 0.08)), shadow); @include tokens((fast: 150ms, ease: cubic-bezier(0.2, 0, 0, 1)), motion); }",
+        ":root { @include tokens((bg: #fff, text: #111), color); }",
+        ":root { @include tokens((blue-500: #3b82f6, blue-600: #2563eb)); }",
+        ":root { @include tokens((red: #ef4444, 500: #3b82f6), blue); }",
+        "[data-theme=\"dark\"] { @include tokens((bg: #09090b, accent: var(--blue-500)), color); }",
+        ":root { @include tokens((body: (\"Readex Pro\", sans-serif), label: \"New\", focus: null), font); }"
+      ],
+      "rejects": [
+        ":root { @include tokens(#fff); }",
+        ":root { @include tokens((brand: (500: #3b82f6)), color); }",
+        ":root { @include tokens((bg: #fff), (color, text)); }",
+        ":root { @include tokens((\"brand color\": #f00)); }",
+        "@include tokens((bg: #fff));"
+      ]
+    },
     {
       "name": "triangle",
       "kind": "mixin",
@@ -1453,21 +1670,25 @@
             "bottom",
             "bottom-left",
             "left",
-            "top-left"
+            "top-left",
+            "inline-start, inline-end, block-start or block-end, which follow the writing direction"
           ]
         },
         {
           "name": "$color",
           "default": "black",
           "accepts": [
-            "any colour value"
+            "a Sass colour, such as red, #333 or oklch(70% 0.1 200)",
+            "currentColor",
+            "var(), color-mix() or light-dark(), which CSS resolves"
           ]
         },
         {
           "name": "$size",
           "default": "10px 8px",
           "accepts": [
-            "one length, or two lengths as width then height"
+            "one length, or two lengths as width then height",
+            "var(), env() or a calculation in place of any length"
           ]
         }
       ],
@@ -1476,11 +1697,19 @@
       "summary": "Draws a CSS triangle out of borders, pointing in a given direction.",
       "examples": [
         ".caret { @include triangle(\"bottom\", black, 10px 8px); }",
-        ".arrow { @include triangle(\"left\", red); }"
+        ".arrow { @include triangle(\"left\", red); }",
+        ".arrow { @include triangle(\"right\", var(--accent), 6px 8px); }",
+        ".arrow { @include triangle(\"right\", currentColor); }",
+        ".arrow { @include triangle(\"top\", color-mix(in srgb, red 50%, blue)); }",
+        ".arrow { @include triangle(\"bottom\", currentColor, var(--caret-w) var(--caret-h)); }",
+        ".next { @include triangle(\"inline-end\", currentColor, 8px 12px); }",
+        ".sort { @include triangle(\"block-start\", currentColor); }"
       ],
       "rejects": [
         ".caret { @include triangle(sideways); }",
-        ".caret { @include triangle(\"top\", notacolor); }"
+        ".caret { @include triangle(\"top\", notacolor); }",
+        ".caret { @include triangle(\"top\", url(a.png)); }",
+        ".caret { @include triangle(\"top\", red, nonsense); }"
       ]
     },
     {
@@ -1501,7 +1730,9 @@
       "examples": [
         ".a { line-height: clearUnit(24px); }"
       ],
-      "rejects": []
+      "rejects": [
+        ".a { line-height: clearUnit(nonsense); }"
+      ]
     },
     {
       "name": "clearWhitespace",
@@ -1543,7 +1774,10 @@
       "examples": [
         ".a { margin: convertToEm(24px); }"
       ],
-      "rejects": []
+      "rejects": [
+        ".a { margin: convertToEm(nonsense); }",
+        ".a { margin: convertToEm(24); }"
+      ]
     },
     {
       "name": "convertToNumber",
@@ -1564,7 +1798,9 @@
         ".a { z-index: convertToNumber(\"42\"); }"
       ],
       "rejects": [
-        ".a { --x: #{convertToNumber(42)}; }"
+        ".a { --x: #{convertToNumber(42)}; }",
+        ".a { z-index: convertToNumber(\"4a\"); }",
+        ".a { z-index: convertToNumber(\"\"); }"
       ]
     },
     {
@@ -1678,7 +1914,10 @@
       "examples": [
         ".a { font-size: fontSizer(16px, 1.5); }"
       ],
-      "rejects": []
+      "rejects": [
+        ".a { font-size: fontSizer(nonsense, 1.5); }",
+        ".a { font-size: fontSizer(16px, 1px); }"
+      ]
     },
     {
       "name": "fontSource",
@@ -1893,7 +2132,11 @@
       "examples": [
         ".a { font-size: remify(24px); }"
       ],
-      "rejects": []
+      "rejects": [
+        ".a { font-size: remify(nonsense); }",
+        ".a { font-size: remify(1.5rem); }",
+        ".a { font-size: remify(24); }"
+      ]
     },
     {
       "name": "shade",
@@ -1921,7 +2164,8 @@
         ".a { color: shade(red, 20%); }"
       ],
       "rejects": [
-        ".a { color: shade(notacolor, 20%); }"
+        ".a { color: shade(notacolor, 20%); }",
+        ".a { color: shade(var(--x), 20%); }"
       ]
     },
     {
@@ -1972,7 +2216,8 @@
         ".a { color: tint(red, 20%); }"
       ],
       "rejects": [
-        ".a { color: tint(notacolor, 20%); }"
+        ".a { color: tint(notacolor, 20%); }",
+        ".a { color: tint(var(--x), 20%); }"
       ]
     },
     {
@@ -2003,13 +2248,14 @@
           "name": "$value",
           "required": true,
           "accepts": [
-            "a length with a unit, or auto, inherit, initial, 0"
+            "a length with a unit, or auto, inherit, initial, 0",
+            "null, returned as null without a warning"
           ]
         }
       ],
       "file": "scss/utilities/_validate-length.scss",
       "signature": "validateLength($value)",
-      "summary": "Returns the value if it is a length or one of auto, inherit, initial, 0.",
+      "summary": "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.",
       "examples": [
         ".a { width: validateLength(20px); }"
       ],
@@ -2025,7 +2271,8 @@
           "accepts": [
             "a string such as \"16/9\" or \"16:9\"",
             "a unitless number",
-            "null for the 16/9 default"
+            "null for the 16/9 default",
+            "var(), returned as it is"
           ]
         }
       ],
@@ -2034,10 +2281,12 @@
       "summary": "Turns an aspect ratio into a value for the CSS aspect-ratio property.",
       "examples": [
         ".a { aspect-ratio: validateRatio(\"16/9\"); }",
-        ".a { aspect-ratio: validateRatio(1.5); }"
+        ".a { aspect-ratio: validateRatio(1.5); }",
+        ".a { aspect-ratio: validateRatio(var(--ratio)); }"
       ],
       "rejects": [
-        ".a { aspect-ratio: validateRatio(16 9); }"
+        ".a { aspect-ratio: validateRatio(16 9); }",
+        ".a { aspect-ratio: validateRatio(\"16 / 9\"); }"
       ]
     },
     {