@mlola-ui/engine 1.0.13 → 1.1.1

package/generated/agents.json

@@ -233,7 +233,7 @@
     },
     {
       "name": "ml-brand-mark",
-      "note": ""
+      "note": "A brand's own logo takes the mark's place: no chip, the text color, the mark's size."
     },
     {
       "name": "ml-brand-name",

package/generated/agents.md

@@ -42,7 +42,8 @@ Set `data-theme` and `data-mode` on any ancestor. Nothing else changes.
 | `aerogel` | Aerogel Glass |
 | `nordic` | Nordic Earth |
 
-`data-mode` is `light` or `dark`.
+`data-mode` is `light`, `dark`, or `system`, which follows the reader's own setting.
+The themes' type reads `--font-inter`, `--font-newsreader` and `--font-jetbrains` before its fallbacks: load those fonts (next/font's `variable` option, or @font-face) and set the variables on the root, or the page uses the system's fonts.
 
 A project defines its own theme in one file, `mlola.theme.json`, which
 overrides fonts, colors, geometry, the spacing and type scale, and any
@@ -129,6 +130,7 @@ component, so a page built from them themes with the rest.
 
 `.ml-actions` `.ml-brand` `.ml-brand-mark` `.ml-brand-name` `.ml-chart` `.ml-chart-bar` `.ml-chart-bars` `.ml-chart-heading` `.ml-check-list` `.ml-cluster` `.ml-definition-list` `.ml-display` `.ml-divider` `.ml-empty-state` `.ml-eyebrow` `.ml-filter-chip` `.ml-filter-group` `.ml-fine-print` `.ml-form` `.ml-form-message` `.ml-form-options` `.ml-grid` `.ml-heading` `.ml-icon-chip` `.ml-inline-form` `.ml-inline-form-field` `.ml-label` `.ml-lede` `.ml-link` `.ml-page-shell` `.ml-person` `.ml-person-copy` `.ml-positive` `.ml-price` `.ml-required-mark` `.ml-section` `.ml-section-description` `.ml-section-header` `.ml-section-header-centered` `.ml-section-muted` `.ml-section-shell` `.ml-stack` `.ml-stat` `.ml-stat-card` `.ml-stat-grid` `.ml-stat-list` `.ml-stat-meta` `.ml-stat-value` `.ml-text-primary` `.ml-value`
 
+- `.ml-brand-mark` — A brand's own logo takes the mark's place: no chip, the text color, the mark's size.
 - `.ml-check-list` — A list of benefits, each after a check. Pricing tiers and feature rows share it.
 - `.ml-link` — A glyph inside a link flows with the text instead of breaking the line.
 - `.ml-page-shell` — The navigation, main and footer are grid items; they may be narrower than their widest content (a table that scrolls), so the page never does.
@@ -151,6 +153,7 @@ correct. This table is read out of the stylesheet, so it is never stale.
 | `.ml-badge` | `data-size` | `lg`, `sm` |
 | `.ml-badge` | `data-tone` | `danger`, `info`, `primary`, `success`, `warning` |
 | `.ml-badge` | `data-variant` | `outline`, `solid` |
+| `.ml-brand-mark` | `data-kind` | `logo` |
 | `.ml-breadcrumb-item` | `data-collapse-indicator` | _presence only_ |
 | `.ml-breadcrumb-item` | `data-collapsible` | _presence only_ |
 | `.ml-button` | `aria-disabled` | `true` |
@@ -159,6 +162,7 @@ correct. This table is read out of the stylesheet, so it is never stale.
 | `.ml-button` | `data-size` | `icon`, `lg`, `sm` |
 | `.ml-button` | `data-state` | `success` |
 | `.ml-button` | `data-variant` | `danger`, `link`, `outline`, `primary`, `secondary`, `subtle` |
+| `.ml-button` | `data-width` | `full` |
 | `.ml-calendar-cell` | `data-preview` | _presence only_ |
 | `.ml-calendar-cell` | `data-range` | `end`, `start` |
 | `.ml-calendar-day` | `aria-disabled` | `true` |
@@ -212,6 +216,7 @@ correct. This table is read out of the stylesheet, so it is never stale.
 | `.ml-heatmap-cell` | `data-level` | `1`, `2`, `3`, `4` |
 | `.ml-heatmap-cell` | `data-outside` | _presence only_ |
 | `.ml-input` | `aria-invalid` | `true` |
+| `.ml-input` | `data-invalid` | _presence only_ |
 | `.ml-input` | `data-size` | `lg`, `sm` |
 | `.ml-input` | `data-variant` | `filled`, `subtle` |
 | `.ml-input-control` | `data-leading` | _presence only_ |

package/generated/contract.json

@@ -60,6 +60,11 @@
           "solid"
         ]
       },
