gerillass 2.2.1 → 2.3.1

package/package.json

@@ -16,7 +16,7 @@
     }
   },
   "license": "Apache-2.0",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/selfishprimate/gerillass.git"

package/scss/internal/_color-problem.scss

@@ -0,0 +1,99 @@
+@charset "UTF-8";
+
+@use "sass:list";
+@use "sass:meta";
+@use "sass:string";
+
+// Shared by the mixins and not public API; see _is-css-function.scss.
+
+// What a browser keeps as a colour, measured in Chrome 152 in `color`,
+// `-webkit-text-stroke-color`, `outline: 2px solid ...`, `background` and a
+// gradient's colour stop:
+//
+// - kept: a colour Sass knows (red, #333, rgba(), hsl(), oklch(), color()),
+//   currentColor in any case, every system colour, deprecated ones included
+//   (Canvas, AccentColor, ActiveBorder), a vendor colour such as -webkit-link,
+//   var() and env(), and the colour functions Sass leaves as text: rgb() with
+//   var() in it, rgb(from ...), color-mix(), light-dark() and contrast-color();
+// - dropped: a word that is none of those (huge, auto, none), a quoted colour,
+//   a length, a number, calc(), and two colours side by side;
+// - CSS-wide keywords were kept in a declaration of their own and dropped inside
+//   `outline` and inside a gradient, so $css-wide says which this is.
+//
+// device-cmyk() is in the specification and Chrome drops it; it is let through,
+// as `run-in` is for display, because refusing it would refuse valid CSS once a
+// browser ships it.
+//
+// Deliberately looser than isColor, which stays strict because tint and shade
+// pass its result to color.mix, and that needs a real Sass colour.
+$-system-colors: "canvas" "canvastext" "linktext" "visitedtext" "activetext" "buttonface" "buttontext" "buttonborder" "field" "fieldtext" "highlight" "highlighttext" "selecteditem" "selecteditemtext" "mark" "marktext" "graytext" "accentcolor" "accentcolortext" "activeborder" "activecaption" "appworkspace" "background" "buttonhighlight" "buttonshadow" "captiontext" "inactiveborder" "inactivecaption" "inactivecaptiontext" "infobackground" "infotext" "menu" "menutext" "scrollbar" "threeddarkshadow" "threedface" "threedhighlight" "threedlightshadow" "threedshadow" "window" "windowframe" "windowtext";
+$-functions: "var" "env" "attr" "rgb" "rgba" "hsl" "hsla" "hwb" "lab" "lch" "oklab" "oklch" "color" "color-mix" "light-dark" "contrast-color" "device-cmyk";
+$-css-wide: "inherit" "initial" "unset" "revert" "revert-layer";
+
+// The CSS named colours and transparent, for a colour that reaches the check as
+// an unquoted string rather than as a Sass colour.
+$-named-colors: "transparent" "aliceblue" "antiquewhite" "aqua" "aquamarine" "azure" "beige" "bisque" "black" "blanchedalmond" "blue" "blueviolet" "brown" "burlywood" "cadetblue" "chartreuse" "chocolate" "coral" "cornflowerblue" "cornsilk" "crimson" "cyan" "darkblue" "darkcyan" "darkgoldenrod" "darkgray" "darkgreen" "darkgrey" "darkkhaki" "darkmagenta" "darkolivegreen" "darkorange" "darkorchid" "darkred" "darksalmon" "darkseagreen" "darkslateblue" "darkslategray" "darkslategrey" "darkturquoise" "darkviolet" "deeppink" "deepskyblue" "dimgray" "dimgrey" "dodgerblue" "firebrick" "floralwhite" "forestgreen" "fuchsia" "gainsboro" "ghostwhite" "gold" "goldenrod" "gray" "green" "greenyellow" "grey" "honeydew" "hotpink" "indianred" "indigo" "ivory" "khaki" "lavender" "lavenderblush" "lawngreen" "lemonchiffon" "lightblue" "lightcoral" "lightcyan" "lightgoldenrodyellow" "lightgray" "lightgreen" "lightgrey" "lightpink" "lightsalmon" "lightseagreen" "lightskyblue" "lightslategray" "lightslategrey" "lightsteelblue" "lightyellow" "lime" "limegreen" "linen" "magenta" "maroon" "mediumaquamarine" "mediumblue" "mediumorchid" "mediumpurple" "mediumseagreen" "mediumslateblue" "mediumspringgreen" "mediumturquoise" "mediumvioletred" "midnightblue" "mintcream" "mistyrose" "moccasin" "navajowhite" "navy" "oldlace" "olive" "olivedrab" "orange" "orangered" "orchid" "palegoldenrod" "palegreen" "paleturquoise" "palevioletred" "papayawhip" "peachpuff" "peru" "pink" "plum" "powderblue" "purple" "rebeccapurple" "red" "rosybrown" "royalblue" "saddlebrown" "salmon" "sandybrown" "seagreen" "seashell" "sienna" "silver" "skyblue" "slateblue" "slategray" "slategrey" "snow" "springgreen" "steelblue" "tan" "teal" "thistle" "tomato" "turquoise" "violet" "wheat" "white" "whitesmoke" "yellow" "yellowgreen";
+
+// A hex colour written as text: # and then 3, 4, 6 or 8 hex digits.
+@function -is-hex($text) {
+  @if string.index($text, "#") != 1 or not list.index(4 5 7 9, string.length($text)) {
+    @return false;
+  }
+  @for $i from 2 through string.length($text) {
+    @if not string.index("0123456789abcdef", string.slice($text, $i, $i)) {
+      @return false;
+    }
+  }
+  @return true;
+}
+
+// Returns what is wrong with $value as one colour, or null when a browser keeps
+// it. null itself is the caller's to decide, since it means a default in some
+// mixins and leaving a declaration out in others.
+@function colorProblem($value, $css-wide: false) {
+  @if meta.type-of($value) == "color" {
+    @return null;
+  }
+  @if meta.type-of($value) == "list" and list.length($value) > 1 {
+    @return "it is several values where one colour is meant";
+  }
+  @if meta.type-of($value) != "string" {
+    @return "it is not a colour";
+  }
+  @if string.slice(meta.inspect($value), 1, 1) == "\"" {
+    @return "a colour in quotes is text, not a colour";
+  }
+  $lower: string.to-lower-case($value);
+  $open: string.index($lower, "(");
+  @if $open {
+    @if list.index($-functions, string.slice($lower, 1, $open - 1)) {
+      @return null;
+    }
+    @return "`#{string.slice($value, 1, $open - 1)}()` is not a colour function";
+  }
+  @if $lower == "currentcolor" or list.index($-system-colors, $lower) {
+    @return null;
+  }
+  // Interpolation, such as `#{$name}` or `#{$hex}`, gives an unquoted string
+  // rather than a colour, and it is written into the CSS as it reads, so a
+  // named or hex colour in one works exactly as the colour itself does.
+  @if list.index($-named-colors, $lower) or -is-hex($lower) {
+    @return null;
+  }
+  // Vendor colours are named rather than matched by prefix. Measured in Chrome
+  // 152, `-webkit-link` and `-webkit-activelink` were kept as colours while
+  // `-webkit-fill-available`, `-webkit-box` and `-webkit-text` were dropped, and
+  // the prefix rule this replaced had let those through. `-webkit-focus-ring-color`
+  // is Safari's, and `-moz-` colours are Firefox's; neither could be measured
+  // here, so they are let through rather than refused unseen.
+  @if list.index("-webkit-link" "-webkit-activelink" "-webkit-focus-ring-color", $lower) or string.index($lower, "-moz-") == 1 {
+    @return null;
+  }
+  @if list.index($-css-wide, $lower) {
+    @if $css-wide {
+      @return null;
+    }
+    @return "a CSS-wide keyword only works as a whole declaration, not inside this value";
+  }
+  @return "it is not a colour";
+}

