@handamade/psi-tokens 0.26.0 → 0.27.0

package/dist/acme.css

@@ -40,6 +40,7 @@
     --psi-border-faint: oklch(from var(--psi-fg-primary) l c h / 0.08);
     --psi-border-neutral: oklch(from var(--psi-fg-primary) l c h / 0.15);
     --psi-border-strong: oklch(from var(--psi-fg-primary) l c h / 0.3);
+    --psi-border-control: oklch(from var(--psi-fg-primary) l c h / 0.55);
     --psi-border-focus: var(--psi-fg-accent);
     --psi-scrim-soft: oklch(from var(--psi-bg-primary) l c h / 0.25);
     --psi-scrim-medium: oklch(from var(--psi-bg-primary) l c h / 0.35);

package/dist/components/checkbox.js

@@ -2,9 +2,11 @@
 export const checkboxVars = {
     fg: "var(--psi-fg-primary)",
     "box-bg": "var(--psi-bg-primary)",
-    "box-border": "var(--psi-border-neutral)",
+    "box-border": "var(--psi-border-control)",
     "box-bg-checked": "var(--psi-fill-accent)",
     "box-border-checked": "var(--psi-fill-accent)",
+    // D108: an unchecked, aria-invalid box, in the error colour Input uses.
+    "box-border-error": "var(--psi-fg-danger)",
     // D56: tracks a sharper theme down, never rounder than radius-4 — the box
     // is ~16px, so the 8px control default would read as a circle.
     "box-radius": "min(var(--psi-control-radius), var(--psi-radius-4))",

package/dist/components/checkbox.vars.css

@@ -2,9 +2,10 @@
   :where(:root, [data-psi-theme]) {
     --psi-checkbox-fg: var(--psi-fg-primary);
     --psi-checkbox-box-bg: var(--psi-bg-primary);
-    --psi-checkbox-box-border: var(--psi-border-neutral);
+    --psi-checkbox-box-border: var(--psi-border-control);
     --psi-checkbox-box-bg-checked: var(--psi-fill-accent);
     --psi-checkbox-box-border-checked: var(--psi-fill-accent);
+    --psi-checkbox-box-border-error: var(--psi-fg-danger);
     --psi-checkbox-box-radius: min(var(--psi-control-radius), var(--psi-radius-4));
     --psi-checkbox-check-fg: var(--psi-fg-on-accent);
     --psi-checkbox-focus-ring: var(--psi-border-focus);

package/dist/components/radio-group.js

@@ -5,9 +5,11 @@
 export const radioGroupVars = {
     fg: "var(--psi-fg-primary)",
     "circle-bg": "var(--psi-bg-primary)",
-    "circle-border": "var(--psi-border-neutral)",
+    "circle-border": "var(--psi-border-control)",
     "circle-bg-checked": "var(--psi-fill-accent)",
     "circle-border-checked": "var(--psi-fill-accent)",
+    // D108: an unchecked, aria-invalid circle, in the error colour Input uses.
+    "circle-border-error": "var(--psi-fg-danger)",
     "dot-fg": "var(--psi-fg-on-accent)",
     "focus-ring": "var(--psi-border-focus)",
 };

package/dist/components/radio-group.vars.css

@@ -2,9 +2,10 @@
   :where(:root, [data-psi-theme]) {
     --psi-radio-group-fg: var(--psi-fg-primary);
     --psi-radio-group-circle-bg: var(--psi-bg-primary);
-    --psi-radio-group-circle-border: var(--psi-border-neutral);
+    --psi-radio-group-circle-border: var(--psi-border-control);
     --psi-radio-group-circle-bg-checked: var(--psi-fill-accent);
     --psi-radio-group-circle-border-checked: var(--psi-fill-accent);
+    --psi-radio-group-circle-border-error: var(--psi-fg-danger);
     --psi-radio-group-dot-fg: var(--psi-fg-on-accent);
     --psi-radio-group-focus-ring: var(--psi-border-focus);
   }

package/dist/components/registry.js

@@ -15,6 +15,7 @@ import { switchVars } from "./switch.js";
 import { tableVars } from "./table.js";
 import { tagVars } from "./tag.js";
 import { toolbarVars } from "./toolbar.js";
+import { textVars } from "./text.js";
 import { tooltipVars } from "./tooltip.js";
 import { cardVars } from "./card.js";
 import { controlVars } from "./control.js";
@@ -57,6 +58,7 @@ export const componentVars = {
     tag: tagVars,
     textarea: textareaVars,
     toolbar: toolbarVars,
+    text: textVars,
     toast: toastVars,
     tooltip: tooltipVars,
 };

package/dist/components/text.d.ts

@@ -0,0 +1,6 @@
+/** Text component tokens (--psi-text-fg*) — D109. Pure indirection onto the
+ * semantic layer. fgPrimary and fgSecondary are gated at 4.5 on every
+ * surface in wcagAAPairs, so no new contrast pair. The prefix shares
+ * `--psi-text-` with the type styles (`--psi-text-14-20-regular`); no type
+ * style is named `fg`, so the two cannot collide. */
+export declare const textVars: Record<string, string>;

package/dist/components/text.js

@@ -0,0 +1,9 @@
+/** Text component tokens (--psi-text-fg*) — D109. Pure indirection onto the
+ * semantic layer. fgPrimary and fgSecondary are gated at 4.5 on every
+ * surface in wcagAAPairs, so no new contrast pair. The prefix shares
+ * `--psi-text-` with the type styles (`--psi-text-14-20-regular`); no type
+ * style is named `fg`, so the two cannot collide. */
+export const textVars = {
+    fg: "var(--psi-fg-primary)",
+    "fg-secondary": "var(--psi-fg-secondary)",
+};

package/dist/components/text.vars.css

@@ -0,0 +1,6 @@
+@layer psi.components {
+  :where(:root, [data-psi-theme]) {
+    --psi-text-fg: var(--psi-fg-primary);
+    --psi-text-fg-secondary: var(--psi-fg-secondary);
+  }
+}

package/dist/components.css

@@ -100,9 +100,10 @@
   :where(:root, [data-psi-theme]) {
     --psi-checkbox-fg: var(--psi-fg-primary);
     --psi-checkbox-box-bg: var(--psi-bg-primary);
-    --psi-checkbox-box-border: var(--psi-border-neutral);
+    --psi-checkbox-box-border: var(--psi-border-control);
     --psi-checkbox-box-bg-checked: var(--psi-fill-accent);
     --psi-checkbox-box-border-checked: var(--psi-fill-accent);
+    --psi-checkbox-box-border-error: var(--psi-fg-danger);
     --psi-checkbox-box-radius: min(var(--psi-control-radius), var(--psi-radius-4));
     --psi-checkbox-check-fg: var(--psi-fg-on-accent);
     --psi-checkbox-focus-ring: var(--psi-border-focus);
@@ -261,9 +262,10 @@
   :where(:root, [data-psi-theme]) {
     --psi-radio-group-fg: var(--psi-fg-primary);
     --psi-radio-group-circle-bg: var(--psi-bg-primary);
-    --psi-radio-group-circle-border: var(--psi-border-neutral);
+    --psi-radio-group-circle-border: var(--psi-border-control);
     --psi-radio-group-circle-bg-checked: var(--psi-fill-accent);
     --psi-radio-group-circle-border-checked: var(--psi-fill-accent);
+    --psi-radio-group-circle-border-error: var(--psi-fg-danger);
     --psi-radio-group-dot-fg: var(--psi-fg-on-accent);
     --psi-radio-group-focus-ring: var(--psi-border-focus);
   }
@@ -446,6 +448,13 @@
   }
 }
 
+@layer psi.components {
+  :where(:root, [data-psi-theme]) {
+    --psi-text-fg: var(--psi-fg-primary);
+    --psi-text-fg-secondary: var(--psi-fg-secondary);
+  }
+}
+
 @layer psi.components {
   :where(:root, [data-psi-theme]) {
     --psi-toast-bg: var(--psi-surface-bg);

package/dist/contrast-matrix.d.ts

@@ -32,3 +32,8 @@ export declare const wcagAAPairs: ContrastPair[];
  * button/tag label on its variant background ≥ 4.5"). Tint-variant labels are
  * already covered by the fg-on-tint pairs in wcagAAPairs. */
 export declare const componentLabelPairs: ContrastPair[];
+/** WCAG 1.4.11 non-text contrast (D106): 3:1 for the visual information that
+ * identifies a control. An unchecked checkbox or radio is identified by its
+ * outline alone, against its own fill (bgPrimary) and the surface it sits on
+ * (bgPrimary on the canvas, bgSecondary on Panel, Dialog and Menu). */
+export declare const nonTextPairs: ContrastPair[];

package/dist/contrast-matrix.js

@@ -136,3 +136,11 @@ export const componentLabelPairs = [
     { fg: "fgStaticBlack", bg: "fillWarning", minRatio: 4.5 }, // Tag warning (D22)
     { fg: "fgOnInverted", bg: "bgInverted", minRatio: 4.5 }, // Tooltip label (D46 inversion pair)
 ];
+/** WCAG 1.4.11 non-text contrast (D106): 3:1 for the visual information that
+ * identifies a control. An unchecked checkbox or radio is identified by its
+ * outline alone, against its own fill (bgPrimary) and the surface it sits on
+ * (bgPrimary on the canvas, bgSecondary on Panel, Dialog and Menu). */
+export const nonTextPairs = [
+    { fg: "borderControl", bg: "bgPrimary", minRatio: 3 },
+    { fg: "borderControl", bg: "bgSecondary", minRatio: 3 },
+];

package/dist/dark.css

@@ -40,6 +40,7 @@
     --psi-border-faint: oklch(from var(--psi-fg-primary) l c h / 0.08);
     --psi-border-neutral: oklch(from var(--psi-fg-primary) l c h / 0.15);
     --psi-border-strong: oklch(from var(--psi-fg-primary) l c h / 0.3);
+    --psi-border-control: oklch(from var(--psi-fg-primary) l c h / 0.4);
     --psi-border-focus: var(--psi-fg-accent);
     --psi-scrim-soft: oklch(from var(--psi-bg-primary) l c h / 0.25);
     --psi-scrim-medium: oklch(from var(--psi-bg-primary) l c h / 0.35);

package/dist/dtcg/acme.json

@@ -420,6 +420,18 @@
           }
         }
       },
