@viewlint/rules 0.0.1

package/dist/rules/corner-radius-coherence.js

@@ -0,0 +1,171 @@
+import { defineRule } from "viewlint/plugin";
+import { getDomHelpersHandle } from "../utils/getDomHelpersHandle.js";
+/**
+ * Detects child elements whose corner radius violates the corner radius law.
+ *
+ * The corner radius law states that for nested rounded corners to look visually
+ * coherent, the child's radius should equal `parent_radius - inset`, where inset
+ * is the distance between the parent's inner edge and the child's outer edge.
+ *
+ * Only reports when the inset is small enough relative to the parent's radius
+ * that the relationship matters visually (inset <= 0.5 * parent_radius).
+ */
+export default defineRule({
+    meta: {
+        severity: "warn",
+        docs: {
+            description: "Detects child elements with corner radius that violates the corner radius law for nested rounded corners",
+            recommended: false,
+        },
+    },
+    async run(context) {
+        const domHelpers = await getDomHelpersHandle(context.page);
+        await context.evaluate(({ report, scope, args: { domHelpers } }) => {
+            const TOLERANCE = 2;
+            const parseRadius = (value) => {
+                const parsed = parseFloat(value);
+                return Number.isNaN(parsed) ? 0 : parsed;
+            };
+            /**
+             * Gets the effective corner radius for an element.
+             * Returns an object with radii for each corner.
+             */
+            const getCornerRadii = (style) => {
+                return {
+                    topLeft: parseRadius(style.borderTopLeftRadius),
+                    topRight: parseRadius(style.borderTopRightRadius),
+                    bottomRight: parseRadius(style.borderBottomRightRadius),
+                    bottomLeft: parseRadius(style.borderBottomLeftRadius),
+                };
+            };
+            /**
+             * Calculates inset for each corner (distance from parent inner edge to child outer edge).
+             */
+            const getCornerInsets = (parentRect, childRect) => {
+                const topInset = childRect.top - parentRect.top;
+                const rightInset = parentRect.right - childRect.right;
+                const bottomInset = parentRect.bottom - childRect.bottom;
+                const leftInset = childRect.left - parentRect.left;
+                return {
+                    topLeft: Math.min(topInset, leftInset),
+                    topRight: Math.min(topInset, rightInset),
+                    bottomRight: Math.min(bottomInset, rightInset),
+                    bottomLeft: Math.min(bottomInset, leftInset),
+                };
+            };
+            const hasRoundedCorners = (radii) => {
+                return (radii.topLeft > 0 ||
+                    radii.topRight > 0 ||
+                    radii.bottomRight > 0 ||
+                    radii.bottomLeft > 0);
+            };
+            /**
+             * Checks if the element has visible styling that would make corner radius visible.
+             * An element needs a border, background, or box-shadow for its corners to be seen.
+             */
+            const hasVisibleCorners = (style) => {
+                // Check for visible border on any side
+                const borderWidths = [
+                    parseFloat(style.borderTopWidth) || 0,
+                    parseFloat(style.borderRightWidth) || 0,
+                    parseFloat(style.borderBottomWidth) || 0,
+                    parseFloat(style.borderLeftWidth) || 0,
+                ];
+                const hasVisibleBorder = borderWidths.some((w) => w > 0);
+                if (hasVisibleBorder)
+                    return true;
+                // Check for visible background color (not transparent)
+                const bgColor = style.backgroundColor;
+                if (bgColor &&
+                    bgColor !== "transparent" &&
+                    bgColor !== "rgba(0, 0, 0, 0)") {
+                    return true;
+                }
+                // Check for background image
+                const bgImage = style.backgroundImage;
+                if (bgImage && bgImage !== "none") {
+                    return true;
+                }
+                // Check for box shadow
+                const boxShadow = style.boxShadow;
+                if (boxShadow && boxShadow !== "none") {
+                    return true;
+                }
+                // Check for outline (although not affected by border-radius, can indicate intent)
+                const outlineWidth = parseFloat(style.outlineWidth) || 0;
+                if (outlineWidth > 0) {
+                    return true;
+                }
+                return false;
+            };
+            const allElements = scope.queryAll("*");
+            for (const el of allElements) {
+                if (!domHelpers.isHtmlElement(el))
+                    continue;
+                if (!domHelpers.isVisible(el))
+                    continue;
+                if (!domHelpers.hasElementRectSize(el))
+                    continue;
+                const parent = el.parentElement;
+                if (!domHelpers.isHtmlElement(parent))
+                    continue;
+                if (!domHelpers.isVisible(parent))
+                    continue;
+                if (!domHelpers.hasElementRectSize(parent))
+                    continue;
+                const parentStyle = window.getComputedStyle(parent);
+                const parentRadii = getCornerRadii(parentStyle);
+                if (!hasRoundedCorners(parentRadii))
+                    continue;
+                const childStyle = window.getComputedStyle(el);
+                // Skip elements without visible styling that would show corner radius
+                // (no border, background, or box-shadow = invisible corners)
+                if (!hasVisibleCorners(childStyle))
+                    continue;
+                const childRadii = getCornerRadii(childStyle);
+                const parentRect = parent.getBoundingClientRect();
+                const childRect = el.getBoundingClientRect();
+                const insets = getCornerInsets(parentRect, childRect);
+                const corners = [
+                    "topLeft",
+                    "topRight",
+                    "bottomRight",
+                    "bottomLeft",
+                ];
+                const violations = [];
+                for (const corner of corners) {
+                    const parentRadius = parentRadii[corner];
+                    const childRadius = childRadii[corner];
+                    const inset = insets[corner];
+                    if (parentRadius <= 0)
+                        continue;
+                    if (inset > 0.5 * parentRadius)
+                        continue;
+                    if (inset < 0)
+                        continue;
+                    const expectedChildRadius = Math.max(0, parentRadius - inset);
+                    const difference = Math.abs(childRadius - expectedChildRadius);
+                    if (difference <= TOLERANCE)
+                        continue;
+                    const cornerLabel = corner
+                        .replace(/([A-Z])/g, "-$1")
+                        .toLowerCase()
+                        .replace(/^-/, "");
+                    violations.push(`${cornerLabel}: expected ~${Math.round(expectedChildRadius)}px, found ${Math.round(childRadius)}px`);
+                }
+                if (violations.length > 0) {
+                    report({
+                        message: `Corner radius violates nesting law: ${violations.join("; ")}`,
+                        element: el,
+                        relations: [
+                            {
+                                description: "Parent with rounded corners",
+                                element: parent,
+                            },
+                        ],
+                    });
+                }
+            }
+        }, { domHelpers });
+    },
+});

