@adrienlcp/styles 0.4.1 → 0.5.0

package/README.md

@@ -94,3 +94,40 @@ into; `font-face` declares one self-hosted `woff2` file.
 
 `$weight`, `$style` (`normal`), `$stretch` (left out) and `$display` (`swap`)
 are optional.
+
+## TypeScript
+
+### `contrast`
+
+A palette is checked where it is written, not by eye: a test lists the token
+pairs that meet on screen, and fails when one falls under its WCAG minimum in
+the light or the dark scheme.
+
+```ts
+import { readFileSync } from 'node:fs'
+
+import { findContrastFailures, WCAG_AA } from '@adrienlcp/styles/contrast'
+import { expect, it } from 'vitest'
+
+const TOKENS = readFileSync(new URL('_tokens.sass', import.meta.url), 'utf8')
+
+it('every ink reads on every surface, in both themes', () => {
+  expect(
+    findContrastFailures(TOKENS, [
+      { foreground: '--ink-soft', background: '--ground', minimum: WCAG_AA.text },
+      { foreground: '--focus', background: '--ground', minimum: WCAG_AA.nonText }
+    ])
+  ).toEqual([])
+})
+```
+
+- `WCAG_AA` is `text` (4.5), `largeText` and `nonText` (3) — controls, icons,
+  focus rings.
+- The stylesheet is `.css` or indented `.sass`. A token is `oklch()` or hex,
+  `light-dark()` of those, or `var()` of another token.
+- A failure is `too-low`, with the ratio and the schemes it fails in, or
+  `unreadable`: a token undeclared, declared twice with different values, a
+  reference loop, a colour it cannot read (computed, or another notation), or a
+  translucent background — what shows through decides that contrast.
+- A translucent foreground is measured over its background. An `oklch()`
+  outside sRGB is clipped, as an sRGB screen draws it.

package/dist/color-tokens.d.ts

@@ -0,0 +1,15 @@
+import { Result } from '@adrienlcp/result';
+import { type Color } from './color.ts';
+export type ColorScheme = 'dark' | 'light';
+export type TokenError = 'circular-reference' | 'declared-twice' | 'undeclared' | 'unsupported-color';
+/** Every custom property a stylesheet declares, with each value it is given. */
+export type TokenDeclarations = ReadonlyMap<string, readonly string[]>;
+/** Reads the custom properties of a `.css` or indented `.sass` source. */
+export declare const readTokenDeclarations: (stylesheet: string) => TokenDeclarations;
+type Resolution = Result<Color, {
+    error: TokenError;
+    token: string;
+}>;
+/** The colour a token paints in one scheme, following `var()` and `light-dark()`. */
+export declare const resolveToken: (declarations: TokenDeclarations, token: string, scheme: ColorScheme, visited?: ReadonlySet<string>) => Resolution;
+export {};

package/dist/color-tokens.js

