@zitadel/config 1.0.0-alpha.21 → 1.0.0-alpha.23

package/README.md

@@ -9,6 +9,8 @@ Versioned Zitadel local config schemas and defaults — the contract behind the
 | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
 | `@zitadel/config/schemas`                          | Zod schemas for the local config files (`schemaConfigSchema`, `flowConfigSchema`, `brandingConfigSchema`) |
 | `@zitadel/config/branding-url`                     | Canonical loopback HTTP URL predicate shared by config and browser render gates                           |
+| `@zitadel/config/branding-contrast`                | Contrast pairs, thresholds and measurement for a branding palette                                         |
+| `@zitadel/config/css-color`                        | Resolves the colour forms a branding palette accepts to sRGB                                              |
 | `@zitadel/config/validate`                         | Validation entry points the CLI runs on `plan`/`apply`                                                    |
 | `@zitadel/config/normalize`                        | Normalization used to compare local files against server state                                            |
 | `@zitadel/config/defaults`                         | The versioned default user schema, login flow, and branding designs                                       |

package/defaults/README-branding.md

@@ -38,7 +38,7 @@ by re-applying an earlier template.
   {
     "$schema": "../meta/branding.json",
     "layout": "split",
-    "liquid_template_file": "./login.liquid",
+    "liquid_template": { "$file": "./login.liquid" },
     "logo_url": "https://example.com/logo.svg",
     "hero_url": "https://example.com/hero.jpg"
   }

package/defaults/README-flows.md

@@ -30,6 +30,11 @@ The common workflow:
 2. Run `zitadel plan` to preview the change.
 3. Run `zitadel apply` to publish it.
 
+Every apply of an edited flow publishes a new immutable revision. Earlier
+revisions stay readable by id. A login that pins the flow's name serves its
+newest revision. A login without a pin serves the project's newest active
+unscoped flow, whatever its name, so revising a flow can make it the default.
+
 Typical edits:
 
 - **Change which fields a step collects** — edit `steps[].fields[]`.
@@ -97,7 +102,7 @@ anything here afterwards.
 
 Editing a schema publishes a new immutable revision. When you `apply` a
 schema edit, the CLI rewrites `user_schema` in the flow files pinned to
-the old revision and updates the flows in the same run — the plan
-announces the re-pin beforehand, and the rewrite shows up in your git
-diff. Remember to update `steps[].fields[]` yourself when the edit
-added or removed properties the flow should collect.
+the old revision and publishes new revisions of those flows in the same
+run — the plan announces the re-pin beforehand, and the rewrite shows up
+in your git diff. Remember to update `steps[].fields[]` yourself when the
+edit added or removed properties the flow should collect.

package/defaults/default-login.json

@@ -20,12 +20,6 @@
           "primary": true,
           "text_key": "identifier.action.continue"
         },
-        {
-          "name": "passkey",
-          "kind": "passkey",
-          "primary": false,
-          "text_key": "identifier.action.passkey"
-        },
         {
           "name": "register",
           "kind": "navigate",
@@ -37,9 +31,6 @@
         "submit": {
           "target": "password"
         },
-        "passkey": {
-          "target": "done"
-        },
         "user_not_found": {
           "target": "register"
         },
@@ -60,20 +51,11 @@
           "kind": "submit",
           "primary": true,
           "text_key": "password.action.signin"
-        },
-        {
-          "name": "passkey",
-          "kind": "passkey",
-          "primary": false,
-          "text_key": "password.action.passkey"
         }
       ],
       "transitions": {
         "submit": {
           "target": "done"
-        },
-        "passkey": {
-          "target": "done"
         }
       }
     },
@@ -89,12 +71,6 @@
           "primary": true,
           "text_key": "register.action.password"
         },
