@maple-kit/lint 0.1.0

package/dist/rendered/collect.js

@@ -0,0 +1,101 @@
+import { captureContext } from "@maple-kit/core/overlay";
+import { describeElement } from "@maple-kit/core/anchor";
+//#region src/rendered/collect.ts
+const INTERACTIVE_TAGS = [
+	"a",
+	"button",
+	"input",
+	"select",
+	"summary",
+	"textarea"
+];
+const INTERACTIVE_ROLES = [
+	"button",
+	"checkbox",
+	"link",
+	"menuitem",
+	"switch",
+	"tab"
+];
+const TEXT_CAP = 80;
+function isInteractive(element) {
+	const tag = element.tagName.toLowerCase();
+	if (INTERACTIVE_TAGS.includes(tag)) return true;
+	const role = element.getAttribute("role");
+	if (role !== null && INTERACTIVE_ROLES.includes(role)) return true;
+	const tabIndex = element.getAttribute("tabindex");
+	return tabIndex !== null && Number.parseInt(tabIndex, 10) >= 0;
+}
+function isOpaque(color) {
+	if (color === "transparent") return false;
+	const alpha = /rgba?\([^)]*[,/]\s*([\d.]+)\s*\)/.exec(color);
+	return alpha === null || Number.parseFloat(alpha[1]) > 0;
+}
+function backdropOf(element) {
+	let node = element;
+	while (node !== null) {
+		const background = getComputedStyle(node).backgroundColor;
+		if (isOpaque(background)) return background;
+		node = node.parentElement;
+	}
+	return "rgb(255, 255, 255)";
+}
+function keyframeProperties(names) {
+	const wanted = names.split(",").map((name) => name.trim());
+	if (wanted.every((name) => name === "none" || name === "")) return [];
+	const found = /* @__PURE__ */ new Set();
+	for (const sheet of [...document.styleSheets]) {
+		let rules;
+		try {
+			rules = sheet.cssRules;
+		} catch {
+			continue;
+		}
+		collectKeyframes(rules, wanted, found);
+	}
+	return [...found];
+}
+function collectKeyframes(rules, wanted, found) {
+	for (const rule of [...rules]) {
+		if (!(rule instanceof CSSKeyframesRule) || !wanted.includes(rule.name)) continue;
+		for (const frame of [...rule.cssRules]) {
+			if (!(frame instanceof CSSKeyframeRule)) continue;
+			for (const property of [...frame.style]) found.add(property);
+		}
+	}
+}
+function paintsOwnText(element) {
+	return [...element.childNodes].some((node) => node.nodeType === Node.TEXT_NODE && (node.textContent ?? "").trim() !== "");
+}
+function recordOf(element) {
+	const style = getComputedStyle(element);
+	const box = element.getBoundingClientRect();
+	return {
+		anchor: describeElement(element),
+		tag: element.tagName.toLowerCase(),
+		text: (element.textContent ?? "").trim().slice(0, TEXT_CAP),
+		paintsText: paintsOwnText(element),
+		interactive: isInteractive(element),
+		color: style.color,
+		backgroundColor: style.backgroundColor,
+		backdrop: backdropOf(element),
+		fontSize: Number.parseFloat(style.fontSize),
+		fontWeight: Number.parseFloat(style.fontWeight),
+		width: box.width,
+		height: box.height,
+		transitionProperty: style.transitionProperty,
+		transitionDuration: style.transitionDuration,
+		animationName: style.animationName,
+		animationDuration: style.animationDuration,
+		animationProperties: keyframeProperties(style.animationName)
+	};
+}
+function readPage() {
+	const elements = [...document.querySelectorAll("[data-maple-src]")];
+	return {
+		context: captureContext(),
+		records: elements.map(recordOf)
+	};
+}
+//#endregion
+export { readPage };

package/dist/rendered/rules.d.ts

