@mlola-ui/engine 1.0.1 → 1.0.3

package/src/config.mjs

@@ -100,7 +100,7 @@ const canonicalMeta = {
 };
 
 /**
- * Canonical themes in the shape the rest of the build reads: the normalised
+ * Canonical themes in the shape the rest of the build reads: the normalized
  * spec, its vector as an ordered array, and the descriptive copy.
  */
 export const profiles = Object.fromEntries(

package/src/contract.mjs

@@ -10,7 +10,7 @@ import { behaviors } from "./behavior-spec.mjs";
  * library actually renders. Any renderer in any language that emits these
  * classes and attributes gets the correct visuals.
  *
- * The behaviour half — which attribute flips on which event, and the keyboard
+ * The behavior half — which attribute flips on which event, and the keyboard
  * map — cannot be read out of CSS, so it is authored in behavior-spec.mjs and
  * audited against this derived data.
  */

package/src/contrast.mjs

@@ -1,5 +1,5 @@
 /**
- * Colour math for the accessibility gate.
+ * Color math for the accessibility gate.
  *
  * The palettes are curated by hand, so "meets WCAG AA" has to be a measured
  * fact rather than a comment. This converts the engine's OKLCH tokens to sRGB,
@@ -44,7 +44,7 @@ export function oklchToSrgb({ L, C, H }) {
   });
 }
 
-/** Composite a possibly translucent colour over an opaque backdrop. */
+/** Composite a possibly translucent color over an opaque backdrop. */
 function composite([top, alpha], [bottom]) {
   return top.map((channel, index) => channel * alpha + bottom[index] * (1 - alpha));
 }

package/src/declarations.mjs

@@ -35,6 +35,8 @@ export function shadowDeclarations(derived, gain = 1) {
     `--ml-shadow-md: 0 1px 2px ${alpha(0.4)}, 0 ${px(y * 0.6)} ${px(blur * 0.9)} -2px ${alpha(0.8)}`,
     `--ml-shadow-lg: 0 2px 4px ${alpha(0.35)}, 0 ${px(y * 1.2)} ${px(blur * 1.6)} -4px ${alpha(1)}`,
     `--ml-shadow-xl: 0 4px 8px ${alpha(0.3)}, 0 ${px(y * 2.2)} ${px(blur * 2.8)} -8px ${alpha(1.25)}`,
+    // The contact shadow's color alone, for shapes a box-shadow cannot follow (filter: drop-shadow).
+    `--ml-shadow-tint: ${alpha(0.8)}`,
   ];
 }
 