package/scss/internal/_color-stops-problem.scss

@@ -0,0 +1,94 @@
+@charset "UTF-8";
+
+@use "sass:list";
+@use "sass:meta";
+@use "sass:string";
+@use "color-problem" as *;
+@use "is-condition-value" as *;
+
+// Shared by the mixins and not public API; see _is-css-function.scss.
+
+// Returns what is wrong with a list of gradient colour stops, or null. The items
+// are read the way the mixins write them, one per comma in the gradient.
+// Measured in Chrome 152 in linear-gradient():
+//
+// - kept: a colour on its own, even a single one (`linear-gradient(to top,
+//   red)`), a colour with one or two positions (`red 0 10%`), a position between
+//   two colours as a hint (`red, 30%, blue`), and var() as a whole stop;
+// - dropped: a position first or last, two positions in a row, a colour with
+//   three positions, a position that is not a length or a percentage
+//   (`red 10deg`), a colour and another colour in one stop (`red 10% blue`), and
+//   anything colorProblem refuses, CSS-wide keywords included.
+
+// True for a value a stop takes as a position: a length, a percentage, 0 or a
+// calculation.
+@function -is-position($value) {
+  @return isConditionValue($value, "length-percentage");
+}
+
+// True for var(), env() or attr(), which may stand for a whole stop or a list of
+// them, so nothing around it can be judged.
+@function -is-substitution($value) {
+  @if meta.type-of($value) != "string" or string.slice(meta.inspect($value), 1, 1) == "\"" {
+    @return false;
+  }
+  $lower: string.to-lower-case($value);
+  @return string.index($lower, "var(") == 1 or string.index($lower, "env(") == 1 or string.index($lower, "attr(") == 1;
+}
+
+@function colorStopsProblem($colors) {
+  @if $colors == null or list.length($colors) == 0 {
+    @return "a gradient needs at least one colour";
+  }
+  $count: list.length($colors);
+  $previous: null;
+  $colors-seen: 0;
+  @for $i from 1 through $count {
+    $item: list.nth($colors, $i);
+    $kind: null;
+    @if -is-substitution($item) {
+      $kind: "substitution";
+    } @else if meta.type-of($item) != "list" and -is-position($item) {
+      $kind: "hint";
+    } @else if meta.type-of($item) == "list" and list.length($item) > 1 {
+      $problem: colorProblem(list.nth($item, 1));
+      @if $problem {
+        @return "`#{meta.inspect($item)}` does not start with a colour: #{$problem}";
+      }
+      @if list.length($item) > 3 {
+        @return "`#{meta.inspect($item)}` has more than two positions, and a colour stop takes at most two";
+      }
+      @for $j from 2 through list.length($item) {
+        @if not -is-position(list.nth($item, $j)) and not -is-substitution(list.nth($item, $j)) {
+          @return "in `#{meta.inspect($item)}`, `#{meta.inspect(list.nth($item, $j))}` is not a position; a stop is a colour followed by up to two lengths or percentages";
+        }
+      }
+      $kind: "stop";
+    } @else {
+      $problem: colorProblem($item);
+      @if $problem {
+        @return "`#{meta.inspect($item)}` is not a colour stop: #{$problem}";
+      }
+      $kind: "stop";
+    }
+
+    @if $kind == "hint" {
+      @if $i == 1 {
+        @return "it starts with the position `#{meta.inspect($item)}`; a position on its own goes between two colours";
+      }
+      @if $i == $count {
+        @return "it ends with the position `#{meta.inspect($item)}`; a position on its own goes between two colours";
+      }
+      @if $previous == "hint" {
+        @return "it has two positions in a row; a position on its own goes between two colours";
+      }
+    } @else {
+      $colors-seen: $colors-seen + 1;
+    }
+    $previous: $kind;
+  }
+  @if $colors-seen == 0 {
+    @return "a gradient needs at least one colour";
+  }
+  @return null;
+}