+      "ml-brand-mark": {
+        "data-kind": [
+          "logo"
+        ]
+      },
       "ml-breadcrumb-item": {
         "data-collapse-indicator": [],
         "data-collapsible": []
@@ -87,6 +92,9 @@
           "primary",
           "secondary",
           "subtle"
+        ],
+        "data-width": [
+          "full"
         ]
       },
       "ml-calendar-cell": {
@@ -283,6 +291,7 @@
         "aria-invalid": [
           "true"
         ],
+        "data-invalid": [],
         "data-size": [
           "lg",
           "sm"

package/generated/recipes.css

@@ -374,6 +374,18 @@
   font-weight: 800;
 }
 
+/* A brand's own logo takes the mark's place: no chip, the text color, the mark's size. */
+.ml-brand-mark[data-kind="logo"] {
+  background: none;
+  color: var(--ml-text);
+}
+
+.ml-brand-mark[data-kind="logo"] > :is(svg, img) {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+
 .ml-brand-name {
   font-size: var(--ml-type-md);
   letter-spacing: -.02em;
@@ -1513,6 +1525,7 @@ button.ml-breadcrumb-link {
 .ml-button {
   position: relative;
   display: inline-flex;
+  max-width: 100%;
   min-height: var(--ml-control-md);
   align-items: center;
   justify-content: center;
@@ -1528,7 +1541,6 @@ button.ml-breadcrumb-link {
   line-height: 1;
   letter-spacing: -.006em;
   text-decoration: none;
-  white-space: nowrap;
   cursor: pointer;
   user-select: none;
   -webkit-tap-highlight-color: transparent;
@@ -1649,10 +1661,22 @@ button.ml-breadcrumb-link {
   padding: 0;
 }
 
+/* A label too long for the space wraps onto balanced lines instead of
+   spilling out. The taller line height is taken back by the margins, so a
+   one-line button is exactly as tall as before. */
 .ml-button-label {
   display: inline-flex;
   align-items: center;
   gap: var(--ml-space-1-5);
+  margin-block: -.1em;
+  line-height: 1.2;
+  text-align: center;
+  text-wrap: balance;
+}
+
+.ml-button[data-width="full"] {
+  display: flex;
+  width: 100%;
 }
 
 .ml-button[data-state="success"] {
@@ -3493,13 +3517,16 @@ button.ml-breadcrumb-link {
   font-size: var(--ml-type-md);
 }
 
+/* A field that is a button or a group says it is invalid with data-invalid: aria-invalid belongs to inputs. */
 .ml-input-field[data-invalid] .ml-input,
-.ml-input[aria-invalid="true"] {
+.ml-input[aria-invalid="true"],
+.ml-input[data-invalid] {
   border-color: var(--ml-danger);
 }
 
 .ml-input-field[data-invalid] .ml-input:focus,
-.ml-input[aria-invalid="true"]:focus {
+.ml-input[aria-invalid="true"]:focus,
+.ml-input[data-invalid]:focus {
   box-shadow: 0 0 0 3px color-mix(in oklab,var(--ml-danger) 20%,transparent);
 }
 

package/generated/theme-spec.schema.json

@@ -105,6 +105,14 @@
           ],
           "description": "Optional different seed for dark mode."
         },
+        "primaryForeground": {
+          "enum": [
+            "auto",
+            "light",
+            "dark"
+          ],
+          "description": "The label on primary fills in light mode. \"auto\" lets the engine choose; \"light\" or \"dark\" moves the fill as far as it must for that label to meet contrast."
+        },
         "neutral": {
           "type": "object",
           "properties": {

package/generated/themes.json

@@ -35,6 +35,7 @@
         "color": {
           "primary": "oklch(0.21 0.006 286)",
           "primaryDark": null,
+          "primaryForeground": "auto",
           "neutral": {
             "hue": 286,
             "chroma": 0.004
@@ -83,6 +84,7 @@
         "color": {
           "primary": "oklch(0.55 0.16 58)",
           "primaryDark": "oklch(0.75 0.16 68)",
+          "primaryForeground": "auto",
           "neutral": {
             "hue": 80,
             "chroma": 0.016
@@ -134,6 +136,7 @@
         "color": {
           "primary": "oklch(0.22 0.01 240)",
           "primaryDark": "oklch(0.78 0.15 210)",
+          "primaryForeground": "auto",
           "neutral": {
             "hue": 240,
             "chroma": 0.004
@@ -185,6 +188,7 @@
         "color": {
           "primary": "oklch(0.55 0.24 285)",
           "primaryDark": "oklch(0.75 0.2 285)",
+          "primaryForeground": "auto",
           "neutral": {
             "hue": 260,
             "chroma": 0.018
@@ -236,6 +240,7 @@
         "color": {
           "primary": "oklch(0.5 0.14 150)",
           "primaryDark": "oklch(0.72 0.15 150)",
+          "primaryForeground": "auto",
           "neutral": {
             "hue": 135,
             "chroma": 0.018

package/generated/tokens.css

@@ -69,7 +69,7 @@
   --ml-font-sans: var(--font-inter, "Inter"), ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
   --ml-font-display: var(--font-inter, "Inter"), ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
   --ml-font-mono: var(--font-jetbrains, "JetBrains Mono"), ui-monospace, "SFMono-Regular", Consolas, monospace;
-  --ml-display-weight: 742;
+  --ml-display-weight: 700;
   --ml-body-leading: 1.495;
   --ml-tracking: -0.0088em;
   --ml-icon-stroke: 1.974;
@@ -200,6 +200,68 @@
   --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
 }
 
+/* data-mode="system" follows the reader's setting: light by default, dark when they ask for it. */
+@media (prefers-color-scheme: dark) {
+:root[data-mode="system"],
+:root[data-theme="graphite"][data-mode="system"],
+[data-theme="graphite"][data-mode="system"] {
+  color-scheme: dark;
+  --ml-background: oklch(0.148 0.005 286);
+  --ml-background-subtle: oklch(0.206 0.005 286);
+  --ml-surface: oklch(0.18 0.005 286);
+  --ml-surface-elevated: oklch(0.215 0.005 286);
+  --ml-text: oklch(0.959 0.004 286);
+  --ml-text-muted: oklch(0.71 0.01 286);
+  --ml-text-faint: oklch(0.64 0.008 286);
+  --ml-border: oklch(0.31 0.006 286);
+  --ml-border-subtle: oklch(0.263 0.005 286);
+  --ml-primary: oklch(0.959 0.006 286);
+  --ml-primary-foreground: oklch(0.18 0.02 286);
+  --ml-primary-hover: oklch(0.862 0.005 286);
+  --ml-primary-text: oklch(0.959 0.006 286);
+  --ml-primary-subtle: oklch(0.236 0.005 286);
+  --ml-success: oklch(0.72 0.15 150);
+  --ml-success-foreground: oklch(0.18 0.02 150);
+  --ml-success-hover: oklch(0.651 0.132 150);
+  --ml-success-text: oklch(0.72 0.15 150);
+  --ml-warning: oklch(0.8 0.16 75);
+  --ml-warning-foreground: oklch(0.18 0.02 75);
+  --ml-warning-hover: oklch(0.722 0.141 75);
+  --ml-warning-text: oklch(0.8 0.16 75);
+  --ml-danger: oklch(0.7 0.191 25);
+  --ml-danger-foreground: oklch(0.18 0.02 25);
+  --ml-danger-hover: oklch(0.75 0.151 25);
+  --ml-danger-text: oklch(0.72 0.174 25);
+  --ml-info: oklch(0.74 0.14 250);
+  --ml-info-foreground: oklch(0.18 0.02 250);
+  --ml-info-hover: oklch(0.669 0.141 250);
+  --ml-info-text: oklch(0.74 0.14 250);
+  --ml-chart-1: oklch(0.74 0.136 255);
+  --ml-chart-2: oklch(0.74 0.138 50);
+  --ml-chart-3: oklch(0.74 0.138 145);
+  --ml-chart-4: oklch(0.74 0.138 300);
+  --ml-chart-5: oklch(0.74 0.13 185);
+  --ml-chart-6: oklch(0.74 0.138 10);
+  --ml-shadow-xs: 0 1px 2px oklch(0 0 0 / 0.1087);
+  --ml-shadow-sm: 0 1px 2px oklch(0 0 0 / 0.0889), 0 2.052px 5.92px -1px oklch(0 0 0 / 0.1186);
+  --ml-shadow-md: 0 1px 2px oklch(0 0 0 / 0.079), 0 4.103px 13.32px -2px oklch(0 0 0 / 0.1581);
+  --ml-shadow-lg: 0 2px 4px oklch(0 0 0 / 0.0692), 0 8.206px 23.68px -4px oklch(0 0 0 / 0.1976);
+  --ml-shadow-xl: 0 4px 8px oklch(0 0 0 / 0.0593), 0 15.044px 41.44px -8px oklch(0 0 0 / 0.247);
+  --ml-shadow-tint: oklch(0 0 0 / 0.1581);
+  --ml-focus: var(--ml-primary-text);
+  --ml-fill-hover: color-mix(in oklab, var(--ml-text) 5%, transparent);
+  --ml-fill-active: color-mix(in oklab, var(--ml-text) 9%, transparent);
+  --ml-track: color-mix(in oklab, var(--ml-text) 12%, transparent);
+  --ml-control-border: var(--ml-text-faint);
+  --ml-ring: 0 0 0 3px color-mix(in oklab, var(--ml-focus) 24%, transparent);
+  --ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28));
+  --ml-highlight: oklch(1 0 0);
+  --ml-knob: var(--ml-highlight);
+  --ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3);
+  --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
+}
+}
+
 @supports (transition-timing-function: linear(0, 1)) {
 :root,
 :root[data-theme="graphite"],
@@ -235,7 +297,7 @@
   --ml-font-sans: var(--font-inter, "Inter"), ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
   --ml-font-display: var(--font-newsreader, "Newsreader"), "Iowan Old Style", Georgia, serif;
   --ml-font-mono: var(--font-jetbrains, "JetBrains Mono"), ui-monospace, "SFMono-Regular", Consolas, monospace;
-  --ml-display-weight: 828;
+  --ml-display-weight: 800;
   --ml-body-leading: 1.536;
   --ml-tracking: -0.0133em;
   --ml-icon-stroke: 1.687;
@@ -365,6 +427,67 @@
   --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
 }
 
+/* data-mode="system" follows the reader's setting: light by default, dark when they ask for it. */
+@media (prefers-color-scheme: dark) {
+:root[data-theme="atelier"][data-mode="system"],
+[data-theme="atelier"][data-mode="system"] {
+  color-scheme: dark;
+  --ml-background: oklch(0.134 0.022 260);
+  --ml-background-subtle: oklch(0.192 0.024 260);
+  --ml-surface: oklch(0.171 0.022 260);
+  --ml-surface-elevated: oklch(0.206 0.024 260);
+  --ml-text: oklch(0.954 0.01 80);
+  --ml-text-muted: oklch(0.705 0.022 80);
+  --ml-text-faint: oklch(0.635 0.016 80);
+  --ml-border: oklch(0.306 0.028 260);
+  --ml-border-subtle: oklch(0.257 0.024 260);
+  --ml-primary: oklch(0.75 0.16 68);
+  --ml-primary-foreground: oklch(0.18 0.02 68);
+  --ml-primary-hover: oklch(0.676 0.141 68);
+  --ml-primary-text: oklch(0.75 0.16 68);
+  --ml-primary-subtle: oklch(0.222 0.049 68);
+  --ml-success: oklch(0.72 0.15 150);
+  --ml-success-foreground: oklch(0.18 0.02 150);
+  --ml-success-hover: oklch(0.65 0.132 150);
+  --ml-success-text: oklch(0.72 0.15 150);
+  --ml-warning: oklch(0.8 0.16 75);
+  --ml-warning-foreground: oklch(0.18 0.02 75);
+  --ml-warning-hover: oklch(0.72 0.141 75);
+  --ml-warning-text: oklch(0.8 0.16 75);
+  --ml-danger: oklch(0.7 0.191 25);
+  --ml-danger-foreground: oklch(0.18 0.02 25);
+  --ml-danger-hover: oklch(0.75 0.151 25);
+  --ml-danger-text: oklch(0.72 0.174 25);
+  --ml-info: oklch(0.74 0.14 250);
+  --ml-info-foreground: oklch(0.18 0.02 250);
+  --ml-info-hover: oklch(0.667 0.141 250);
+  --ml-info-text: oklch(0.74 0.14 250);
+  --ml-chart-1: oklch(0.74 0.147 58);
+  --ml-chart-2: oklch(0.74 0.136 255);
+  --ml-chart-3: oklch(0.74 0.147 145);
+  --ml-chart-4: oklch(0.74 0.147 10);
+  --ml-chart-5: oklch(0.74 0.147 300);
+  --ml-chart-6: oklch(0.74 0.13 185);
+  --ml-shadow-xs: 0 1px 2px oklch(0 0 0 / 0.1735);
+  --ml-shadow-sm: 0 1px 2px oklch(0 0 0 / 0.142), 0 3.189px 10.974px -1px oklch(0 0 0 / 0.1893);
+  --ml-shadow-md: 0 1px 2px oklch(0 0 0 / 0.1262), 0 6.378px 24.692px -2px oklch(0 0 0 / 0.2524);
+  --ml-shadow-lg: 0 2px 4px oklch(0 0 0 / 0.1104), 0 12.756px 43.898px -4px oklch(0 0 0 / 0.3155);
+  --ml-shadow-xl: 0 4px 8px oklch(0 0 0 / 0.0946), 0 23.387px 76.821px -8px oklch(0 0 0 / 0.3944);
+  --ml-shadow-tint: oklch(0 0 0 / 0.2524);
+  --ml-focus: var(--ml-primary-text);
+  --ml-fill-hover: color-mix(in oklab, var(--ml-text) 5%, transparent);
+  --ml-fill-active: color-mix(in oklab, var(--ml-text) 9%, transparent);
+  --ml-track: color-mix(in oklab, var(--ml-text) 12%, transparent);
+  --ml-control-border: var(--ml-text-faint);
+  --ml-ring: 0 0 0 3px color-mix(in oklab, var(--ml-focus) 24%, transparent);
+  --ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28));
+  --ml-highlight: oklch(1 0 0);
+  --ml-knob: var(--ml-highlight);
+  --ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3);
+  --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
+}
+}
+
 @supports (transition-timing-function: linear(0, 1)) {
 :root[data-theme="atelier"],
 [data-theme="atelier"] {
@@ -399,7 +522,7 @@
   --ml-font-sans: var(--font-jetbrains, "JetBrains Mono"), ui-monospace, "SFMono-Regular", Consolas, monospace;
   --ml-font-display: var(--font-jetbrains, "JetBrains Mono"), ui-monospace, "SFMono-Regular", Consolas, monospace;
   --ml-font-mono: var(--font-jetbrains, "JetBrains Mono"), ui-monospace, "SFMono-Regular", Consolas, monospace;
-  --ml-display-weight: 723;
+  --ml-display-weight: 700;
   --ml-body-leading: 1.47;
   --ml-tracking: -0.0076em;
   --ml-icon-stroke: 2.049;
@@ -529,6 +652,67 @@
   --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
 }
 
+/* data-mode="system" follows the reader's setting: light by default, dark when they ask for it. */
+@media (prefers-color-scheme: dark) {
+:root[data-theme="machined"][data-mode="system"],
+[data-theme="machined"][data-mode="system"] {
+  color-scheme: dark;
+  --ml-background: oklch(0.145 0.012 240);
+  --ml-background-subtle: oklch(0.203 0.013 240);
+  --ml-surface: oklch(0.177 0.012 240);
+  --ml-surface-elevated: oklch(0.212 0.013 240);
+  --ml-text: oklch(0.958 0.004 240);
+  --ml-text-muted: oklch(0.708 0.01 240);
+  --ml-text-faint: oklch(0.638 0.008 240);
+  --ml-border: oklch(0.309 0.016 240);
+  --ml-border-subtle: oklch(0.261 0.013 240);
+  --ml-primary: oklch(0.78 0.135 210);
+  --ml-primary-foreground: oklch(0.18 0.02 210);
+  --ml-primary-hover: oklch(0.704 0.122 210);
+  --ml-primary-text: oklch(0.78 0.135 210);
+  --ml-primary-subtle: oklch(0.233 0.04 210);
+  --ml-success: oklch(0.72 0.15 150);
+  --ml-success-foreground: oklch(0.18 0.02 150);
+  --ml-success-hover: oklch(0.651 0.132 150);
+  --ml-success-text: oklch(0.72 0.15 150);
+  --ml-warning: oklch(0.8 0.16 75);
+  --ml-warning-foreground: oklch(0.18 0.02 75);
+  --ml-warning-hover: oklch(0.721 0.141 75);
+  --ml-warning-text: oklch(0.8 0.16 75);
+  --ml-danger: oklch(0.7 0.191 25);
+  --ml-danger-foreground: oklch(0.18 0.02 25);
+  --ml-danger-hover: oklch(0.75 0.151 25);
+  --ml-danger-text: oklch(0.72 0.174 25);
+  --ml-info: oklch(0.74 0.14 250);
+  --ml-info-foreground: oklch(0.18 0.02 250);
+  --ml-info-hover: oklch(0.669 0.141 250);
+  --ml-info-text: oklch(0.74 0.14 250);
+  --ml-chart-1: oklch(0.74 0.136 255);
+  --ml-chart-2: oklch(0.74 0.138 50);
+  --ml-chart-3: oklch(0.74 0.138 145);
+  --ml-chart-4: oklch(0.74 0.138 300);
+  --ml-chart-5: oklch(0.74 0.13 185);
+  --ml-chart-6: oklch(0.74 0.138 10);
+  --ml-shadow-xs: 0 1px 2px oklch(0 0 0 / 0.1093);
+  --ml-shadow-sm: 0 1px 2px oklch(0 0 0 / 0.0894), 0 1.914px 5.925px -1px oklch(0 0 0 / 0.1193);
+  --ml-shadow-md: 0 1px 2px oklch(0 0 0 / 0.0795), 0 3.828px 13.331px -2px oklch(0 0 0 / 0.159);
+  --ml-shadow-lg: 0 2px 4px oklch(0 0 0 / 0.0696), 0 7.655px 23.699px -4px oklch(0 0 0 / 0.1988);
+  --ml-shadow-xl: 0 4px 8px oklch(0 0 0 / 0.0596), 0 14.034px 41.474px -8px oklch(0 0 0 / 0.2485);
+  --ml-shadow-tint: oklch(0 0 0 / 0.159);
+  --ml-focus: var(--ml-primary-text);
+  --ml-fill-hover: color-mix(in oklab, var(--ml-text) 5%, transparent);
+  --ml-fill-active: color-mix(in oklab, var(--ml-text) 9%, transparent);
+  --ml-track: color-mix(in oklab, var(--ml-text) 12%, transparent);
+  --ml-control-border: var(--ml-text-faint);
+  --ml-ring: 0 0 0 3px color-mix(in oklab, var(--ml-focus) 24%, transparent);
+  --ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28));
+  --ml-highlight: oklch(1 0 0);
+  --ml-knob: var(--ml-highlight);
+  --ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3);
+  --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
+}
+}
+
 @supports (transition-timing-function: linear(0, 1)) {
 :root[data-theme="machined"],
 [data-theme="machined"] {
@@ -563,7 +747,7 @@
   --ml-font-sans: var(--font-inter, "Inter"), ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
   --ml-font-display: var(--font-inter, "Inter"), ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
   --ml-font-mono: var(--font-jetbrains, "JetBrains Mono"), ui-monospace, "SFMono-Regular", Consolas, monospace;
-  --ml-display-weight: 782;
+  --ml-display-weight: 800;
   --ml-body-leading: 1.558;
   --ml-tracking: -0.009em;
   --ml-icon-stroke: 1.736;
@@ -693,6 +877,67 @@
   --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
 }
 
+/* data-mode="system" follows the reader's setting: light by default, dark when they ask for it. */
+@media (prefers-color-scheme: dark) {
+:root[data-theme="aerogel"][data-mode="system"],
+[data-theme="aerogel"][data-mode="system"] {
+  color-scheme: dark;
+  --ml-background: oklch(0.141 0.034 270);
+  --ml-background-subtle: oklch(0.199 0.037 270);
+  --ml-surface: oklch(0.185 0.034 270);
+  --ml-surface-elevated: oklch(0.22 0.037 270);
+  --ml-text: oklch(0.956 0.01 260);
+  --ml-text-muted: oklch(0.712 0.025 260);
+  --ml-text-faint: oklch(0.642 0.018 260);
+  --ml-border: oklch(0.309 0.044 270);
+  --ml-border-subtle: oklch(0.261 0.037 270);
+  --ml-primary: oklch(0.75 0.134 285);
+  --ml-primary-foreground: oklch(0.18 0.02 285);
+  --ml-primary-hover: oklch(0.677 0.176 285);
+  --ml-primary-text: oklch(0.75 0.134 285);
+  --ml-primary-subtle: oklch(0.229 0.07 285);
+  --ml-success: oklch(0.72 0.15 150);
+  --ml-success-foreground: oklch(0.18 0.02 150);
+  --ml-success-hover: oklch(0.651 0.132 150);
+  --ml-success-text: oklch(0.72 0.15 150);
+  --ml-warning: oklch(0.8 0.16 75);
+  --ml-warning-foreground: oklch(0.18 0.02 75);
+  --ml-warning-hover: oklch(0.721 0.141 75);
+  --ml-warning-text: oklch(0.8 0.16 75);
+  --ml-danger: oklch(0.7 0.191 25);
+  --ml-danger-foreground: oklch(0.18 0.02 25);
+  --ml-danger-hover: oklch(0.75 0.151 25);
+  --ml-danger-text: oklch(0.72 0.174 25);
+  --ml-info: oklch(0.74 0.14 250);
+  --ml-info-foreground: oklch(0.18 0.02 250);
+  --ml-info-hover: oklch(0.668 0.141 250);
+  --ml-info-text: oklch(0.74 0.14 250);
+  --ml-chart-1: oklch(0.74 0.14 285);
+  --ml-chart-2: oklch(0.74 0.156 145);
+  --ml-chart-3: oklch(0.74 0.156 50);
+  --ml-chart-4: oklch(0.74 0.156 10);
+  --ml-chart-5: oklch(0.74 0.13 185);
+  --ml-chart-6: oklch(0.74 0.136 255);
+  --ml-shadow-xs: 0 1px 2px oklch(0 0 0 / 0.2121);
+  --ml-shadow-sm: 0 1px 2px oklch(0 0 0 / 0.1735), 0 4.909px 14.309px -1px oklch(0 0 0 / 0.2313);
+  --ml-shadow-md: 0 1px 2px oklch(0 0 0 / 0.1542), 0 9.818px 32.195px -2px oklch(0 0 0 / 0.3084);
+  --ml-shadow-lg: 0 2px 4px oklch(0 0 0 / 0.1349), 0 19.636px 57.235px -4px oklch(0 0 0 / 0.3855);
+  --ml-shadow-xl: 0 4px 8px oklch(0 0 0 / 0.1157), 0 35.999px 100.162px -8px oklch(0 0 0 / 0.4819);
+  --ml-shadow-tint: oklch(0 0 0 / 0.3084);
+  --ml-focus: var(--ml-primary-text);
+  --ml-fill-hover: color-mix(in oklab, var(--ml-text) 5%, transparent);
+  --ml-fill-active: color-mix(in oklab, var(--ml-text) 9%, transparent);
+  --ml-track: color-mix(in oklab, var(--ml-text) 12%, transparent);
+  --ml-control-border: var(--ml-text-faint);
+  --ml-ring: 0 0 0 3px color-mix(in oklab, var(--ml-focus) 24%, transparent);
+  --ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28));
+  --ml-highlight: oklch(1 0 0);
+  --ml-knob: var(--ml-highlight);
+  --ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3);
+  --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
+}
+}
+
 @supports (transition-timing-function: linear(0, 1)) {
 :root[data-theme="aerogel"],
 [data-theme="aerogel"] {
@@ -727,7 +972,7 @@
   --ml-font-sans: var(--font-inter, "Inter"), ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
   --ml-font-display: var(--font-inter, "Inter"), ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
   --ml-font-mono: var(--font-jetbrains, "JetBrains Mono"), ui-monospace, "SFMono-Regular", Consolas, monospace;
-  --ml-display-weight: 792;
+  --ml-display-weight: 800;
   --ml-body-leading: 1.541;
   --ml-tracking: -0.011em;
   --ml-icon-stroke: 1.834;
@@ -857,6 +1102,67 @@
   --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
 }
 
+/* data-mode="system" follows the reader's setting: light by default, dark when they ask for it. */
+@media (prefers-color-scheme: dark) {
+:root[data-theme="nordic"][data-mode="system"],
+[data-theme="nordic"][data-mode="system"] {
+  color-scheme: dark;
+  --ml-background: oklch(0.133 0.029 145);
+  --ml-background-subtle: oklch(0.191 0.032 145);
+  --ml-surface: oklch(0.167 0.029 145);
+  --ml-surface-elevated: oklch(0.202 0.032 145);
+  --ml-text: oklch(0.953 0.01 135);
+  --ml-text-muted: oklch(0.701 0.025 135);
+  --ml-text-faint: oklch(0.632 0.018 135);
+  --ml-border: oklch(0.302 0.037 145);
+  --ml-border-subtle: oklch(0.255 0.032 145);
+  --ml-primary: oklch(0.72 0.15 150);
+  --ml-primary-foreground: oklch(0.18 0.02 150);
+  --ml-primary-hover: oklch(0.65 0.132 150);
+  --ml-primary-text: oklch(0.72 0.15 150);
+  --ml-primary-subtle: oklch(0.221 0.061 150);
+  --ml-success: oklch(0.72 0.15 150);
+  --ml-success-foreground: oklch(0.18 0.02 150);
+  --ml-success-hover: oklch(0.65 0.132 150);
+  --ml-success-text: oklch(0.72 0.15 150);
+  --ml-warning: oklch(0.8 0.16 75);
+  --ml-warning-foreground: oklch(0.18 0.02 75);
+  --ml-warning-hover: oklch(0.72 0.141 75);
+  --ml-warning-text: oklch(0.8 0.16 75);
+  --ml-danger: oklch(0.7 0.191 25);
+  --ml-danger-foreground: oklch(0.18 0.02 25);
+  --ml-danger-hover: oklch(0.75 0.151 25);
+  --ml-danger-text: oklch(0.72 0.174 25);
+  --ml-info: oklch(0.74 0.14 250);
+  --ml-info-foreground: oklch(0.18 0.02 250);
+  --ml-info-hover: oklch(0.667 0.141 250);
+  --ml-info-text: oklch(0.74 0.14 250);
+  --ml-chart-1: oklch(0.74 0.129 150);
+  --ml-chart-2: oklch(0.74 0.129 300);
+  --ml-chart-3: oklch(0.74 0.129 50);
+  --ml-chart-4: oklch(0.74 0.129 255);
+  --ml-chart-5: oklch(0.74 0.129 10);
+  --ml-chart-6: oklch(0.74 0.129 185);
+  --ml-shadow-xs: 0 1px 2px oklch(0 0 0 / 0.1456);
+  --ml-shadow-sm: 0 1px 2px oklch(0 0 0 / 0.1191), 0 2.444px 8.702px -1px oklch(0 0 0 / 0.1588);
+  --ml-shadow-md: 0 1px 2px oklch(0 0 0 / 0.1059), 0 4.887px 19.58px -2px oklch(0 0 0 / 0.2118);
+  --ml-shadow-lg: 0 2px 4px oklch(0 0 0 / 0.0927), 0 9.775px 34.81px -4px oklch(0 0 0 / 0.2647);
+  --ml-shadow-xl: 0 4px 8px oklch(0 0 0 / 0.0794), 0 17.92px 60.917px -8px oklch(0 0 0 / 0.3309);
+  --ml-shadow-tint: oklch(0 0 0 / 0.2118);
+  --ml-focus: var(--ml-primary-text);
+  --ml-fill-hover: color-mix(in oklab, var(--ml-text) 5%, transparent);
+  --ml-fill-active: color-mix(in oklab, var(--ml-text) 9%, transparent);
+  --ml-track: color-mix(in oklab, var(--ml-text) 12%, transparent);
+  --ml-control-border: var(--ml-text-faint);
+  --ml-ring: 0 0 0 3px color-mix(in oklab, var(--ml-focus) 24%, transparent);
+  --ml-scrim: oklch(from var(--ml-background) calc(l * 0.22) c h / calc(0.54 - l * 0.28));
+  --ml-highlight: oklch(1 0 0);
+  --ml-knob: var(--ml-highlight);
+  --ml-knob-shadow: 0 0 0 1px oklch(0 0 0 / 0.25), 0 1px 4px oklch(0 0 0 / 0.3);
+  --ml-sheen: linear-gradient(135deg, color-mix(in oklab, var(--ml-highlight) 18%, transparent), transparent 46%, oklch(0 0 0 / 0.05));
+}
+}
+
 @supports (transition-timing-function: linear(0, 1)) {
 :root[data-theme="nordic"],
 [data-theme="nordic"] {

package/generated/tokens.json

@@ -145,6 +145,7 @@
           "color": {
             "primary": "oklch(0.21 0.006 286)",
             "primaryDark": null,
+            "primaryForeground": "auto",
             "neutral": {
               "hue": 286,
               "chroma": 0.004
@@ -1187,6 +1188,7 @@
           "color": {
             "primary": "oklch(0.55 0.16 58)",
             "primaryDark": "oklch(0.75 0.16 68)",
+            "primaryForeground": "auto",
             "neutral": {
               "hue": 80,
               "chroma": 0.016
@@ -2232,6 +2234,7 @@
           "color": {
             "primary": "oklch(0.22 0.01 240)",
             "primaryDark": "oklch(0.78 0.15 210)",
+            "primaryForeground": "auto",
             "neutral": {
               "hue": 240,
               "chroma": 0.004
@@ -3277,6 +3280,7 @@
           "color": {
             "primary": "oklch(0.55 0.24 285)",
             "primaryDark": "oklch(0.75 0.2 285)",
+            "primaryForeground": "auto",
             "neutral": {
               "hue": 260,
               "chroma": 0.018
@@ -4322,6 +4326,7 @@
           "color": {
             "primary": "oklch(0.5 0.14 150)",
             "primaryDark": "oklch(0.72 0.15 150)",
+            "primaryForeground": "auto",
             "neutral": {
               "hue": 135,
               "chroma": 0.018

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlola-ui/engine",
-  "version": "1.0.13",
+  "version": "1.1.1",
   "description": "Framework-free CSS, spring easings, and the machine-readable contract for Mlola UI",
   "type": "module",
   "sideEffects": [
@@ -21,7 +21,11 @@
     "./motion.css": "./generated/motion.css",
     "./accessibility.css": "./generated/accessibility.css",
     "./tokens.json": "./generated/tokens.json",
-    "./manifest.json": "./generated/manifest.json"
+    "./manifest.json": "./generated/manifest.json",
+    "./theme": {
+      "types": "./src/theme.d.ts",
+      "default": "./src/theme.mjs"
+    }
   },
   "scripts": {
     "build": "node build.mjs",

package/src/declarations.mjs

@@ -92,7 +92,9 @@ export function themeDeclarations(spec) {
     `--ml-font-sans: ${fonts.sans}`,
     `--ml-font-display: ${fonts.display}`,
     `--ml-font-mono: ${fonts.mono}`,
-    `--ml-display-weight: ${derived.displayWeight}`,
+    // Written as a whole hundred: a font that ships only static weights
+    // (400, 700, 900) would render 737 as the next weight up, often a heavy 900.
+    `--ml-display-weight: ${Math.round(derived.displayWeight / 100) * 100}`,
     `--ml-body-leading: ${round(derived.bodyLeading)}`,
     `--ml-tracking: ${round(derived.tracking, 4)}em`,
     `--ml-icon-stroke: ${round(derived.iconStroke)}`,

package/src/palette.mjs

@@ -63,22 +63,28 @@ const inkOn = (hue) => ({ L: 0.18, C: 0.02, H: hue });
 
 /**
  * Pick whichever of white or dark ink reads better on `fill`. If neither
- * reaches the target, move the fill until the better one does.
+ * reaches the target, move the fill until the better one does: it is the
+ * closer of the two, so the fill moves least. `preferDark` settles a tie.
  */
-function fillPair(fill, target, preferLight) {
-  let base = fill;
+function fillPair(fill, target, preferDark) {
   const dark = inkOn(fill.H);
-  const light = contrast(WHITE, base);
-  const deep = contrast(dark, base);
-  if (Math.max(light, deep) >= target) {
-    return { fill: base, foreground: light >= deep ? WHITE : dark };
-  }
-  if (preferLight ? deep > light : light >= deep) {
-    base = solveLightness(base, dark, target, "lighter");
-    return { fill: base, foreground: dark };
-  }
-  base = solveLightness(base, WHITE, target, "darker");
-  return { fill: base, foreground: WHITE };
+  const light = contrast(WHITE, fill);
+  const deep = contrast(dark, fill);
+  const useDark = deep > light || (deep === light && preferDark);
+  if (Math.max(light, deep) >= target) return { fill, foreground: useDark ? dark : WHITE };
+  if (useDark) return { fill: solveLightness(fill, dark, target, "lighter"), foreground: dark };
+  return { fill: solveLightness(fill, WHITE, target, "darker"), foreground: WHITE };
+}
+
+/**
+ * The label a theme asked for, and the fill moved (darker for white, lighter
+ * for dark ink) only as far as that label needs to meet the target. Light
+ * mode only: at night a fill dark enough for white would sink into the page.
+ */
+function fillFor(fill, foreground, target) {
+  const ink = foreground === "light" ? WHITE : inkOn(fill.H);
+  const moved = contrast(ink, fill) >= target ? fill : solveLightness(fill, ink, target, foreground === "light" ? "darker" : "lighter");
+  return { fill: moved, foreground: ink };
 }
 
 const tint = (hue, chroma, L) => ({ L, C: chroma, H: hue });
@@ -156,7 +162,9 @@ function primaryFor(spec, mode, neutrals) {
     fill = solveLightness(fill, neutrals.background, TARGETS.separation, mode === "light" ? "darker" : "lighter");
   }
   fill = deepenForWhite(fill, mode);
-  const pair = fillPair(fill, TARGETS.body, mode === "dark");
+  const pair = mode === "light" && spec.color.primaryForeground && spec.color.primaryForeground !== "auto"
+    ? fillFor(fill, spec.color.primaryForeground, TARGETS.body)
+    : fillPair(fill, TARGETS.body, mode === "dark");
   // Links and focus rings follow the brand. A monochrome brand inverted for
   // the night reads as the inverted ink, not a mid gray lifted from the day's.
   const textSeed = mode === "dark" && !spec.color.primaryDark && isAchromatic(seed) ? fill : seed;

package/src/spec.mjs

@@ -133,6 +133,9 @@ export const PALETTE_TOKENS = [
 
 const ID_PATTERN = /^[a-z][a-z0-9-]{0,47}$/;
 
+/** What a theme may ask for on primary fills: the engine's choice, white, or dark ink. */
+const FOREGROUNDS = ["auto", "light", "dark"];
+
 const DEFAULT_SPEC = {
   specVersion: SPEC_VERSION,
   id: "custom",
@@ -141,6 +144,7 @@ const DEFAULT_SPEC = {
   color: {
     primary: "oklch(0.21 0.006 286)",
     primaryDark: null,
+    primaryForeground: "auto",
     neutral: { hue: 286, chroma: 0.004 },
     ink: null,
   },
@@ -227,6 +231,7 @@ export function normalizeSpec(input = {}, base = DEFAULT_SPEC) {
     color: {
       primary: readColor(color.primary ?? legacySignal, base.color.primary),
       primaryDark: readColor(color.primaryDark ?? legacySignalDark, base.color.primaryDark ?? null),
+      primaryForeground: FOREGROUNDS.includes(color.primaryForeground) ? color.primaryForeground : (base.color.primaryForeground ?? "auto"),
       neutral: readTint(color.neutral, base.color.neutral),
       ink: color.ink === null ? null : readTint(color.ink, base.color.ink ?? null),
     },
@@ -255,6 +260,9 @@ export function validateSpec(input) {
   if (input.color?.primaryDark != null && !parseColor(input.color.primaryDark)) {
     problems.push("color.primaryDark must be an oklch() or hex color, or null.");
   }
+  if (input.color?.primaryForeground !== undefined && !FOREGROUNDS.includes(input.color.primaryForeground)) {
+    problems.push(`color.primaryForeground must be one of ${FOREGROUNDS.join(", ")}.`);
+  }
   const neutral = input.color?.neutral;
   if (!neutral || typeof neutral.hue !== "number" || typeof neutral.chroma !== "number" || neutral.chroma < 0 || neutral.chroma > 0.06) {
     problems.push("color.neutral needs a hue and a chroma from 0 to 0.06.");
@@ -302,6 +310,10 @@ export function renderSpecSchema() {
         properties: {
           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." },
+          primaryForeground: {
+            enum: FOREGROUNDS,
+            description: "The label on primary fills in light mode. \"auto\" lets the engine choose; \"light\" or \"dark\" moves the fill as far as it must for that label to meet contrast.",
+          },
           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

@@ -17,13 +17,14 @@ function paletteLines(palette) {
   return Object.entries(palette).map(([token, value]) => `--ml-${token}: ${value}`);
 }
 
-function selectorList(spec, { root, aliases }, dark) {
+/** The theme's selectors, for light (no mode), or for a mode: "dark", or "system" (dark only when the reader asks for it). */
+function selectorList(spec, { root, aliases }, mode) {
   const attributes = [spec.id, ...aliases].map((name) => `[data-theme="${name}"]`);
   const list = [];
   if (root) list.push(":root");
   for (const attribute of attributes) list.push(`:root${attribute}`, attribute);
-  if (!dark) return list.join(",\n");
-  return list.map((selector) => (selector === ":root" ? ':root[data-mode="dark"]' : `${selector}[data-mode="dark"]`)).join(",\n");
+  if (!mode) return list.join(",\n");
+  return list.map((selector) => `${selector}[data-mode="${mode}"]`).join(",\n");
 }
 
 /**
@@ -45,6 +46,7 @@ export function renderSpecCss(spec, { root = false, aliases = [], banner = true
   const options = { root, aliases };
 
   const title = spec.label.replace(/\*\//g, "* /");
+  const darkBlock = `  color-scheme: dark;\n${indent(paletteLines(dark))}\n${indent(darkShadowDeclarations(spec.vector))}\n${indent(PALETTE_DERIVED)}`;
   return `${banner ? `/* ${title} — generated by @mlola-ui/engine from its theme spec. Do not hand edit. */\n` : ""}${selectorList(spec, options, false)} {
   color-scheme: light;
 ${indent(themeDeclarations(spec))}
@@ -52,11 +54,15 @@ ${indent(paletteLines(light))}
 ${indent(PALETTE_DERIVED)}
 }
 
-${selectorList(spec, options, true)} {
-  color-scheme: dark;
-${indent(paletteLines(dark))}
-${indent(darkShadowDeclarations(spec.vector))}
-${indent(PALETTE_DERIVED)}
+${selectorList(spec, options, "dark")} {
+${darkBlock}
+}
+
+/* data-mode="system" follows the reader's setting: light by default, dark when they ask for it. */
+@media (prefers-color-scheme: dark) {
+${selectorList(spec, options, "system")} {
+${darkBlock}
+}
 }
 
 @supports (transition-timing-function: linear(0, 1)) {

package/src/theme.d.ts

@@ -0,0 +1,17 @@
+/** A project theme: a theme spec plus `inherit`, `scale` and `extend`. See https://ui.mlola.com/docs/theming#custom. */
+export type ThemeInput = Record<string, unknown>;
+
+export interface ProjectTheme extends Record<string, unknown> {
+  /** The theme's id: its `data-theme` value. */
+  id: string;
+  label: string;
+  /** The canonical theme whose decisions fill what the file leaves out. */
+  inherit: string;
+}
+
+export const THEME_CHANNELS: readonly string[];
+/** The spec with every default filled in. */
+export function defineTheme(input?: ThemeInput): ProjectTheme;
+/** The theme's CSS, on the same `data-theme` contract as every canonical theme. */
+export function renderThemeCss(input: ThemeInput): string;
+export function renderThemeManifest(projectThemeInput?: ThemeInput | null): Array<Record<string, unknown>>;