@@ -0,0 +1,64 @@
+import { Result } from '@adrienlcp/result';
+import { parseColor } from './color.js';
+const DECLARATION_PATTERN = /(--[\w-]+)\s*:\s*([^;\n}]+)/g;
+const COMMENT_PATTERN = /\/\*[\s\S]*?\*\/|^\s*\/\/.*$/gm;
+const VAR_PATTERN = /^var\(\s*(--[\w-]+)\s*(?:,\s*(.+))?\)$/;
+const LIGHT_DARK_PATTERN = /^light-dark\((.+)\)$/;
+/** Reads the custom properties of a `.css` or indented `.sass` source. */
+export const readTokenDeclarations = (stylesheet) => {
+    const declarations = new Map();
+    for (const [, name = '', value = ''] of stylesheet
+        .replace(COMMENT_PATTERN, '')
+        .matchAll(DECLARATION_PATTERN)) {
+        const values = declarations.get(name) ?? [];
+        const trimmed = value.trim();
+        if (!values.includes(trimmed))
+            values.push(trimmed);
+        declarations.set(name, values);
+    }
+    return declarations;
+};
+/** Splits `a, b` on its top-level comma, the one no parenthesis encloses. */
+const splitArguments = (list) => {
+    let depth = 0;
+    for (const [index, character] of [...list].entries()) {
+        if (character === '(')
+            depth += 1;
+        if (character === ')')
+            depth -= 1;
+        if (character === ',' && depth === 0)
+            return [list.slice(0, index).trim(), list.slice(index + 1).trim()];
+    }
+    return [list.trim()];
+};
+const resolveValue = (declarations, value, scheme, token, visited) => {
+    const reference = value.match(VAR_PATTERN);
+    if (reference) {
+        const [, name = '', fallback] = reference;
+        if (!declarations.has(name) && fallback)
+            return resolveValue(declarations, fallback, scheme, token, visited);
+        return resolveToken(declarations, name, scheme, visited);
+    }
+    const lightDark = value.match(LIGHT_DARK_PATTERN);
+    if (lightDark?.[1]) {
+        const [light = '', dark = light] = splitArguments(lightDark[1]);
+        const chosen = scheme === 'light' ? light : dark;
+        return resolveValue(declarations, chosen, scheme, token, visited);
+    }
+    const color = parseColor(value);
+    if (color.status === 'failure')
+        return Result.failure({ error: color.error, token });
+    return color;
+};
+/** The colour a token paints in one scheme, following `var()` and `light-dark()`. */
+export const resolveToken = (declarations, token, scheme, visited = new Set()) => {
+    if (visited.has(token))
+        return Result.failure({ error: 'circular-reference', token });
+    const values = declarations.get(token);
+    if (!values)
+        return Result.failure({ error: 'undeclared', token });
+    const [value] = values;
+    if (values.length > 1 || value === undefined)
+        return Result.failure({ error: 'declared-twice', token });
+    return resolveValue(declarations, value, scheme, token, new Set([...visited, token]));
+};

package/dist/color.d.ts

@@ -0,0 +1,16 @@
+/** A colour in gamma-encoded sRGB, each channel and the alpha in `[0, 1]`. */
+export type Color = {
+    alpha: number;
+    blue: number;
+    green: number;
+    red: number;
+};
+/** Reads an `oklch()` or hex colour, the two forms a token is written in. */
+export declare const parseColor: (value: string) => import("@adrienlcp/result").FailureResult<"unsupported-color"> | {
+    data: Color;
+    status: "success";
+};
+/** Paints a translucent colour over an opaque one, blending in gamma-encoded sRGB as browsers do. */
+export declare const composite: (top: Color, beneath: Color) => Color;
+/** The WCAG 2 contrast ratio of two opaque colours, from 1 to 21. */
+export declare const contrastRatio: (first: Color, second: Color) => number;

package/dist/color.js