package/scss/internal/_condition-width.scss

@@ -0,0 +1,22 @@
+@charset "UTF-8";
+
+@use "sass:meta";
+@use "../utilities/validate-breakpoint" as *;
+@use "is-condition-value" as *;
+
+// Shared by the mixins and not public API; see _is-css-function.scss.
+
+// Resolves a size for a width condition and refuses one no condition can match.
+// validateBreakpoint turns a key into its width and refuses a word that is not a
+// key; it passes a percentage or a bare number through, because a declaration
+// takes them. A width condition does not: `(min-width: 50%)` and
+// `(min-width: 768)` never matched in Chrome 152, so they are refused here.
+// Returns the same value validateBreakpoint does, so a call that worked writes
+// the same query.
+@function conditionWidth($value, $mixin, $at-rule: "@media") {
+  $width: validateBreakpoint($value);
+  @if not isConditionValue($width, "length") {
+    @error "`#{meta.inspect($value)}` cannot be used as a size in `#{$mixin}`: a width condition takes a length, and one written with `#{meta.inspect($width)}` would never match in #{$at-rule}. Pass a length such as `600px`, `40em` or `calc(30em + 1px)`, or a key from $map-for-breakpoints.";
+  }
+  @return $width;
+}

package/scss/internal/_custom-property-in.scss