package/dist/rules/hit-target-obscured.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Detects interactive elements that are obscured by other elements,
+ * making them unclickable or partially unclickable.
+ *
+ * Uses elementFromPoint to sample click positions and verify the element
+ * or its descendants receive the click.
+ */
+declare const _default: import("viewlint").RuleDefinition<undefined>;
+export default _default;
+//# sourceMappingURL=hit-target-obscured.d.ts.map

package/dist/rules/hit-target-obscured.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hit-target-obscured.d.ts","sourceRoot":"","sources":["../../src/rules/hit-target-obscured.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;;AACH,wBAiRE"}

package/dist/rules/hit-target-obscured.js

@@ -0,0 +1,237 @@
+import { defineRule } from "viewlint/plugin";
+import { getDomHelpersHandle } from "../utils/getDomHelpersHandle.js";
+/**
+ * Detects interactive elements that are obscured by other elements,
+ * making them unclickable or partially unclickable.
+ *
+ * Uses elementFromPoint to sample click positions and verify the element
+ * or its descendants receive the click.
+ */
+export default defineRule({
+    meta: {
+        severity: "error",
+        docs: {
+            description: "Detects clickable elements that are obscured by other elements",
+            recommended: true,
+        },
+    },
+    async run(context) {
+        const domHelpers = await getDomHelpersHandle(context.page);
+        await context.evaluate(({ report, scope, args: { domHelpers } }) => {
+            const isLabelControlPair = (label, candidate) => {
+                if (!(label instanceof HTMLLabelElement))
+                    return false;
+                if (!candidate)
+                    return false;
+                const control = label.control;
+                if (!control)
+                    return false;
+                return control === candidate || control.contains(candidate);
+            };
+            const parseAlphaFromRgba = (value) => {
+                const match = value
+                    .trim()
+                    .match(/^rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*([0-9.]+)\s*\)$/i);
+                if (!match)
+                    return null;
+                const parsed = Number.parseFloat(match[1] ?? "");
+                return Number.isFinite(parsed) ? parsed : null;
+            };
+            const isEffectivelyInvisibleOverlay = (el) => {
+                if (!domHelpers.isVisible(el))
+                    return true;
+                const style = window.getComputedStyle(el);
+                const opacity = Number.parseFloat(style.opacity);
+                if (Number.isFinite(opacity) && opacity === 0)
+                    return true;
+                const tag = el.tagName.toLowerCase();
+                const isFormControl = tag === "input" ||
+                    tag === "select" ||
+                    tag === "textarea" ||
+                    tag === "button";
+                if (isFormControl)
+                    return false;
+                const bg = style.backgroundColor;
+                const bgAlpha = bg === "transparent" ? 0 : (parseAlphaFromRgba(bg) ?? 1);
+                const hasOpaqueBackground = bgAlpha > 0;
+                const hasBackgroundImage = style.backgroundImage !== "none";
+                const hasShadow = style.boxShadow !== "none";
+                const hasOutline = Number.parseFloat(style.outlineWidth) > 0;
+                const borderWidths = [
+                    Number.parseFloat(style.borderTopWidth) || 0,
+                    Number.parseFloat(style.borderRightWidth) || 0,
+                    Number.parseFloat(style.borderBottomWidth) || 0,
+                    Number.parseFloat(style.borderLeftWidth) || 0,
+                ];
+                const hasBorder = borderWidths.some((w) => w > 0);
+                const hasVisibleFillOrStroke = hasOpaqueBackground ||
+                    hasBackgroundImage ||
+                    hasBorder ||
+                    hasShadow ||
+                    hasOutline;
+                if (hasVisibleFillOrStroke)
+                    return false;
+                const hasText = el.innerText.trim().length > 0;
+                if (hasText)
+                    return false;
+                return true;
+            };
+            const isInteractive = (el) => {
+                const tagName = el.tagName.toLowerCase();
+                const interactiveTags = [
+                    "a",
+                    "button",
+                    "input",
+                    "select",
+                    "textarea",
+                    "label",
+                ];
+                if (interactiveTags.includes(tagName))
+                    return true;
+                if (el.hasAttribute("onclick"))
+                    return true;
+                if (el.hasAttribute("tabindex")) {
+                    const tabindex = el.getAttribute("tabindex");
+                    if (tabindex && parseInt(tabindex, 10) >= 0)
+                        return true;
+                }
+                const role = el.getAttribute("role");
+                if (role === "button" || role === "link" || role === "menuitem") {
+                    return true;
+                }
+                return false;
+            };
+            const isDisabled = (el) => {
+                if (el.hasAttribute("disabled"))
+                    return true;
+                if (el.getAttribute("aria-disabled") === "true")
+                    return true;
+                return false;
+            };
+            const getRect = (el) => {
+                const rect = el.getBoundingClientRect();
+                if (rect.width <= 0 || rect.height <= 0)
+                    return null;
+                return rect;
+            };
+            const isInViewport = (rect) => {
+                return (rect.bottom > 0 &&
+                    rect.right > 0 &&
+                    rect.top < window.innerHeight &&
+                    rect.left < window.innerWidth);
+            };
+            const getSamplePoints = (rect) => {
+                const points = [];
+                const padding = 2;
+                const left = rect.left + padding;
+                const right = rect.right - padding;
+                const top = rect.top + padding;
+                const bottom = rect.bottom - padding;
+                if (left >= right || top >= bottom) {
+                    points.push({
+                        x: rect.left + rect.width / 2,
+                        y: rect.top + rect.height / 2,
+                    });
+                    return points;
+                }
+                const centerX = (left + right) / 2;
+                const centerY = (top + bottom) / 2;
+                points.push({ x: centerX, y: centerY });
+                points.push({ x: left, y: top });
+                points.push({ x: right, y: top });
+                points.push({ x: left, y: bottom });
+                points.push({ x: right, y: bottom });
+                points.push({ x: centerX, y: top });
+                points.push({ x: centerX, y: bottom });
+                points.push({ x: left, y: centerY });
+                points.push({ x: right, y: centerY });
+                return points.filter((p) => p.x >= 0 &&
+                    p.y >= 0 &&
+                    p.x < window.innerWidth &&
+                    p.y < window.innerHeight);
+            };
+            const isElementOrDescendant = (target, elementAtPoint) => {
+                if (!elementAtPoint)
+                    return false;
+                if (target === elementAtPoint)
+                    return true;
+                if (target.contains(elementAtPoint))
+                    return true;
+                if (elementAtPoint.contains(target))
+                    return true;
+                return false;
+            };
+            const allElements = scope.queryAll("*");
+            for (const el of allElements) {
+                if (!domHelpers.isHtmlElement(el))
+                    continue;
+                if (!isInteractive(el))
+                    continue;
+                if (!domHelpers.isVisible(el, { checkPointerEvents: true }))
+                    continue;
+                if (isDisabled(el))
+                    continue;
+                const clippingAncestor = domHelpers.findIntentionallyClippedAncestor(el);
+                if (clippingAncestor &&
+                    domHelpers.isElementClippedBy(el, clippingAncestor)) {
+                    continue;
+                }
+                const rect = getRect(el);
+                if (!rect)
+                    continue;
+                if (!isInViewport(rect))
+                    continue;
+                const samplePoints = getSamplePoints(rect);
+                if (samplePoints.length === 0)
+                    continue;
+                let obscuredCount = 0;
+                let totalChecked = 0;
+                let obscuringElement = null;
+                for (const point of samplePoints) {
+                    const elementAtPoint = document.elementFromPoint(point.x, point.y);
+                    totalChecked++;
+                    if (domHelpers.isHtmlElement(elementAtPoint)) {
+                        if (isLabelControlPair(el, elementAtPoint)) {
+                            continue;
+                        }
+                        if (isEffectivelyInvisibleOverlay(elementAtPoint)) {
+                            continue;
+                        }
+                    }
+                    if (!isElementOrDescendant(el, elementAtPoint)) {
+                        obscuredCount++;
+                        if (!obscuringElement &&
+                            elementAtPoint &&
+                            domHelpers.isHtmlElement(elementAtPoint)) {
+                            obscuringElement = elementAtPoint;
+                        }
+                    }
+                }
+                if (obscuredCount > 0 && totalChecked > 0) {
+                    const obscuredRatio = obscuredCount / totalChecked;
+                    if (obscuredRatio >= 0.5) {
+                        const percentage = Math.round(obscuredRatio * 100);
+                        if (obscuringElement) {
+                            report({
+                                message: `Interactive element is ~${percentage}% obscured and may not be clickable`,
+                                element: el,
+                                relations: [
+                                    {
+                                        description: "Obscuring element",
+                                        element: obscuringElement,
+                                    },
+                                ],
+                            });
+                        }
+                        else {
+                            report({
+                                message: `Interactive element is ~${percentage}% obscured and may not be clickable`,
+                                element: el,
+                            });
+                        }
+                    }
+                }
+            }
+        }, { domHelpers });
+    },
+});