+      "control": {
+        "$type": "color",
+        "$value": "#3c28258c",
+        "$description": "ref(fgPrimary) → alpha(0.55)",
+        "$extensions": {
+          "psi": {
+            "scopes": [
+              "border"
+            ]
+          }
+        }
+      },
       "focus": {
         "$type": "color",
         "$value": "#b10b00",

package/dist/dtcg/dark.json

@@ -420,6 +420,18 @@
           }
         }
       },
+      "control": {
+        "$type": "color",
+        "$value": "#e3e8ee66",
+        "$description": "ref(fgPrimary) → alpha(0.4)",
+        "$extensions": {
+          "psi": {
+            "scopes": [
+              "border"
+            ]
+          }
+        }
+      },
       "focus": {
         "$type": "color",
         "$value": "#7daeff",

package/dist/dtcg/ember.json

@@ -420,6 +420,18 @@
           }
         }
       },
+      "control": {
+        "$type": "color",
+        "$value": "#f3ede666",
+        "$description": "ref(fgPrimary) → alpha(0.4)",
+        "$extensions": {
+          "psi": {
+            "scopes": [
+              "border"
+            ]
+          }
+        }
+      },
       "focus": {
         "$type": "color",
         "$value": "#ff885d",

package/dist/dtcg/light.json

@@ -420,6 +420,18 @@
           }
         }
       },
