gerillass 2.3.0 → 3.0.0

package/package.json

@@ -16,7 +16,7 @@
     }
   },
   "license": "Apache-2.0",
-  "version": "2.3.0",
+  "version": "3.0.0",
   "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/_gradient.scss

@@ -0,0 +1,425 @@
+@charset "UTF-8";
+
+@use "sass:list";
+@use "sass:map";
+@use "sass:math";
+@use "sass:meta";
+@use "sass:string";
+@use "../maps/map-for-directions" as *;
+@use "../maps/map-for-positions" as *;
+@use "color-stops-problem" as *;
+@use "is-condition-value" as *;
+@use "is-css-function" as *;
+@use "words" as *;
+
+// Shared by the mixins and not public API; see _is-css-function.scss.
+//
+// Builds a linear, radial or conic gradient, plain or repeating, with an
+// optional colour interpolation space, and checks every part of it. The
+// gradient mixin, the gradientValue function, text-gradient, background-image,
+// background-dots and background-stripes all write their gradients through it.
+//
+// What Chrome 152 kept and dropped, checked with CSS.supports in
+// background-image:
+//
+// - a linear direction: an angle in deg, grad, rad or turn, a unitless 0, calc(),
+//   and `to` with one side or a side and a corner in either order (`to left
+//   top`); `to center`, `to top bottom` and a length were dropped;
+// - a conic start: `from` an angle or 0, dropped with a length; a conic position
+//   takes `at` and a position like radial, and a size or shape dropped it;
+// - a conic stop: an angle, a percentage, 0 or calc(), dropped with a length;
+// - `in` a space: srgb, srgb-linear, display-p3, display-p3-linear, a98-rgb,
+//   prophoto-rgb, rec2020, lab, oklab, xyz, xyz-d50 and xyz-d65, or a polar
+//   hsl, hwb, lch or oklch with an optional `shorter`, `longer`, `increasing` or
+//   `decreasing hue`; a hue method on a rectangular space, `hue` without a
+//   method, a method without `hue`, and `rgb` or `hsv` were dropped. `in
+//   var(--s)` with `--s: oklab` computed to `in oklab`.
+//
+// The shape, size and position checks came from radial-gradient, removed in
+// 3.0.0, with the measurements behind them.
+
+$-types: "linear" "radial" "conic";
+$-rectangular-spaces: "srgb" "srgb-linear" "display-p3" "display-p3-linear" "a98-rgb" "prophoto-rgb" "rec2020" "lab" "oklab" "xyz" "xyz-d50" "xyz-d65";
+$-polar-spaces: "hsl" "hwb" "lch" "oklch";
+$-hue-methods: "shorter" "longer" "increasing" "decreasing";
+$-sides: "top" "bottom" "left" "right";
+
+$-extents: "closest-side" "closest-corner" "farthest-side" "farthest-corner";
+$-places: "left" "center" "right" "top" "bottom";
+
+// "extent", "length" or "percentage" for a word that can size the gradient,
+// or null.
+@function -size-kind($word) {
+  $lower: string.to-lower-case("#{$word}");
+  @if list.index($-extents, $lower) {
+    @return "extent";
+  }
+  @if string.index($lower, "-") == 1 {
+    @return null;
+  }
+  @if isConditionValue($word, "length") {
+    @return "length";
+  }
+  @if isConditionValue($word, "length-percentage") {
+    @return "percentage";
+  }
+  @return null;
+}
+
+// Checks the size words before `at`. $shape is the shape named, or null.
+@function -size-problem($words, $shape) {
+  $extents: 0;
+  $lengths: 0;
+  $percentages: 0;
+  @each $word in $words {
+    $kind: -size-kind($word);
+    @if $kind == null {
+      @return "`#{$word}` is not a shape, an extent keyword such as `closest-side`, or a length";
+    } @else if $kind == "extent" {
+      $extents: $extents + 1;
+    } @else if $kind == "length" {
+      $lengths: $lengths + 1;
+    } @else {
+      $percentages: $percentages + 1;
+    }
+  }
+  $sizes: $lengths + $percentages;
+  @if $extents > 1 or ($extents == 1 and $sizes > 0) {
+    @return "it gives the size twice";
+  }
+  @if $sizes > 2 {
+    @return "a size is one length or two";
+  }
+  @if $sizes == 1 and ($percentages == 1 or $shape == "ellipse") {
+    @return "one size is a circle's radius, which is a length and not a percentage";
+  }
+  @if $sizes == 2 and $shape == "circle" {
+    @return "a circle takes one length, not two";
+  }
+  @return null;
+}
+
+@function -shape-problem($shape) {
+  @if string.index($shape, "(") {
+    @return null;
+  }
+  $named: null;
+  $sizes: ();
+  @each $word in wordsOf($shape) {
+    $lower: string.to-lower-case($word);
+    @if list.index("circle" "ellipse", $lower) {
+      @if $named {
+        @return "it names the shape twice";
+      }
+      $named: $lower;
+    } @else {
+      $sizes: list.append($sizes, $word);
+    }
+  }
+  @return -size-problem($sizes, $named);
+}
+
+@function -position-problem($position) {
+  @if map.has-key($map-for-positions, $position) or string.index($position, "(") {
+    @return null;
+  }
+  $sizes: ();
+  $places: ();
+  $after-at: false;
+  @each $word in wordsOf($position) {
+    $lower: string.to-lower-case($word);
+    @if $lower == "at" {
+      @if $after-at {
+        @return "it has `at` twice";
+      }
+      $after-at: true;
+    } @else if $after-at {
+      $places: list.append($places, $word);
+    } @else if list.index("circle" "ellipse", $lower) {
+      @return "the shape goes in $shape, not $position";
+    } @else {
+      $sizes: list.append($sizes, $word);
+    }
+  }
+  $problem: -size-problem($sizes, null);
+  @if $problem {
+    @return "#{$problem}. Pass a position name such as `center` or `top-left`, an extent keyword such as `closest-side`, or `at` followed by a position, such as `at 30% 40%`";
+  }
+  @if $after-at and list.length($places) == 0 {
+    @return "`at` needs a position after it, such as `at center`";
+  }
+  @if list.length($places) > 4 {
+    @return "a position takes at most four values";
+  }
+  $keywords: 0;
+  @each $word in $places {
+    @if list.index($-places, string.to-lower-case($word)) {
+      $keywords: $keywords + 1;
+    } @else if not isConditionValue($word, "length-percentage") {
+      @return "`#{$word}` is not a position; after `at` pass left, center, right, top, bottom or a length";
+    }
+  }
+  @if $keywords > 2 and $keywords == list.length($places) {
+    @return "a position of keywords alone takes at most two, such as `at top left`";
+  }
+  @return null;
+}
+
+// True for var(), env() or attr(), which may stand for anything, so it is
+// written as it is.
+@function -is-substitution($value) {
+  @return isCssFunction($value, "var" "env" "attr");
+}
+
+// True for an angle, a unitless 0, a calculation or var().
+@function -is-angle($value) {
+  @return $value == 0 or isConditionValue($value, "angle") or -is-substitution($value);
+}
+
+// The CSS for a linear gradient's $direction, or null when a browser would
+// drop it. background-image checks its $filter-direction with this.
+@function gradientDirection($direction) {
+  @if map.has-key($map-for-directions, $direction) {
+    @return map.get($map-for-directions, $direction);
+  }
+  @if -is-angle($direction) {
+    @return $direction;
+  }
+  $words: wordsOf($direction);
+  @if meta.type-of($direction) == "string" and string.to-lower-case("#{list.nth($words, 1)}") == "to" and list.length($words) >= 2 and list.length($words) <= 3 {
+    $vertical: 0;
+    $horizontal: 0;
+    @for $i from 2 through list.length($words) {
+      $word: string.to-lower-case("#{list.nth($words, $i)}");
+      @if $word == "top" or $word == "bottom" {
+        $vertical: $vertical + 1;
+      } @else if $word == "left" or $word == "right" {
+        $horizontal: $horizontal + 1;
+      } @else {
+        @return null;
+      }
+    }
+    @if $vertical <= 1 and $horizontal <= 1 {
+      @return string.unquote($direction);
+    }
+  }
+  @return null;
+}
+
+// What is wrong with $in, or null.
+@function -in-problem($in) {
+  // Measured in Chrome 152: `in var(--s)` with `--s: oklab` computed to
+  // `in oklab`, so var() is written as it is.
+  @if -is-substitution($in) {
+    @return null;
+  }
+  @if not list.index("string" "list", meta.type-of($in)) {
+    @return "it is not a colour space";
+  }
+  $words: ();
+  @each $word in wordsOf($in) {
+    $words: list.append($words, string.to-lower-case("#{$word}"));
+  }
+  $space: list.nth($words, 1);
+  $count: list.length($words);
+  @if list.index($-rectangular-spaces, $space) {
+    @if $count > 1 {
+      @return "a hue method such as `longer hue` needs a polar space: hsl, hwb, lch or oklch";
+    }
+    @return null;
+  }
+  @if list.index($-polar-spaces, $space) {
+    @if $count == 1 {
+      @return null;
+    }
+    @if $count == 3 and list.index($-hue-methods, list.nth($words, 2)) and list.nth($words, 3) == "hue" {
+      @return null;
+    }
+    @return "after a polar space comes a hue method and the word hue, such as `oklch longer hue`";
+  }
+  @return "`#{$space}` is not a colour space; pass one such as oklab or oklch";
+}
+
+// What is wrong with a conic gradient's stops, or null. A position there is an
+// angle or a percentage, so each is checked for that and then replaced with 0,
+// and the list goes through colorStopsProblem for everything else.
+@function -conic-stops-problem($colors) {
+  $checked: ();
+  @each $item in $colors {
+    @if meta.type-of($item) == "list" and list.length($item) > 1 {
+      $stop: (list.nth($item, 1),);
+      @for $i from 2 through list.length($item) {
+        $position: list.nth($item, $i);
+        @if not -is-conic-position($position) {
+          @return "in `#{meta.inspect($item)}`, `#{meta.inspect($position)}` is not an angle or a percentage, and a conic stop is placed by one";
+        }
+        @if -is-substitution($position) {
+          $stop: list.append($stop, $position, space);
+        } @else {
+          $stop: list.append($stop, 0, space);
+        }
+      }
+      $checked: list.append($checked, $stop, comma);
+    } @else if meta.type-of($item) == "number" or isConditionValue($item, "length-percentage") or isConditionValue($item, "angle") {
+      @if not -is-conic-position($item) {
+        @return "`#{meta.inspect($item)}` is not an angle or a percentage, and a conic hint is placed by one";
+      }
+      $checked: list.append($checked, 0, comma);
+    } @else {
+      $checked: list.append($checked, $item, comma);
+    }
+  }
+  @return colorStopsProblem($checked);
+}
+
+@function -is-conic-position($value) {
+  @if -is-angle($value) or meta.type-of($value) == "calculation" {
+    @return true;
+  }
+  @if meta.type-of($value) == "number" {
+    @return math.unit($value) == "%";
+  }
+  $text: string.unquote("#{$value}");
+  @return string.slice($text, -1) == "%" and isConditionValue($value, "length-percentage");
+}
+
+
+// A gradient, as a value. $member, $colors-name and $direction-name are the
+// names an error gives, so a mixin that passes its own arguments through names
+// them as its user wrote them. $warn is false for the fallback a mixin writes
+// before a gradient with $in, so a single colour warns once.
+@function gradientOf(
+  $colors,
+  $type: linear,
+  $direction: null,
+  $shape: null,
+  $position: null,
+  $from: null,
+  $in: null,
+  $repeating: false,
+  $member: "gradient",
+  $colors-name: "$colors",
+  $direction-name: "$direction",
+  $warn: true
+) {
+  $kind: string.to-lower-case("#{$type}");
+  @if meta.type-of($type) != "string" or not list.index($-types, $kind) {
+    @error "`#{meta.inspect($type)}` is not a valid $type for `#{$member}`. Pass linear, radial or conic.";
+  }
+  @if meta.type-of($repeating) != "bool" {
+    @error "`#{meta.inspect($repeating)}` is not a valid $repeating for `#{$member}`. Pass true or false.";
+  }
+
+  // An argument the type does not read would be dropped without a word.
+  @if $direction != null and $kind != "linear" {
+    $hint: "Use $position for where a radial gradient sits.";
+    @if $kind == "conic" {
+      $hint: "Use $from for where a conic gradient starts.";
+    }
+    @error "#{$direction-name} is for a linear gradient, and this one is #{$kind}. #{$hint}";
+  }
+  @if $shape != null and $kind != "radial" {
+    @error "$shape is for a radial gradient, and this one is #{$kind}.";
+  }
+  @if $position != null and $kind == "linear" {
+    @error "$position is for a radial or conic gradient, and this one is linear. Use #{$direction-name}.";
+  }
+  @if $from != null and $kind != "conic" {
+    @error "$from is for a conic gradient, and this one is #{$kind}.";
+  }
+
+  $prelude: ();
+
+  @if $kind == "linear" and $direction != null {
+    $value: gradientDirection($direction);
+    @if $value == null {
+      @error "`#{meta.inspect($direction)}` is not a valid #{$direction-name} for `#{$member}`. Pass an angle such as `45deg` or `0.25turn`, `\"to top right\"`, or one of: #{map.keys($map-for-directions)}.";
+    }
+    $prelude: list.append($prelude, $value, space);
+  }
+
+  // A shape or position written without quotes, such as `ellipse 70% 60%` or
+  // `at 50% 0%`, reaches here as a space-separated list; it is the same words.
+  @if meta.type-of($shape) == "list" and list.separator($shape) == "space" {
+    $shape: "#{$shape}";
+  }
+  @if meta.type-of($position) == "list" and list.separator($position) == "space" {
+    $position: "#{$position}";
+  }
+
+  @if $kind == "radial" and $shape != null {
+    @if meta.type-of($shape) != "string" {
+      @error "`#{meta.inspect($shape)}` is not a valid $shape for `#{$member}`. Pass circle or ellipse, optionally with a size.";
+    }
+    $shape: string.unquote($shape);
+    $problem: -shape-problem($shape);
+    @if $problem {
+      @error "`#{$shape}` is not a valid $shape for `#{$member}`: #{$problem}. A browser drops the whole gradient.";
+    }
+    $prelude: list.append($prelude, $shape, space);
+  }
+
+  @if $kind == "conic" and $from != null {
+    @if not -is-angle($from) {
+      @error "`#{meta.inspect($from)}` is not a valid $from for `#{$member}`. Pass an angle, such as `45deg` or `0.25turn`.";
+    }
+    $prelude: list.append($prelude, string.unquote("from #{$from}"), space);
+  }
+
+  @if $position != null {
+    @if meta.type-of($position) != "string" {
+      @error "`#{meta.inspect($position)}` is not a valid $position for `#{$member}`. Pass a position name such as `center` or `top-left`, or a CSS position as a string, such as `\"at 30% 40%\"`.";
+    }
+    $position: string.unquote($position);
+    @if map.has-key($map-for-positions, $position) {
+      $prelude: list.append($prelude, map.get($map-for-positions, $position), space);
+    } @else {
+      $problem: -position-problem($position);
+      @if not $problem and $kind == "conic" and not string.index($position, "(") and string.to-lower-case(list.nth(wordsOf($position), 1)) != "at" {
+        $problem: "a conic gradient has no size, so its position starts with `at`";
+      }
+      @if $problem {
+        @error "`#{$position}` is not a valid $position for `#{$member}`: #{$problem}. A browser drops the whole gradient.";
+      }
+      $prelude: list.append($prelude, $position, space);
+    }
+  }
+
+  $problem: null;
+  @if $kind == "conic" {
+    $problem: -conic-stops-problem($colors);
+  } @else {
+    $problem: colorStopsProblem($colors);
+  }
+  @if $problem {
+    @error "`#{meta.inspect($colors)}` is not a valid #{$colors-name} for `#{$member}`: #{$problem}. A browser drops the whole gradient.";
+  }
+  // From the compat data, not measured in an old browser: a gradient with one
+  // colour is kept only from Chrome 135, Firefox 136 and Safari 18.4.
+  @if $warn and list.length($colors) == 1 and not -is-substitution(list.nth($colors, 1)) {
+    @warn "`#{$member}` was given one colour, `#{meta.inspect($colors)}`. Browsers before Chrome 135, Firefox 136 and Safari 18.4 drop a gradient with a single colour stop; pass two colours, or use background-color.";
+  }
+
+  @if $in != null {
+    $problem: -in-problem($in);
+    @if $problem {
+      @error "`#{meta.inspect($in)}` is not a valid $in for `#{$member}`: #{$problem}. A browser drops the whole gradient.";
+    }
+    $prelude: list.append($prelude, string.unquote("in #{$in}"), space);
+  }
+
+  $stops: ();
+  @each $item in $colors {
+    $stops: list.append($stops, $item, comma);
+  }
+
+  $name: "#{$kind}-gradient";
+  @if $repeating {
+    $name: "repeating-#{$name}";
+  }
+  $function: meta.get-function($name, $css: true);
+  @if list.length($prelude) > 0 {
+    @return meta.call($function, $prelude, $stops...);
+  }
+  @return meta.call($function, $stops...);
+}