@quilltap/theme-storybook 1.0.61 → 1.0.63

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to `@quilltap/theme-storybook` will be documented in this file.
 
+## [1.0.63] - 2026-08-25
+
+### Added
+- The rest of the `qt-*` utility families the app actually ships, so a theme can be previewed against what it will really meet: the missing opacity steps for `qt-bg-muted` (20–80), `qt-bg-card` (50–90), `qt-bg-primary`, `qt-bg-destructive`, `qt-bg-success`, `qt-bg-warning`, `qt-bg-info` and `qt-bg-secondary`; `qt-border-default`, `qt-border-primary`, `qt-border-destructive`, `qt-border-warning` and `qt-border-success` at their used opacities; `qt-text-secondary/50–80` and the status colours at `/80`; and the surface colours `qt-bg-default`, `qt-bg-input`, `qt-bg-secondary`, `qt-border-accent`, `qt-border-primary-foreground`.
+- 34 state forms of those utilities — `hover:`, `focus:`, `disabled:`, `placeholder:`, `file:` and one named `group-hover/thumb:`. In the app every one of these is hand-written and escaped, because Tailwind generates no variants for a class declared inside `@layer utilities`; they are mirrored here so a theme author previewing hover states sees what the app actually ships rather than a resting state that never moves.
+
+### Notes
+- The typography-sizing classes (`qt-text-small`, `qt-text-xs`, `qt-text-label`, `qt-text-label-xs`, `qt-text-large`, `qt-text-lead`, `qt-text-section`) live in the app's `@layer components` sheet and have never been mirrored here. Still outstanding; the color-carrying `qt-text-*` utilities are complete.
+
+## [1.0.62] - 2026-08-25
+
+### Added
+- `qt-text-on-primary`, `qt-text-on-success`, and `qt-text-on-destructive`: the rest of the on-a-filled-surface foreground family that `qt-text-on-accent` started, each mapping to the theme's matching `*Foreground` token. Plus the hand-written hover partners `hover:qt-text-on-accent/-primary/-success/-destructive`, for controls that sit quiet at rest and take a filled background on hover. Mirrors the app-side definitions.
+- `Surfaces` story: a "Foregrounds on filled surfaces" section previewing all four fills with their foregrounds, and a hover row for the hover partners. It also spells out the naming trap — the classes are `-on-<fill>`, never `-<fill>-foreground`, which is the Tailwind spelling and no `qt-` class at all.
+
 ## [1.0.44] - 2026-06-14
 
 ### Added

package/dist/{chunk-XSNC4J5T.mjs → chunk-TESCTXU3.mjs}