+      "control": {
+        "$type": "color",
+        "$value": "#222f3c8c",
+        "$description": "ref(fgPrimary) → alpha(0.55)",
+        "$extensions": {
+          "psi": {
+            "scopes": [
+              "border"
+            ]
+          }
+        }
+      },
       "focus": {
         "$type": "color",
         "$value": "#0053c9",

package/dist/ember.css

@@ -40,6 +40,7 @@
     --psi-border-faint: oklch(from var(--psi-fg-primary) l c h / 0.08);
     --psi-border-neutral: oklch(from var(--psi-fg-primary) l c h / 0.15);
     --psi-border-strong: oklch(from var(--psi-fg-primary) l c h / 0.3);
+    --psi-border-control: oklch(from var(--psi-fg-primary) l c h / 0.4);
     --psi-border-focus: var(--psi-fg-accent);
     --psi-scrim-soft: oklch(from var(--psi-bg-primary) l c h / 0.25);
     --psi-scrim-medium: oklch(from var(--psi-bg-primary) l c h / 0.35);

package/dist/generate/derive.js

@@ -1,4 +1,4 @@
-import { checkContrast, componentLabelPairs, wcagAAPairs } from "../contrast-matrix.js";
+import { checkContrast, componentLabelPairs, nonTextPairs, wcagAAPairs } from "../contrast-matrix.js";
 import { resolve } from "../dsl/resolver.js";
 import { cap, set, slot, token } from "../dsl/builders.js";
 import { assembleCustomerTheme, } from "../themes/customers/index.js";
@@ -25,7 +25,10 @@ function withAlpha(hex, alpha) {
 }
 /**
  * The gate, and it must be the SAME set `scripts/build.ts` runs over every
- * committed theme: `[...wcagAAPairs, ...componentLabelPairs]`, 33 pairs.
+ * committed theme: `[...wcagAAPairs, ...componentLabelPairs, ...nonTextPairs]`,
+ * 38 pairs (this said 33 until D106; D62 and D86 had grown it). The two
+ * non-text pairs (D106) are not solved here: `borderControl` is a fixed alpha
+ * of `fgPrimary`, and the sweep test proves it holds.
  *
  * Checking only `wcagAAPairs` (28) is what let "a theme derived from any
  * prompt clears the AA matrix by construction" ship false a third time. The
@@ -40,7 +43,7 @@ function withAlpha(hex, alpha) {
  * `accentLightness` there for why the fix has to be upstream of this loop
  * rather than another escalating target inside it).
  */
-const AA_MATRIX = [...wcagAAPairs, ...componentLabelPairs];
+const AA_MATRIX = [...wcagAAPairs, ...componentLabelPairs, ...nonTextPairs];
 const BASE_TARGET = 4.5;
 const TARGET_ESCALATION = 0.1;
 const MAX_OUTER_ATTEMPTS = 40;

package/dist/generate/palette.js

@@ -26,7 +26,7 @@ const ACCENT_L = 0.55;
  * renders white-on-accent at **4.4979:1** — under AA, and the exact failure
  * the prompt "bold calm app" produced. It cleared CI only because `derive.ts`
  * checked the 28-pair `wcagAAPairs` while `scripts/build.ts` gates committed
- * themes on all 33.
+ * themes on the full matrix.
  *
  * So the accent is darkened — never lightened — to the lightest value that
  * still carries a white label at `LABEL_TARGET`, a deliberate margin above
@@ -45,7 +45,7 @@ const ACCENT_L = 0.55;
  * `fillDanger`, `fgStaticBlack` on `fillWarning`) sit on fixed hues and were
  * measured at 5.16 / 5.21 / 6.94:1 worst-case across the same sweep, so they
  * need no equivalent treatment — but the sweep in
