import { fileURLToPath } from "node:url";
import { GoalError, refSafe, type Judge } from "./goal.ts";
type Entries = Readonly<Record<string, string>>;
export interface VisualLanguage {
readonly id: string;
readonly name: string;
readonly tokens: Entries;
readonly rules: Entries;
}
interface LanguageDefinition {
id: string;
name: string;
extends?: VisualLanguage;
tokens?: Entries;
rules?: Entries;
}
/** Each supplied key replaces one inherited value. Resolved definitions are immutable. */
export function defineVisualLanguage(definition: LanguageDefinition): VisualLanguage {
const { id, name, extends: parent } = definition;
refSafe("visual language id", id);
if (!name.trim()) throw new GoalError("A visual language needs a name");
const tokens = Object.freeze({ ...parent?.tokens, ...definition.tokens });
const rules = Object.freeze({ ...parent?.rules, ...definition.rules });
if (!Object.keys(rules).length) throw new GoalError("A visual language needs at least one design rule");
for (const [key, value] of [...Object.entries(tokens), ...Object.entries(rules)]) {
if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(key) || typeof value !== "string" || !value.trim()) {
throw new GoalError(`Invalid visual language entry "${key}": use a lowercase hyphenated name and a nonempty value`);
}
}
return Object.freeze({ id, name, tokens, rules });
}
export const mnmxVisualLanguage = defineVisualLanguage({
id: "design.mnmx",
name: "mnmx homepage",
tokens: {
paper: "#f6f0e7", ink: "#30221d", muted: "#69564b", line: "#d8cabd",
accent: "#934b32", highlight: "#ebcba8", focus: "#b56743",
"heading-font": "'Manrope', sans-serif", "body-font": "'DM Sans', sans-serif",
"control-radius": "5px", "panel-radius": "10px",
},
rules: {
palette: "Use paper for the canvas, ink for primary text, muted for supporting text, and line for separators. Reserve accent for the main action. On an inverse ink surface, use paper text and highlight for emphasis.",
type: "Use the heading face at medium weight with tight tracking for the main title. Use the body face for reading and compact control labels. Use local sans-serif fallbacks when the fonts are unavailable.",
layout: "Align headings and controls to shared edges. Give the main content generous outer space. Group related rows with thin rules and tighter internal spacing. Let controls wrap or stack on small screens.",
surfaces: "Use flat surfaces and modest radii. Where a working group needs emphasis, an inverse panel can frame a group of paper-colored elements. Choose its role according to the content.",
interaction: "Distinguish the main action with a filled accent control. Keep secondary actions quiet and readable. Show keyboard focus with a visible offset ring. Distinguish selection, completion and disabled states by more than hue.",
},
});
/** Resolve design choices into the acceptance text that both builder and reviewer see. */
export function visualLanguageGoal(language: VisualLanguage, judge: Judge,
prompt = fileURLToPath(new URL("../goals/judges/visual-language.md", import.meta.url))) {
const acceptance: Record<string, string> = {};
for (const [key, value] of Object.entries(language.tokens)) acceptance[`token-${key}`] = `Use ${value} for the ${key} token.`;
for (const [key, value] of Object.entries(language.rules)) acceptance[`rule-${key}`] = value;
return {
id: language.id, statement: `Apply the ${language.name} visual language to the selected interface.`,
acceptance, judge,
criteria: { prompt, scale: { 1: "Material design or usability conflicts", 3: "Recognizable language with visible gaps", 5: "Consistent, usable expression of the adopted language" } },
};
}