@@ -1043,6 +1043,11 @@ var note = {
 };
 var Surfaces = () => {
   return /* @__PURE__ */ jsxs9("div", { style: { padding: "1.5rem" }, children: [
+    /* @__PURE__ */ jsx9("style", { children: `
+        .surfaces-demo-fill-primary:hover { background-color: var(--color-primary); }
+        .surfaces-demo-fill-success:hover { background-color: var(--color-success); }
+        .surfaces-demo-fill-destructive:hover { background-color: var(--color-destructive); }
+      ` }),
     /* @__PURE__ */ jsx9("h2", { style: { fontSize: "1.5rem", fontWeight: 700, marginBottom: "0.5rem" }, children: "Surfaces" }),
     /* @__PURE__ */ jsxs9("p", { style: { ...note, maxWidth: "44rem" }, children: [
       "How accent-coloured surfaces stay legible no matter how bold a theme makes its ",
@@ -1079,6 +1084,53 @@ var Surfaces = () => {
         /* @__PURE__ */ jsx9("kbd", { className: "qt-bg-accent qt-text-on-accent", style: { padding: "0.125rem 0.375rem", borderRadius: "0.25rem", fontSize: "0.75rem" }, children: "\u21B5" })
       ] })
     ] }),
+    /* @__PURE__ */ jsxs9("section", { style: { marginBottom: "2rem" }, children: [
+      /* @__PURE__ */ jsxs9("h3", { style: sectionHeading2, children: [
+        "Foregrounds on filled surfaces \u2014 the ",
+        /* @__PURE__ */ jsx9("code", { children: "qt-text-on-*" }),
+        " family"
+      ] }),
+      /* @__PURE__ */ jsxs9("p", { style: note, children: [
+        "The same contract, extended to every filled surface the app paints:",
+        " ",
+        /* @__PURE__ */ jsx9("code", { children: "qt-text-on-accent" }),
+        ", ",
+        /* @__PURE__ */ jsx9("code", { children: "qt-text-on-primary" }),
+        ",",
+        " ",
+        /* @__PURE__ */ jsx9("code", { children: "qt-text-on-success" }),
+        ", and ",
+        /* @__PURE__ */ jsx9("code", { children: "qt-text-on-destructive" }),
+        ", each mapping to the theme's matching ",
+        /* @__PURE__ */ jsx9("code", { children: "*Foreground" }),
+        " token. Note the naming \u2014 ",
+        /* @__PURE__ */ jsxs9("code", { children: [
+          "-on-",
+          /* @__PURE__ */ jsx9("em", { children: "fill" })
+        ] }),
+        ", never ",
+        /* @__PURE__ */ jsxs9("code", { children: [
+          "-",
+          /* @__PURE__ */ jsx9("em", { children: "fill" }),
+          "-foreground"
+        ] }),
+        ", which is the Tailwind spelling and is not a ",
+        /* @__PURE__ */ jsx9("code", { children: "qt-" }),
+        " class at all."
+      ] }),
+      /* @__PURE__ */ jsxs9("div", { style: { display: "flex", flexWrap: "wrap", gap: "0.75rem", alignItems: "center" }, children: [
+        /* @__PURE__ */ jsx9("span", { className: "qt-bg-accent qt-text-on-accent", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600 }, children: "on accent" }),
+        /* @__PURE__ */ jsx9("span", { className: "qt-bg-primary qt-text-on-primary", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600 }, children: "on primary" }),
+        /* @__PURE__ */ jsx9("span", { className: "qt-bg-success qt-text-on-success", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600 }, children: "on success" }),
+        /* @__PURE__ */ jsx9("span", { className: "qt-bg-destructive qt-text-on-destructive", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600 }, children: "on destructive" })
+      ] }),
+      /* @__PURE__ */ jsx9("p", { style: { ...note, marginTop: "1rem" }, children: "Each has a hover partner for controls that stay quiet at rest and take the fill on hover. Tailwind generates no variants for these classes, so the hover forms are written out by hand \u2014 reach for one that was never written and it is simply inert. Hover the buttons below." }),
+      /* @__PURE__ */ jsxs9("div", { style: { display: "flex", flexWrap: "wrap", gap: "0.75rem", alignItems: "center" }, children: [
+        /* @__PURE__ */ jsx9("button", { className: "qt-bg-card qt-text-secondary surfaces-demo-fill-primary hover:qt-text-on-primary", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600, border: "1px solid var(--color-border)", cursor: "pointer" }, children: "hover:qt-text-on-primary" }),
+        /* @__PURE__ */ jsx9("button", { className: "qt-bg-card qt-text-secondary surfaces-demo-fill-success hover:qt-text-on-success", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600, border: "1px solid var(--color-border)", cursor: "pointer" }, children: "hover:qt-text-on-success" }),
+        /* @__PURE__ */ jsx9("button", { className: "qt-bg-card qt-text-secondary surfaces-demo-fill-destructive hover:qt-text-on-destructive", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600, border: "1px solid var(--color-border)", cursor: "pointer" }, children: "hover:qt-text-on-destructive" })
+      ] })
+    ] }),
     /* @__PURE__ */ jsxs9("section", { style: { marginBottom: "2rem" }, children: [
       /* @__PURE__ */ jsxs9("h3", { style: sectionHeading2, children: [
         "Hover-highlight rows \u2014 ",

package/dist/index.css

@@ -1948,6 +1948,150 @@ body {
 .qt-text-on-accent {
   color: var(--color-accent-foreground);
 }
+.qt-text-on-primary {
+  color: var(--color-primary-foreground);
+}
+.qt-text-on-success {
+  color: var(--color-success-foreground);
+}
+.qt-text-on-destructive {
+  color: var(--color-destructive-foreground);
+}
+.qt-bg-card\/50 {
+  background-color: color-mix(in srgb, var(--color-card) 50%, transparent);
+}
+.qt-bg-card\/60 {
+  background-color: color-mix(in srgb, var(--color-card) 60%, transparent);
+}
+.qt-bg-card\/80 {
+  background-color: color-mix(in srgb, var(--color-card) 80%, transparent);
+}
+.qt-bg-card\/90 {
+  background-color: color-mix(in srgb, var(--color-card) 90%, transparent);
+}
+.qt-bg-default {
+  background-color: var(--color-background);
+}
+.qt-bg-destructive\/15 {
+  background-color: color-mix(in srgb, var(--color-destructive) 15%, transparent);
+}
+.qt-bg-destructive\/80 {
+  background-color: color-mix(in srgb, var(--color-destructive) 80%, transparent);
+}
+.qt-bg-info\/15 {
+  background-color: color-mix(in srgb, var(--color-info) 15%, transparent);
+}
+.qt-bg-input {
+  background-color: var(--color-input);
+}
+.qt-bg-muted-foreground\/20 {
+  background-color: color-mix(in srgb, var(--color-muted-foreground) 20%, transparent);
+}
+.qt-bg-muted\/20 {
+  background-color: color-mix(in srgb, var(--color-muted) 20%, transparent);
+}
+.qt-bg-muted\/30 {
+  background-color: color-mix(in srgb, var(--color-muted) 30%, transparent);
+}
+.qt-bg-muted\/40 {
+  background-color: color-mix(in srgb, var(--color-muted) 40%, transparent);
+}
+.qt-bg-muted\/50 {
+  background-color: color-mix(in srgb, var(--color-muted) 50%, transparent);
+}
+.qt-bg-muted\/60 {
+  background-color: color-mix(in srgb, var(--color-muted) 60%, transparent);
+}
+.qt-bg-muted\/70 {
+  background-color: color-mix(in srgb, var(--color-muted) 70%, transparent);
+}
+.qt-bg-muted\/80 {
+  background-color: color-mix(in srgb, var(--color-muted) 80%, transparent);
+}
+.qt-bg-primary\/15 {
+  background-color: color-mix(in srgb, var(--color-primary) 15%, transparent);
+}
+.qt-bg-primary\/30 {
+  background-color: color-mix(in srgb, var(--color-primary) 30%, transparent);
+}
+.qt-bg-secondary\/50 {
+  background-color: color-mix(in srgb, var(--color-secondary) 50%, transparent);
+}
+.qt-bg-success\/15 {
+  background-color: color-mix(in srgb, var(--color-success) 15%, transparent);
+}
+.qt-bg-warning\/15 {
+  background-color: color-mix(in srgb, var(--color-warning) 15%, transparent);
+}
+.qt-border-accent {
+  border-color: var(--color-accent);
+}
+.qt-border-default\/50 {
+  border-color: color-mix(in srgb, var(--color-border) 50%, transparent);
+}
+.qt-border-default\/60 {
+  border-color: color-mix(in srgb, var(--color-border) 60%, transparent);
+}
+.qt-border-default\/70 {
+  border-color: color-mix(in srgb, var(--color-border) 70%, transparent);
+}
+.qt-border-destructive\/20 {
+  border-color: color-mix(in srgb, var(--color-destructive) 20%, transparent);
+}
+.qt-border-destructive\/40 {
+  border-color: color-mix(in srgb, var(--color-destructive) 40%, transparent);
+}
+.qt-border-destructive\/50 {
+  border-color: color-mix(in srgb, var(--color-destructive) 50%, transparent);
+}
+.qt-border-primary-foreground {
+  border-color: var(--color-primary-foreground);
+}
+.qt-border-primary\/20 {
+  border-color: color-mix(in srgb, var(--color-primary) 20%, transparent);
+}
+.qt-border-primary\/30 {
+  border-color: color-mix(in srgb, var(--color-primary) 30%, transparent);
+}
+.qt-border-primary\/40 {
+  border-color: color-mix(in srgb, var(--color-primary) 40%, transparent);
+}
+.qt-border-primary\/50 {
+  border-color: color-mix(in srgb, var(--color-primary) 50%, transparent);
+}
+.qt-border-primary\/60 {
+  border-color: color-mix(in srgb, var(--color-primary) 60%, transparent);
+}
+.qt-border-success\/50 {
+  border-color: color-mix(in srgb, var(--color-success) 50%, transparent);
+}
+.qt-border-warning\/50 {
+  border-color: color-mix(in srgb, var(--color-warning) 50%, transparent);
+}
+.qt-text-destructive\/80 {
+  color: color-mix(in srgb, var(--color-destructive) 80%, transparent);
+}
+.qt-text-info\/80 {
+  color: color-mix(in srgb, var(--color-info) 80%, transparent);
+}
+.qt-text-secondary\/50 {
+  color: color-mix(in srgb, var(--color-muted-foreground) 50%, transparent);
+}
+.qt-text-secondary\/60 {
+  color: color-mix(in srgb, var(--color-muted-foreground) 60%, transparent);
+}
+.qt-text-secondary\/70 {
+  color: color-mix(in srgb, var(--color-muted-foreground) 70%, transparent);
+}
+.qt-text-secondary\/80 {
+  color: color-mix(in srgb, var(--color-muted-foreground) 80%, transparent);
+}
+.qt-text-success\/80 {
+  color: color-mix(in srgb, var(--color-success) 80%, transparent);
+}
+.qt-text-warning\/80 {
+  color: color-mix(in srgb, var(--color-warning) 80%, transparent);
+}
 .qt-hover-accent {
   transition: background-color 0.15s ease, color 0.15s ease;
 }
@@ -2078,6 +2222,123 @@ body {
 .hover\:qt-bg-primary\/10:hover {
   background-color: color-mix(in srgb, var(--color-primary) 10%, transparent);
 }
+.hover\:qt-text-on-accent:hover {
+  color: var(--color-accent-foreground);
+}
+.hover\:qt-text-on-primary:hover {
+  color: var(--color-primary-foreground);
+}
+.hover\:qt-text-on-success:hover {
+  color: var(--color-success-foreground);
+}
+.hover\:qt-text-on-destructive:hover {
+  color: var(--color-destructive-foreground);
+}
+.hover\:qt-bg-surface-hover:hover {
+  background-color: var(--color-muted);
+}
+.hover\:qt-bg-muted:hover {
+  background-color: var(--color-muted);
+}
+.hover\:qt-bg-muted\/30:hover {
+  background-color: color-mix(in srgb, var(--color-muted) 30%, transparent);
+}
+.hover\:qt-bg-muted\/40:hover {
+  background-color: color-mix(in srgb, var(--color-muted) 40%, transparent);
+}
+.hover\:qt-bg-muted\/50:hover {
+  background-color: color-mix(in srgb, var(--color-muted) 50%, transparent);
+}
+.hover\:qt-bg-muted\/80:hover {
+  background-color: color-mix(in srgb, var(--color-muted) 80%, transparent);
+}
+.hover\:qt-bg-primary\/5:hover {
+  background-color: color-mix(in srgb, var(--color-primary) 5%, transparent);
+}
+.hover\:qt-bg-primary\/15:hover {
+  background-color: color-mix(in srgb, var(--color-primary) 15%, transparent);
+}
+.hover\:qt-bg-primary\/20:hover {
+  background-color: color-mix(in srgb, var(--color-primary) 20%, transparent);
+}
+.hover\:qt-bg-primary\/90:hover {
+  background-color: color-mix(in srgb, var(--color-primary) 90%, transparent);
+}
+.hover\:qt-bg-destructive:hover {
+  background-color: var(--color-destructive);
+}
+.hover\:qt-bg-destructive\/20:hover {
+  background-color: color-mix(in srgb, var(--color-destructive) 20%, transparent);
+}
+.hover\:qt-bg-destructive\/90:hover {
+  background-color: color-mix(in srgb, var(--color-destructive) 90%, transparent);
+}
+.hover\:qt-bg-success\/20:hover {
+  background-color: color-mix(in srgb, var(--color-success) 20%, transparent);
+}
+.hover\:qt-bg-success\/90:hover {
+  background-color: color-mix(in srgb, var(--color-success) 90%, transparent);
+}
+.hover\:qt-bg-warning\/20:hover {
+  background-color: color-mix(in srgb, var(--color-warning) 20%, transparent);
+}
+.hover\:qt-bg-info\/20:hover {
+  background-color: color-mix(in srgb, var(--color-info) 20%, transparent);
+}
+.hover\:qt-text-destructive:hover {
+  color: var(--color-destructive);
+}
+.hover\:qt-text-destructive\/80:hover {
+  color: color-mix(in srgb, var(--color-destructive) 80%, transparent);
+}
+.hover\:qt-text-warning\/80:hover {
+  color: color-mix(in srgb, var(--color-warning) 80%, transparent);
+}
+.hover\:qt-text-info\/80:hover {
+  color: color-mix(in srgb, var(--color-info) 80%, transparent);
+}
+.hover\:qt-text-primary:hover {
+  color: var(--qt-text-primary-fg, var(--color-foreground));
+}
+.hover\:qt-border-primary:hover {
+  border-color: var(--color-primary);
+}
+.hover\:qt-border-primary\/50:hover {
+  border-color: color-mix(in srgb, var(--color-primary) 50%, transparent);
+}
+.hover\:qt-border-primary\/60:hover {
+  border-color: color-mix(in srgb, var(--color-primary) 60%, transparent);
+}
+.hover\:qt-border-accent:hover {
+  border-color: var(--color-accent);
+}
+.focus\:qt-border-primary:focus {
+  border-color: var(--color-primary);
+}
+.disabled\:qt-bg-muted:disabled {
+  background-color: var(--color-muted);
+}
+.disabled\:qt-text-secondary:disabled {
+  color: var(--color-muted-foreground);
+}
+.placeholder\:qt-text-secondary::-moz-placeholder {
+  color: var(--color-muted-foreground);
+}
+.placeholder\:qt-text-secondary::placeholder {
+  color: var(--color-muted-foreground);
+}
+.file\:qt-bg-primary\/20::file-selector-button {
+  background-color: color-mix(in srgb, var(--color-primary) 20%, transparent);
+}
+.hover\:file\:qt-bg-primary\/30:hover::file-selector-button {
+  background-color: color-mix(in srgb, var(--color-primary) 30%, transparent);
+}
+.hover\:qt-shadow-md:hover {
+  box-shadow: var(--qt-card-shadow-hover, 0 4px 12px hsl(225 18% 10% / 0.1), 0 2px 4px hsl(225 18% 10% / 0.05));
+}
+.group\/thumb:hover .group-hover\/thumb\:qt-bg-overlay-light {
+  background-color: var(--qt-overlay-light-bg, rgb(0 0 0 / 0.2));
+}
 .qt-bg-overlay {
   background-color: var(--qt-overlay-bg, rgb(0 0 0 / 0.85));
 }

package/dist/index.js

@@ -1153,6 +1153,11 @@ var note = {
 };
 var Surfaces = () => {
   return /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("div", { style: { padding: "1.5rem" }, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("style", { children: `
+        .surfaces-demo-fill-primary:hover { background-color: var(--color-primary); }
+        .surfaces-demo-fill-success:hover { background-color: var(--color-success); }
+        .surfaces-demo-fill-destructive:hover { background-color: var(--color-destructive); }
+      ` }),
     /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("h2", { style: { fontSize: "1.5rem", fontWeight: 700, marginBottom: "0.5rem" }, children: "Surfaces" }),
     /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("p", { style: { ...note, maxWidth: "44rem" }, children: [
       "How accent-coloured surfaces stay legible no matter how bold a theme makes its ",
@@ -1189,6 +1194,53 @@ var Surfaces = () => {
         /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("kbd", { className: "qt-bg-accent qt-text-on-accent", style: { padding: "0.125rem 0.375rem", borderRadius: "0.25rem", fontSize: "0.75rem" }, children: "\u21B5" })
       ] })
     ] }),
+    /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("section", { style: { marginBottom: "2rem" }, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("h3", { style: sectionHeading2, children: [
+        "Foregrounds on filled surfaces \u2014 the ",
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("code", { children: "qt-text-on-*" }),
+        " family"
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("p", { style: note, children: [
+        "The same contract, extended to every filled surface the app paints:",
+        " ",
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("code", { children: "qt-text-on-accent" }),
+        ", ",
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("code", { children: "qt-text-on-primary" }),
+        ",",
+        " ",
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("code", { children: "qt-text-on-success" }),
+        ", and ",
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("code", { children: "qt-text-on-destructive" }),
+        ", each mapping to the theme's matching ",
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("code", { children: "*Foreground" }),
+        " token. Note the naming \u2014 ",
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("code", { children: [
+          "-on-",
+          /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("em", { children: "fill" })
+        ] }),
+        ", never ",
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("code", { children: [
+          "-",
+          /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("em", { children: "fill" }),
+          "-foreground"
+        ] }),
+        ", which is the Tailwind spelling and is not a ",
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("code", { children: "qt-" }),
+        " class at all."
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("div", { style: { display: "flex", flexWrap: "wrap", gap: "0.75rem", alignItems: "center" }, children: [
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("span", { className: "qt-bg-accent qt-text-on-accent", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600 }, children: "on accent" }),
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("span", { className: "qt-bg-primary qt-text-on-primary", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600 }, children: "on primary" }),
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("span", { className: "qt-bg-success qt-text-on-success", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600 }, children: "on success" }),
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("span", { className: "qt-bg-destructive qt-text-on-destructive", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600 }, children: "on destructive" })
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("p", { style: { ...note, marginTop: "1rem" }, children: "Each has a hover partner for controls that stay quiet at rest and take the fill on hover. Tailwind generates no variants for these classes, so the hover forms are written out by hand \u2014 reach for one that was never written and it is simply inert. Hover the buttons below." }),
+      /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("div", { style: { display: "flex", flexWrap: "wrap", gap: "0.75rem", alignItems: "center" }, children: [
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("button", { className: "qt-bg-card qt-text-secondary surfaces-demo-fill-primary hover:qt-text-on-primary", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600, border: "1px solid var(--color-border)", cursor: "pointer" }, children: "hover:qt-text-on-primary" }),
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("button", { className: "qt-bg-card qt-text-secondary surfaces-demo-fill-success hover:qt-text-on-success", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600, border: "1px solid var(--color-border)", cursor: "pointer" }, children: "hover:qt-text-on-success" }),
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("button", { className: "qt-bg-card qt-text-secondary surfaces-demo-fill-destructive hover:qt-text-on-destructive", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600, border: "1px solid var(--color-border)", cursor: "pointer" }, children: "hover:qt-text-on-destructive" })
+      ] })
+    ] }),
     /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("section", { style: { marginBottom: "2rem" }, children: [
       /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("h3", { style: sectionHeading2, children: [
         "Hover-highlight rows \u2014 ",

package/dist/index.mjs

@@ -21,7 +21,7 @@ import {
   ThemeComparison,
   Typography,
   Workspace
-} from "./chunk-XSNC4J5T.mjs";
+} from "./chunk-TESCTXU3.mjs";
 import "./chunk-WUKYLWAZ.mjs";
 
 // src/preview.tsx

package/dist/stories/index.js

@@ -1090,6 +1090,11 @@ var note = {
 };
 var Surfaces = () => {
   return /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)("div", { style: { padding: "1.5rem" }, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("style", { children: `
+        .surfaces-demo-fill-primary:hover { background-color: var(--color-primary); }
+        .surfaces-demo-fill-success:hover { background-color: var(--color-success); }
+        .surfaces-demo-fill-destructive:hover { background-color: var(--color-destructive); }
+      ` }),
     /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("h2", { style: { fontSize: "1.5rem", fontWeight: 700, marginBottom: "0.5rem" }, children: "Surfaces" }),
     /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)("p", { style: { ...note, maxWidth: "44rem" }, children: [
       "How accent-coloured surfaces stay legible no matter how bold a theme makes its ",
@@ -1126,6 +1131,53 @@ var Surfaces = () => {
         /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("kbd", { className: "qt-bg-accent qt-text-on-accent", style: { padding: "0.125rem 0.375rem", borderRadius: "0.25rem", fontSize: "0.75rem" }, children: "\u21B5" })
       ] })
     ] }),
+    /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)("section", { style: { marginBottom: "2rem" }, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)("h3", { style: sectionHeading2, children: [
+        "Foregrounds on filled surfaces \u2014 the ",
+        /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("code", { children: "qt-text-on-*" }),
+        " family"
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)("p", { style: note, children: [
+        "The same contract, extended to every filled surface the app paints:",
+        " ",
+        /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("code", { children: "qt-text-on-accent" }),
+        ", ",
+        /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("code", { children: "qt-text-on-primary" }),
+        ",",
+        " ",
+        /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("code", { children: "qt-text-on-success" }),
+        ", and ",
+        /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("code", { children: "qt-text-on-destructive" }),
+        ", each mapping to the theme's matching ",
+        /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("code", { children: "*Foreground" }),
+        " token. Note the naming \u2014 ",
+        /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)("code", { children: [
+          "-on-",
+          /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("em", { children: "fill" })
+        ] }),
+        ", never ",
+        /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)("code", { children: [
+          "-",
+          /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("em", { children: "fill" }),
+          "-foreground"
+        ] }),
+        ", which is the Tailwind spelling and is not a ",
+        /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("code", { children: "qt-" }),
+        " class at all."
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)("div", { style: { display: "flex", flexWrap: "wrap", gap: "0.75rem", alignItems: "center" }, children: [
+        /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("span", { className: "qt-bg-accent qt-text-on-accent", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600 }, children: "on accent" }),
+        /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("span", { className: "qt-bg-primary qt-text-on-primary", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600 }, children: "on primary" }),
+        /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("span", { className: "qt-bg-success qt-text-on-success", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600 }, children: "on success" }),
+        /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("span", { className: "qt-bg-destructive qt-text-on-destructive", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600 }, children: "on destructive" })
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("p", { style: { ...note, marginTop: "1rem" }, children: "Each has a hover partner for controls that stay quiet at rest and take the fill on hover. Tailwind generates no variants for these classes, so the hover forms are written out by hand \u2014 reach for one that was never written and it is simply inert. Hover the buttons below." }),
+      /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)("div", { style: { display: "flex", flexWrap: "wrap", gap: "0.75rem", alignItems: "center" }, children: [
+        /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("button", { className: "qt-bg-card qt-text-secondary surfaces-demo-fill-primary hover:qt-text-on-primary", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600, border: "1px solid var(--color-border)", cursor: "pointer" }, children: "hover:qt-text-on-primary" }),
+        /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("button", { className: "qt-bg-card qt-text-secondary surfaces-demo-fill-success hover:qt-text-on-success", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600, border: "1px solid var(--color-border)", cursor: "pointer" }, children: "hover:qt-text-on-success" }),
+        /* @__PURE__ */ (0, import_jsx_runtime9.jsx)("button", { className: "qt-bg-card qt-text-secondary surfaces-demo-fill-destructive hover:qt-text-on-destructive", style: { padding: "0.25rem 0.625rem", borderRadius: "0.375rem", fontSize: "0.8125rem", fontWeight: 600, border: "1px solid var(--color-border)", cursor: "pointer" }, children: "hover:qt-text-on-destructive" })
+      ] })
+    ] }),
     /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)("section", { style: { marginBottom: "2rem" }, children: [
       /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)("h3", { style: sectionHeading2, children: [
         "Hover-highlight rows \u2014 ",

package/dist/stories/index.mjs

@@ -21,7 +21,7 @@ import {
   ThemeComparison,
   Typography,
   Workspace
-} from "../chunk-XSNC4J5T.mjs";
+} from "../chunk-TESCTXU3.mjs";
 import "../chunk-WUKYLWAZ.mjs";
 export {
   Avatars,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quilltap/theme-storybook",
-  "version": "1.0.61",
+  "version": "1.0.63",
   "description": "Storybook preset and stories for developing Quilltap theme plugins",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -65,7 +65,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/foundry-9/quilltap-server.git",
+    "url": "git+https://github.com/foundry-9/quilltap-server.git",
     "directory": "packages/theme-storybook"
   },
   "homepage": "https://github.com/foundry-9/quilltap-server/tree/main/packages/theme-storybook#readme",

package/src/css/qt-components.css

@@ -2354,10 +2354,216 @@
   background-color: var(--color-muted-foreground);
 }
 
+/* Foregrounds intended for use ON a filled surface — the paired counterparts of
+   the accent/primary/success/destructive fills. Each maps to the token a theme
+   defines for text sitting on that fill, so a badge or a solid button keeps its
+   contrast on every theme instead of inheriting whatever colour the surrounding
+   page happens to be using.
+
+     <span class="qt-bg-accent qt-text-on-accent">…</span>
+     <button class="qt-bg-destructive qt-text-on-destructive">…</button>
+
+   Mind the naming: these are `-on-<fill>`, never `-<fill>-foreground`. */
 .qt-text-on-accent {
   color: var(--color-accent-foreground);
 }
 
+.qt-text-on-primary {
+  color: var(--color-primary-foreground);
+}
+
+.qt-text-on-success {
+  color: var(--color-success-foreground);
+}
+
+.qt-text-on-destructive {
+  color: var(--color-destructive-foreground);
+}
+
+/* The remaining opacity steps and surface colours of the utility families. A
+   theme that overrides --color-muted or --color-border gets all of these for
+   free; they exist so that the app never has to reach for a raw Tailwind
+   colour on a themed surface. */
+.qt-bg-card\/50 {
+  background-color: color-mix(in srgb, var(--color-card) 50%, transparent);
+}
+
+.qt-bg-card\/60 {
+  background-color: color-mix(in srgb, var(--color-card) 60%, transparent);
+}
+
+.qt-bg-card\/80 {
+  background-color: color-mix(in srgb, var(--color-card) 80%, transparent);
+}
+
+.qt-bg-card\/90 {
+  background-color: color-mix(in srgb, var(--color-card) 90%, transparent);
+}
+
+.qt-bg-default {
+  background-color: var(--color-background);
+}
+
+.qt-bg-destructive\/15 {
+  background-color: color-mix(in srgb, var(--color-destructive) 15%, transparent);
+}
+
+.qt-bg-destructive\/80 {
+  background-color: color-mix(in srgb, var(--color-destructive) 80%, transparent);
+}
+
+.qt-bg-info\/15 {
+  background-color: color-mix(in srgb, var(--color-info) 15%, transparent);
+}
+
+.qt-bg-input {
+  background-color: var(--color-input);
+}
+
+.qt-bg-muted-foreground\/20 {
+  background-color: color-mix(in srgb, var(--color-muted-foreground) 20%, transparent);
+}
+
+.qt-bg-muted\/20 {
+  background-color: color-mix(in srgb, var(--color-muted) 20%, transparent);
+}
+
+.qt-bg-muted\/30 {
+  background-color: color-mix(in srgb, var(--color-muted) 30%, transparent);
+}
+
+.qt-bg-muted\/40 {
+  background-color: color-mix(in srgb, var(--color-muted) 40%, transparent);
+}
+
+.qt-bg-muted\/50 {
+  background-color: color-mix(in srgb, var(--color-muted) 50%, transparent);
+}
+
+.qt-bg-muted\/60 {
+  background-color: color-mix(in srgb, var(--color-muted) 60%, transparent);
+}
+
+.qt-bg-muted\/70 {
+  background-color: color-mix(in srgb, var(--color-muted) 70%, transparent);
+}
+
+.qt-bg-muted\/80 {
+  background-color: color-mix(in srgb, var(--color-muted) 80%, transparent);
+}
+
+.qt-bg-primary\/15 {
+  background-color: color-mix(in srgb, var(--color-primary) 15%, transparent);
+}
+
+.qt-bg-primary\/30 {
+  background-color: color-mix(in srgb, var(--color-primary) 30%, transparent);
+}
+
+.qt-bg-secondary\/50 {
+  background-color: color-mix(in srgb, var(--color-secondary) 50%, transparent);
+}
+
+.qt-bg-success\/15 {
+  background-color: color-mix(in srgb, var(--color-success) 15%, transparent);
+}
+
+.qt-bg-warning\/15 {
+  background-color: color-mix(in srgb, var(--color-warning) 15%, transparent);
+}
+
+.qt-border-accent {
+  border-color: var(--color-accent);
+}
+
+.qt-border-default\/50 {
+  border-color: color-mix(in srgb, var(--color-border) 50%, transparent);
+}
+
+.qt-border-default\/60 {
+  border-color: color-mix(in srgb, var(--color-border) 60%, transparent);
+}
+
+.qt-border-default\/70 {
+  border-color: color-mix(in srgb, var(--color-border) 70%, transparent);
+}
+
+.qt-border-destructive\/20 {
+  border-color: color-mix(in srgb, var(--color-destructive) 20%, transparent);
+}
+
+.qt-border-destructive\/40 {
+  border-color: color-mix(in srgb, var(--color-destructive) 40%, transparent);
+}
+
+.qt-border-destructive\/50 {
+  border-color: color-mix(in srgb, var(--color-destructive) 50%, transparent);
+}
+
+.qt-border-primary-foreground {
+  border-color: var(--color-primary-foreground);
+}
+
+.qt-border-primary\/20 {
+  border-color: color-mix(in srgb, var(--color-primary) 20%, transparent);
+}
+
+.qt-border-primary\/30 {
+  border-color: color-mix(in srgb, var(--color-primary) 30%, transparent);
+}
+
+.qt-border-primary\/40 {
+  border-color: color-mix(in srgb, var(--color-primary) 40%, transparent);
+}
+
+.qt-border-primary\/50 {
+  border-color: color-mix(in srgb, var(--color-primary) 50%, transparent);
+}
+
+.qt-border-primary\/60 {
+  border-color: color-mix(in srgb, var(--color-primary) 60%, transparent);
+}
+
+.qt-border-success\/50 {
+  border-color: color-mix(in srgb, var(--color-success) 50%, transparent);
+}
+
+.qt-border-warning\/50 {
+  border-color: color-mix(in srgb, var(--color-warning) 50%, transparent);
+}
+
+.qt-text-destructive\/80 {
+  color: color-mix(in srgb, var(--color-destructive) 80%, transparent);
+}
+
+.qt-text-info\/80 {
+  color: color-mix(in srgb, var(--color-info) 80%, transparent);
+}
+
+.qt-text-secondary\/50 {
+  color: color-mix(in srgb, var(--color-muted-foreground) 50%, transparent);
+}
+
+.qt-text-secondary\/60 {
+  color: color-mix(in srgb, var(--color-muted-foreground) 60%, transparent);
+}
+
+.qt-text-secondary\/70 {
+  color: color-mix(in srgb, var(--color-muted-foreground) 70%, transparent);
+}
+
+.qt-text-secondary\/80 {
+  color: color-mix(in srgb, var(--color-muted-foreground) 80%, transparent);
+}
+
+.qt-text-success\/80 {
+  color: color-mix(in srgb, var(--color-success) 80%, transparent);
+}
+
+.qt-text-warning\/80 {
+  color: color-mix(in srgb, var(--color-warning) 80%, transparent);
+}
+
 /* Hoverable accent surface — list rows, menu items, and option cards that
    should highlight on hover. On hover it paints the accent background AND
    forces the accent foreground onto the row and every descendant, so the whole
@@ -2549,6 +2755,167 @@
   background-color: color-mix(in srgb, var(--color-primary) 10%, transparent);
 }
 
+/* Hover foregrounds for filled surfaces — the hover partners of the
+   qt-text-on-* family, for controls that sit quiet at rest and take a filled
+   background on hover (`qt-text-secondary hover:qt-bg-success
+   hover:qt-text-on-success`). */
+.hover\:qt-text-on-accent:hover {
+  color: var(--color-accent-foreground);
+}
+
+.hover\:qt-text-on-primary:hover {
+  color: var(--color-primary-foreground);
+}
+
+.hover\:qt-text-on-success:hover {
+  color: var(--color-success-foreground);
+}
+
+.hover\:qt-text-on-destructive:hover {
+  color: var(--color-destructive-foreground);
+}
+
+/* State forms of the utilities above. Tailwind generates variants only for
+   utilities it knows about, and a class declared in @layer utilities is
+   invisible to it — so in the app every one of these is hand-written, escaped,
+   with its own pseudo-selector, and an unwritten one is inert. Mirrored here so
+   a theme author previewing hover states sees what the app actually ships. */
+.hover\:qt-bg-surface-hover:hover {
+  background-color: var(--color-muted);
+}
+
+.hover\:qt-bg-muted:hover {
+  background-color: var(--color-muted);
+}
+
+.hover\:qt-bg-muted\/30:hover {
+  background-color: color-mix(in srgb, var(--color-muted) 30%, transparent);
+}
+
+.hover\:qt-bg-muted\/40:hover {
+  background-color: color-mix(in srgb, var(--color-muted) 40%, transparent);
+}
+
+.hover\:qt-bg-muted\/50:hover {
+  background-color: color-mix(in srgb, var(--color-muted) 50%, transparent);
+}
+
+.hover\:qt-bg-muted\/80:hover {
+  background-color: color-mix(in srgb, var(--color-muted) 80%, transparent);
+}
+
+.hover\:qt-bg-primary\/5:hover {
+  background-color: color-mix(in srgb, var(--color-primary) 5%, transparent);
+}
+
+.hover\:qt-bg-primary\/15:hover {
+  background-color: color-mix(in srgb, var(--color-primary) 15%, transparent);
+}
+
+.hover\:qt-bg-primary\/20:hover {
+  background-color: color-mix(in srgb, var(--color-primary) 20%, transparent);
+}
+
+.hover\:qt-bg-primary\/90:hover {
+  background-color: color-mix(in srgb, var(--color-primary) 90%, transparent);
+}
+
+.hover\:qt-bg-destructive:hover {
+  background-color: var(--color-destructive);
+}
+
+.hover\:qt-bg-destructive\/20:hover {
+  background-color: color-mix(in srgb, var(--color-destructive) 20%, transparent);
+}
+
+.hover\:qt-bg-destructive\/90:hover {
+  background-color: color-mix(in srgb, var(--color-destructive) 90%, transparent);
+}
+
+.hover\:qt-bg-success\/20:hover {
+  background-color: color-mix(in srgb, var(--color-success) 20%, transparent);
+}
+
+.hover\:qt-bg-success\/90:hover {
+  background-color: color-mix(in srgb, var(--color-success) 90%, transparent);
+}
+
+.hover\:qt-bg-warning\/20:hover {
+  background-color: color-mix(in srgb, var(--color-warning) 20%, transparent);
+}
+
+.hover\:qt-bg-info\/20:hover {
+  background-color: color-mix(in srgb, var(--color-info) 20%, transparent);
+}
+
+.hover\:qt-text-destructive:hover {
+  color: var(--color-destructive);
+}
+
+.hover\:qt-text-destructive\/80:hover {
+  color: color-mix(in srgb, var(--color-destructive) 80%, transparent);
+}
+
+.hover\:qt-text-warning\/80:hover {
+  color: color-mix(in srgb, var(--color-warning) 80%, transparent);
+}
+
+.hover\:qt-text-info\/80:hover {
+  color: color-mix(in srgb, var(--color-info) 80%, transparent);
+}
+
+.hover\:qt-text-primary:hover {
+  color: var(--qt-text-primary-fg, var(--color-foreground));
+}
+
+.hover\:qt-border-primary:hover {
+  border-color: var(--color-primary);
+}
+
+.hover\:qt-border-primary\/50:hover {
+  border-color: color-mix(in srgb, var(--color-primary) 50%, transparent);
+}
+
+.hover\:qt-border-primary\/60:hover {
+  border-color: color-mix(in srgb, var(--color-primary) 60%, transparent);
+}
+
+.hover\:qt-border-accent:hover {
+  border-color: var(--color-accent);
+}
+
+.focus\:qt-border-primary:focus {
+  border-color: var(--color-primary);
+}
+
+.disabled\:qt-bg-muted:disabled {
+  background-color: var(--color-muted);
+}
+
+.disabled\:qt-text-secondary:disabled {
+  color: var(--color-muted-foreground);
+}
+
+.placeholder\:qt-text-secondary::placeholder {
+  color: var(--color-muted-foreground);
+}
+
+.file\:qt-bg-primary\/20::file-selector-button {
+  background-color: color-mix(in srgb, var(--color-primary) 20%, transparent);
+}
+
+.hover\:file\:qt-bg-primary\/30:hover::file-selector-button {
+  background-color: color-mix(in srgb, var(--color-primary) 30%, transparent);
+}
+
+.hover\:qt-shadow-md:hover {
+  box-shadow: var(--qt-card-shadow-hover, 0 4px 12px hsl(225 18% 10% / 0.1), 0 2px 4px hsl(225 18% 10% / 0.05));
+}
+
+.group\/thumb:hover .group-hover\/thumb\:qt-bg-overlay-light {
+  background-color: var(--qt-overlay-light-bg, rgb(0 0 0 / 0.2));
+}
+
 /* ==========================================================================
    OVERLAY UTILITIES
    For image modals, lightboxes, and overlay UI elements.

package/src/stories/components/Surfaces.tsx

@@ -27,6 +27,14 @@ const note: React.CSSProperties = {
 export const Surfaces: React.FC = () => {
   return (
     <div style={{ padding: '1.5rem' }}>
+      {/* Story-local: the app pairs the hover foregrounds with Tailwind's
+          hover:bg-* fills, which don't exist here. Demo fills only — these are
+          not qt-* utilities and must not be copied into an app or a theme. */}
+      <style>{`
+        .surfaces-demo-fill-primary:hover { background-color: var(--color-primary); }
+        .surfaces-demo-fill-success:hover { background-color: var(--color-success); }
+        .surfaces-demo-fill-destructive:hover { background-color: var(--color-destructive); }
+      `}</style>
       <h2 style={{ fontSize: '1.5rem', fontWeight: 700, marginBottom: '0.5rem' }}>Surfaces</h2>
       <p style={{ ...note, maxWidth: '44rem' }}>
         How accent-coloured surfaces stay legible no matter how bold a theme makes
@@ -57,6 +65,50 @@ export const Surfaces: React.FC = () => {
         </div>
       </section>
 
+      {/* Foregrounds on filled surfaces */}
+      <section style={{ marginBottom: '2rem' }}>
+        <h3 style={sectionHeading}>Foregrounds on filled surfaces — the <code>qt-text-on-*</code> family</h3>
+        <p style={note}>
+          The same contract, extended to every filled surface the app paints:{' '}
+          <code>qt-text-on-accent</code>, <code>qt-text-on-primary</code>,{' '}
+          <code>qt-text-on-success</code>, and <code>qt-text-on-destructive</code>, each
+          mapping to the theme&apos;s matching <code>*Foreground</code> token. Note the
+          naming — <code>-on-<em>fill</em></code>, never <code>-<em>fill</em>-foreground</code>,
+          which is the Tailwind spelling and is not a <code>qt-</code> class at all.
+        </p>
+        <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem', alignItems: 'center' }}>
+          <span className="qt-bg-accent qt-text-on-accent" style={{ padding: '0.25rem 0.625rem', borderRadius: '0.375rem', fontSize: '0.8125rem', fontWeight: 600 }}>
+            on accent
+          </span>
+          <span className="qt-bg-primary qt-text-on-primary" style={{ padding: '0.25rem 0.625rem', borderRadius: '0.375rem', fontSize: '0.8125rem', fontWeight: 600 }}>
+            on primary
+          </span>
+          <span className="qt-bg-success qt-text-on-success" style={{ padding: '0.25rem 0.625rem', borderRadius: '0.375rem', fontSize: '0.8125rem', fontWeight: 600 }}>
+            on success
+          </span>
+          <span className="qt-bg-destructive qt-text-on-destructive" style={{ padding: '0.25rem 0.625rem', borderRadius: '0.375rem', fontSize: '0.8125rem', fontWeight: 600 }}>
+            on destructive
+          </span>
+        </div>
+        <p style={{ ...note, marginTop: '1rem' }}>
+          Each has a hover partner for controls that stay quiet at rest and take the fill
+          on hover. Tailwind generates no variants for these classes, so the hover forms
+          are written out by hand — reach for one that was never written and it is simply
+          inert. Hover the buttons below.
+        </p>
+        <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem', alignItems: 'center' }}>
+          <button className="qt-bg-card qt-text-secondary surfaces-demo-fill-primary hover:qt-text-on-primary" style={{ padding: '0.25rem 0.625rem', borderRadius: '0.375rem', fontSize: '0.8125rem', fontWeight: 600, border: '1px solid var(--color-border)', cursor: 'pointer' }}>
+            hover:qt-text-on-primary
+          </button>
+          <button className="qt-bg-card qt-text-secondary surfaces-demo-fill-success hover:qt-text-on-success" style={{ padding: '0.25rem 0.625rem', borderRadius: '0.375rem', fontSize: '0.8125rem', fontWeight: 600, border: '1px solid var(--color-border)', cursor: 'pointer' }}>
+            hover:qt-text-on-success
+          </button>
+          <button className="qt-bg-card qt-text-secondary surfaces-demo-fill-destructive hover:qt-text-on-destructive" style={{ padding: '0.25rem 0.625rem', borderRadius: '0.375rem', fontSize: '0.8125rem', fontWeight: 600, border: '1px solid var(--color-border)', cursor: 'pointer' }}>
+            hover:qt-text-on-destructive
+          </button>
+        </div>
+      </section>
+
       {/* Hover-highlight rows */}
       <section style={{ marginBottom: '2rem' }}>
         <h3 style={sectionHeading}>Hover-highlight rows — <code>qt-hover-accent</code></h3>