@@ -0,0 +1,25 @@
+@charset "UTF-8";
+
+@use "sass:meta";
+@use "sass:string";
+
+// Shared by the mixins and not public API; see _is-css-function.scss.
+
+// Returns the first value in $value that holds var(), looking inside lists and
+// calculations, or null. Custom properties are not evaluated in a @media or
+// @container condition, so a rule built from one never applies, and nothing
+// warns. Measured in Chrome 152: `(min-width: var(--wide))` did not match with
+// `--wide: 200px`, while `(min-width: 200px)` did.
+@function customPropertyIn($value) {
+  @each $item in $value {
+    @if meta.type-of($item) == "list" or meta.type-of($item) == "arglist" {
+      $found: customPropertyIn($item);
+      @if $found {
+        @return $found;
+      }
+    } @else if string.index(meta.inspect($item), "var(") {
+      @return $item;
+    }
+  }
+  @return null;
+}

package/scss/internal/_image-value.scss

@@ -0,0 +1,68 @@
+@charset "UTF-8";
+
+@use "sass:meta";
+@use "sass:string";
+@use "is-css-function" as *;
+
+// Shared by the mixins and not public API; see _is-css-function.scss.
+
+// An image path goes into url(). A var(), url(), image-set() or gradient is
+// already an image, and wrapping it produced url(var(--x)), which loads nothing.
+//
+// $unquote is there because the copies this replaced differed:
+// background-dots and background-stripes wrote `url(a.png)`, the other three
+// `url("a.png")`. Both load the same file, and keeping each as it was means no
+// stylesheet changes.
+//
+// What it refuses, measured in Chrome 152:
+//
+// - a list where one image is meant: `url(16 9)` was dropped;
+// - a number, a colour or a boolean: `url(42)`, `url(#ff0000)` and `url(true)`
+//   are kept, but ask for a file named 42, a fragment of the page, or a file
+//   named true, which is never the image meant. background-dots and
+//   background-stripes refused these already.
+//
+// And an unquoted path is quoted when it has to be: `url(a b)`, `url(a(1).png)`
+// and `url(a'b.png)` were dropped, while the same paths in quotes were kept and
+// `url("a b")` resolved to `a%20b`. Every other path is written as before.
+@function imageValue($value, $mixin, $argument, $unquote: false) {
+  // paint(), image() and -webkit-cross-fade() were kept as images in Chrome
+  // 152 and used to be wrapped into url(paint(...)), which loads nothing;
+  // cross-fade(), element() and -moz-element() are in the specification or
+  // other engines.
+  @if isCssFunction($value, "var" "url" "image-set" "linear-gradient" "radial-gradient" "conic-gradient" "repeating-linear-gradient" "repeating-radial-gradient" "repeating-conic-gradient" "paint" "image" "cross-fade" "-webkit-cross-fade" "element" "-moz-element") {
+    @return $value;
+  }
+  @if meta.type-of($value) == "list" or meta.type-of($value) == "arglist" or meta.type-of($value) == "map" {
+    @error "`#{meta.inspect($value)}` is not a valid #{$argument} for `#{$mixin}`: it is a list where one image is meant, and a browser drops `url()` with a list in it. Pass one path as a string, such as `\"/img/hero.png\"`.";
+  }
+  @if meta.type-of($value) != "string" {
+    @error "`#{meta.inspect($value)}` is not a valid #{$argument} for `#{$mixin}`: an image path is a string, and `url(#{meta.inspect($value)})` asks for a file of that name, which is never the image. Pass a path as a string, such as `\"/img/hero.png\"`, or var() or a gradient.";
+  }
+  @if not $unquote {
+    @return url($value);
+  }
+  $text: string.unquote($value);
+  @if not (string.index($text, " ") or string.index($text, "(") or string.index($text, ")") or string.index($text, "'") or string.index($text, "\"")) {
+    @return url(string.unquote($value));
+  }
+  @if string.index($text, "\"") {
+    @return string.unquote("url('#{-escaped-single-quotes($text)}')");
+  }
+  @return string.unquote("url(\"#{$text}\")");
+}
+
+// A path holding a double quote goes into single quotes, so any single quote in
+// it is escaped.
+@function -escaped-single-quotes($text) {
+  $result: "";
+  @for $i from 1 through string.length($text) {
+    $character: string.slice($text, $i, $i);
+    @if $character == "'" {
+      $result: $result + "\\'";
+    } @else {
+      $result: $result + $character;
+    }
+  }
+  @return $result;
+}