@@ -0,0 +1,30 @@
+import { Finding, Severity } from "../types.js";
+import { StyleRecord } from "./collect.js";
+import { TokenSet } from "../tokens.js";
+//#region src/rendered/rules.d.ts
+/** What a rule is, for the docs table and for a host overriding a severity. */
+export interface RuleDefinition {
+  readonly id: string;
+  readonly severity: Severity;
+  /** One line, the same sentence the docs table shows. */
+  readonly summary: string;
+}
+/** The properties motion is allowed on: the two the compositor can animate. */
+export declare const MOTION_SAFE: readonly ["opacity", "transform"];
+/** Smallest touch target that is not a finding, from WCAG 2.5.8 AA. */
+export declare const MIN_TOUCH_TARGET = 24;
+/** Every rendered rule, in the order the docs list them. */
+export declare const RENDERED_RULES: readonly RuleDefinition[];
+/**
+ * Every rule that reads one pass of the page, called once per viewport by the
+ * driver. These are the rendered tier's own rules only: a judged rule reaches a
+ * model through a connector, and lands with #126 rather than here.
+ */
+export declare function renderedFindings(records: readonly StyleRecord[], tokens: TokenSet): readonly Finding[];
+/**
+ * Colours the page painted that no rule could judge, distinct and in the order
+ * they were met. A run reports these rather than quietly checking less than it
+ * was asked to.
+ */
+export declare function unreadableColors(records: readonly StyleRecord[]): readonly string[];
+//#endregion

package/dist/rendered/rules.js

@@ -0,0 +1,131 @@
+import { colorKey, contrastRatio, isUnreadableColor, over, parseColor } from "../color.js";
+//#region src/rendered/rules.ts
+const MOTION_SAFE = ["opacity", "transform"];
+const MIN_TOUCH_TARGET = 24;
+const DOCS = "https://github.com/maple-kit/maple/blob/main/docs/lint.md";
+const RENDERED_RULES = [
+	{
+		id: "maple/rendered-color-token",
+		severity: "error",
+		summary: "Colours come from the token set."
+	},
+	{
+		id: "maple/rendered-type-scale",
+		severity: "error",
+		summary: "Font sizes come from the type scale."
+	},
+	{
+		id: "maple/rendered-touch-target",
+		severity: "error",
+		summary: `Interactive elements are at least 24px on both axes.`
+	},
+	{
+		id: "maple/rendered-contrast",
+		severity: "error",
+		summary: "Text meets WCAG AA contrast."
+	},
+	{
+		id: "maple/rendered-motion-property",
+		severity: "error",
+		summary: "Motion animates only opacity and transform."
+	},
+	{
+		id: "maple/rendered-reduced-motion",
+		severity: "error",
+		summary: "Motion stops under prefers-reduced-motion."
+	}
+];
+const SEVERITY = new Map(RENDERED_RULES.map((rule) => [rule.id, rule.severity]));
+function finding(rule, record, message) {
+	return {
+		rule,
+		tier: "rendered",
+		severity: SEVERITY.get(rule) ?? "warn",
+		message,
+		anchor: record.anchor,
+		url: `${DOCS}#${rule.replace("maple/", "")}`
+	};
+}
+function isTokenColor(color, tokens) {
+	return tokens.colors.has(colorKey(color)) || tokens.colors.has(colorKey({
+		...color,
+		a: 1
+	}));
+}
+function colorFindings(record, tokens) {
+	const rule = "maple/rendered-color-token";
+	if (tokens.colors.size === 0) return [];
+	return [["text colour", record.color], ["background", record.backgroundColor]].flatMap(([what, value]) => {
+		const color = parseColor(value);
+		if (!color || color.a === 0 || isTokenColor(color, tokens)) return [];
+		return [finding(rule, record, `The ${what} ${value} is not a token.`)];
+	});
+}
+function typeScaleFindings(record, tokens) {
+	if (tokens.fontSizes.size === 0 || tokens.fontSizes.has(record.fontSize)) return [];
+	const scale = [...tokens.fontSizes].sort((first, second) => first - second).join("px, ");
+	return [finding("maple/rendered-type-scale", record, `The font size ${record.fontSize}px is off the scale (${scale}px).`)];
+}
+function touchTargetFindings(record) {
+	const tooSmall = record.width < 24 || record.height < 24;
+	if (!record.interactive || !tooSmall || record.width === 0 || record.height === 0) return [];
+	const size = `${Math.round(record.width)}×${Math.round(record.height)}px`;
+	return [finding("maple/rendered-touch-target", record, `This ${record.tag} is ${size}, under the 24px touch target.`)];
+}
+function isLargeText(record) {
+	return record.fontSize >= 24 || record.fontSize >= 18.66 && record.fontWeight >= 700;
+}
+function contrastFindings(record) {
+	if (!record.paintsText || record.text === "") return [];
+	const foreground = parseColor(record.color);
+	const backdrop = parseColor(record.backdrop);
+	if (!foreground || !backdrop) return [];
+	const ratio = contrastRatio(over(foreground, backdrop), backdrop);
+	const required = isLargeText(record) ? 3 : 4.5;
+	if (ratio >= required) return [];
+	return [finding("maple/rendered-contrast", record, `Contrast is ${ratio.toFixed(2)}:1, under the ${required}:1 this text needs.`)];
+}
+function transitioned(record) {
+	return record.transitionProperty.split(",").map((property) => property.trim()).filter((property) => property !== "" && property !== "none");
+}
+function isStill(duration) {
+	return duration.split(",").every((value) => Number.parseFloat(value) === 0 || Number.isNaN(Number.parseFloat(value)));
+}
+function motionPropertyFindings(record) {
+	const rule = "maple/rendered-motion-property";
+	const safe = (property) => MOTION_SAFE.includes(property);
+	const moving = isStill(record.transitionDuration) ? [] : transitioned(record);
+	const animated = isStill(record.animationDuration) ? [] : record.animationProperties;
+	const offending = [.../* @__PURE__ */ new Set([...moving, ...animated])].filter((property) => !safe(property));
+	if (offending.length === 0) return [];
+	return [finding(rule, record, `Motion is on ${offending.join(", ")}, not opacity or transform.`)];
+}
+function renderedFindings(records, tokens) {
+	return records.flatMap((record) => [
+		...colorFindings(record, tokens),
+		...typeScaleFindings(record, tokens),
+		...touchTargetFindings(record),
+		...contrastFindings(record),
+		...motionPropertyFindings(record)
+	]);
+}
+function unreadableColors(records) {
+	const found = /* @__PURE__ */ new Set();
+	for (const record of records) for (const value of [
+		record.color,
+		record.backgroundColor,
+		record.backdrop
+	]) if (isUnreadableColor(value)) found.add(value);
+	return [...found];
+}
+function movesBeyondFade(record) {
+	const moving = isStill(record.transitionDuration) ? [] : transitioned(record);
+	const animated = isStill(record.animationDuration) ? [] : record.animationProperties;
+	const properties = [.../* @__PURE__ */ new Set([...moving, ...animated])];
+	return properties.length > 0 && properties.some((property) => property !== "opacity");
+}
+function reducedMotionFindings(records) {
+	return records.filter((record) => movesBeyondFade(record)).map((record) => finding("maple/rendered-reduced-motion", record, "This still moves under prefers-reduced-motion."));
+}
+//#endregion
+export { MIN_TOUCH_TARGET, MOTION_SAFE, RENDERED_RULES, colorFindings, contrastFindings, motionPropertyFindings, reducedMotionFindings, renderedFindings, touchTargetFindings, typeScaleFindings, unreadableColors };