package/dist/rules/misalignment.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Detects elements that appear to be intended for alignment but are slightly misaligned.
+ *
+ * Finds the closest alignment edge between siblings and reports only if that edge
+ * is in the "mistake range" - close enough that it looks like an alignment attempt
+ * but not quite aligned perfectly.
+ */
+declare const _default: import("viewlint").RuleDefinition<undefined>;
+export default _default;
+//# sourceMappingURL=misalignment.d.ts.map

package/dist/rules/misalignment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"misalignment.d.ts","sourceRoot":"","sources":["../../src/rules/misalignment.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;;AACH,wBA6LE"}

package/dist/rules/misalignment.js

@@ -0,0 +1,154 @@
+import { defineRule } from "viewlint/plugin";
+import { getDomHelpersHandle } from "../utils/getDomHelpersHandle.js";
+/**
+ * Detects elements that appear to be intended for alignment but are slightly misaligned.
+ *
+ * Finds the closest alignment edge between siblings and reports only if that edge
+ * is in the "mistake range" - close enough that it looks like an alignment attempt
+ * but not quite aligned perfectly.
+ */
+export default defineRule({
+    meta: {
+        severity: "warn",
+        docs: {
+            description: "Detects elements that should be aligned but are slightly off",
+            recommended: false,
+        },
+    },
+    async run(context) {
+        const domHelpers = await getDomHelpersHandle(context.page);
+        await context.evaluate(({ report, scope, args: { domHelpers } }) => {
+            const PERFECT_THRESHOLD = 1;
+            const MIN_MISALIGN = 2;
+            const MAX_MISALIGN = 6;
+            const MIN_ELEMENT_SIZE = 24;
+            const hasSize = (el) => {
+                return domHelpers.hasElementRectSize(el, MIN_ELEMENT_SIZE, MIN_ELEMENT_SIZE);
+            };
+            const isLayoutChild = (el) => {
+                const parent = el.parentElement;
+                if (!parent)
+                    return false;
+                const parentStyle = window.getComputedStyle(parent);
+                const display = parentStyle.display;
+                return display === "flex" || display === "inline-flex";
+            };
+            const getFlexDirection = (el) => {
+                const parent = el.parentElement;
+                if (!parent)
+                    return null;
+                const parentStyle = window.getComputedStyle(parent);
+                if (parentStyle.display !== "flex" &&
+                    parentStyle.display !== "inline-flex") {
+                    return null;
+                }
+                const dir = parentStyle.flexDirection;
+                return dir === "column" || dir === "column-reverse" ? "column" : "row";
+            };
+            /**
+             * Gets alignment offsets for edges that make sense given the flex direction.
+             * For row layouts: check vertical alignment (top, bottom, center-y)
+             * For column layouts: check horizontal alignment (left, right, center-x)
+             */
+            const getRelevantAlignments = (a, b, direction) => {
+                if (direction === "row") {
+                    return [
+                        { edge: "top", offset: Math.abs(a.top - b.top) },
+                        { edge: "bottom", offset: Math.abs(a.bottom - b.bottom) },
+                        {
+                            edge: "center-y",
+                            offset: Math.abs((a.top + a.bottom) / 2 - (b.top + b.bottom) / 2),
+                        },
+                    ];
+                }
+                return [
+                    { edge: "left", offset: Math.abs(a.left - b.left) },
+                    { edge: "right", offset: Math.abs(a.right - b.right) },
+                    {
+                        edge: "center-x",
+                        offset: Math.abs((a.left + a.right) / 2 - (b.left + b.right) / 2),
+                    },
+                ];
+            };
+            /**
+             * Finds misalignment only if:
+             * 1. One edge is clearly the "intended" alignment (closest)
+             * 2. But it's not quite perfect (in the mistake range)
+             * 3. No other edge is perfectly aligned
+             */
+            const findMisalignment = (a, b, direction) => {
+                const alignments = getRelevantAlignments(a, b, direction);
+                alignments.sort((x, y) => x.offset - y.offset);
+                const hasAnyPerfectAlignment = alignments.some((al) => al.offset <= PERFECT_THRESHOLD);
+                if (hasAnyPerfectAlignment)
+                    return null;
+                const closest = alignments[0];
+                if (!closest)
+                    return null;
+                if (closest.offset >= MIN_MISALIGN &&
+                    closest.offset <= MAX_MISALIGN) {
+                    return closest;
+                }
+                return null;
+            };
+            const reportedPairs = new Set();
+            const getSiblings = (el) => {
+                const parent = el.parentElement;
+                if (!parent)
+                    return [];
+                const siblings = [];
+                for (const child of parent.children) {
+                    if (child === el)
+                        continue;
+                    if (!domHelpers.isHtmlElement(child))
+                        continue;
+                    if (!domHelpers.isVisible(child))
+                        continue;
+                    if (!hasSize(child))
+                        continue;
+                    siblings.push(child);
+                }
+                return siblings;
+            };
+            const allElements = scope.queryAll("*");
+            for (const el of allElements) {
+                if (!domHelpers.isHtmlElement(el))
+                    continue;
+                if (!domHelpers.isVisible(el))
+                    continue;
+                if (!hasSize(el))
+                    continue;
+                if (!isLayoutChild(el))
+                    continue;
+                const direction = getFlexDirection(el);
+                if (!direction)
+                    continue;
+                const rect = el.getBoundingClientRect();
+                const siblings = getSiblings(el);
+                for (const sibling of siblings) {
+                    const siblingRect = sibling.getBoundingClientRect();
+                    const pairKey = [rect, siblingRect]
+                        .map((r) => `${r.left.toFixed(0)},${r.top.toFixed(0)}`)
+                        .sort()
+                        .join("|");
+                    if (reportedPairs.has(pairKey))
+                        continue;
+                    const misalignment = findMisalignment(rect, siblingRect, direction);
+                    if (!misalignment)
+                        continue;
+                    reportedPairs.add(pairKey);
+                    report({
+                        message: `Sibling elements misaligned: ${misalignment.edge} edges differ by ${Math.round(misalignment.offset)}px`,
+                        element: el,
+                        relations: [
+                            {
+                                description: "Misaligned sibling",
+                                element: sibling,
+                            },
+                        ],
+                    });
+                }
+            }
+        }, { domHelpers });
+    },
+});

package/dist/rules/overlapped-elements.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Detects elements that overlap unintentionally within the same layout context.
+ * - Elements must be visible in the viewport.
+ * - Elements positioned absolute/fixed are not candidates.
+ * - Overlap is only checked when both elements share the same nearest
+ *   absolute/fixed ancestor (or neither has one).
+ */
+declare const _default: import("viewlint").RuleDefinition<undefined>;
+export default _default;
+//# sourceMappingURL=overlapped-elements.d.ts.map

package/dist/rules/overlapped-elements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlapped-elements.d.ts","sourceRoot":"","sources":["../../src/rules/overlapped-elements.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;;AACH,wBAuRE"}