- * `__tests__/generate-derive.test.ts` gates all 33 pairs, not just this one.
+ * `__tests__/generate-derive.test.ts` gates the full matrix, not just this one.
  */
 const LABEL_TARGET = 4.65;
 function accentLightness(c, h) {

package/dist/light.css

@@ -40,6 +40,7 @@
     --psi-border-faint: oklch(from var(--psi-fg-primary) l c h / 0.08);
     --psi-border-neutral: oklch(from var(--psi-fg-primary) l c h / 0.15);
     --psi-border-strong: oklch(from var(--psi-fg-primary) l c h / 0.3);
+    --psi-border-control: oklch(from var(--psi-fg-primary) l c h / 0.55);
     --psi-border-focus: var(--psi-fg-accent);
     --psi-scrim-soft: oklch(from var(--psi-bg-primary) l c h / 0.25);
     --psi-scrim-medium: oklch(from var(--psi-bg-primary) l c h / 0.35);

package/dist/resolved/acme.json

@@ -431,6 +431,20 @@
         "border"
       ]
     },
+    "borderControl": {
+      "name": "borderControl",
+      "oklch": {
+        "l": 0.3,
+        "c": 0.03,
+        "h": 30,
+        "alpha": 0.55
+      },
+      "hex": "#3c2825",
+      "formula": "ref(fgPrimary) → alpha(0.55)",
+      "scopes": [
+        "border"
+      ]
+    },
     "borderFocus": {
       "name": "borderFocus",
       "oklch": {

package/dist/resolved/dark.json

@@ -431,6 +431,20 @@
         "border"
       ]
     },