-        {
-          "name": "passkey_register",
-          "kind": "passkey_register",
-          "primary": false,
-          "text_key": "register.action.passkey"
-        },
         {
           "name": "sign_in",
           "kind": "navigate",
@@ -106,9 +82,6 @@
         "submit": {
           "target": "register-password"
         },
-        "passkey_register": {
-          "target": "done"
-        },
         "user_already_exists": {
           "target": "password"
         },

package/dist/branding-contrast.d.mts

@@ -0,0 +1,107 @@
+//#region src/branding-contrast.d.ts
+/**
+ * Contrast checks for a branding revision's palettes.
+ *
+ * Advisory, not a gate. The server rejects a colour whose *form* is unsafe
+ * (`branding-css.ts`); this reports a pair whose *result* is hard to read.
+ * Publishing is not blocked on it: which pairs a surface actually renders
+ * depends on the step, the text size, and the template, so a revision that
+ * reads poorly is a judgement for the person publishing it rather than a
+ * value the API can refuse.
+ *
+ * Every colour form the palette accepts is measured, `color-mix()` and
+ * `currentColor` included (`css-color.ts`). A value that still cannot be
+ * resolved comes back `unresolved`, so a caller says "not checked" rather than
+ * implying a pass.
+ *
+ * Translucent values are composited before measuring: what a reader sees is
+ * the blend, so a ratio against the raw value would describe a colour nobody
+ * sees. Each role composites over what is actually behind it — a button fill
+ * over the card, the card over the page — rather than over the page in every
+ * case. A translucent page has the host application behind it, which is not
+ * ours to know, so that pair stays unresolved.
+ */
+/** WCAG 2.2 AA: body text. */
+declare const CONTRAST_AA_TEXT = 4.5;
+/** WCAG 2.2 AA: large text, and the boundary of a user-interface component. */
+declare const CONTRAST_AA_LARGE = 3;
+type BrandingPaletteColors = Record<string, string | undefined>;
+type ContrastPair = {
+  /**
+   * Stable join key, `foreground/background`. Downstream attaches a warning to
+   * a row and counts issues per section by this id, so it must not change even
+   * if the palette keys behind it are renamed.
+   */
+  id: string; /** Palette key carrying the foreground colour. */
+  foreground: string; /** Palette key carrying the surface it sits on. */
+  background: string; /** The ratio this pair has to reach. */
+  minimum: number; /** What the reader sees, for a message that names the thing rather than the key. */
+  describes: string;
+};
+/**
+ * The pairs a login surface actually puts next to each other. A palette key
+ * appears more than once where the design system paints it on more than one
+ * surface: `text` lands on both the page and the card, and a brand can pick a
+ * background those two disagree about.
+ */
+declare const BRANDING_CONTRAST_PAIRS: readonly ContrastPair[];
+type ContrastFinding = ContrastPair & {
+  status: "pass" | "fail" | "unresolved"; /** Absent when the pair could not be measured. */
+  ratio?: number;
+};
+/**
+ * Contrast ratio between two colours, per WCAG 2.2. Order does not matter.
+ * Both must be opaque: composite them first, since the ratio depends on what
+ * a translucent value is sitting on.
+ */
+declare function contrastRatio(a: string, b: string, context?: ContrastContext): number | undefined;
+type ContrastContext = {
+  currentColor?: string;
+};
+/**
+ * Check one side's palette. A pair whose colours are not both set is skipped
+ * rather than reported: an omitted key takes the maintained default for that
+ * side, which the design system already holds to this bar.
+ */
+declare function checkPaletteContrast(palette: BrandingPaletteColors | undefined): ContrastFinding[];
+/**
+ * The warnings a revision carries, in the shape the console renders and the
+ * API will later return: one entry per failing pair per side, and nothing for
+ * a pair that passes or could not be measured. An empty array means no
+ * warnings.
+ *
+ * Warning-only by decision: a failing pair never blocks saving or publishing.
+ */
+declare function contrastIssues(branding: {
+  theme?: {
+    light?: {
+      palette?: BrandingPaletteColors;
+    };
+    dark?: {
+      palette?: BrandingPaletteColors;
+    };
+  };
+}): ContrastIssue[];
+type ContrastIssue = {
+  theme: "light" | "dark"; /** Stable pair id, e.g. `on_primary/primary`. */
+  pair: string; /** Measured ratio, rounded to two decimals. */
+  ratio: number; /** The ratio this pair had to reach. */
+  required: number;
+};
+/** Both sides of a revision, keyed by the side each finding belongs to. */
+declare function checkBrandingContrast(branding: {
+  theme?: {
+    light?: {
+      palette?: BrandingPaletteColors;
+    };
+    dark?: {
+      palette?: BrandingPaletteColors;
+    };
+  };
+}): {
+  light: ContrastFinding[];
+  dark: ContrastFinding[];
+};
+//#endregion
+export { BRANDING_CONTRAST_PAIRS, BrandingPaletteColors, CONTRAST_AA_LARGE, CONTRAST_AA_TEXT, ContrastContext, ContrastFinding, ContrastIssue, ContrastPair, checkBrandingContrast, checkPaletteContrast, contrastIssues, contrastRatio };
+//# sourceMappingURL=branding-contrast.d.mts.map

package/dist/branding-contrast.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branding-contrast.d.mts","names":[],"sources":["../src/branding-contrast.ts"],"mappings":";;AAwBA;;;;;AAEA;;;;;AAIA;;;;;AAEA;;;;;;;cARa,gBAAA;;cAEA,iBAAA;AAAA,KAID,qBAAA,GAAwB,MAAA;AAAA,KAExB,YAAA;EA0CX;;;;AAED;EAtCE,EAAA;EAEA,UAAA,UAoC4B;EAlC5B,UAAA,UAqCA;EAnCA,OAAA,UAmCK;EAjCL,SAAA;AAAA;;;;;;;cASW,uBAAA,WAAkC,YAAA;AAAA,KAqBnC,eAAA,GAAkB,YAAA;EAC5B,MAAA,kCAkByB;EAhBzB,KAAA;AAAA;;AA+BF;;;;iBAvBgB,aAAA,CAAc,CAAA,UAAW,CAAA,UAAW,OAAA,GAAU,eAAA;AAAA,KAQlD,eAAA;EAAoB,YAAA;AAAA;;AAyFhC;;;;iBA1EgB,oBAAA,CAAqB,OAAA,EAAS,qBAAA,eAAoC,eAAA;;;;;;;;;iBA0ElE,cAAA,CAAe,QAAA;EAC7B,KAAA;IAAU,KAAA;MAAU,OAAA,GAAU,qBAAA;IAAA;IAAyB,IAAA;MAAS,OAAA,GAAU,qBAAA;IAAA;EAAA;AAAA,IACxE,aAAA;AAAA,KAiBQ,aAAA;EACV,KAAA,oBAIA;EAFA,IAAA,UAIQ;EAFR,KAAA,UAMc;EAJd,QAAA;AAAA;;iBAIc,qBAAA,CAAsB,QAAA;EACpC,KAAA;IAAU,KAAA;MAAU,OAAA,GAAU,qBAAA;IAAA;IAAyB,IAAA;MAAS,OAAA,GAAU,qBAAA;IAAA;EAAA;AAAA;EACtE,KAAA,EAAO,eAAA;EAAmB,IAAA,EAAM,eAAA;AAAA"}

package/dist/branding-contrast.mjs

@@ -0,0 +1,229 @@
+import { compositeOver, parseCssColor, relativeLuminance } from "./css-color.mjs";
+//#region src/branding-contrast.ts
+/**
+* Contrast checks for a branding revision's palettes.
+*
+* Advisory, not a gate. The server rejects a colour whose *form* is unsafe
+* (`branding-css.ts`); this reports a pair whose *result* is hard to read.
+* Publishing is not blocked on it: which pairs a surface actually renders
+* depends on the step, the text size, and the template, so a revision that
+* reads poorly is a judgement for the person publishing it rather than a
+* value the API can refuse.
+*
+* Every colour form the palette accepts is measured, `color-mix()` and
+* `currentColor` included (`css-color.ts`). A value that still cannot be
+* resolved comes back `unresolved`, so a caller says "not checked" rather than
+* implying a pass.
+*
+* Translucent values are composited before measuring: what a reader sees is
+* the blend, so a ratio against the raw value would describe a colour nobody
+* sees. Each role composites over what is actually behind it — a button fill
+* over the card, the card over the page — rather than over the page in every
+* case. A translucent page has the host application behind it, which is not
+* ours to know, so that pair stays unresolved.
+*/
+/** WCAG 2.2 AA: body text. */
+const CONTRAST_AA_TEXT = 4.5;
+/** WCAG 2.2 AA: large text, and the boundary of a user-interface component. */
+const CONTRAST_AA_LARGE = 3;
+/**
+* The pairs a login surface actually puts next to each other. A palette key
+* appears more than once where the design system paints it on more than one
+* surface: `text` lands on both the page and the card, and a brand can pick a
+* background those two disagree about.
+*/
+const BRANDING_CONTRAST_PAIRS = [
+	{
+		id: "text/background",
+		foreground: "text",
+		background: "background",
+		minimum: CONTRAST_AA_TEXT,
+		describes: "body text on the page"
+	},
+	{
+		id: "text/surface",
+		foreground: "text",
+		background: "surface",
+		minimum: CONTRAST_AA_TEXT,
+		describes: "body text on the card"
+	},
+	{
+		id: "text_muted/surface",
+		foreground: "text_muted",
+		background: "surface",
+		minimum: CONTRAST_AA_TEXT,
+		describes: "secondary text on the card"
+	},
+	{
+		id: "text/muted",
+		foreground: "text",
+		background: "muted",
+		minimum: CONTRAST_AA_TEXT,
+		describes: "the secondary button's label"
+	},
+	{
+		id: "text_muted/muted",
+		foreground: "text_muted",
+		background: "muted",
+		minimum: CONTRAST_AA_TEXT,
+		describes: "supporting text in an alert"
+	},
+	{
+		id: "on_primary/primary",
+		foreground: "on_primary",
+		background: "primary",
+		minimum: CONTRAST_AA_TEXT,
+		describes: "the primary button's label"
+	},
+	{
+		id: "link/surface",
+		foreground: "link",
+		background: "surface",
+		minimum: CONTRAST_AA_TEXT,
+		describes: "links on the card"
+	},
+	{
+		id: "error/surface",
+		foreground: "error",
+		background: "surface",
+		minimum: CONTRAST_AA_TEXT,
+		describes: "error text on the card"
+	},
+	{
+		id: "success/surface",
+		foreground: "success",
+		background: "surface",
+		minimum: CONTRAST_AA_TEXT,
+		describes: "success text on the card"
+	},
+	{
+		id: "warning/surface",
+		foreground: "warning",
+		background: "surface",
+		minimum: CONTRAST_AA_TEXT,
+		describes: "warning text on the card"
+	},
+	{
+		id: "border/surface",
+		foreground: "border",
+		background: "surface",
+		minimum: 3,
+		describes: "the outline of inputs"
+	}
+];
+/**
+* Contrast ratio between two colours, per WCAG 2.2. Order does not matter.
+* Both must be opaque: composite them first, since the ratio depends on what
+* a translucent value is sitting on.
+*/
+function contrastRatio(a, b, context) {
+	const first = parseCssColor(a, context ?? {});
+	const second = parseCssColor(b, context ?? {});
+	if (!first || !second) return void 0;
+	if (first.a < 1 || second.a < 1) return void 0;
+	return ratioOf(first, second);
+}
+function ratioOf(a, b) {
+	const la = relativeLuminance(a);
+	const lb = relativeLuminance(b);
+	const lighter = Math.max(la, lb);
+	const darker = Math.min(la, lb);
+	return (lighter + .05) / (darker + .05);
+}
+/**
+* Check one side's palette. A pair whose colours are not both set is skipped
+* rather than reported: an omitted key takes the maintained default for that
+* side, which the design system already holds to this bar.
+*/
+function checkPaletteContrast(palette) {
+	if (!palette) return [];
+	const context = { currentColor: palette["text"] };
+	const findings = [];
+	for (const pair of BRANDING_CONTRAST_PAIRS) {
+		const foreground = palette[pair.foreground];
+		const background = palette[pair.background];
+		if (!foreground || !background) continue;
+		const resolved = resolvePair(foreground, pair.background, palette, context);
+		if (!resolved) {
+			findings.push({
+				...pair,
+				status: "unresolved"
+			});
+			continue;
+		}
+		const ratio = ratioOf(resolved.foreground, resolved.background);
+		findings.push({
+			...pair,
+			status: ratio >= pair.minimum ? "pass" : "fail",
+			ratio
+		});
+	}
+	return findings;
+}
+/**
+* What sits behind each painted role. The card sits on the page; the button
+* and alert fills sit on the card. A role absent from this map is the page
+* itself, which has the host application behind it.
+*/
+const BACKDROP = {
+	surface: "background",
+	primary: "surface",
+	muted: "surface"
+};
+function resolvePair(foregroundValue, backgroundRole, palette, context) {
+	const fg = parseCssColor(foregroundValue, context);
+	const bg = resolveSurface(backgroundRole, palette, context, /* @__PURE__ */ new Set());
+	if (!fg || !bg) return void 0;
+	return {
+		foreground: compositeOver(fg, bg),
+		background: bg
+	};
+}
+/** Resolve a role to an opaque colour, compositing it down its own stack. */
+function resolveSurface(role, palette, context, seen) {
+	if (seen.has(role)) return void 0;
+	seen.add(role);
+	const value = palette[role];
+	if (!value) return void 0;
+	const color = parseCssColor(value, context);
+	if (!color) return void 0;
+	if (color.a >= 1) return color;
+	const behind = BACKDROP[role];
+	if (!behind) return void 0;
+	const backdrop = resolveSurface(behind, palette, context, seen);
+	if (!backdrop) return void 0;
+	return compositeOver(color, backdrop);
+}
+/**
+* The warnings a revision carries, in the shape the console renders and the
+* API will later return: one entry per failing pair per side, and nothing for
+* a pair that passes or could not be measured. An empty array means no
+* warnings.
+*
+* Warning-only by decision: a failing pair never blocks saving or publishing.
+*/
+function contrastIssues(branding) {
+	const byTheme = checkBrandingContrast(branding);
+	const issues = [];
+	for (const theme of ["light", "dark"]) for (const finding of byTheme[theme]) {
+		if (finding.status !== "fail" || finding.ratio === void 0) continue;
+		issues.push({
+			theme,
+			pair: finding.id,
+			ratio: Math.round(finding.ratio * 100) / 100,
+			required: finding.minimum
+		});
+	}
+	return issues;
+}
+/** Both sides of a revision, keyed by the side each finding belongs to. */
+function checkBrandingContrast(branding) {
+	return {
+		light: checkPaletteContrast(branding.theme?.light?.palette),
+		dark: checkPaletteContrast(branding.theme?.dark?.palette)
+	};
+}
+//#endregion
+export { BRANDING_CONTRAST_PAIRS, CONTRAST_AA_LARGE, CONTRAST_AA_TEXT, checkBrandingContrast, checkPaletteContrast, contrastIssues, contrastRatio };
+
+//# sourceMappingURL=branding-contrast.mjs.map

package/dist/branding-contrast.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"branding-contrast.mjs","names":[],"sources":["../src/branding-contrast.ts"],"sourcesContent":["/**\n * Contrast checks for a branding revision's palettes.\n *\n * Advisory, not a gate. The server rejects a colour whose *form* is unsafe\n * (`branding-css.ts`); this reports a pair whose *result* is hard to read.\n * Publishing is not blocked on it: which pairs a surface actually renders\n * depends on the step, the text size, and the template, so a revision that\n * reads poorly is a judgement for the person publishing it rather than a\n * value the API can refuse.\n *\n * Every colour form the palette accepts is measured, `color-mix()` and\n * `currentColor` included (`css-color.ts`). A value that still cannot be\n * resolved comes back `unresolved`, so a caller says \"not checked\" rather than\n * implying a pass.\n *\n * Translucent values are composited before measuring: what a reader sees is\n * the blend, so a ratio against the raw value would describe a colour nobody\n * sees. Each role composites over what is actually behind it — a button fill\n * over the card, the card over the page — rather than over the page in every\n * case. A translucent page has the host application behind it, which is not\n * ours to know, so that pair stays unresolved.\n */\n\n/** WCAG 2.2 AA: body text. */\nexport const CONTRAST_AA_TEXT = 4.5;\n/** WCAG 2.2 AA: large text, and the boundary of a user-interface component. */\nexport const CONTRAST_AA_LARGE = 3;\n\nimport { compositeOver, parseCssColor, relativeLuminance, type Rgba } from \"./css-color.js\";\n\nexport type BrandingPaletteColors = Record<string, string | undefined>;\n\nexport type ContrastPair = {\n  /**\n   * Stable join key, `foreground/background`. Downstream attaches a warning to\n   * a row and counts issues per section by this id, so it must not change even\n   * if the palette keys behind it are renamed.\n   */\n  id: string;\n  /** Palette key carrying the foreground colour. */\n  foreground: string;\n  /** Palette key carrying the surface it sits on. */\n  background: string;\n  /** The ratio this pair has to reach. */\n  minimum: number;\n  /** What the reader sees, for a message that names the thing rather than the key. */\n  describes: string;\n};\n\n/**\n * The pairs a login surface actually puts next to each other. A palette key\n * appears more than once where the design system paints it on more than one\n * surface: `text` lands on both the page and the card, and a brand can pick a\n * background those two disagree about.\n */\nexport const BRANDING_CONTRAST_PAIRS: readonly ContrastPair[] = [\n  { id: \"text/background\", foreground: \"text\", background: \"background\", minimum: CONTRAST_AA_TEXT, describes: \"body text on the page\" },\n  { id: \"text/surface\", foreground: \"text\", background: \"surface\", minimum: CONTRAST_AA_TEXT, describes: \"body text on the card\" },\n  { id: \"text_muted/surface\", foreground: \"text_muted\", background: \"surface\", minimum: CONTRAST_AA_TEXT, describes: \"secondary text on the card\" },\n  // `muted` fills the secondary button and the alert, both of which draw text\n  // on it — a palette can read perfectly on the card and be unreadable here.\n  { id: \"text/muted\", foreground: \"text\", background: \"muted\", minimum: CONTRAST_AA_TEXT, describes: \"the secondary button's label\" },\n  { id: \"text_muted/muted\", foreground: \"text_muted\", background: \"muted\", minimum: CONTRAST_AA_TEXT, describes: \"supporting text in an alert\" },\n  { id: \"on_primary/primary\", foreground: \"on_primary\", background: \"primary\", minimum: CONTRAST_AA_TEXT, describes: \"the primary button's label\" },\n  { id: \"link/surface\", foreground: \"link\", background: \"surface\", minimum: CONTRAST_AA_TEXT, describes: \"links on the card\" },\n  { id: \"error/surface\", foreground: \"error\", background: \"surface\", minimum: CONTRAST_AA_TEXT, describes: \"error text on the card\" },\n  { id: \"success/surface\", foreground: \"success\", background: \"surface\", minimum: CONTRAST_AA_TEXT, describes: \"success text on the card\" },\n  { id: \"warning/surface\", foreground: \"warning\", background: \"surface\", minimum: CONTRAST_AA_TEXT, describes: \"warning text on the card\" },\n  // The one pair that is not text. A field outline is a user-interface\n  // component boundary, which WCAG 2.2 holds to 3:1 rather than 4.5:1 — an\n  // input the visitor cannot find is a real failure, not decoration. Dropping\n  // it would make `required` a constant, which is the only argument for\n  // leaving it out.\n  { id: \"border/surface\", foreground: \"border\", background: \"surface\", minimum: CONTRAST_AA_LARGE, describes: \"the outline of inputs\" },\n];\n\nexport type ContrastFinding = ContrastPair & {\n  status: \"pass\" | \"fail\" | \"unresolved\";\n  /** Absent when the pair could not be measured. */\n  ratio?: number;\n};\n\n/**\n * Contrast ratio between two colours, per WCAG 2.2. Order does not matter.\n * Both must be opaque: composite them first, since the ratio depends on what\n * a translucent value is sitting on.\n */\nexport function contrastRatio(a: string, b: string, context?: ContrastContext): number | undefined {\n  const first = parseCssColor(a, context ?? {});\n  const second = parseCssColor(b, context ?? {});\n  if (!first || !second) return undefined;\n  if (first.a < 1 || second.a < 1) return undefined;\n  return ratioOf(first, second);\n}\n\nexport type ContrastContext = { currentColor?: string };\n\nfunction ratioOf(a: Rgba, b: Rgba): number {\n  const la = relativeLuminance(a);\n  const lb = relativeLuminance(b);\n  const lighter = Math.max(la, lb);\n  const darker = Math.min(la, lb);\n  return (lighter + 0.05) / (darker + 0.05);\n}\n\n/**\n * Check one side's palette. A pair whose colours are not both set is skipped\n * rather than reported: an omitted key takes the maintained default for that\n * side, which the design system already holds to this bar.\n */\nexport function checkPaletteContrast(palette: BrandingPaletteColors | undefined): ContrastFinding[] {\n  if (!palette) return [];\n  // `currentColor` on a palette key means the text colour it would inherit.\n  // Everything the pairs below draw sits on the card, so that is the side's\n  // own `text` — which is why this is answerable here and not in general CSS.\n  const context = { currentColor: palette[\"text\"] };\n  const findings: ContrastFinding[] = [];\n  for (const pair of BRANDING_CONTRAST_PAIRS) {\n    const foreground = palette[pair.foreground];\n    const background = palette[pair.background];\n    if (!foreground || !background) continue;\n    const resolved = resolvePair(foreground, pair.background, palette, context);\n    if (!resolved) {\n      findings.push({ ...pair, status: \"unresolved\" });\n      continue;\n    }\n    const ratio = ratioOf(resolved.foreground, resolved.background);\n    findings.push({ ...pair, status: ratio >= pair.minimum ? \"pass\" : \"fail\", ratio });\n  }\n  return findings;\n}\n\n/**\n * What sits behind each painted role. The card sits on the page; the button\n * and alert fills sit on the card. A role absent from this map is the page\n * itself, which has the host application behind it.\n */\nconst BACKDROP: Record<string, string> = {\n  surface: \"background\",\n  primary: \"surface\",\n  muted: \"surface\",\n};\n\nfunction resolvePair(\n  foregroundValue: string,\n  backgroundRole: string,\n  palette: BrandingPaletteColors,\n  context: ContrastContext,\n): { foreground: Rgba; background: Rgba } | undefined {\n  const fg = parseCssColor(foregroundValue, context);\n  const bg = resolveSurface(backgroundRole, palette, context, new Set());\n  if (!fg || !bg) return undefined;\n  return { foreground: compositeOver(fg, bg), background: bg };\n}\n\n/** Resolve a role to an opaque colour, compositing it down its own stack. */\nfunction resolveSurface(\n  role: string,\n  palette: BrandingPaletteColors,\n  context: ContrastContext,\n  seen: Set<string>,\n): Rgba | undefined {\n  if (seen.has(role)) return undefined;\n  seen.add(role);\n  const value = palette[role];\n  if (!value) return undefined;\n  const color = parseCssColor(value, context);\n  if (!color) return undefined;\n  if (color.a >= 1) return color;\n  const behind = BACKDROP[role];\n  if (!behind) return undefined;\n  const backdrop = resolveSurface(behind, palette, context, seen);\n  if (!backdrop) return undefined;\n  return compositeOver(color, backdrop);\n}\n\n/**\n * The warnings a revision carries, in the shape the console renders and the\n * API will later return: one entry per failing pair per side, and nothing for\n * a pair that passes or could not be measured. An empty array means no\n * warnings.\n *\n * Warning-only by decision: a failing pair never blocks saving or publishing.\n */\nexport function contrastIssues(branding: {\n  theme?: { light?: { palette?: BrandingPaletteColors }; dark?: { palette?: BrandingPaletteColors } };\n}): ContrastIssue[] {\n  const byTheme = checkBrandingContrast(branding);\n  const issues: ContrastIssue[] = [];\n  for (const theme of [\"light\", \"dark\"] as const) {\n    for (const finding of byTheme[theme]) {\n      if (finding.status !== \"fail\" || finding.ratio === undefined) continue;\n      issues.push({\n        theme,\n        pair: finding.id,\n        ratio: Math.round(finding.ratio * 100) / 100,\n        required: finding.minimum,\n      });\n    }\n  }\n  return issues;\n}\n\nexport type ContrastIssue = {\n  theme: \"light\" | \"dark\";\n  /** Stable pair id, e.g. `on_primary/primary`. */\n  pair: string;\n  /** Measured ratio, rounded to two decimals. */\n  ratio: number;\n  /** The ratio this pair had to reach. */\n  required: number;\n};\n\n/** Both sides of a revision, keyed by the side each finding belongs to. */\nexport function checkBrandingContrast(branding: {\n  theme?: { light?: { palette?: BrandingPaletteColors }; dark?: { palette?: BrandingPaletteColors } };\n}): { light: ContrastFinding[]; dark: ContrastFinding[] } {\n  return {\n    light: checkPaletteContrast(branding.theme?.light?.palette),\n    dark: checkPaletteContrast(branding.theme?.dark?.palette),\n  };\n}\n"],"mappings":"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"}