@@ -0,0 +1,73 @@
+import { Result } from '@adrienlcp/result';
+const OKLCH_PATTERN = /^oklch\(\s*([\d.]+%?)\s+([\d.]+%?)\s+([\d.]+(?:deg)?|none)\s*(?:\/\s*([\d.]+%?)\s*)?\)$/i;
+const HEX_PATTERN = /^#([\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/i;
+const FULL_OKLCH_CHROMA = 0.4;
+const parseAmount = (value, whole) => value.endsWith('%')
+    ? (Number.parseFloat(value) / 100) * whole
+    : Number.parseFloat(value);
+const clampUnit = (value) => Math.min(1, Math.max(0, value));
+const encodeGamma = (linear) => linear <= 0.0031308 ? 12.92 * linear : 1.055 * linear ** (1 / 2.4) - 0.055;
+const decodeGamma = (encoded) => encoded <= 0.04045 ? encoded / 12.92 : ((encoded + 0.055) / 1.055) ** 2.4;
+/** OKLCH to sRGB through OKLab; an out-of-gamut channel is clipped, as a browser on an sRGB screen draws it. */
+const fromOklch = (lightness, chroma, hueDegrees, alpha) => {
+    const hue = (hueDegrees * Math.PI) / 180;
+    const a = chroma * Math.cos(hue);
+    const b = chroma * Math.sin(hue);
+    const l = (lightness + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+    const m = (lightness - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+    const s = (lightness - 0.0894841775 * a - 1.291485548 * b) ** 3;
+    const toChannel = (linear) => encodeGamma(clampUnit(linear));
+    return {
+        alpha: clampUnit(alpha),
+        blue: toChannel(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s),
+        green: toChannel(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
+        red: toChannel(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s)
+    };
+};
+const parseOklch = (match) => {
+    const [, lightness = '', chroma = '', hue = '', alpha = '1'] = match;
+    return fromOklch(parseAmount(lightness, 1), parseAmount(chroma, FULL_OKLCH_CHROMA), hue === 'none' ? 0 : Number.parseFloat(hue), parseAmount(alpha, 1));
+};
+const parseHex = (digits) => {
+    const full = digits.length <= 4
+        ? [...digits].map((digit) => digit + digit).join('')
+        : digits;
+    const channel = (index) => Number.parseInt(full.slice(index * 2, index * 2 + 2), 16) / 255;
+    return {
+        alpha: full.length === 8 ? channel(3) : 1,
+        blue: channel(2),
+        green: channel(1),
+        red: channel(0)
+    };
+};
+/** Reads an `oklch()` or hex colour, the two forms a token is written in. */
+export const parseColor = (value) => {
+    const oklch = value.match(OKLCH_PATTERN);
+    if (oklch)
+        return Result.success(parseOklch(oklch));
+    const hex = value.match(HEX_PATTERN);
+    if (hex?.[1])
+        return Result.success(parseHex(hex[1]));
+    return Result.failure('unsupported-color');
+};
+/** Paints a translucent colour over an opaque one, blending in gamma-encoded sRGB as browsers do. */
+export const composite = (top, beneath) => {
+    const blend = (over, under) => over * top.alpha + under * (1 - top.alpha);
+    return {
+        alpha: 1,
+        blue: blend(top.blue, beneath.blue),
+        green: blend(top.green, beneath.green),
+        red: blend(top.red, beneath.red)
+    };
+};
+const relativeLuminance = (color) => 0.2126 * decodeGamma(color.red) +
+    0.7152 * decodeGamma(color.green) +
+    0.0722 * decodeGamma(color.blue);
+/** The WCAG 2 contrast ratio of two opaque colours, from 1 to 21. */
+export const contrastRatio = (first, second) => {
+    const [lighter, darker] = [
+        relativeLuminance(first),
+        relativeLuminance(second)
+    ].sort((left, right) => right - left);
+    return ((lighter ?? 0) + 0.05) / ((darker ?? 0) + 0.05);
+};

package/dist/contrast.d.ts

@@ -0,0 +1,40 @@
+import { type ColorScheme, type TokenError } from './color-tokens.ts';
+export type { ColorScheme, TokenError };
+/** WCAG 2.2 level AA minimum contrast ratios. */
+export declare const WCAG_AA: {
+    /** Text at 24px, or 18.66px bold, and larger. */
+    readonly largeText: 3;
+    /** Controls, icons, focus rings, the boundary of an input. */
+    readonly nonText: 3;
+    /** Body text, labels, placeholders. */
+    readonly text: 4.5;
+};
+/** Two tokens that meet on screen, named as declared: `{ foreground: '--ink', background: '--ground', minimum: WCAG_AA.text }`. */
+export type ContrastPair = {
+    background: string;
+    foreground: string;
+    minimum: number;
+};
+export type ContrastFailure = {
+    kind: 'too-low';
+    pair: ContrastPair;
+    ratio: number;
+    schemes: ColorScheme[];
+} | {
+    error: TokenError | 'translucent-background';
+    kind: 'unreadable';
+    pair: ContrastPair;
+    token: string;
+};
+/**
+ * Every pair below its minimum, in either scheme, read straight from the
+ * stylesheet that declares the tokens. A translucent foreground is measured
+ * over its background; a translucent background cannot be measured, since
+ * what shows through decides it.
+ *
+ * @example
+ * expect(findContrastFailures(tokens, [
+ *   { foreground: '--ink-soft', background: '--ground', minimum: WCAG_AA.text }
+ * ])).toEqual([])
+ */
+export declare const findContrastFailures: (stylesheet: string, pairs: readonly ContrastPair[]) => ContrastFailure[];

package/dist/contrast.js

@@ -0,0 +1,57 @@
+import { composite, contrastRatio } from './color.js';
+import { readTokenDeclarations, resolveToken } from './color-tokens.js';
+/** WCAG 2.2 level AA minimum contrast ratios. */
+export const WCAG_AA = {
+    /** Text at 24px, or 18.66px bold, and larger. */
+    largeText: 3,
+    /** Controls, icons, focus rings, the boundary of an input. */
+    nonText: 3,
+    /** Body text, labels, placeholders. */
+    text: 4.5
+};
+const SCHEMES = ['light', 'dark'];
+const roundRatio = (ratio) => Math.floor(ratio * 100) / 100;
+const sameFailure = (failure, other) => JSON.stringify({ ...failure, schemes: [] }) ===
+    JSON.stringify({ ...other, schemes: [] });
+const checkPair = (declarations, pair, scheme) => {
+    const background = resolveToken(declarations, pair.background, scheme);
+    if (background.status === 'failure')
+        return { kind: 'unreadable', pair, ...background.error };
+    if (background.data.alpha < 1)
+        return {
+            error: 'translucent-background',
+            kind: 'unreadable',
+            pair,
+            token: pair.background
+        };
+    const foreground = resolveToken(declarations, pair.foreground, scheme);
+    if (foreground.status === 'failure')
+        return { kind: 'unreadable', pair, ...foreground.error };
+    const ratio = roundRatio(contrastRatio(composite(foreground.data, background.data), background.data));
+    if (ratio >= pair.minimum)
+        return undefined;
+    return { kind: 'too-low', pair, ratio, schemes: [scheme] };
+};
+/**
+ * Every pair below its minimum, in either scheme, read straight from the
+ * stylesheet that declares the tokens. A translucent foreground is measured
+ * over its background; a translucent background cannot be measured, since
+ * what shows through decides it.
+ *
+ * @example
+ * expect(findContrastFailures(tokens, [
+ *   { foreground: '--ink-soft', background: '--ground', minimum: WCAG_AA.text }
+ * ])).toEqual([])
+ */
+export const findContrastFailures = (stylesheet, pairs) => {
+    const declarations = readTokenDeclarations(stylesheet);
+    return pairs.flatMap((pair) => {
+        const [light, dark] = SCHEMES.map((scheme) => checkPair(declarations, pair, scheme));
+        if (light && sameFailure(light, dark)) {
+            if (light.kind === 'unreadable')
+                return [light];
+            return [{ ...light, schemes: [...SCHEMES] }];
+        }
+        return [light, dark].filter((failure) => failure !== undefined);
+    });
+};

package/package.json

@@ -1,7 +1,10 @@
 {
   "author": "Adrien Lacourpaille",
   "bugs": "https://github.com/AdrienLcp/packages/issues",
-  "description": "A reset, a reduced-motion switch, and Sass mixins for self-hosted fonts, container queries and a breakpoint",
+  "dependencies": {
+    "@adrienlcp/result": "^0.1.0"
+  },
+  "description": "A reset, a reduced-motion switch, Sass mixins for self-hosted fonts, container queries and a breakpoint, and a WCAG contrast check for colour tokens",
   "devDependencies": {
     "sass": "^1.105.0"
   },
@@ -12,6 +15,7 @@
     "./containers": {
       "sass": "./src/_containers.sass"
     },
+    "./contrast": "./dist/contrast.js",
     "./fonts": {
       "sass": "./src/_fonts.sass"
     },
@@ -20,15 +24,18 @@
     "./reset.css": "./src/reset.css"
   },
   "files": [
+    "dist",
     "src/*.css",
     "src/*.sass"
   ],
   "homepage": "https://github.com/AdrienLcp/packages/tree/main/packages/styles#readme",
   "keywords": [
+    "contrast",
     "css",
     "font-face",
     "reset",
-    "sass"
+    "sass",
+    "wcag"
   ],
   "license": "MIT",
   "name": "@adrienlcp/styles",
@@ -49,8 +56,9 @@
     "*.css"
   ],
   "type": "module",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "scripts": {
+    "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "test:watch": "vitest --watch"
   }