package/scss/internal/_is-condition-value.scss

@@ -0,0 +1,94 @@
+@charset "UTF-8";
+
+@use "sass:list";
+@use "sass:math";
+@use "sass:meta";
+@use "sass:string";
+
+// Shared by the mixins and not public API; see _is-css-function.scss.
+
+// Every length unit a width condition kept in Chrome 152, in @media and
+// @container alike and in any case: `(min-width: 10PX)` matched. `x`, `dppx`,
+// `fr`, `s`, `%` and a made-up unit never matched, and neither did a unitless
+// number other than 0.
+$-length-units: "px" "cm" "mm" "q" "in" "pt" "pc" "em" "rem" "ex" "rex" "ch" "rch" "cap" "rcap" "ic" "ric" "lh" "rlh" "vw" "vh" "vi" "vb" "vmin" "vmax" "svw" "svh" "svi" "svb" "svmin" "svmax" "lvw" "lvh" "lvi" "lvb" "lvmin" "lvmax" "dvw" "dvh" "dvi" "dvb" "dvmin" "dvmax" "cqw" "cqh" "cqi" "cqb" "cqmin" "cqmax";
+
+// The units a resolution condition kept, also in any case. A unitless number, a
+// length and a negative resolution never matched; `0dppx` was kept.
+$-resolution-units: "dpi" "dpcm" "dppx" "x";
+
+// Angles, for an oblique `font-style`: `oblique 0.2rad` was kept in a @font-face
+// rule and `oblique 10`, unitless, was dropped.
+$-angle-units: "deg" "grad" "rad" "turn";
+
+// True for a value a @media or @container condition can match: a number in one
+// of the units above, a calculation, or either written as a quoted string, which
+// Sass writes into a condition without its quotes, so `breakpoint(min, "600px")`
+// has always worked. A calculation is taken on trust: `calc(30em + 1px)`,
+// `clamp()`, `min()` and `max()` were all kept, and Sass reduces `calc(10deg)`
+// to a number before it gets here, so that one is checked like any other.
+//
+// $kind is "length" or "resolution" for a condition. A negative length was
+// kept, since it is valid and simply matches every width or none; a negative
+// resolution was not. Two more kinds serve values outside a condition, where a
+// caller rules out a negative itself if the property does: "length-percentage",
+// a length or a percentage, and "angle".
+@function isConditionValue($value, $kind: "length") {
+  $units: $-length-units;
+  @if $kind == "resolution" {
+    $units: $-resolution-units;
+  } @else if $kind == "length-percentage" {
+    $units: list.append($-length-units, "%");
+  } @else if $kind == "angle" {
+    $units: $-angle-units;
+  }
+
+  @if meta.type-of($value) == "calculation" {
+    @return true;
+  }
+  @if meta.type-of($value) == "number" {
+    @if math.is-unitless($value) {
+      @return ($kind == "length" or $kind == "length-percentage") and $value == 0;
+    }
+    @if $kind == "resolution" and $value < 0 {
+      @return false;
+    }
+    @return list.index($units, string.to-lower-case(math.unit($value))) != null;
+  }
+  @if meta.type-of($value) != "string" {
+    @return false;
+  }
+
+  $text: string.to-lower-case(string.unquote($value));
+  @each $function in "calc(" "clamp(" "min(" "max(" {
+    @if string.index($text, $function) == 1 {
+      @return true;
+    }
+  }
+
+  // A quoted length, such as "600px": the number runs up to the first
+  // character that cannot be part of one, and the rest is the unit.
+  $unit-start: null;
+  $digits: 0;
+  @for $i from 1 through string.length($text) {
+    $character: string.slice($text, $i, $i);
+    @if $unit-start == null {
+      @if string.index("0123456789", $character) {
+        $digits: $digits + 1;
+      } @else if not string.index(".+-", $character) {
+        $unit-start: $i;
+      }
+    }
+  }
+  @if $digits == 0 {
+    @return false;
+  }
+  @if $unit-start == null {
+    // A quoted unitless number: only zero, and only for a length.
+    @return ($kind == "length" or $kind == "length-percentage") and not string.index($text, "1") and not string.index($text, "2") and not string.index($text, "3") and not string.index($text, "4") and not string.index($text, "5") and not string.index($text, "6") and not string.index($text, "7") and not string.index($text, "8") and not string.index($text, "9");
+  }
+  @if $kind == "resolution" and string.index(string.slice($text, 1, $unit-start - 1), "-") {
+    @return false;
+  }
+  @return list.index($units, string.slice($text, $unit-start)) != null;
+}