@@ -113,7 +115,7 @@ export function themeDeclarations(spec) {
  */
 export const PALETTE_DERIVED = [
   "--ml-focus: var(--ml-primary-text)",
-  // Hover and pressed fills move a colour toward the page, so they lighten in
+  // Hover and pressed fills move a color toward the page, so they lighten in
   // light mode and darken in dark mode without a second palette.
   "--ml-primary-hover: color-mix(in oklab, var(--ml-primary) 88%, var(--ml-background))",
   "--ml-fill-hover: color-mix(in oklab, var(--ml-text) 5%, transparent)",
@@ -128,4 +130,16 @@ export const PALETTE_DERIVED = [
   // it carries the theme's tint, and more opaque the darker the page, so it
   // reads as a light veil by day and still separates layers at night.
   "--ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28))",
+  // Pure light: a specular glint, the lit side of an orb. Light in both modes,
+  // as light is.
+  "--ml-highlight: oklch(1 0 0)",
+  // The thumb of a switch or slider. It stays light on any track and in dark
+  // mode, like a physical control; a theme may give it another finish.
+  "--ml-knob: var(--ml-highlight)",
+  // A knob that must read over any color at all (a color picker's handle)
+  // carries its own edge: a hairline and a small drop.
+  "--ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3)",
+  // The sheen of a specular surface: light from the top left, a little shade
+  // in the far corner.
+  "--ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05))",
 ];

package/src/library-recipes.mjs

@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
  * Assemble the library's stylesheets from the CSS files their owners keep.
  *
  * Each component carries its own `<name>.css` next to its source, so a
- * component's markup, behaviour and styling are reviewed and copied together.
+ * component's markup, behavior and styling are reviewed and copied together.
  * The engine only concatenates them, in a stable order, into the published
  * layers:
  *

package/src/palette.mjs

@@ -4,23 +4,23 @@ import { contrast, formatColor, parseColor, solveLightness } from "./color.mjs";
  * Palettes are derived, not curated.
  *
  * A spec gives a primary seed and the tint of the neutrals; this module builds
- * every colour token for light and dark mode from them. Each text or fill
+ * every color token for light and dark mode from them. Each text or fill
  * pairing is solved to a WCAG target instead of being picked and then tested,
  * so any seed a person or a model supplies produces an accessible palette.
  *
  * Roles, so a token is never asked to do two jobs:
  *   - `primary`, `success`, ... are fills; their `-foreground` sits on them.
- *   - `primary-text` is the brand colour solved for text on the page (links,
+ *   - `primary-text` is the brand color solved for text on the page (links,
  *     focus rings). A vivid yellow stays a yellow button; its links go darker.
- *   - `success-text`, `danger-text`, ... are the status colours for text on
- *     the page, which a fill colour usually cannot be in both modes.
+ *   - `success-text`, `danger-text`, ... are the status colors for text on
+ *     the page, which a fill color usually cannot be in both modes.
  */
 
 /** WCAG thresholds with a small margin, so rounding never drops below them. */
 export const TARGETS = {
   text: 17,
   textDark: 17.5,
-  // Coloured text is solved with headroom, so it still clears AA on the
+  // Colored text is solved with headroom, so it still clears AA on the
   // hover fills and ~15% tints the library draws under it.
   body: 5.3,
   // Every text role is readable text. Faint is the quietest level, not a
@@ -42,7 +42,7 @@ function hardestBackground(foreground, neutrals) {
   );
 }
 
-/** Solve a text colour against every page background it may sit on. */
+/** Solve a text color against every page background it may sit on. */
 function solveText(color, neutrals, target, direction) {
   let solved = solveLightness(color, neutrals.background, target, direction);
   solved = solveLightness(solved, hardestBackground(solved, neutrals), target, direction);
@@ -130,17 +130,17 @@ function primaryFor(spec, mode, neutrals) {
   let fill = { L: seed.L, C: seed.C, H: seed.H };
   if (mode === "dark" && !spec.color.primaryDark) {
     // Without an explicit night seed, a near-black brand inverts to near-white
-    // and a deep brand colour is lifted, so neither sinks into the page.
+    // and a deep brand color is lifted, so neither sinks into the page.
     fill = isAchromatic(seed)
       ? { L: neutrals.text.L, C: seed.C, H: seed.H }
       : { L: Math.max(seed.L, 0.62), C: seed.C, H: seed.H };
   }
-  // A fill keeps the brand's colour; it only has to stand apart from the page
+  // A fill keeps the brand's color; it only has to stand apart from the page
   // and carry its own label. Text contrast is primary-text's job.
   if (contrast(fill, neutrals.background) < TARGETS.separation) {
     fill = solveLightness(fill, neutrals.background, TARGETS.separation, mode === "light" ? "darker" : "lighter");
   }
-  // WCAG 2's ratio favours dark ink on mid-tone saturated colours, but eyes read
+  // WCAG 2's ratio favours dark ink on mid-tone saturated colors, but eyes read
   // white on a violet, blue or red far better. In light mode a chromatic,
   // non-warm brand darkens a little (at most 0.12 L) so white clears the
   // target; yellows and oranges keep dark ink, as convention expects.
@@ -172,7 +172,7 @@ function statusFor(name, mode, neutrals) {
 }
 
 /**
- * Six categorical colours for charts, apart from the status roles so a series
+ * Six categorical colors for charts, apart from the status roles so a series
  * never reads as "good" or "bad" by accident. The first follows the brand's
  * hue (blue for a monochrome brand); the rest are the hues furthest from those
  * already taken, so neighbours never share a family. Each is solved to 3:1

package/src/render.mjs

@@ -105,6 +105,10 @@ export function renderMotionCss() {
   return `/* Motion and accessibility layer. */\n${readEngineCss("motion")}`;
 }
 
+export function renderAccessibilityCss() {
+  return `/* Accessibility layer: last in the cascade, so these guarantees hold over any recipe. */\n${readEngineCss("accessibility")}`;
+}
+
 export function renderDtcg() {
   const dtcgColor = (value) => {
     const match = value.match(/^oklch\(([\d.]+)\s+([\d.]+)\s+([\d.]+)(?:\s*\/\s*([\d.]+))?\)$/);

package/src/spec.mjs

@@ -11,7 +11,7 @@ import { parseColor } from "./color.mjs";
  *
  * Every field is one atomic decision, so it can be answered by one typed
  * question: a channel is a score on an ordered scale, a material or a font set
- * is a choice among named options, a colour is either given or chosen from a
+ * is a choice among named options, a color is either given or chosen from a
  * hue family.
  *
  * Deliberate choices, because this has to survive a decade:
@@ -47,7 +47,7 @@ export const MATERIALS = {
   anodized: "Opaque surfaces with a machined top highlight.",
 };
 
-/** Hue families a colour can be chosen from, as OKLCH hue angles. */
+/** Hue families a color can be chosen from, as OKLCH hue angles. */
 export const HUE_FAMILIES = {
   red: 25,
   orange: 50,
@@ -202,7 +202,7 @@ export function resolveFonts(fonts) {
 }
 
 /**
- * Normalise any theme input into a complete spec. Never throws: a partial
+ * Normalize any theme input into a complete spec. Never throws: a partial
  * theme inherits the rest from `base`, which defaults to a neutral spec.
  *
  * Also reads the pre-1.0 theme file shape (`theme` for the vector, `inherit`,
@@ -246,9 +246,9 @@ export function validateSpec(input) {
     const value = input.vector?.[channel];
     if (typeof value !== "number" || value < 0 || value > 1) problems.push(`vector.${channel} must be a number from 0 to 1.`);
   }
-  if (!parseColor(input.color?.primary)) problems.push("color.primary must be an oklch() or hex colour.");
+  if (!parseColor(input.color?.primary)) problems.push("color.primary must be an oklch() or hex color.");
   if (input.color?.primaryDark != null && !parseColor(input.color.primaryDark)) {
-    problems.push("color.primaryDark must be an oklch() or hex colour, or null.");
+    problems.push("color.primaryDark must be an oklch() or hex color, or null.");
   }
   const neutral = input.color?.neutral;
   if (!neutral || typeof neutral.hue !== "number" || typeof neutral.chroma !== "number" || neutral.chroma < 0 || neutral.chroma > 0.06) {
@@ -295,7 +295,7 @@ export function renderSpecSchema() {
       color: {
         type: "object",
         properties: {
-          primary: { type: "string", description: "Seed for the primary colour, oklch() or hex. Lightness is adjusted to meet contrast." },
+          primary: { type: "string", description: "Seed for the primary color, oklch() or hex. Lightness is adjusted to meet contrast." },
           primaryDark: { type: ["string", "null"], description: "Optional different seed for dark mode." },
           neutral: { ...tint, description: "Tint of the page and surfaces." },
           ink: { anyOf: [tint, { type: "null" }], description: "Tint of text and dark-mode surfaces. Defaults to neutral." },

package/src/theme-css.mjs

@@ -27,7 +27,7 @@ function selectorList(spec, { root, aliases }, dark) {
 }
 
 /**
- * Render a normalised spec as a self-contained stylesheet.
+ * Render a normalized spec as a self-contained stylesheet.
  *
  * `root` also applies the theme to `:root`, which only the default theme
  * does. `aliases` are further `data-theme` names for the same theme, such as