@josueavalosjim/taste-check 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josue Avalos Jimenez
+
+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

@@ -0,0 +1,235 @@
+# taste-check
+
+Two deterministic checks for a design system you already have. It computes WCAG
+contrast ratios from your own custom properties, and flags class names and
+literal values that are not on your own approved list.
+
+It has no opinion about which colours you use or which classes are allowed.
+You supply both.
+
+```bash
+npx @josueavalosjim/taste-check --config tastecheck.config.json
+```
+
+Installed as a dependency, the command is just `taste-check`:
+
+```bash
+npm i -D @josueavalosjim/taste-check
+```
+
+```
+contrast ok, 10 pairs across 2 themes
+    ok  17.76:1  needs 4.5  light  --text-strong on --surface  body text
+    ok   5.32:1  needs 4.5  light  --text-quiet on --surface  the translucent one
+    ok   4.10:1  needs 3.0  light  --hairline on --surface  borders
+
+treatments FAILED
+  FAIL  src/Promo.jsx:7 class "promo-huge" on <div> is not approved
+  FAIL  src/Promo.jsx:8 inline value "#ff0055" on <a> is a one-off. Use a token, or add it to approvedValues.
+```
+
+Zero runtime dependencies. Node 22 or newer.
+
+## Why this exists
+
+Most quality tooling checks compliance and has no point of view. axe tells you
+an element fails 4.5:1. It cannot tell you that your borders answer to 3:1
+while your captions answer to 4.5:1, because that distinction is yours, not the
+spec's.
+
+Design systems drift in a specific way: a value gets hardcoded because the
+token did not quite fit, a class gets invented because nobody knew the approved
+one existed. Written rules do not stop it. A rule in a stylesheet comment is
+enforced by people re-reading stylesheets, and nobody re-reads a stylesheet
+while writing markup. So the rules get a check that runs instead.
+
+## What counts as a failure
+
+Each of these exits 1 rather than passing quietly:
+
+- a pair naming a token that does not exist
+- a file pattern matching no files
+- a theme whose scopes resolve no tokens
+- a colour value the parser does not understand
+- an unknown key in the config, which is usually a typo doing nothing
+
+A check that cannot fail is worse than no check, because it goes green and gets
+quoted as evidence.
+
+## The contrast check
+
+Give it your custom properties, describe your themes, and list what must clear
+what.
+
+```json
+{
+  "contrast": {
+    "tokens": ["styles/tokens.css"],
+    "themes": [
+      { "name": "light", "scopes": [":root"] },
+      { "name": "dark", "scopes": [":root", "[data-theme=\"dark\"]"] }
+    ],
+    "pairs": [
+      { "fg": "--text", "bg": "--surface", "min": 4.5, "label": "body text" },
+      { "fg": "--hairline", "bg": "--surface", "min": 3.0, "themes": ["light"] }
+    ]
+  }
+}
+```
+
+Passing pairs are printed with their ratio, not just failing ones, so you can
+see which pair is one background nudge away from dropping under its floor.
+
+`min` has no default. WCAG's 4.5 and 3.0 are documented here and never assumed
+in code, because the floor for a decorative hairline and the floor for body
+text are different decisions and both are yours.
+
+A theme is an ordered list of scopes and later scopes win, which is the cascade
+for equal specificity. Declarations inside an at-rule are ignored unless a
+scope opts in:
+
+```json
+{ "name": "dark-system", "scopes": [":root", { "selector": ":root", "atRule": "prefers-color-scheme: dark" }] }
+```
+
+Without that rule a `@media (prefers-color-scheme: dark)` block containing
+`:root` would overwrite the light theme, and the light checks would silently
+measure against colours the light theme never paints.
+
+Two details make the numbers match a browser rather than approximate it.
+Translucent foregrounds are composited over their background before measuring,
+so `rgb(0 0 0 / 0.58)` on white scores 5.32:1 and not 21:1. And `var()`
+indirection is followed within the theme, so a token pointing at another token
+resolves to the value that theme actually uses.
+
+A background that resolves to a translucent colour is refused rather than
+measured. There is no page here to look through, so name the opaque surface
+behind it instead.
+
+## The treatments check
+
+Give it your markup and your approved list.
+
+```json
+{
+  "treatments": {
+    "files": ["src/**/*.jsx"],
+    "elements": ["a", "button", "div", "span", "p"],
+    "approvedClasses": ["card", "card__link", "button"],
+    "allowPrefixes": ["u-"],
+    "approvedValues": ["0", "100%"]
+  }
+}
+```
+
+It reports two things: a class name that is not approved and matches no allowed
+prefix, and a literal colour or length hardcoded into an inline `style`.
+
+The parsing is a scanner, not a regex, and that is the whole reason it works. The obvious implementation is `/<a\b[^>]*?className="([^"]*)"/`, which
+finds almost nothing while looking like it passes:
+
+- `[^>]*` cannot cross `onClick={() => x}`. It stops at the arrow's own `>`,
+  and the tag is skipped in silence.
+- `title="a > b"` ends the tag early for the same reason.
+- A `className` built as an expression is not a quoted string at all.
+
+So tags are found by walking the source with quote and brace depth tracked, and
+class names are collected from every string literal inside a `className`
+expression. A ternary contributes both of its branches on purpose, because the
+question is whether a class can appear at all. Over-reporting is the safer
+direction to be wrong in.
+
+Template literal holes are read into rather than blanked, so a class written
+inside `` `card ${on ? 'card--on' : ''}` `` is seen.
+
+## Config
+
+Point your editor at `schema/config.schema.json` for completion and inline
+docs. Paths inside a config resolve against the config file, so it can be run
+from anywhere.
+
+| Key | Meaning |
+| --- | --- |
+| `contrast.tokens` | CSS files holding the custom properties. Later files override earlier ones. |
+| `contrast.themes[].scopes` | Selectors applied in order, later winning. A string, or `{ selector, atRule }`. |
+| `contrast.pairs[].fg` / `.bg` | A token name, or a literal colour. `bg` must resolve to something opaque. |
+| `contrast.pairs[].min` | The floor this pair must clear. Required. |
+| `contrast.pairs[].themes` | Limit a pair to some themes. Omit to check it everywhere. |
+| `treatments.files` | Markup to scan. Supports `dir/*.ext` and any-depth `**` patterns. |
+| `treatments.elements` | Element names to scan. Omit or use `["*"]` for all of them. |
+| `treatments.approvedClasses` | Every class allowed to appear. |
+| `treatments.allowPrefixes` | Prefixes that are always allowed, as a deliberate escape hatch. |
+| `treatments.approvedValues` | Literal values allowed inside inline styles. |
+
+```
+taste-check [options]
+
+  -c, --config <path>   Config file (default: tastecheck.config.json)
+      --only <name>     Run one check: contrast or treatments
+      --json            Machine-readable output
+      --version         Print the version
+```
+
+Exit code is 1 if any check fails, 0 if every check ran and passed.
+
+## What this does not do
+
+Read this before trusting a green run.
+
+**It reads tokens, not a rendered page.** This is the real limit. The check it
+was ported from ran in a browser and read colours off `getComputedStyle`,
+because a token file cannot tell you what is actually painted behind an
+element. An overlay, an ancestor background or a colour set inline by a
+component are all invisible here. What this gives you is that the
+values in your token file relate to each other the way you said they should. It
+does not prove what a visitor sees.
+
+**Only some colour formats parse.** Hex in 3, 4, 6 and 8 digits, `rgb()` and
+`rgba()` in both the comma and the space syntax, and `white` / `black` /
+`transparent`. `hsl()`, `oklch()` and `color-mix()` are not parsed yet, and a
+value it cannot parse is a failure rather than a skip, so you will hear about
+it immediately.
+
+**There is no specificity resolution.** Scopes apply in the order you list
+them. If your tokens rely on `.a.b` beating `.b`, list the scopes in the order
+you want.
+
+**Component indirection is invisible.** Classes applied by a helper
+function, a `clsx` call importing names from elsewhere, or CSS-in-JS are
+invisible to it.
+
+## Future directions
+
+Not built. Written down so the shape is clear.
+
+**A fresh-eyes checklist hook.** The deterministic checks here cover what can
+be measured. The judgment half of design review cannot be, and the useful
+pattern for it is a fresh context: a separate model call that sees a screenshot
+and a checklist, and nothing else. Judging in the same context that produced
+the work is unreliable, because the reasoning that justified a choice is still
+sitting there to justify it again. The plan is a plugin hook that takes your
+screenshot command and your checklist file and reports back in the same format
+as the checks above. The checklist stays yours: a shipped one would just be
+somebody else's taste.
+
+**A runtime mode**, closing the gap named above by measuring `getComputedStyle`
+in a real browser, as an optional peer dependency so the core stays free of one.
+
+**YAML configs**, once there is a reason to take on a parser.
+
+**More colour formats**, `hsl()` first.
+
+## Development
+
+```bash
+npm test
+```
+
+34 tests. Most of them plant a violation into a fixture that was passing a
+moment earlier and demand it gets caught: a token darkened below its floor, an
+unapproved class added to a clean file, a class buried in a template literal
+hole, a file pattern pointed at nothing.
+
+## License
+
+MIT