package/scss/internal/_is-css-function.scss

@@ -0,0 +1,21 @@
+@charset "UTF-8";
+
+@use "sass:list";
+@use "sass:meta";
+@use "sass:string";
+
+// scss/internal/ holds checks the mixins share. No _index.scss forwards it, so
+// a user cannot reach these functions and they are not public API: through
+// `@use "gerillass" as *` or `@import` a call to one renders as literal CSS,
+// and through a namespace it is an undefined function. Their names must not
+// start with `-` or `_`, which would make them private to their own file.
+
+// True for an unquoted call to one of $names, such as var(--x). A quoted string
+// stays text, so `"var(--x)"` is not a call.
+@function isCssFunction($value, $names) {
+  @if meta.type-of($value) != "string" or string.slice(meta.inspect($value), 1, 1) == "\"" {
+    @return false;
+  }
+  $open: string.index($value, "(");
+  @return $open != null and list.index($names, string.to-lower-case(string.slice($value, 1, $open - 1))) != null;
+}

package/scss/internal/_is-size.scss

@@ -0,0 +1,22 @@
+@charset "UTF-8";
+
+@use "sass:list";
+@use "sass:meta";
+@use "sass:string";
+
+// Shared by the mixins and not public API; see _is-css-function.scss.
+
+// A size Sass can use inside calc(): a number, a calculation such as calc(),
+// min() or clamp(), or var() and env(), which only the browser can resolve.
+// Anything else would pass silently through calc(): `calc(nonsense * 5)`
+// compiles.
+@function isSize($value) {
+  @if meta.type-of($value) == "number" or meta.type-of($value) == "calculation" {
+    @return true;
+  }
+  @if meta.type-of($value) == "string" and string.slice(meta.inspect($value), 1, 1) != "\"" {
+    $open: string.index($value, "(");
+    @return $open != null and list.index("var" "env", string.to-lower-case(string.slice($value, 1, $open - 1))) != null;
+  }
+  @return false;
+}

