sass-apca 0.0.1 → 1.0.0

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2023 Philipp Gfeller
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2023 Philipp Gfeller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,2 +1,51 @@
-# sass-apca
-Sass implementation of the [Accessible Perceptual Contrast Algorithm (APCA)](https://git.apcacontrast.com/) for the WCAG 3.0 specification.
+# sass-apca
+Sass implementation of the [Accessible Perceptual Contrast Algorithm (APCA)](https://git.apcacontrast.com/) for the WCAG 3.0 specification.
+
+## Installation
+
+These scss functions are compatible with [sass (dart sass)](https://www.npmjs.com/package/sass) v1.33 and up.
+
+```bash
+npm install sass-apca
+```
+
+## Usage
+
+### Contrast
+
+APCA reports lightness contrast as an L<sup>c</sup> value from L<sup>c</sup> 0 to L<sup>c</sup> 106 for dark text on a light background, and L<sup>c</sup> 0 to L<sup>c</sup> -108 for light text on a dark background (dark mode). The minus sign merely indicates negative contrast, which means light text on a dark background[^1].
+
+| Parameter | Type | Description |
+|:--- |:--- |:--- |
+| $text-color | [Sass Color](https://sass-lang.com/documentation/values/colors) | Color of the text |
+| $background-color | [Sass Color](https://sass-lang.com/documentation/values/colors) | Color of the background |
+
+```scss
+@use 'sass-apca/apca';
+
+$contrast-black-on-white: apca.contrast(black, white); // 106.0406668287
+$contrast-white-on-black: apca.contrast(white, black); // -107.8847261151
+```
+
+## About
+These general levels are appropriate for use by themselves, without the need to reference a lookup table. APCA reports contrast as an L<sup>c</sup> value (lightness contrast) from L<sup>c</sup> 0 to L<sup>c</sup> 105+. For accessibility, consider L<sup>c</sup> 15 the point of invisibility for many users, and L<sup>c</sup> 90 is preferred for body text[^2].
+
+- **L<sup>c</sup> 90** • Preferred level for fluent text and columns of body text with a font no smaller than 14px/weight 400 (normal).
+- **L<sup>c</sup> 75** • The minimum level for columns of body text with a font no smaller than 18px/400. L<sup>c</sup> 75 should be considered a minimum for text where readability is important.
+- **L<sup>c</sup> 60** • The minimum level recommended for content text that is not body, column, or block text. In other words, text you want people to read. The minimums: 24px normal weight (400) or 16px/700 (bold). These values based on the reference font Helvetica.
+- **L<sup>c</sup> 45** • The minimum for larger, heavier text (36px normal weight or 24px bold) such as headlines. This is also the minimum for pictograms with fine details.
+- **L<sup>c</sup> 30** • The absolute minimum for any text not listed above. This includes placeholder text and disabled element text. This is also the minimum for large/solid semantic & understandable non-text elements.
+- **L<sup>c</sup> 15** • The absolute minimum for any non-text that needs to be discernible and differentiable, and is no less than 6px in its smallest dimension. This may include disabled large buttons. Designers should treat anything below this level as invisible, as it will not be visible for many users. This minimum level should be avoided for any items important to the use, understanding, or interaction of the site.
+
+## Roadmap
+- Polarity function for figuring out if light or dark text has a higher contrast on any given background
+- Compliance check for getting the current level of compliance of a given contrast ratio
+
+
+
+## License
+
+Code published in this repository licensed under the [MIT license](https://github.com/gfellerph/sass-apca/blob/main/LICENSE).
+
+[^1]: APCA contrast calculator (https://www.myndex.com/APCA/)
+[^2]: Why APCA (https://git.apcacontrast.com/documentation/WhyAPCA#use-case-ranges)

package/apca.scss

@@ -1,83 +1,92 @@
-@use "sass:math";
-@use "sass:color";
-
-// -------------------
-//
-// Sass APCA
-//
-// Implementation of the [Accessible Perceptual Contrast Algorithm (APCA)](https://git.apcacontrast.com/) for the WCAG 3.0 specification.
-//
-// -------------------
-
-// Powercurve exponents
-$Strc: 2.4;
-$Ntx: 0.57;
-$Nbg: 0.56;
-$Rtx: 0.62;
-$Rbg: 0.65;
-
-// Clamps and scalers
-$Bclip: 1.414;
-$Bthrsh: 0.022;
-$Wscale: 1.14;
-$Woffset: 0.027;
-$Wclamp: 0.1;
-
-// Multipliers
-$redMultiplier: 0.2126729;
-$greenMultiplier: 0.7151522;
-$blueMultiplier: 0.072175;
-
-@function luminance($color) {
-  // The floating point precision is poor so white would return 1.000001
-  @if ($color == white) {
-    @return 1;
-  }
-
-  @if ($color == black) {
-    @return 0;
-  }
-
-  $red: color.red($color);
-  $green: color.green($color);
-  $blue: color.blue($color);
-
-  $redLuminance: math.pow($red / 255, $Strc) * $redMultiplier;
-  $greenLuminance: math.pow($green / 255, $Strc) * $greenMultiplier;
-  $blueLuminance: math.pow($blue / 255, $Strc) * $blueMultiplier;
-
-  @return $redLuminance + $greenLuminance + $blueLuminance;
-}
-
-@function softClip($luminance) {
-  @if ($luminance < 0) {
-    @return 0;
-  } @else if ($luminance < $Bthrsh) {
-    @return $luminance + math.pow(($Bthrsh - $luminance), $Bclip);
-  } @else {
-    @return $luminance;
-  }
-}
-
-@function polarity($textColor, $backgroundColor) {
-  $Ytxt: softClip(luminance($textColor));
-  $Ybg: softClip(luminance($backgroundColor));
-
-  @if ($Ybg > $Ytxt) {
-    @return (math.pow($Ybg, $Nbg) - math.pow($Ytxt, $Ntx)) * $Wscale;
-  } @else {
-    @return (math.pow($Ybg, $Rbg) - math.pow($Ytxt, $Rtx)) * $Wscale;
-  }
-}
-
-@function contrast($textColor, $backgroundColor) {
-  $polarity: polarity($textColor, $backgroundColor);
-
-  @if (math.abs($polarity) < $Wclamp) {
-    @return 0;
-  } @else if ($polarity > 0) {
-    @return ($polarity - $Woffset) * 100;
-  } @else {
-    @return ($polarity + $Woffset) * 100;
-  }
-}
+@use "sass:math";
+@use "sass:color";
+@use "sass:meta";
+
+// -------------------
+//
+// Sass APCA
+//
+// Implementation of the [Accessible Perceptual Contrast Algorithm (APCA)](https://git.apcacontrast.com/) for the WCAG 3.0 specification.
+//
+// -------------------
+
+// Powercurve exponents
+$_Strc: 2.4;
+$_Ntx: 0.57;
+$_Nbg: 0.56;
+$_Rtx: 0.62;
+$_Rbg: 0.65;
+
+// Clamps and scalers
+$_Bclip: 1.414;
+$_Bthrsh: 0.022;
+$_Wscale: 1.14;
+$_Woffset: 0.027;
+$_Wclamp: 0.1;
+
+// Multipliers
+$_redMultiplier: 0.2126729;
+$_greenMultiplier: 0.7151522;
+$_blueMultiplier: 0.072175;
+
+@function _luminance($color) {
+  // The floating point precision is poor so white would return 1.000001
+  @if ($color == white) {
+    @return 1;
+  }
+
+  @if ($color == black) {
+    @return 0;
+  }
+
+  $red: color.red($color);
+  $green: color.green($color);
+  $blue: color.blue($color);
+
+  $redLuminance: math.pow($red / 255, $_Strc) * $_redMultiplier;
+  $greenLuminance: math.pow($green / 255, $_Strc) * $_greenMultiplier;
+  $blueLuminance: math.pow($blue / 255, $_Strc) * $_blueMultiplier;
+
+  @return $redLuminance + $greenLuminance + $blueLuminance;
+}
+
+@function _softClip($luminance) {
+  @if ($luminance < 0) {
+    @return 0;
+  } @else if ($luminance < $_Bthrsh) {
+    @return $luminance + math.pow(($_Bthrsh - $luminance), $_Bclip);
+  } @else {
+    @return $luminance;
+  }
+}
+
+@function _polarity($textColor, $backgroundColor) {
+  $Ytxt: _softClip(_luminance($textColor));
+  $Ybg: _softClip(_luminance($backgroundColor));
+
+  @if ($Ybg > $Ytxt) {
+    @return (math.pow($Ybg, $_Nbg) - math.pow($Ytxt, $_Ntx)) * $_Wscale;
+  } @else {
+    @return (math.pow($Ybg, $_Rbg) - math.pow($Ytxt, $_Rtx)) * $_Wscale;
+  }
+}
+
+@function contrast($textColor, $backgroundColor) {
+  @if (meta.type-of($textColor) != 'color') {
+    @error "Type Error: apca.contrast expects a color as first argument but received #{meta.type-of($textColor)}. Please provide a valid color.";
+  }
+
+  @if (meta.type-of($backgroundColor) != 'color') {
+    @error "Type Error: apca.contrast expects a color as second argument but received #{meta.type-of($backgroundColor)}. Please provide a valid color.";
+  }
+
+  $polarity: _polarity($textColor, $backgroundColor);
+
+  @if (math.abs($polarity) < $_Wclamp) {
+    @return 0;
+  } @else if ($polarity > 0) {
+    @return ($polarity - $_Woffset) * 100;
+  } @else {
+    @return ($polarity + $_Woffset) * 100;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sass-apca",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "description": "Sass implementation of the [Accessible Perceptual Contrast Algorithm (APCA)](https://git.apcacontrast.com/) for the WCAG 3.0 specification.",
   "keywords": [
     "sass",

package/test.scss

@@ -1,35 +1,35 @@
-@use './apca';
-
-/* tests */
-luminances {
-  --red-luminance: apca.luminance(red);
-  --green-luminance: apca.luminance(green);
-  --blue-luminance: apca.luminance(blue);
-
-  --yellow-luminance: apca.luminance(yellow);
-  --brown-luminance: apca.luminance(brown);
-  --violet-luminance: apca.luminance(violet);
-
-  --white-luminance: apca.luminance(white);
-  --black-luminance: apca.luminance(black);
-}
-
-softClip {
-  --black: apca.softClip(apca.luminance(black));
-  --white: apca.softClip(apca.luminance(white));
-  --brown: apca.softClip(apca.luminance(brown));
-}
-
-polarity {
-  --black-on-white: apca.polarity(black, white);
-  --white-on-black: apca.polarity(white, black);
-  --red-on-green: apca.polarity(red, green);
-  --green-on-red: apca.polarity(green, red);
-  --yellow-on-white: apca.polarity(#fc0, white);
-  --white-on-yellow: apca.polarity(white, #fc0);
-}
-
-contrast {
-  --black-on-white: apca.contrast(black, white);
-  --white-on-black: apca.contrast(white, black);
-}
+@use './apca';
+
+/* tests */
+luminances {
+  --red-luminance: apca.luminance(red);
+  --green-luminance: apca.luminance(green);
+  --blue-luminance: apca.luminance(blue);
+
+  --yellow-luminance: apca.luminance(yellow);
+  --brown-luminance: apca.luminance(brown);
+  --violet-luminance: apca.luminance(violet);
+
+  --white-luminance: apca.luminance(white);
+  --black-luminance: apca.luminance(black);
+}
+
+softClip {
+  --black: apca.softClip(apca.luminance(black));
+  --white: apca.softClip(apca.luminance(white));
+  --brown: apca.softClip(apca.luminance(brown));
+}
+
+polarity {
+  --black-on-white: apca.polarity(black, white);
+  --white-on-black: apca.polarity(white, black);
+  --red-on-green: apca.polarity(red, green);
+  --green-on-red: apca.polarity(green, red);
+  --yellow-on-white: apca.polarity(#fc0, white);
+  --white-on-yellow: apca.polarity(white, #fc0);
+}
+
+contrast {
+  --black-on-white: apca.contrast(black, white);
+  --white-on-black: apca.contrast(white, black);
+}