package/bin/taste-check.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * taste-check CLI.
+ *
+ * Exits 1 on any failure and 0 only when every check ran and passed. "Ran" is
+ * load-bearing: a config that matches no files, names a token that does not
+ * exist, or scopes a pair to a theme that is not defined is a failure here,
+ * not a quiet skip.
+ */
+import { load } from '../src/config.mjs';
+import { run } from '../src/index.mjs';
+import { failed, toJson, toText } from '../src/report.mjs';
+
+const USAGE = `taste-check
+
+  taste-check [options]
+
+Options:
+  -c, --config <path>   Config file (default: tastecheck.config.json)
+      --only <name>     Run one check: contrast or treatments
+      --json            Machine-readable output
+  -h, --help            This
+      --version         Print the version
+
+Exit code is 1 if any check fails, 0 if every check ran and passed.`;
+
+function parseArgs(argv) {
+  const options = { config: 'tastecheck.config.json', only: null, json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const next = () => {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith('-')) throw new Error(`${arg} needs a value`);
+      i += 1;
+      return value;
+    };
+    if (arg === '-h' || arg === '--help') return { help: true };
+    else if (arg === '--version') return { version: true };
+    else if (arg === '-c' || arg === '--config') options.config = next();
+    else if (arg === '--only') {
+      options.only = next();
+      if (options.only !== 'contrast' && options.only !== 'treatments') {
+        throw new Error(`--only takes "contrast" or "treatments", not "${options.only}"`);
+      }
+    } else if (arg === '--json') options.json = true;
+    else throw new Error(`unknown option "${arg}"`);
+  }
+  return options;
+}
+
+const die = (message) => {
+  console.error(`taste-check: ${message}`);
+  process.exit(1);
+};
+
+let options;
+try {
+  options = parseArgs(process.argv.slice(2));
+} catch (error) {
+  die(`${error.message}\n\n${USAGE}`);
+}
+
+if (options.help) {
+  console.log(USAGE);
+  process.exit(0);
+}
+if (options.version) {
+  const { version } = JSON.parse(
+    await import('node:fs').then((fs) =>
+      fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+    ),
+  );
+  console.log(version);
+  process.exit(0);
+}
+
+const loaded = load(options.config);
+if (!loaded.ok) {
+  console.error(`taste-check: ${options.config} could not be used:\n`);
+  for (const error of loaded.errors) console.error(`  ${error}`);
+  process.exit(1);
+}
+
+const results = run(loaded.config, loaded.dir, { only: options.only });
+if (!results.length) {
+  die(`nothing to run. ${options.config} defines no ${options.only ?? 'contrast or treatments'} check.`);
+}
+
+console.log(options.json ? toJson(results) : toText(results));
+process.exit(failed(results) ? 1 : 0);

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@josueavalosjim/taste-check",
+  "version": "0.1.0",
+  "description": "Deterministic design-system checks: WCAG contrast over your own tokens, and a one-off value linter over your own approved list. No palette, no class list, no opinions shipped.",
+  "keywords": [
+    "accessibility",
+    "cli",
+    "contrast",
+    "design-system",
+    "design-tokens",
+    "lint",
+    "wcag"
+  ],
+  "homepage": "https://github.com/josueavalosjim/taste-check#readme",
+  "bugs": {
+    "url": "https://github.com/josueavalosjim/taste-check/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/josueavalosjim/taste-check.git"
+  },
+  "license": "MIT",
+  "author": "Josue Avalos Jimenez",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "taste-check": "bin/taste-check.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "schema",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test \"test/**/*.test.mjs\""
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {}
+}