package/dist/css-color.d.mts

@@ -0,0 +1,36 @@
+//#region src/css-color.d.ts
+/** An sRGB colour, channels 0-255, alpha 0-1. */
+type Rgba = {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+};
+type ResolveContext = {
+  /**
+   * What `currentColor` inherits at the point this value is painted. Left
+   * unset, `currentColor` stays unresolved rather than being guessed at.
+   */
+  currentColor?: string;
+};
+/**
+ * Parse any colour form a palette accepts. Returns `undefined` for a value
+ * that is malformed, or for `currentColor` with no context to resolve it
+ * against.
+ */
+declare function parseCssColor(input: string, context?: ResolveContext): Rgba | undefined;
+/**
+ * Composite a colour over an opaque backdrop. A translucent foreground is what
+ * the reader sees blended with what is behind it, so a ratio measured against
+ * the raw value would describe a colour nobody sees.
+ */
+declare function compositeOver(color: Rgba, backdrop: Rgba): Rgba;
+/** WCAG 2.2 relative luminance of an opaque sRGB colour. */
+declare function relativeLuminance({
+  r,
+  g,
+  b
+}: Rgba): number;
+//#endregion
+export { ResolveContext, Rgba, compositeOver, parseCssColor, relativeLuminance };
+//# sourceMappingURL=css-color.d.mts.map

package/dist/css-color.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"css-color.d.mts","names":[],"sources":["../src/css-color.ts"],"mappings":";;KA8BY,IAAA;EAAS,CAAA;EAAW,CAAA;EAAW,CAAA;EAAW,CAAA;AAAA;AAAA,KAE1C,cAAA;EAF0C;;;AAEtD;EAKE,YAAA;AAAA;;;AA0CF;;;iBAAgB,aAAA,CAAc,KAAA,UAAe,OAAA,GAAS,cAAA,GAAsB,IAAA;;;;;;iBAqK5D,aAAA,CAAc,KAAA,EAAO,IAAA,EAAM,QAAA,EAAU,IAAA,GAAO,IAAA;AAA5D;AAAA,iBAYgB,iBAAA,CAAA;EAAoB,CAAA;EAAG,CAAA;EAAG;AAAA,GAAK,IAAA"}