Files
opencode/script/check-greys.ts
T

171 lines
6.6 KiB
TypeScript

#!/usr/bin/env bun
// Keeps the web surfaces' greys on one shared scale. Fails when a stylesheet uses a grey, black or
// white that isn't on the scale, or types a scale grey straight into a rule instead of using a
// token. Files with a fixed look of their own (the arcade, the video tools, print) are listed in
// EXCEPTIONS with the reason. Usage:
// bun script/check-greys.ts report problems, exit 1 if any
// bun script/check-greys.ts --json every neutral literal with its outcome, for the colour audit
import path from "node:path"
const ROOTS = ["services/site/src", "packages/nav-menus/src", "packages/data/app/src"]
// The shared neutral scale. A step is a role, and the same step does the same job in light and dark.
const SCALE = {
light: [
"#fbfbfb",
"#ffffff",
"#f5f5f5",
"#eeeeee",
"#e0e0e0",
"#d2d2d2",
"#888888",
"#6b6b6b",
"#5c5c5c",
"#3a3a3a",
"#161616",
],
dark: [
"#0c0c0c",
"#161616",
"#1a1a1a",
"#242424",
"#2e2e2e",
"#4b4b4b",
"#6a6a6a",
"#8f8f8f",
"#aeaeae",
"#dbdbdb",
"#fafafa",
],
}
// Pure black and white always pass in masks (where #000 only means "opaque") and shadows.
const ALPHA_CONTEXT = /^(mask|-webkit-mask|box-shadow|text-shadow|filter|backdrop-filter|--[\w-]*shadow)/
const EXCEPTIONS: [RegExp, string][] = [
[/component\/site\/arcade\//, "Arcade game: its own cabinet, screen and metal colours"],
[/component\/site\/arcade3d\//, "Arcade game: its own cabinet, screen and metal colours"],
[/component\/video-editor\//, "Internal video editor"],
[/component\/font-film\//, "Font film: rendered video frames"],
[/component\/font-share\//, "Font share cards: exported images"],
[/component\/site\/device-preview\.css$/, "Device preview tool: device frames"],
[/component\/site\/design-mode\.css$/, "Design mode: internal overlay"],
[/component\/site\/legal-print\.css$/, "Print: black on white whatever the theme"],
[
/style\/token\/color\.css$/,
"Legacy tokens: to remove when the dropdown, language picker, 404 and limits graph move to site tokens",
],
]
// Pure black is a token only for video letterboxing (--media-black).
const scale = new Set([...SCALE.light, ...SCALE.dark, "#000000"])
const files = (
await Promise.all(ROOTS.map((root) => Array.fromAsync(new Bun.Glob(`${root}/**/*.css`).scan({ cwd: repo() }))))
).flat()
const entries = (
await Promise.all(
files.map(async (file) => {
const source = await Bun.file(path.join(repo(), file)).text()
const exception = EXCEPTIONS.find(([re]) => re.test(file))?.[1]
const allowed = allowedRanges(source)
return declarations(source).flatMap((decl) =>
neutrals(decl.value).map((hex) => ({
file,
line: decl.line,
property: decl.property,
hex: hex.value,
alpha: hex.alpha,
text: `${decl.property}: ${decl.value}`.replace(/\s+/g, " ").slice(0, 160),
outcome: outcome(
decl,
hex,
exception ?? allowed.find((range) => decl.line >= range.from && decl.line <= range.to)?.why,
),
})),
)
}),
)
).flat()
if (process.argv.includes("--json")) {
console.log(JSON.stringify({ scale: SCALE, exceptions: EXCEPTIONS.map(([re, why]) => [re.source, why]), entries }))
process.exit(0)
}
const problems = entries.filter((entry) => entry.outcome.startsWith("problem"))
for (const p of problems) console.error(`${p.file}:${p.line} ${p.hex} ${p.outcome.slice(9)} (${p.text})`)
if (problems.length) {
console.error(
`\n${problems.length} grey${problems.length === 1 ? "" : "s"} off the shared scale (script/check-greys.ts).`,
)
process.exit(1)
}
function outcome(
decl: { property: string; value: string },
hex: { value: string; alpha: boolean },
exception: string | undefined,
) {
const pure = hex.value === "#000000" || hex.value === "#ffffff"
if (exception) return `exception: ${exception}`
if (/^--([a-z]+-)?logo-/.test(decl.property)) return "exception: Brand logo greys (brand guidelines)"
if (ALPHA_CONTEXT.test(decl.property) && pure) return "allowed: mask or shadow"
if (hex.alpha && pure) return "allowed: black or white wash"
if (pure && /color-mix\(.*#(000|fff)\b/i.test(decl.value)) return "allowed: shades a colour"
if (!scale.has(hex.value)) return "problem: not on the scale"
if (decl.property.startsWith("--") || decl.property === "initial-value") return "token"
return "problem: use a token"
}
// Lines between `/* grey-ok: <reason> */` and `/* grey-ok-end */` keep their literal greys, for the
// few places tokens can't reach, such as the page behind the site.
function allowedRanges(source: string) {
const lines = source.split("\n")
return lines.flatMap((line, i) => {
const why = line.match(/grey-ok:\s*(.*?)\s*\*\//)?.[1]
if (!why) return []
const end = lines.findIndex((next, j) => j > i && next.includes("grey-ok-end"))
return [{ from: i + 1, to: end === -1 ? i + 1 : end + 1, why }]
})
}
// Every declaration with its property and the line it starts on. Comments are blanked first, keeping
// line numbers.
function declarations(source: string) {
const text = source.replace(/\/\*[\s\S]*?\*\//g, (comment) => comment.replace(/[^\n]/g, " "))
return [...text.matchAll(/([\w-]+)\s*:([^;{}]+)/g)]
.filter((m) => /#[0-9a-fA-F]|hsl|rgb/.test(m[2]))
.map((m) => ({ property: m[1], value: m[2].trim(), line: text.slice(0, m.index).split("\n").length }))
}
// Neutral colour literals in a value: hex, hsl() with 0% saturation, and rgb() with equal channels.
function neutrals(value: string) {
return [
...[...value.matchAll(/#([0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b/g)].map((m) => {
const h = m[1].length <= 4 ? [...m[1]].map((c) => c + c).join("") : m[1]
return { value: `#${h.slice(0, 6).toLowerCase()}`, alpha: h.length === 8 }
}),
...[...value.matchAll(/hsla?\(\s*[\d.]+(?:deg)?[\s,]+0%[\s,]+([\d.]+)%\s*(?:[,/]\s*([\d.]+%?))?\s*\)/g)].map(
(m) => {
const v = Math.round((Number(m[1]) / 100) * 255)
.toString(16)
.padStart(2, "0")
return { value: `#${v}${v}${v}`, alpha: m[2] !== undefined }
},
),
...[...value.matchAll(/rgba?\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)\s*(?:[,/]\s*([\d.]+%?))?\s*\)/g)].map((m) => ({
value: `#${[m[1], m[2], m[3]].map((c) => Number(c).toString(16).padStart(2, "0")).join("")}`,
alpha: m[4] !== undefined,
})),
].filter((hex) => {
const [r, g, b] = [1, 3, 5].map((i) => parseInt(hex.value.slice(i, i + 2), 16))
return Math.max(r, g, b) - Math.min(r, g, b) <= 6
})
}
function repo() {
return path.resolve(import.meta.dir, "..")
}