@loidolt/theme-tokens 0.4.0 → 0.6.0

package/README.md

@@ -14,3 +14,15 @@ import { colors, semantic, spacing, tokens } from '@loidolt/theme-tokens';
 @import '@loidolt/theme-tokens/css';
 @import '@loidolt/theme-tokens/css/dark';
 ```
+
+WCAG contrast arithmetic, for colours chosen at runtime:
+
+```ts
+import { getContrastRatio, getContrastTextColor, meetsContrast } from '@loidolt/theme-tokens';
+
+meetsContrast('#767676', '#ffffff'); // true — AA for body text
+getContrastTextColor(userColour); // the theme ink that reads best on it
+```
+
+Named media frames live in `aspectRatio` (`square`, `video`, `photo`, `portrait`, `wide`) and as
+`--loidolt-aspect-*`.

package/dist/index.d.ts

@@ -1,3 +1,53 @@
+/**
+ * WCAG 2.x contrast arithmetic, shared by the token tests and by applications that need to pick
+ * or validate a colour at runtime (a user-chosen swatch, a generated label). Pure functions over
+ * hex strings, so they run anywhere — build scripts, servers, and the browser.
+ *
+ * @see https://www.w3.org/TR/WCAG22/#dfn-relative-luminance
+ */
+type ContrastLevel = 'AA' | 'AAA';
+type TextSize = 'normal' | 'large';
+interface ContrastValidation {
+    ratio: number;
+    /** `ratio` to two decimals, e.g. `'4.52:1'`. */
+    ratioString: string;
+    passesAANormal: boolean;
+    passesAALarge: boolean;
+    passesAAANormal: boolean;
+    passesAAALarge: boolean;
+}
+/** Minimum ratio per level and text size. Large text is 18.66px bold or 24px regular and up. */
+declare const contrastRequirements: {
+    readonly AA: {
+        readonly normal: 4.5;
+        readonly large: 3;
+    };
+    readonly AAA: {
+        readonly normal: 7;
+        readonly large: 4.5;
+    };
+};
+/** Relative luminance, from 0 (black) to 1 (white). Accepts `#rgb` and `#rrggbb`. */
+declare function getLuminance(hex: string): number;
+/** Contrast ratio between two colours, from 1 to 21. Order does not matter. */
+declare function getContrastRatio(foreground: string, background: string): number;
+/** Whether a pair clears the WCAG threshold for the given level and text size. */
+declare function meetsContrast(foreground: string, background: string, { level, size }?: {
+    level?: ContrastLevel;
+    size?: TextSize;
+}): boolean;
+/** Every threshold at once, for reporting. */
+declare function validateContrast(foreground: string, background: string): ContrastValidation;
+/**
+ * Whichever of two inks reads better on `background` — by measured ratio, not a luminance
+ * cut-off, so it stays right for any pair you pass. Defaults to the theme's own deep ink and
+ * panel, rather than pure black and white.
+ */
+declare function getContrastTextColor(background: string, { dark, light }?: {
+    dark?: string;
+    light?: string;
+}): string;
+
 /**
  * Design tokens for Loidolt applications.
  *
@@ -120,6 +170,17 @@ declare const breakpoints: {
     readonly expanded: "1024px";
     readonly wide: "1400px";
 };
+/**
+ * Named frames for media, as CSS `aspect-ratio` values. `Thumbnail`, `AspectRatio` and the media
+ * components accept these names so a gallery and its lightbox agree on shape.
+ */
+declare const aspectRatio: {
+    readonly square: "1 / 1";
+    readonly video: "16 / 9";
+    readonly photo: "4 / 3";
+    readonly portrait: "3 / 4";
+    readonly wide: "21 / 9";
+};
 /**
  * The role layer. Every value links to a primitive, so overriding a primitive propagates and
  * overriding a role restyles every component that plays it.
@@ -322,6 +383,13 @@ declare const tokens: {
         readonly expanded: "1024px";
         readonly wide: "1400px";
     };
+    readonly aspectRatio: {
+        readonly square: "1 / 1";
+        readonly video: "16 / 9";
+        readonly photo: "4 / 3";
+        readonly portrait: "3 / 4";
+        readonly wide: "21 / 9";
+    };
     readonly semantic: {
         readonly background: string;
         readonly surface: string;
@@ -399,4 +467,4 @@ declare const tokens: {
 };
 type ThemeTokens = typeof tokens;
 
-export { type ThemeTokens, type TokenRef, borders, breakpoints, colors, cssVarName, darkSemantic, tokens as default, flattenTokens, generateCss, generateDarkCss, motion, semantic, shadows, sizing, spacing, tokens, typography, zIndex };
+export { type ContrastLevel, type ContrastValidation, type TextSize, type ThemeTokens, type TokenRef, aspectRatio, borders, breakpoints, colors, contrastRequirements, cssVarName, darkSemantic, tokens as default, flattenTokens, generateCss, generateDarkCss, getContrastRatio, getContrastTextColor, getLuminance, meetsContrast, motion, semantic, shadows, sizing, spacing, tokens, typography, validateContrast, zIndex };

package/dist/index.js

@@ -1,3 +1,46 @@
+// src/contrast.ts
+var contrastRequirements = {
+  AA: { normal: 4.5, large: 3 },
+  AAA: { normal: 7, large: 4.5 }
+};
+var channels = (hex, caller) => {
+  const match = /^#?([\da-f]{3}|[\da-f]{6})$/i.exec(hex.trim());
+  if (!match) throw new RangeError(`${caller}: invalid hex colour ${JSON.stringify(hex)}`);
+  const digits = match[1].length === 3 ? [...match[1]].map((digit) => digit + digit).join("") : match[1];
+  return [0, 2, 4].map((index) => parseInt(digits.slice(index, index + 2), 16));
+};
+var luminanceOf = (hex, caller) => {
+  const [r, g, b] = channels(hex, caller).map((channel) => channel / 255).map((channel) => channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+function getLuminance(hex) {
+  return luminanceOf(hex, "getLuminance");
+}
+function getContrastRatio(foreground, background) {
+  const [high, low] = [
+    luminanceOf(foreground, "getContrastRatio"),
+    luminanceOf(background, "getContrastRatio")
+  ].sort((a, b) => b - a);
+  return (high + 0.05) / (low + 0.05);
+}
+function meetsContrast(foreground, background, { level = "AA", size = "normal" } = {}) {
+  return getContrastRatio(foreground, background) >= contrastRequirements[level][size];
+}
+function validateContrast(foreground, background) {
+  const ratio = getContrastRatio(foreground, background);
+  return {
+    ratio,
+    ratioString: `${ratio.toFixed(2)}:1`,
+    passesAANormal: ratio >= contrastRequirements.AA.normal,
+    passesAALarge: ratio >= contrastRequirements.AA.large,
+    passesAAANormal: ratio >= contrastRequirements.AAA.normal,
+    passesAAALarge: ratio >= contrastRequirements.AAA.large
+  };
+}
+function getContrastTextColor(background, { dark = "#20231d", light = "#f5f2e9" } = {}) {
+  return getContrastRatio(dark, background) >= getContrastRatio(light, background) ? dark : light;
+}
+
 // src/index.ts
 var ref = (name) => ({ $ref: `--loidolt-${name}` });
 var isRef = (value) => typeof value === "object" && value !== null && "$ref" in value;
@@ -88,6 +131,13 @@ var zIndex = {
   skipLink: "1000"
 };
 var breakpoints = { compact: "760px", expanded: "1024px", wide: "1400px" };
+var aspectRatio = {
+  square: "1 / 1",
+  video: "16 / 9",
+  photo: "4 / 3",
+  portrait: "3 / 4",
+  wide: "21 / 9"
+};
 var semanticDefs = {
   background: ref("color-paper"),
   surface: ref("color-panel"),
@@ -141,7 +191,8 @@ var PRIMITIVE_GROUPS = [
   ["border", borders],
   ["shadow", shadows],
   ["motion", motion],
-  ["z", zIndex]
+  ["z", zIndex],
+  ["aspect", aspectRatio]
 ];
 var flattenInto = (prefix, tree, out) => {
   for (const [key, value] of Object.entries(tree)) {
@@ -245,20 +296,27 @@ var tokens = {
   motion,
   zIndex,
   breakpoints,
+  aspectRatio,
   semantic,
   darkSemantic
 };
 var index_default = tokens;
 export {
+  aspectRatio,
   borders,
   breakpoints,
   colors,
+  contrastRequirements,
   cssVarName,
   darkSemantic,
   index_default as default,
   flattenTokens,
   generateCss,
   generateDarkCss,
+  getContrastRatio,
+  getContrastTextColor,
+  getLuminance,
+  meetsContrast,
   motion,
   semantic,
   shadows,
@@ -266,5 +324,6 @@ export {
   spacing,
   tokens,
   typography,
+  validateContrast,
   zIndex
 };

package/dist/tokens.css

@@ -71,6 +71,11 @@
   --loidolt-z-toast: 80;
   --loidolt-z-tooltip: 90;
   --loidolt-z-skip-link: 1000;
+  --loidolt-aspect-square: 1 / 1;
+  --loidolt-aspect-video: 16 / 9;
+  --loidolt-aspect-photo: 4 / 3;
+  --loidolt-aspect-portrait: 3 / 4;
+  --loidolt-aspect-wide: 21 / 9;
   --loidolt-background: var(--loidolt-color-paper);
   --loidolt-surface: var(--loidolt-color-panel);
   --loidolt-surface-alt: var(--loidolt-color-panel-alt);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loidolt/theme-tokens",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Typed design tokens for Loidolt applications",
   "license": "MIT",
   "type": "module",