package/dist/tokens.d.ts

@@ -0,0 +1,39 @@
+//#region src/tokens.d.ts
+/**
+ * The token set a rendered rule checks against, read from the same CSS files
+ * the static tier is configured with.
+ *
+ * A token file is read as text and scanned for custom-property declarations
+ * rather than parsed as a stylesheet: the rules only need the values, and a
+ * scan has no opinion about the selectors they were declared under.
+ */
+/** Every value a rule is allowed to see, keyed the way the rule compares it. */
+export interface TokenSet {
+  /** Declared colours, as `colorKey` strings. */
+  readonly colors: ReadonlySet<string>;
+  /** Declared lengths that read as a font size, in px. */
+  readonly fontSizes: ReadonlySet<number>;
+  /** Custom-property names, for a message that can name the token. */
+  readonly names: ReadonlyMap<string, string>;
+  /**
+   * Declarations meant to be a colour that could not be read, by name. Every
+   * element painted from one would be judged against a set lacking it.
+   */
+  readonly unreadable: ReadonlyMap<string, string>;
+}
+/** How a rem in a token file converts to the px a computed style reports. */
+export declare const ROOT_FONT_SIZE = 16;
+/** Converts a CSS length to px, or undefined when it is not one. */
+export declare function lengthToPx(value: string, rootFontSize?: number): number | undefined;
+/**
+ * Scans CSS text for custom properties. A theme layer that declares
+ * `--surface: var(--grey-100)` contributes the colour it resolves to, because
+ * an element painted from it computes to that colour and nothing else.
+ */
+export declare function parseTokens(css: string, rootFontSize?: number): TokenSet;
+/**
+ * Reads every configured token file as one sheet, so a theme file that refers
+ * to a base file's token resolves the way the browser resolves it.
+ */
+export declare function readTokenFiles(paths: readonly string[], rootFontSize?: number): Promise<TokenSet>;
+//#endregion

