oh-my-opencode 5.1.51 → 5.1.55

package/packages/shared-skills/skills/frontend/scripts/detect/rules/source/support/markup-scope.ts

@@ -0,0 +1,44 @@
+import { jsPunctuation } from "./js-punctuation"
+
+export function tagAt(text: string, index: number): string {
+	for (const m of text.matchAll(/<[a-z][\w:.-]*(?:[^"'`{}>]|"[^"]*"|'[^']*'|`[^`]*`|\{(?:[^{}]|\{[^{}]*\})*\})*>/gi)) {
+		if ((m.index ?? 0) <= index && index <= (m.index ?? 0) + m[0].length) return m[0]
+	}
+	return text
+}
+
+export function exclusiveScopes(text: string): readonly string[] {
+	let question = -1
+	let paren = 0
+	let brace = 0
+	let colon = -1
+	let nested = 0
+	let end = text.length
+	for (const token of jsPunctuation(text)) {
+		const sameDepth = token.paren === paren && token.brace === brace
+		const isQuestion = token.ch === "?" && !/[?.]/.test(text[token.at - 1] ?? "") && !/[?.]/.test(text[token.at + 1] ?? "")
+		if (colon >= 0) {
+			if (token.ch === "," && sameDepth) { end = token.at; break }
+		} else if (question < 0 && isQuestion) {
+			question = token.at
+			paren = token.paren
+			brace = token.brace
+		} else if (question >= 0 && isQuestion && sameDepth) nested++
+		else if (question >= 0 && token.ch === ":" && sameDepth) {
+			if (nested > 0) nested--
+			else colon = token.at
+		}
+	}
+	if (question < 0 || colon < 0) return [text]
+	return [text.slice(question + 1, colon), text.slice(colon + 1, end)].flatMap((part) => exclusiveScopes(part).map((arm) => text.slice(0, question) + arm + text.slice(end)))
+}
+
+export function solidBackground(scope: string, gray = false): string | null {
+	for (const m of scope.matchAll(/\bbg-(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-(\d+)\b/g)) {
+		const at = m.index ?? 0
+		const prefix = scope.slice(0, at).split(/\s/).at(-1) ?? ""
+		const state = /(?:^|:)(?:!?hover|focus(?:-visible|-within)?|active|visited|disabled|checked|open|enabled|invalid|placeholder|group-[^:]*|peer-[^:]*|aria-[^:]*|data-[^:]*):$/.test(prefix)
+		if (scope[at + m[0].length] !== "/" && !state && (!gray || Number(m[1]) >= 200)) return m[0]
+	}
+	return null
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rules/source/support/source-color.ts

@@ -0,0 +1,42 @@
+import { parseColor, type Rgba } from "../../../core/color"
+
+const named: Readonly<Record<string, string>> = {
+	black: "#000", white: "#fff", gray: "#808080", grey: "#808080", silver: "#c0c0c0", dimgray: "#696969", dimgrey: "#696969", darkgray: "#a9a9a9", darkgrey: "#a9a9a9",
+	lightgray: "#d3d3d3", lightgrey: "#d3d3d3", gainsboro: "#dcdcdc", whitesmoke: "#f5f5f5", red: "#f00", blue: "#00f", green: "#008000", lime: "#0f0", yellow: "#ff0",
+	orange: "#ffa500", purple: "#800080", rebeccapurple: "#663399", pink: "#ffc0cb", teal: "#008080", cyan: "#0ff", aqua: "#0ff", magenta: "#f0f", fuchsia: "#f0f", coral: "#ff7f50", crimson: "#dc143c", navy: "#000080", maroon: "#800000", olive: "#808000",
+}
+
+export function authoredColor(value: string): Rgba | null {
+	const text = value.trim().toLowerCase()
+	const parsed = parseColor(named[text] ?? text)
+	if (parsed) return parsed
+	const match = /^(hsla?|hwb)\((.*)\)$/.exec(text)
+	if (!match) return null
+	const parts = (match[2] ?? "").replace(/[,/]/g, " ").split(/\s+/).filter(Boolean)
+	const hue = Number.parseFloat(parts[0] ?? "0") / (parts[0]?.endsWith("turn") ? 1 : parts[0]?.endsWith("rad") ? 2 * Math.PI : 360)
+	const s = Number.parseFloat(parts[1] ?? "0") / 100
+	const l = Number.parseFloat(parts[2] ?? "0") / 100
+	const alpha = parts[3]
+	const a = alpha === undefined ? 1 : Number.parseFloat(alpha) / (alpha.endsWith("%") ? 100 : 1)
+	const channel = (n: number): number => {
+		const k = ((n + hue * 12) % 12 + 12) % 12
+		return l - s * Math.min(l, 1 - l) * Math.max(-1, Math.min(k - 3, 9 - k, 1))
+	}
+	if (match[1] !== "hwb") return { r: channel(0) * 255, g: channel(8) * 255, b: channel(4) * 255, a }
+	if (s + l >= 1) return { r: 255 * s / (s + l), g: 255 * s / (s + l), b: 255 * s / (s + l), a }
+	const pure = authoredColor(`hsl(${hue * 360} 100% 50%)`)
+	return pure ? { r: pure.r * (1 - s - l) + 255 * s, g: pure.g * (1 - s - l) + 255 * s, b: pure.b * (1 - s - l) + 255 * s, a } : null
+}
+
+export function authoredColors(value: string): readonly Rgba[] {
+	return [...value.matchAll(/(?:rgba?|hsla?|hwb|color|oklab|oklch)\([^()]*\)|#[0-9a-f]{3,8}\b|\b[a-z]+\b/gi)].flatMap((m) => {
+		const color = authoredColor(m[0])
+		return color ? [color] : []
+	})
+}
+
+export function chromatic(value: string): boolean {
+	const color = authoredColor(value) ?? authoredColors(value)[0]
+	if (color) return color.a >= 0.1 && Math.max(color.r, color.g, color.b) - Math.min(color.r, color.g, color.b) >= 30
+	return !/\b(?:transparent|currentcolor|black|white|gr[ae]y|silver|gainsboro|whitesmoke)\b|url\(/i.test(value)
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rules/source/support/source-shadow.ts

@@ -0,0 +1,15 @@
+import { parseShadow, type ShadowLayer } from "../../../core/shadow"
+import { authoredColor } from "./source-color"
+
+export function sourceShadows(value: string, status = false): readonly ShadowLayer[] {
+	const filled = value.replace(/var\([^)]*\)|(?:rgba?|hsla?|hwb|color|oklab|oklch)\([^()]*\)|#[0-9a-f]{3,8}\b|\b[a-z]+\b(?!\s*\()/gi, (token) => {
+		if (token.toLowerCase() === "inset" || token.toLowerCase() === "px") return token
+		if (token.startsWith("var(")) {
+			const colored = /(?:^|-)(?:accent|kinpaku|patina|gold|red|orange|amber|yellow|lime|green|emerald|teal|cyan|blue|indigo|violet|purple|magenta|pink|rose|coral|aqua|mint|burgundy|crimson|scarlet)(?:-|[);])/i.test(token) || (status && /danger|error|warning|success|broken/.test(token))
+			return colored ? "#d0342c" : "#000"
+		}
+		const c = authoredColor(token)
+		return c ? `rgba(${c.r}, ${c.g}, ${c.b}, ${c.a})` : token
+	})
+	return parseShadow(filled)
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rules/source/support/source-text.ts

@@ -0,0 +1,110 @@
+import { extensionOf, lineAt, positionAt } from "../../../core/source"
+import type { SourceContext, SourceHit } from "../../../rule"
+
+export const sourceExtensions = ["css", "scss", "sass", "less", "js", "jsx", "ts", "tsx", "mjs", "cjs", "vue", "svelte", "astro"]
+export const componentExtensions = ["vue", "svelte", "astro"]
+export const sheetExtensions = ["css", "scss", "sass", "less"]
+export type SourcePass = { readonly text: string; readonly offset: number; readonly css: boolean; readonly sass: boolean }
+export type LineMatch = {
+	readonly match: RegExpMatchArray
+	readonly line: string
+	readonly scope: string
+	readonly offset: number
+	readonly pass: SourcePass
+	readonly source: string
+	readonly context: SourceContext
+}
+
+const blank = (text: string): string => text.replace(/[^\n\r]/g, " ")
+
+export function stripComments(text: string, script: boolean): string {
+	let out = ""
+	let quote = ""
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i] ?? ""
+		const next = text[i + 1]
+		if (quote) {
+			out += ch
+			if (ch === "\\") out += text[++i] ?? ""
+			else if (ch === quote) quote = ""
+			continue
+		}
+		if (ch === '"' || ch === "'" || (script && ch === "`")) {
+			quote = ch
+			out += ch
+		} else if (ch === "/" && next === "*") {
+			const end = text.indexOf("*/", i + 2)
+			const stop = end < 0 ? text.length : end + 2
+			out += blank(text.slice(i, stop))
+			i = stop - 1
+		} else if (ch === "/" && next === "/" && text[i - 1] !== ":") {
+			const end = text.indexOf("\n", i)
+			const stop = end < 0 ? text.length : end
+			out += blank(text.slice(i, stop))
+			i = stop - 1
+		} else if (text.startsWith("<!--", i)) {
+			const end = text.indexOf("-->", i + 4)
+			const stop = end < 0 ? text.length : end + 3
+			out += blank(text.slice(i, stop))
+			i = stop - 1
+		} else out += ch
+	}
+	return out
+}
+
+export function sourcePasses(context: SourceContext): readonly SourcePass[] {
+	const ext = extensionOf(context.file.path)
+	const css = sheetExtensions.includes(ext)
+	const text = stripComments(context.file.text, !css)
+	const passes: SourcePass[] = [{ text, offset: 0, css, sass: ext === "sass" }]
+	if (componentExtensions.includes(ext)) {
+		for (const m of text.matchAll(/<style\b([^>]*)>([\s\S]*?)<\/style\s*>/gi)) {
+			const body = m[2] ?? ""
+			passes.push({ text: stripComments(body, false), offset: (m.index ?? 0) + m[0].indexOf(">") + 1, css: true, sass: /\blang\s*=\s*["']sass["']/.test(m[1] ?? "") })
+		}
+	}
+	if (["js", "jsx", "ts", "tsx"].includes(ext)) {
+		for (const m of text.matchAll(/(?:\bstyled(?:\s*\([^`]*?\)|\.[\w.]+)(?:\([^`]*?\))?|\bcss|\bcreateGlobalStyle|<style\s+jsx[^>]*>\s*\{)\s*`([\s\S]*?)`/g)) {
+			const body = m[1] ?? ""
+			passes.push({ text: stripComments(body, false), offset: (m.index ?? 0) + m[0].indexOf("`") + 1, css: true, sass: false })
+		}
+	}
+	let source = text
+	for (const pass of passes.slice(1)) source = source.slice(0, pass.offset) + pass.text + source.slice(pass.offset + pass.text.length)
+	return [{ text: source, offset: 0, css, sass: ext === "sass" }, ...passes.slice(1)]
+}
+
+export function sourceHit(text: string, offset: number, message: string, snippet = lineAt(text, offset)): SourceHit {
+	return { ...positionAt(text, offset), message, snippet }
+}
+
+export function lineCheck(patterns: readonly RegExp[], test: (match: LineMatch) => string | null): (context: SourceContext) => readonly SourceHit[] {
+	return (context) => {
+		const hits: SourceHit[] = []
+		for (const pass of sourcePasses(context)) {
+			const lines = pass.text.split("\n")
+			let start = 0
+			for (const [i, line] of lines.entries()) {
+				const scope = pass.css ? lines.slice(Math.max(0, i - 3), i + 4).join(" ") : line
+				for (const pattern of patterns) {
+					for (const match of line.matchAll(pattern)) {
+						const offset = start + (match.index ?? 0)
+						const message = test({ match, line, scope, offset, pass, source: pass.text, context })
+						if (message === null) continue
+						const hit = sourceHit(context.file.text, pass.offset + offset, message, message)
+						if (!hits.some((h) => h.snippet === hit.snippet && Math.abs(h.line - hit.line) <= 2)) hits.push(hit)
+					}
+				}
+				start += line.length + 1
+			}
+		}
+		return hits
+	}
+}
+
+export function pageSource(context: SourceContext): string | null {
+	if (!componentExtensions.includes(extensionOf(context.file.path))) return null
+	return /<!doctype\s|<html[\s>]|<head[\s>]/i.test(context.file.text.replace(/<!--[\s\S]*?-->/g, "")) ? context.file.text : null
+}
+
+export const bodyText = (text: string): string => text.replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, " ").replace(/<!--[\s\S]*?-->/g, " ").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ")

package/packages/shared-skills/skills/frontend/scripts/detect/rules/typography/all-caps-body.test.ts

@@ -0,0 +1,24 @@
+import { expect, test } from "bun:test"
+import { buildSnapshot } from "../../testing/build-snapshot"
+import { allCapsBody } from "./all-caps-body"
+
+test("#given sentence-length uppercase prose and short labels #then only prose is flagged", () => {
+	const snapshot = buildSnapshot([
+		{ id: "paragraph", tag: "p", text: "Reading copy ".repeat(8), style: { "text-transform": "uppercase" } },
+		{ id: "blurb", text: "A product blurb with more than eighty characters. ".repeat(3), style: { "text-transform": "uppercase" } },
+		{ id: "short", text: "A short kicker", style: { "text-transform": "uppercase" } },
+		{ id: "heading", tag: "h2", text: "Reading copy ".repeat(8), style: { "text-transform": "uppercase" } },
+		{ id: "normal", text: "Reading copy ".repeat(8) },
+		{ id: "parent", text: "Short bar label", style: { "text-transform": "uppercase" }, children: [{ text: "Child copy ".repeat(8) }] },
+	])
+	expect(allCapsBody.check({ snapshot, config: {} }).map(h => h.element?.selector)).toEqual(["#paragraph", "#blurb"])
+})
+
+test("#given eighty-character boundary and hidden text #then only the visible boundary reports", () => {
+	const snapshot = buildSnapshot([
+		{ id: "floor", text: "a".repeat(80), style: { "text-transform": "uppercase" } },
+		{ id: "below", text: "a".repeat(79), style: { "text-transform": "uppercase" } },
+		{ id: "hidden", text: "a".repeat(80), style: { "text-transform": "uppercase", display: "none" } },
+	])
+	expect(allCapsBody.check({ snapshot, config: {} }).map(h => h.element?.selector)).toEqual(["#floor"])
+})

package/packages/shared-skills/skills/frontend/scripts/detect/rules/typography/all-caps-body.ts

@@ -0,0 +1,15 @@
+import { isHeading, shortSnippet, styleOf } from "../../core/page"
+import type { PageRule } from "../../rule"
+import { visibleText } from "./support/text-context"
+
+export const allCapsBody: PageRule = {
+	meta: {
+		id: "all-caps-body", name: "All-caps body text", category: "quality", severity: "warning", engine: "page",
+		description: "Uppercase sentences lose the word shapes readers use to scan prose.",
+		fixHint: "Set running copy in sentence case; keep uppercase for headings and short labels.",
+	},
+	check: ({ snapshot }) => snapshot.elements.filter(e =>
+		visibleText(snapshot, e) && isHeading(e) === false && styleOf(e, "text-transform") === "uppercase" &&
+		e.ownText.trim().replace(/\s+/g, " ").length >= 80)
+		.map(element => ({ element, message: "Uppercase on 80 or more characters of body copy", snippet: shortSnippet(element) })),
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rules/typography/design-system-font-size.test.ts

@@ -0,0 +1,21 @@
+import { expect, test } from "bun:test"
+import { buildSnapshot } from "../../testing/build-snapshot"
+import { designSystemFontSize } from "./design-system-font-size"
+
+test("#given a size ramp with near-token and duplicate sizes #then unique off-ramp sizes report", () => {
+	const snapshot = buildSnapshot([
+		{ text: "Token", style: { "font-size": "16px" } },
+		{ text: "Tolerated", style: { "font-size": "16.5px" } },
+		{ id: "off", text: "Off ramp", style: { "font-size": "17px" } },
+		{ text: "Duplicate", style: { "font-size": "17px" } },
+		{ text: "Hidden", style: { "font-size": "19px", visibility: "hidden" } },
+	])
+	expect(designSystemFontSize.check({ snapshot, config: { designTokens: { fontSizes: [16, 24] } } }).map(h => h.element?.selector)).toEqual(["#off"])
+})
+
+test("#given no size ramp #then sizes are not judged", () => {
+	const snapshot = buildSnapshot([{ text: "Off ramp", style: { "font-size": "17px" } }])
+	expect(designSystemFontSize.check({ snapshot, config: {} })).toEqual([])
+	expect(designSystemFontSize.check({ snapshot, config: { designTokens: { fontSizes: [] } } })).toEqual([])
+	expect(designSystemFontSize.check({ snapshot, config: { designTokens: { fontSizes: [16] } } })).toHaveLength(1)
+})

package/packages/shared-skills/skills/frontend/scripts/detect/rules/typography/design-system-font-size.ts

@@ -0,0 +1,23 @@
+import { fontSizePx, shortSnippet } from "../../core/page"
+import type { PageRule } from "../../rule"
+import { visibleText } from "./support/text-context"
+
+export const designSystemFontSize: PageRule = {
+	meta: {
+		id: "design-system-font-size", name: "Font size outside DESIGN.md", category: "quality", severity: "advisory", engine: "page",
+		description: "A rendered font size is outside the configured type ramp.",
+		fixHint: "Use a configured size token or add the intentional step to designTokens.fontSizes.",
+	},
+	check: ({ snapshot, config }) => {
+		const allowed = config.designTokens?.fontSizes
+		if (allowed === undefined || allowed.length === 0) return []
+		const seen = new Set<number>()
+		return snapshot.elements.flatMap(element => {
+			const size = fontSizePx(element)
+			if (visibleText(snapshot, element) === false || element.ownText.trim() === "" ||
+				size <= 0 || allowed.some(n => Math.abs(n - size) <= 0.5) || seen.has(size)) return []
+			seen.add(size)
+			return [{ element, message: `${size}px is outside configured type ramp`, snippet: shortSnippet(element) }]
+		})
+	},
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rules/typography/design-system-font.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from "bun:test"
+import { buildSnapshot } from "../../testing/build-snapshot"
+import { designSystemFont } from "./design-system-font"
+
+test("#given declared fonts, off-system duplicates and quoted commas #then unique undeclared families report", () => {
+	const snapshot = buildSnapshot([
+		{ text: "Allowed font", style: { "font-family": "Georgia, serif" } },
+		{ id: "off", text: "Different font", style: { "font-family": "Comic Sans MS, cursive" } },
+		{ text: "Same different font", style: { "font-family": '"Comic Sans MS", cursive' } },
+		{ text: "Comma family", style: { "font-family": '"Foo, Bar", serif' } },
+		{ text: "Platform only", style: { "font-family": "system-ui, sans-serif" } },
+		{ text: "Invisible", style: { "font-family": "Hidden Face", display: "none" } },
+	])
+	expect(designSystemFont.check({ snapshot, config: { designTokens: { fonts: ["GEORGIA", "Foo, Bar"] } } }).map(h => h.element?.selector)).toEqual(["#off"])
+})
+
+test("#given absent font tokens #then no font drift is inferred", () => {
+	const snapshot = buildSnapshot([{ text: "Different font", style: { "font-family": "Comic Sans MS" } }])
+	expect(designSystemFont.check({ snapshot, config: {} })).toEqual([])
+	expect(designSystemFont.check({ snapshot, config: { designTokens: { fonts: [] } } })).toEqual([])
+	expect(designSystemFont.check({ snapshot, config: { designTokens: { fonts: ["Georgia"] } } })).toHaveLength(1)
+})

package/packages/shared-skills/skills/frontend/scripts/detect/rules/typography/design-system-font.ts

@@ -0,0 +1,24 @@
+import { shortSnippet, styleOf } from "../../core/page"
+import type { PageRule } from "../../rule"
+import { normalizeFont, primaryFont } from "./support/font-family"
+import { visibleText } from "./support/text-context"
+
+export const designSystemFont: PageRule = {
+	meta: {
+		id: "design-system-font", name: "Font outside DESIGN.md", category: "quality", severity: "warning", engine: "page",
+		description: "A text face is absent from the configured typography tokens.",
+		fixHint: "Use a configured font token or add the intentional face to designTokens.fonts.",
+	},
+	check: ({ snapshot, config }) => {
+		const allowed = config.designTokens?.fonts?.map(normalizeFont)
+		if (allowed === undefined || allowed.length === 0) return []
+		const seen = new Set<string>()
+		return snapshot.elements.flatMap(element => {
+			const family = primaryFont(styleOf(element, "font-family"), true)
+			if (visibleText(snapshot, element) === false || element.ownText.trim() === "" ||
+				family === "" || allowed.includes(family) || seen.has(family)) return []
+			seen.add(family)
+			return [{ element, message: `Font ${family} is outside configured tokens`, snippet: shortSnippet(element) }]
+		})
+	},
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rules/typography/extreme-negative-tracking.test.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "bun:test"
+import { buildSnapshot } from "../../testing/build-snapshot"
+import { extremeNegativeTracking } from "./extreme-negative-tracking"
+
+test("#given crushed reading and display tracking with optical controls #then only crushed runs report", () => {
+	const snapshot = buildSnapshot([
+		{ id: "body", text: "Tracking crushed paragraph that still needs to read.", style: { "font-size": "16px", "letter-spacing": "-1.28px" } },
+		{ id: "small", text: "Tracking crushed paragraph in a smaller face.", style: { "font-size": "14px", "letter-spacing": "-1.4px" } },
+		{ id: "display", tag: "h2", text: "Tracking crushed display heading variant", style: { "font-size": "48px", "letter-spacing": "-4.8px" } },
+		{ id: "optical", text: "Optically tightened display headline", style: { "font-size": "72px", "letter-spacing": "-4.32px" } },
+		{ id: "body-floor", text: "Tracking at the exact reading-size limit", style: { "font-size": "16px", "letter-spacing": "-1.12px" } },
+		{ id: "display-floor", text: "Tracking at the exact display-size limit", style: { "font-size": "40px", "letter-spacing": "-3.6px" } },
+		{ id: "cjk", text: "この段落は日本語の文字組みで、字間を詰めても文字の形は崩れません。", style: { "font-size": "18px", "letter-spacing": "-1.8px" } },
+	])
+	expect(extremeNegativeTracking.check({ snapshot, config: {} }).map(h => h.element?.selector)).toEqual(["#body", "#small", "#display"])
+})
+
+test("#given short or hidden crushed text beside visible prose #then only prose reports", () => {
+	const style = { "letter-spacing": "-2px" }
+	const snapshot = buildSnapshot([{ id: "flag", text: "A visible paragraph longer than twenty characters.", style },
+		{ text: "Short", style }, { text: "A hidden paragraph longer than twenty characters.", style: { ...style, opacity: "0" } }])
+	expect(extremeNegativeTracking.check({ snapshot, config: {} }).map(h => h.element?.selector)).toEqual(["#flag"])
+})

package/packages/shared-skills/skills/frontend/scripts/detect/rules/typography/extreme-negative-tracking.ts

@@ -0,0 +1,18 @@
+import { fontSizePx, px, shortSnippet, styleOf } from "../../core/page"
+import type { PageRule } from "../../rule"
+import { cjk, visibleText } from "./support/text-context"
+
+export const extremeNegativeTracking: PageRule = {
+	meta: {
+		id: "extreme-negative-tracking", name: "Crushed letter spacing", category: "slop", severity: "warning", engine: "page",
+		description: "Negative tracking beyond the reading or display threshold damages letter shapes.",
+		fixHint: "Keep tracking at or above -0.07em for reading text and -0.09em for display type.",
+	},
+	check: ({ snapshot }) => snapshot.elements.flatMap(element => {
+		const size = fontSizePx(element)
+		const tracking = (px(styleOf(element, "letter-spacing")) ?? 0) / size
+		if (visibleText(snapshot, element) === false || element.ownText.length <= 10 || element.text.length <= 20 ||
+			size <= 0 || tracking >= (size >= 40 ? -0.09 : -0.07) || cjk(element.text)) return []
+		return [{ element, message: `Letter spacing ${tracking.toFixed(2)}em at ${size}px`, snippet: shortSnippet(element) }]
+	}),
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rules/typography/flat-type-hierarchy.test.ts

@@ -0,0 +1,33 @@
+import { expect, test } from "bun:test"
+import { buildSnapshot } from "../../testing/build-snapshot"
+import { flatTypeHierarchy } from "./flat-type-hierarchy"
+
+const nodes = (tag: string, size: number, count = 1) => Array.from({ length: count }, () => ({
+	tag, text: "Ordinary visible text for this role", style: { "font-size": `${size}px` },
+}))
+const check = (specs: Parameters<typeof buildSnapshot>[0]) => flatTypeHierarchy.check({ snapshot: buildSnapshot(specs), config: {} })
+
+test("#given compressed roles and a strong ramp #then only the compressed hierarchy reports", () => {
+	expect(check([...nodes("h1", 18), ...nodes("h2", 16), ...nodes("h3", 15), ...nodes("p", 14)])).toHaveLength(1)
+	expect(check([...nodes("h1", 48), ...nodes("h2", 30), ...nodes("h3", 22), ...nodes("p", 16)])).toEqual([])
+	expect(check([...nodes("h1", 16), ...nodes("p", 16)])).toEqual([])
+})
+
+test("#given tied h1 sizes and an h1 label #then neither flattens the visible ladder", () => {
+	expect(check([...nodes("h1", 66.56), ...nodes("h1", 48.64), ...nodes("h2", 18.4, 4), ...nodes("h3", 20.8, 4), ...nodes("p", 17, 3)])).toEqual([])
+	expect(check([...nodes("h1", 14), ...nodes("h2", 15, 3), ...nodes("p", 16, 3)])).toEqual([])
+	expect(check([...nodes("h1", 16), ...nodes("h2", 15, 3), ...nodes("p", 16, 3)])).toHaveLength(1)
+})
+
+test("#given dropped heading roles #then their possible sizes must not break the ladder", () => {
+	const base = [...nodes("h1", 16), ...nodes("h2", 16, 3), ...nodes("p", 14, 4)]
+	expect(check([...base, ...nodes("h3", 14, 3), ...nodes("h3", 16, 3), ...nodes("h3", 20, 3)])).toEqual([])
+	expect(check([...nodes("h1", 18), ...nodes("h3", 16), ...nodes("p", 16, 6), ...nodes("h2", 17, 3), ...nodes("h2", 18, 3)])).toHaveLength(1)
+})
+
+test("#given near-tied heading sizes and body chips #then only settled text roles determine flatness", () => {
+	expect(check([...nodes("h1", 16), ...nodes("p", 16, 12), ...nodes("h2", 16, 12), ...nodes("h2", 24, 10), ...nodes("h3", 18, 3)])).toEqual([])
+	expect(check([...nodes("h1", 18), ...nodes("h2", 16), ...nodes("p", 16, 3),
+		...Array.from({ length: 20 }, () => ({ tag: "td", text: "GG", style: { "font-size": "24px" } })),
+	])).toHaveLength(1)
+})

package/packages/shared-skills/skills/frontend/scripts/detect/rules/typography/flat-type-hierarchy.ts

@@ -0,0 +1,26 @@
+import { childrenOf, fontSizePx, isHeading } from "../../core/page"
+import type { PageRule } from "../../rule"
+import { readingTags, visibleText } from "./support/text-context"
+import { flatHierarchy } from "./support/type-hierarchy"
+
+export const flatTypeHierarchy: PageRule = {
+	meta: {
+		id: "flat-type-hierarchy", name: "Flat type hierarchy", category: "slop", severity: "warning", engine: "page",
+		description: "Heading and body roles have no adjacent size step of at least 1.25.",
+		fixHint: "Add a stronger size step between at least two heading or body roles.",
+	},
+	check: ({ snapshot }) => {
+		const sampled = (tag: string): boolean => /^h[1-6]$/.test(tag) || readingTags.includes(tag)
+		const ownChars = (e: (typeof snapshot.elements)[number]): number =>
+			e.ownText.replace(/\s/g, "").length + childrenOf(snapshot, e)
+				.filter(n => sampled(n.tag) === false && visibleText(snapshot, n))
+				.reduce((count, n) => count + ownChars(n), 0)
+		const samples = snapshot.elements.filter(e => sampled(e.tag) && e.text.trim() !== "" && visibleText(snapshot, e) &&
+			fontSizePx(e) >= 8 && fontSizePx(e) < 200 &&
+			(isHeading(e) || [1, 2].includes(ownChars(e)) === false))
+			.map(e => ({ role: isHeading(e) ? e.tag : "body", size: fontSizePx(e), weight: Number.parseFloat(e.style["font-weight"] ?? "400") }))
+		const roles = flatHierarchy(samples)
+		if (roles.length === 0) return []
+		return [{ element: null, message: `Flat role sizes: ${roles.map(([r, size]) => `${r} ${size}px`).join(", ")}`, snippet: "All adjacent type steps are below 1.25" }]
+	},
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rules/typography/index.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "../../rule"
+import { allCapsBody } from "./all-caps-body"
+import { designSystemFont } from "./design-system-font"
+import { designSystemFontSize } from "./design-system-font-size"
+import { extremeNegativeTracking } from "./extreme-negative-tracking"
+import { flatTypeHierarchy } from "./flat-type-hierarchy"
+import { italicSerifDisplay } from "./italic-serif-display"
+import { justifiedText } from "./justified-text"
+import { lineLength } from "./line-length"
+import { oversizedH1 } from "./oversized-h1"
+import { overusedFont } from "./overused-font"
+import { tightLeading } from "./tight-leading"
+import { tinyText } from "./tiny-text"
+import { undersizedUiText } from "./undersized-ui-text"
+import { wideTracking } from "./wide-tracking"
+
+export const TYPOGRAPHY_RULES: readonly Rule[] = [
+	overusedFont, flatTypeHierarchy, italicSerifDisplay, oversizedH1, extremeNegativeTracking,
+	tinyText, undersizedUiText, allCapsBody, wideTracking, tightLeading, justifiedText,
+	lineLength, designSystemFont, designSystemFontSize,
+]

package/packages/shared-skills/skills/frontend/scripts/detect/rules/typography/italic-serif-display.test.ts

@@ -0,0 +1,24 @@
+import { expect, test } from "bun:test"
+import { buildSnapshot } from "../../testing/build-snapshot"
+import { italicSerifDisplay } from "./italic-serif-display"
+
+test("#given italic serif heroes and roman or sans controls #then only serif heroes report", () => {
+	const snapshot = buildSnapshot([
+		...["Fraunces", "Recoleta", "Playfair Display", "CustomSerifFace"].map((f, i) =>
+			({ id: `flag-${i}`, tag: "h1", text: "Display heading", style: { "font-size": "56px", "font-style": "italic", "font-family": `"${f}", serif` } })),
+		{ tag: "h1", text: "Sans Italic Display", style: { "font-family": "Karla, sans-serif", "font-size": "64px", "font-style": "italic" } },
+		{ tag: "h1", text: "Roman Serif Display", style: { "font-family": "Fraunces, serif", "font-size": "88px" } },
+		{ tag: "blockquote", text: "Pull quote", style: { "font-family": "Georgia, serif", "font-size": "64px", "font-style": "italic" } },
+		{ tag: "h2", text: "Small italic heading", style: { "font-size": "32px", "font-style": "italic" } },
+	])
+	expect(italicSerifDisplay.check({ snapshot, config: {} }).map(h => h.element?.selector)).toEqual(["#flag-0", "#flag-1", "#flag-2", "#flag-3"])
+})
+
+test("#given several italic descendants in one roman heading #then one heading finding reports", () => {
+	const style = { "font-size": "72px", "font-style": "italic", "font-family": "Georgia, serif" }
+	const snapshot = buildSnapshot([
+		{ id: "hero", tag: "h1", children: [{ tag: "em", text: "One", style }, { tag: "em", text: "Two", style }] },
+		{ tag: "h1", children: [{ tag: "em", text: "Invisible", style: { ...style, display: "none" } }] },
+	])
+	expect(italicSerifDisplay.check({ snapshot, config: {} }).map(h => h.element?.selector)).toEqual(["#hero"])
+})

package/packages/shared-skills/skills/frontend/scripts/detect/rules/typography/italic-serif-display.ts

@@ -0,0 +1,24 @@
+import { descendants, fontSizePx, shortSnippet, styleOf } from "../../core/page"
+import type { PageRule } from "../../rule"
+import { visibleText } from "./support/text-context"
+import { primaryFont } from "./support/font-family"
+
+const serifNames = ["fraunces", "recoleta", "newsreader", "playfair display", "playfair", "cormorant", "cormorant garamond", "garamond", "eb garamond", "tiempos", "tiempos headline", "tiempos text", "lora", "vollkorn", "spectral", "source serif pro", "source serif 4", "source serif", "ibm plex serif", "merriweather", "libre caslon", "libre baskerville", "baskerville", "georgia", "times new roman", "times", "dm serif display", "dm serif text", "instrument serif", "gt sectra", "ogg", "canela", "freight display", "freight text"]
+
+export const italicSerifDisplay: PageRule = {
+	meta: {
+		id: "italic-serif-display", name: "Italic serif display headline", category: "slop", severity: "warning", engine: "page",
+		description: "An italic serif at hero scale repeats a common landing-page treatment.",
+		fixHint: "Use roman type or a non-serif display face unless the brief calls for editorial typography.",
+	},
+	check: ({ snapshot }) => snapshot.elements.flatMap(element => {
+		if (["h1", "h2"].includes(element.tag) === false || visibleText(snapshot, element) === false) return []
+		const italic = [element, ...descendants(snapshot, element)].some(n => {
+			const families = styleOf(n, "font-family").toLowerCase().split(",").map(f => f.trim().replace(/^['"]|['"]$/g, ""))
+			const primary = primaryFont(styleOf(n, "font-family"), true)
+			return visibleText(snapshot, n) && n.ownText.trim() !== "" && styleOf(n, "font-style") === "italic" &&
+				fontSizePx(n) >= 48 && primary !== "" && (serifNames.includes(primary) || families.includes("serif"))
+		})
+		return italic ? [{ element, message: "Italic serif heading at 48px or larger", snippet: shortSnippet(element) }] : []
+	}),
+}

package/packages/shared-skills/skills/frontend/scripts/detect/rules/typography/justified-text.test.ts

@@ -0,0 +1,31 @@
+import { expect, test } from "bun:test"
+import { buildSnapshot } from "../../testing/build-snapshot"
+import { justifiedText } from "./justified-text"
+
+test("#given narrow justified columns and wide, hyphenated or script controls #then only narrow Latin prose reports", () => {
+	const text = "Forcing every line of a narrow column to the same width stretches the spaces between words."
+	const style = { "text-align": "justify", "line-height": "24px" }
+	const lineRects = [{ x: 0, y: 0, width: 300, height: 18 }, { x: 0, y: 24, width: 280, height: 18 }]
+	const snapshot = buildSnapshot([
+		{ id: "narrow", tag: "p", text, style, rect: { width: 300 }, lineRects },
+		{ id: "manual", tag: "p", text, style: { ...style, hyphens: "manual" }, rect: { width: 260 }, lineRects },
+		{ tag: "p", text, style, rect: { width: 760 }, lineRects },
+		{ tag: "p", text, style: { ...style, hyphens: "auto" }, rect: { width: 300 }, lineRects },
+		{ tag: "p", text: "永慶房屋專注本業堅持創新提供消費者透明的資訊與安心的服務", style, lineRects },
+		{ tag: "p", text: "การจัดวางข้อความแบบชิดขอบทั้งสองด้านในภาษาไทย", style, lineRects },
+		{ tag: "p", text: "يعتمد ضبط النص في الخط العربي على استطالة الحروف على السطر", style, lineRects },
+		{ tag: "h4", text: "Research topics", style, rect: { width: 300 }, lineRects: [lineRects[0] ?? { x: 0, y: 0, width: 100, height: 18 }] },
+	])
+	expect(justifiedText.check({ snapshot, config: {} }).map(h => h.element?.selector)).toEqual(["#narrow", "#manual"])
+})
+
+test("#given inline text inheriting justification #then the containing block supplies the measure", () => {
+	const text = "Wrapping the whole paragraph in a span changes nothing about the narrow measure it occupies."
+	const style = { "text-align": "justify", "line-height": "24px" }
+	const lineRects = [{ x: 0, y: 0, width: 280, height: 18 }, { x: 0, y: 24, width: 260, height: 18 }]
+	const snapshot = buildSnapshot([
+		{ rect: { width: 280 }, style, children: [{ id: "span", tag: "span", text, style, lineRects }] },
+		{ rect: { width: 760 }, style, text: "A paragraph with text of its own.", children: [{ tag: "a", text, style, lineRects }] },
+	])
+	expect(justifiedText.check({ snapshot, config: {} }).map(h => h.element?.selector)).toEqual(["#span"])
+})

package/packages/shared-skills/skills/frontend/scripts/detect/rules/typography/justified-text.ts

@@ -0,0 +1,32 @@
+import { ancestors, fontSizePx, px, shortSnippet, styleOf } from "../../core/page"
+import type { PageRule } from "../../rule"
+import { letters, visibleText } from "./support/text-context"
+import { mergedLines, phrasingNodes } from "./support/text-lines"
+
+export const justifiedText: PageRule = {
+	meta: {
+		id: "justified-text", name: "Justified text", category: "quality", severity: "warning", engine: "page",
+		description: "Narrow justified columns without automatic hyphenation stretch word spaces into gaps.",
+		fixHint: "Align text left, widen the column, or enable hyphens: auto.",
+	},
+	check: ({ snapshot }) => snapshot.elements.flatMap(element => {
+		if (visibleText(snapshot, element) === false || element.ownText.length <= 10 ||
+			styleOf(element, "text-align") !== "justify" || styleOf(element, "hyphens") === "auto") return []
+		let block = element
+		if (styleOf(element, "display") === "inline") {
+			const ancestor = [...ancestors(snapshot, element)].find(n => ["inline", "contents"].includes(styleOf(n, "display")) === false)
+			if (ancestor === undefined || ancestor.ownText.length > 10) return []
+			block = ancestor
+		}
+		const size = fontSizePx(element)
+		if (size <= 0 || block.rect.width <= 0 || block.rect.width / (size * 0.5) > 45) return []
+		const lines = mergedLines(phrasingNodes(snapshot, block))
+		const first = lines[0]
+		if (first && Math.max(...lines.map(l => l.y + l.height)) - first.y <
+			(px(styleOf(block, "line-height")) ?? size * 1.2) + size * 0.75) return []
+		const chars = letters([...element.ownText].slice(0, 400).join(""))
+		const exempt = chars.filter(c => /[\u0600-\u06ff\u0750-\u077f\u08a0-\u08ff\u0e00-\u0e7f\u1100-\u11ff\u2e80-\u9fff\ua960-\ud7ff\uf900-\ufaff\ufb50-\ufdff\ufe70-\ufeff\uff66-\uff9f\u{20000}-\u{3134f}]/u.test(c)).length
+		if (exempt * 2 > chars.length) return []
+		return [{ element, message: "Narrow justified text without automatic hyphenation", snippet: shortSnippet(element) }]
+	}),
+}