package/schema/config.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/josueavalosjim/taste-check/schema/config.schema.json",
+  "title": "taste-check config",
+  "description": "Checks are driven entirely by this file. The tool ships no palette, no class list and no contrast floors.",
+  "type": "object",
+  "additionalProperties": false,
+  "minProperties": 1,
+  "anyOf": [{ "required": ["contrast"] }, { "required": ["treatments"] }],
+  "properties": {
+    "$schema": { "type": "string" },
+    "contrast": {
+      "type": "object",
+      "description": "WCAG contrast ratios computed from your own custom properties.",
+      "additionalProperties": false,
+      "required": ["tokens", "themes", "pairs"],
+      "properties": {
+        "tokens": {
+          "type": "array",
+          "minItems": 1,
+          "description": "CSS files holding the custom properties. Paths resolve against this config file. Later files override earlier ones.",
+          "items": { "type": "string" }
+        },
+        "themes": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Each theme is an ordered list of scopes. Later scopes win, which is the cascade for equal specificity. There is no specificity resolution.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "scopes"],
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "scopes": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "oneOf": [
+                    { "type": "string", "description": "A selector, matched exactly against one entry in a rule's selector list." },
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": ["selector"],
+                      "properties": {
+                        "selector": { "type": "string", "minLength": 1 },
+                        "atRule": {
+                          "type": "string",
+                          "description": "Opt into declarations nested in a matching at-rule prelude, for example \"prefers-color-scheme: dark\". Without this, at-rule declarations are ignored."
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "pairs": {
+          "type": "array",
+          "minItems": 1,
+          "description": "What must clear what. A pair naming a token that does not exist is a failure, never a skip.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["fg", "bg", "min"],
+            "properties": {
+              "fg": { "type": "string", "minLength": 1, "description": "A token name like --text, or a literal colour." },
+              "bg": { "type": "string", "minLength": 1, "description": "As fg, but it must resolve to an opaque colour." },
+              "min": { "type": "number", "exclusiveMinimum": 0, "description": "The floor this pair must clear. No default: you decide what the rule is." },
+              "label": { "type": "string", "description": "Why this pair matters. Printed with the result." },
+              "themes": {
+                "type": "array",
+                "minItems": 1,
+                "description": "Limit the pair to these themes. Omit to check it in all of them.",
+                "items": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "treatments": {
+      "type": "object",
+      "description": "Class names and literal values in markup, against a list you supply.",
+      "additionalProperties": false,
+      "required": ["files"],
+      "properties": {
+        "files": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Markup to scan. A pattern matching nothing is a failure, never a clean run.",
+          "items": { "type": "string" }
+        },
+        "elements": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Element names to scan. Use [\"*\"] or omit for every element.",
+          "items": { "type": "string" }
+        },
+        "approvedClasses": {
+          "type": "array",
+          "description": "Every class name allowed to appear. Anything else is reported.",
+          "items": { "type": "string" }
+        },
+        "allowPrefixes": {
+          "type": "array",
+          "description": "Class name prefixes that are always allowed, for a deliberate escape hatch.",
+          "items": { "type": "string" }
+        },
+        "approvedValues": {
+          "type": "array",
+          "description": "Literal values allowed in inline styles. Everything else that looks like a colour or a length is reported.",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/src/color.mjs

@@ -0,0 +1,140 @@
+/**
+ * Colour parsing and the WCAG contrast arithmetic.
+ *
+ * The maths here is the standard sRGB relative-luminance formula, but two
+ * details are worth stating because they are the reason a naive contrast
+ * checker disagrees with a browser:
+ *
+ *   1. Alpha is composited, not ignored. A token like `rgb(0 0 0 / 0.58)` is
+ *      not a 21:1 black; it is whatever it becomes over the ground behind it.
+ *      Measuring the raw value is measuring a colour that is never painted.
+ *
+ *   2. A value this parser does not understand is an error, not a skip. A
+ *      skipped pair would be reported as a pass, so an unsupported colour
+ *      format would quietly shrink the suite instead of failing it.
+ *
+ * Everything returns a result object rather than throwing, so the caller can
+ * attach its own context (which token, which theme) to the failure.
+ */
+
+/** The three named colours that actually turn up in token files. */
+const NAMED = {
+  white: [255, 255, 255, 1],
+  black: [0, 0, 0, 1],
+  transparent: [0, 0, 0, 0],
+};
+
+/** Formats deliberately not supported in v1, named so the error is useful. */
+const KNOWN_UNSUPPORTED = ['hsl', 'hsla', 'hwb', 'lab', 'lch', 'oklab', 'oklch', 'color-mix', 'color'];
+
+const NUMBER = /^[+-]?(?:\d+\.?\d*|\.\d+)%?$/;
+
+const ok = (rgba) => ({ ok: true, rgba });
+const err = (reason) => ({ ok: false, reason });
+
+/** A channel token to 0-255, or null if it is not a number. */
+function channel(token) {
+  if (!NUMBER.test(token)) return null;
+  const n = parseFloat(token);
+  return token.endsWith('%') ? (n / 100) * 255 : n;
+}
+
+/** An alpha token to 0-1, or null if it is not a number. */
+function alpha(token) {
+  if (!NUMBER.test(token)) return null;
+  const n = parseFloat(token);
+  return token.endsWith('%') ? n / 100 : n;
+}
+
+const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
+
+/**
+ * Parse a CSS colour into [r, g, b, a] with r/g/b in 0-255 and a in 0-1.
+ *
+ * Supported: #rgb, #rgba, #rrggbb, #rrggbbaa; rgb()/rgba() in both the legacy
+ * comma syntax and the modern space syntax with a slash alpha; and the three
+ * named colours above. Anything else fails loudly.
+ */
+export function parseColor(input) {
+  if (typeof input !== 'string') return err('not a string');
+  const text = input.trim();
+  if (!text) return err('empty value');
+
+  const named = NAMED[text.toLowerCase()];
+  if (named) return ok([...named]);
+
+  if (text.startsWith('#')) {
+    const hex = text.slice(1);
+    if (!/^[0-9a-fA-F]+$/.test(hex)) return err(`"${text}" is not a valid hex colour`);
+    const wide = hex.length === 6 || hex.length === 8;
+    const short = hex.length === 3 || hex.length === 4;
+    if (!wide && !short) return err(`"${text}" is not a 3, 4, 6 or 8 digit hex colour`);
+    const size = wide ? 2 : 1;
+    const at = (i) => {
+      const part = hex.slice(i * size, i * size + size);
+      return parseInt(short ? part + part : part, 16);
+    };
+    const hasAlpha = hex.length === 4 || hex.length === 8;
+    return ok([at(0), at(1), at(2), hasAlpha ? at(3) / 255 : 1]);
+  }
+
+  const fn = text.match(/^([a-zA-Z-]+)\s*\(([\s\S]*)\)$/);
+  if (fn) {
+    const name = fn[1].toLowerCase();
+    if (name !== 'rgb' && name !== 'rgba') {
+      const hint = KNOWN_UNSUPPORTED.includes(name)
+        ? `${name}() is not supported in v1. Convert the token to hex or rgb(), or open an issue.`
+        : `${name}() is not a colour function this tool understands`;
+      return err(`"${text}": ${hint}`);
+    }
+    // Both syntaxes at once: `rgb(1, 2, 3, .5)` and `rgb(1 2 3 / .5)`. Split on
+    // the slash first so a modern alpha is never mistaken for a fourth channel.
+    const [head, ...tail] = fn[2].split('/');
+    if (tail.length > 1) return err(`"${text}" has more than one slash`);
+    const parts = head.trim().split(/[,\s]+/).filter(Boolean);
+    const alphaToken = tail.length ? tail[0].trim() : parts[3];
+    if (parts.length < 3) return err(`"${text}" needs three colour channels`);
+    if (tail.length === 0 && parts.length > 4) return err(`"${text}" has too many channels`);
+    if (tail.length === 1 && parts.length !== 3) return err(`"${text}" has too many channels`);
+    const rgb = [channel(parts[0]), channel(parts[1]), channel(parts[2])];
+    if (rgb.some((c) => c === null)) return err(`"${text}" has a channel that is not a number`);
+    let a = 1;
+    if (alphaToken !== undefined) {
+      const parsed = alpha(alphaToken);
+      if (parsed === null) return err(`"${text}" has an alpha that is not a number`);
+      a = parsed;
+    }
+    return ok([...rgb.map((c) => clamp(c, 0, 255)), clamp(a, 0, 1)]);
+  }
+
+  if (text.includes('var(')) {
+    return err(`"${text}" still contains var(). The token it points at was not found.`);
+  }
+  return err(`"${text}" is not a colour this tool can parse`);
+}
+
+/** Composite a translucent foreground over an opaque ground. */
+export function composite(fg, bg) {
+  return [0, 1, 2].map((i) => fg[3] * fg[i] + (1 - fg[3]) * bg[i]);
+}
+
+/** Relative luminance, per WCAG 2.x. */
+export function luminance([r, g, b]) {
+  const lin = (c) => {
+    const v = c / 255;
+    return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/**
+ * The contrast ratio of a foreground against an opaque ground, with the
+ * foreground composited over that ground first.
+ */
+export function contrastRatio(fg, bg) {
+  const over = composite(fg, bg);
+  const [hi, lo] = [luminance(over), luminance(bg)].sort((a, b) => b - a);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+export const isOpaque = (rgba) => rgba[3] > 0.999;