package/dist/tokens.js

@@ -0,0 +1,49 @@
+import { colorKey, isUnreadableColor, parseColor } from "./color.js";
+import { readFile } from "node:fs/promises";
+//#region src/tokens.ts
+const ROOT_FONT_SIZE = 16;
+const DECLARATION = /(--\w[\w-]*)\s*:([^;}]+)/g;
+const REFERENCE = /^var\(\s*(--[\w-]+)\s*(?:,([^)]*))?\)$/;
+const MAX_INDIRECTION = 8;
+const LENGTH = /^(-?[\d.]+)(px|rem|em)$/;
+function lengthToPx(value, rootFontSize = 16) {
+	const match = LENGTH.exec(value.trim());
+	if (!match) return void 0;
+	const size = Number.parseFloat(match[1]);
+	return match[2] === "px" ? size : size * rootFontSize;
+}
+function resolve(value, names, depth = 0) {
+	const reference = REFERENCE.exec(value.trim());
+	if (!reference || depth >= MAX_INDIRECTION) return value;
+	const next = names.get(reference[1]) ?? reference[2]?.trim();
+	return next === void 0 ? value : resolve(next, names, depth + 1);
+}
+function parseTokens(css, rootFontSize = 16) {
+	const colors = /* @__PURE__ */ new Set();
+	const fontSizes = /* @__PURE__ */ new Set();
+	const names = /* @__PURE__ */ new Map();
+	const unreadable = /* @__PURE__ */ new Map();
+	for (const [, name, raw] of css.matchAll(DECLARATION)) names.set(name, raw.trim());
+	for (const [name, declared] of names) {
+		const value = resolve(declared, names);
+		const color = parseColor(value);
+		if (color) colors.add(colorKey(color));
+		else if (isUnreadableColor(value)) unreadable.set(name, value);
+		const length = lengthToPx(value, rootFontSize);
+		if (length !== void 0 && isTypeToken(name)) fontSizes.add(length);
+	}
+	return {
+		colors,
+		fontSizes,
+		names,
+		unreadable
+	};
+}
+function isTypeToken(name) {
+	return /(^|-)(text|font|type)(-|$)/.test(name);
+}
+async function readTokenFiles(paths, rootFontSize = 16) {
+	return parseTokens((await Promise.all(paths.map((path) => readFile(path, "utf8")))).join("\n"), rootFontSize);
+}
+//#endregion
+export { ROOT_FONT_SIZE, lengthToPx, parseTokens, readTokenFiles };

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+import { Anchor } from "@maple-kit/core/anchor";
+//#region src/types.d.ts
+/** Which tier found it: how much the finding can be trusted to be exact. */
+export type Tier = "judged" | "rendered" | "static";
+/**
+ * How a host is asked to treat it. Deterministic tiers may block; a judged
+ * finding defaults to advice, because a model's opinion is not a gate.
+ */
+export type Severity = "advice" | "error" | "warn";
+/** One thing a rule found, at one place on the page. */
+export interface Finding {
+  /** Rule id, `maple/` for a predefined rule. */
+  readonly rule: string;
+  readonly tier: Tier;
+  readonly severity: Severity;
+  /** One sentence, in the reviewer's words, naming the value that is wrong. */
+  readonly message: string;
+  /**
+   * Where it is, in the cascade's own type. A finding and a comment mean the
+   * same thing by "where", which is what lets one be pinned beside the other.
+   */
+  readonly anchor: Anchor;
+  /** Where the rule is documented. */
+  readonly url?: string;
+}
+//#endregion

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@maple-kit/lint",
+  "version": "0.1.0",
+  "description": "Design-system lint for Maple: rendered-tier rules over a live preview",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maple-kit/maple.git",
+    "directory": "packages/lint"
+  },
+  "homepage": "https://github.com/maple-kit/maple/tree/main/packages/lint",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@maple-kit/core": "0.10.0"
+  },
+  "peerDependencies": {
+    "playwright": "^1.50.0"
+  },
+  "devDependencies": {
+    "playwright": "1.63.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}