+    "borderControl": {
+      "name": "borderControl",
+      "oklch": {
+        "l": 0.93,
+        "c": 0.01,
+        "h": 250,
+        "alpha": 0.4
+      },
+      "hex": "#e3e8ee",
+      "formula": "ref(fgPrimary) → alpha(0.4)",
+      "scopes": [
+        "border"
+      ]
+    },
     "borderFocus": {
       "name": "borderFocus",
       "oklch": {

package/dist/resolved/ember.json

@@ -431,6 +431,20 @@
         "border"
       ]
     },
+    "borderControl": {
+      "name": "borderControl",
+      "oklch": {
+        "l": 0.949,
+        "c": 0.011,
+        "h": 72,
+        "alpha": 0.4
+      },
+      "hex": "#f3ede6",
+      "formula": "ref(fgPrimary) → alpha(0.4)",
+      "scopes": [
+        "border"
+      ]
+    },
     "borderFocus": {
       "name": "borderFocus",
       "oklch": {

package/dist/resolved/light.json

@@ -431,6 +431,20 @@
         "border"
       ]
     },
+    "borderControl": {
+      "name": "borderControl",
+      "oklch": {
+        "l": 0.3,
+        "c": 0.03,
+        "h": 250,
+        "alpha": 0.55
+      },
+      "hex": "#222f3c",
+      "formula": "ref(fgPrimary) → alpha(0.55)",
+      "scopes": [
+        "border"
+      ]
+    },
     "borderFocus": {
       "name": "borderFocus",
       "oklch": {

package/dist/scope-map.json

@@ -173,6 +173,9 @@
     "border-strong": [
       "border"
     ],
+    "border-control": [
+      "border"
+    ],
     "border-focus": [
       "border"
     ],
@@ -349,6 +352,9 @@
     "checkbox-box-border-checked": [
       "border"
     ],
+    "checkbox-box-border-error": [
+      "border"
+    ],
     "checkbox-check-fg": [
       "text"
     ],
@@ -499,6 +505,9 @@
     "radio-group-circle-border-checked": [
       "border"
     ],
+    "radio-group-circle-border-error": [
+      "border"
+    ],
     "radio-group-dot-fg": [
       "text"
     ],
@@ -691,6 +700,12 @@
     "textarea-counter-fg": [
       "text"
     ],
+    "text-fg": [
+      "text"
+    ],
+    "text-fg-secondary": [
+      "text"
+    ],
     "toast-bg": [
       "surface"
     ],

package/dist/theme/gate.js

@@ -1,7 +1,7 @@
 import { validate } from "../dsl/validator.js";
 import { resolve } from "../dsl/resolver.js";
 import { gamutWarnings } from "../gamut.js";
-import { checkContrast, wcagAAPairs, componentLabelPairs } from "../contrast-matrix.js";
+import { checkContrast, wcagAAPairs, componentLabelPairs, nonTextPairs } from "../contrast-matrix.js";
 import { checkScopes, checkOverrideScopes } from "../scope-gate.js";
 import { componentVars } from "../components/registry.js";
 /** Thrown when a theme fails the WCAG AA contrast gate or the D46 scope gate. */
@@ -32,7 +32,7 @@ export function gateTheme(name, theme, palette, slots, componentOverrides = {})
     validate(theme, slots);
     const resolved = resolve(theme, palette, slots);
     const warnings = gamutWarnings(resolved, theme, palette, slots);
-    const contrastFailures = checkContrast(resolved, [...wcagAAPairs, ...componentLabelPairs]).filter((r) => !r.pass);
+    const contrastFailures = checkContrast(resolved, [...wcagAAPairs, ...componentLabelPairs, ...nonTextPairs]).filter((r) => !r.pass);
     const scopeViolations = [
         ...checkScopes(componentVars, theme),
         ...checkOverrideScopes(componentOverrides, componentVars, theme),

package/dist/themes/dark.js

@@ -41,6 +41,10 @@ export const darkTheme = {
     borderFaint: token({ from: ref.fgPrimary, alpha: 0.08, scopes: ["border"] }),
     borderNeutral: token({ from: ref.fgPrimary, alpha: 0.15, scopes: ["border"] }),
     borderStrong: token({ from: ref.fgPrimary, alpha: 0.3, scopes: ["border"] }),
+    /** D106: the outline that alone identifies an unchecked checkbox or radio,
+     * so WCAG 1.4.11 asks 3:1 for it (`nonTextPairs`). borderNeutral measured
+     * 1.32-1.48. Alpha chosen by sweep over every derivable theme. */
+    borderControl: token({ from: ref.fgPrimary, alpha: 0.4, scopes: ["border"] }),
     borderFocus: token({ from: ref.fgAccent, scopes: ["border"] }),
     // Scrims (D32): page-canvas surfaces at alpha — never text pairs, so they
     // carry no AA gate entries.

package/dist/themes/light.js

@@ -44,6 +44,10 @@ export const lightTheme = {
     borderFaint: token({ from: ref.fgPrimary, alpha: 0.08, scopes: ["border"] }),
     borderNeutral: token({ from: ref.fgPrimary, alpha: 0.15, scopes: ["border"] }),
     borderStrong: token({ from: ref.fgPrimary, alpha: 0.3, scopes: ["border"] }),
+    /** D106: the outline that alone identifies an unchecked checkbox or radio,
+     * so WCAG 1.4.11 asks 3:1 for it (`nonTextPairs`). borderNeutral measured
+     * 1.32-1.48. Alpha chosen by sweep over every derivable theme. */
+    borderControl: token({ from: ref.fgPrimary, alpha: 0.55, scopes: ["border"] }),
     borderFocus: token({ from: ref.fgAccent, scopes: ["border"] }),
     // Scrims (D32): page-canvas surfaces at alpha — never text pairs, so they
     // carry no AA gate entries.

package/dist/types/index.d.ts

@@ -4,6 +4,7 @@ export type TokenName =
   | "bgInverted"
   | "bgPrimary"
   | "bgSecondary"
+  | "borderControl"
   | "borderFaint"
   | "borderFocus"
   | "borderNeutral"

package/llms.txt

@@ -39,6 +39,7 @@ OKLCH formula-based design tokens. Code is the source of truth; all artifacts ge
 ## Scrims and borders
 - --psi-scrim-soft/medium/heavy: bgPrimary-derived translucent overlays (0.25/0.35/0.82 alpha) for text-over-media legibility.
 - --psi-border-faint: low-contrast hairline border (fgPrimary at 0.08 alpha), used by Card/NavBar and other bordered surfaces.
+- --psi-border-control: the outline that alone identifies an unchecked Checkbox or Radio (fgPrimary at 0.55 alpha in light-based themes, 0.40 in dark-based), gated at 3:1 on bgPrimary and bgSecondary by `nonTextPairs` (WCAG 1.4.11, D106). Bind it, not --psi-border-neutral (1.32-1.48:1), for any control identified by its outline alone. A consumer theme built with buildThemeCss is held to the same 3:1.
 
 ## Media tint (--psi-media-tint, .psi-media-tint)
 - --psi-media-tint is a brand-defined filter chain (D35); apply the .psi-media-tint utility class to media elements to get a tinted-at-rest, true-color-on-hover/focus treatment, transitioning over --psi-duration-450 / --psi-ease-soft.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handamade/psi-tokens",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "license": "MIT",
   "type": "module",
   "exports": {