package/scss/internal/_keyword-value.scss

@@ -0,0 +1,76 @@
+@charset "UTF-8";
+
+@use "sass:list";
+@use "sass:meta";
+@use "sass:string";
+@use "words" as *;
+
+// Shared by the mixins and not public API; see _is-css-function.scss.
+
+$-css-wide: "inherit" "initial" "unset" "revert" "revert-layer";
+
+// Returns what is wrong with $value as a keyword value, or null when it is fine.
+// It checks the kind of each word, not whether the words make sense together;
+// a mixin whose property has a grammar, such as display, checks that itself.
+//
+// - null is fine: the declaration is left out, as it always was.
+// - Any word holding a parenthesis makes the whole value fine when $functions is
+//   true. var(), env() and calc() are resolved by the browser, and a value such
+//   as `var(--x) auto` cannot be judged here. In a @font-face descriptor, which
+//   drops var(), the caller passes false.
+// - Up to $max-words words, each one of $keywords in any case; `STICKY` and
+//   `BOTH` were kept in Chrome 152.
+// - A CSS-wide keyword only on its own: `overflow: inherit auto` was dropped.
+// - A vendor-prefixed word when $vendor is true. Chrome drops `-webkit-sticky`
+//   and `-moz-box`, but other engines use them, so refusing one could break a
+//   stylesheet written for Safari.
+@function keywordProblem($value, $keywords, $max-words: 1, $functions: true, $vendor: false) {
+  @if $value == null {
+    @return null;
+  }
+  @if meta.type-of($value) == "list" and list.separator($value) == "comma" {
+    @return "it takes a space-separated value, not a comma-separated list";
+  }
+  $words: wordsOf($value);
+  @if list.length($words) == 0 {
+    @return "it is empty";
+  }
+  @each $word in $words {
+    @if meta.type-of($word) == "string" and string.index($word, "(") {
+      @if $functions {
+        @return null;
+      }
+      @return "a function cannot supply it here";
+    }
+  }
+  @if list.length($words) > $max-words {
+    @if $max-words == 1 {
+      @return "it takes one keyword, and got #{list.length($words)}";
+    }
+    @return "it takes at most #{$max-words} keywords, and got #{list.length($words)}";
+  }
+  $expected: list.join($keywords, (), $separator: comma);
+  @each $word in $words {
+    @if meta.type-of($word) != "string" {
+      @if list.length($words) == 1 {
+        @return "it takes a keyword, one of: #{$expected}";
+      }
+      @return "`#{meta.inspect($word)}` is not a keyword; pass words from: #{$expected}";
+    }
+    $lower: string.to-lower-case(string.unquote($word));
+    @if list.index($-css-wide, $lower) {
+      @if list.length($words) > 1 {
+        @return "`#{$lower}` only works as the whole value";
+      }
+    } @else if not list.index($keywords, $lower) {
+      $prefixed: string.index($lower, "-webkit-") == 1 or string.index($lower, "-moz-") == 1 or string.index($lower, "-ms-") == 1 or string.index($lower, "-o-") == 1;
+      @if not ($vendor and $prefixed) {
+        @if list.length($words) == 1 {
+          @return "it is not one of: #{$expected}";
+        }
+        @return "`#{$lower}` is not one of: #{$expected}";
+      }
+    }
+  }
+  @return null;
+}