@mohasinac/appkit 4.58.0 → 4.60.0

package/dist/tokens/themes/default-dark.js

@@ -41,8 +41,8 @@ export const DEFAULT_DARK_THEME = {
         "appkit-color-secondary-950": "#083344",
         "appkit-color-bg": "#020617",
         "appkit-color-surface": "#0f172a",
-        "appkit-color-surface-elevated": "rgba(15, 23, 42, 0.9)",
-        "appkit-color-surface-input": "rgba(30, 41, 59, 0.6)",
+        "appkit-color-surface-elevated": "#1e293b",
+        "appkit-color-surface-input": "#0b1220",
         // Theme-inverting interactive fills. Must stay byte-identical to the
         // [data-theme="default-dark"] block in tokens.css — audit-theme-drift
         // compares them.
@@ -87,16 +87,19 @@ export const DEFAULT_DARK_THEME = {
         "appkit-space-18": "4.5rem",
         "appkit-space-20": "5rem",
         "appkit-space-24": "6rem",
-        "appkit-text-2xs": "0.625rem",
-        "appkit-text-xs": "0.6875rem",
-        "appkit-text-sm": "0.8125rem",
-        "appkit-text-base": "0.9375rem",
-        "appkit-text-lg": "1rem",
-        "appkit-text-xl": "1.125rem",
-        "appkit-text-2xl": "1.375rem",
-        "appkit-text-3xl": "1.625rem",
-        "appkit-text-4xl": "1.875rem",
-        "appkit-text-5xl": "2.5rem",
+        "appkit-text-2xs": "0.6875rem",
+        "appkit-text-xs": "0.75rem",
+        "appkit-text-sm": "0.875rem",
+        "appkit-text-base": "1rem",
+        "appkit-text-lg": "1.125rem",
+        "appkit-text-xl": "1.25rem",
+        "appkit-text-2xl": "1.5rem",
+        "appkit-text-3xl": "1.875rem",
+        "appkit-text-4xl": "2.25rem",
+        "appkit-text-5xl": "3rem",
+        "appkit-text-6xl": "3.75rem",
+        "appkit-text-7xl": "4.5rem",
+        "appkit-text-8xl": "6rem",
     },
     gradients: {
         brand: "linear-gradient(to right, var(--appkit-color-primary), var(--appkit-color-secondary))",

package/dist/tokens/themes/default-light.js

@@ -45,7 +45,7 @@ export const DEFAULT_LIGHT_THEME = {
         "appkit-color-bg": "#fafafa",
         "appkit-color-surface": "#ffffff",
         "appkit-color-surface-elevated": "#ffffff",
-        "appkit-color-surface-input": "#ffffff",
+        "appkit-color-surface-input": "#fafafa",
         // Theme-inverting interactive fills. Must stay byte-identical to the
         // matching :root block in tokens.css — audit-theme-drift compares them.
         "appkit-color-surface-hover": "#f4f4f5",
@@ -94,16 +94,19 @@ export const DEFAULT_LIGHT_THEME = {
         "appkit-space-18": "4.5rem",
         "appkit-space-20": "5rem",
         "appkit-space-24": "6rem",
-        "appkit-text-2xs": "0.625rem",
-        "appkit-text-xs": "0.6875rem",
-        "appkit-text-sm": "0.8125rem",
-        "appkit-text-base": "0.9375rem",
-        "appkit-text-lg": "1rem",
-        "appkit-text-xl": "1.125rem",
-        "appkit-text-2xl": "1.375rem",
-        "appkit-text-3xl": "1.625rem",
-        "appkit-text-4xl": "1.875rem",
-        "appkit-text-5xl": "2.5rem",
+        "appkit-text-2xs": "0.6875rem",
+        "appkit-text-xs": "0.75rem",
+        "appkit-text-sm": "0.875rem",
+        "appkit-text-base": "1rem",
+        "appkit-text-lg": "1.125rem",
+        "appkit-text-xl": "1.25rem",
+        "appkit-text-2xl": "1.5rem",
+        "appkit-text-3xl": "1.875rem",
+        "appkit-text-4xl": "2.25rem",
+        "appkit-text-5xl": "3rem",
+        "appkit-text-6xl": "3.75rem",
+        "appkit-text-7xl": "4.5rem",
+        "appkit-text-8xl": "6rem",
     },
     gradients: {
         brand: "linear-gradient(to right, var(--appkit-color-primary), var(--appkit-color-secondary))",

package/dist/tokens/tokens.css

@@ -264,7 +264,13 @@
   --appkit-color-bg:               #fafafa;    /* zinc-50 */
   --appkit-color-surface:          #ffffff;    /* white */
   --appkit-color-surface-elevated: #ffffff;
-  --appkit-color-surface-input:    #ffffff;
+  /* 🛑 A FILL, not white. This was `#ffffff` — identical to `surface` — so a
+   * field on a white card had nothing but a 1px `#e4e4e7` border to mark it,
+   * which measures ~1.2:1 and is why the audit reported fields reading as
+   * faint outlines rather than objects. A recessed well is the cheaper fix
+   * than darkening every border in the product, because `--appkit-color-border`
+   * is also every divider and table rule. */
+  --appkit-color-surface-input:    #fafafa;    /* zinc-50 — recessed on a white card */
 
   /* --- Interactive surfaces ------------------------------------------------
    * `-hover` is the neutral chrome hover fill; `-raised` is a resting panel one
@@ -335,6 +341,49 @@
   --appkit-color-info-on-solid:    #ffffff;
 
   --appkit-color-focus-ring:       #0d9488;    /* primary-600 = teal */
+
+  /* --- The focus ring, in ONE place ----------------------------------------
+   *
+   * 🛑 `--appkit-color-focus-ring` HAD NO READER. It is declared by all four
+   * built-in themes, listed in `required.ts`, and surfaced as an editable
+   * swatch in the admin Theme Manager — and not one stylesheet consumed it.
+   * Every ring in the product was a hardcoded `rgba()` of the brand RETIRED
+   * on 2026-08-17: lime green `rgba(101, 196, 8, …)` in 9 primitives and hot
+   * pink `rgba(233, 30, 140, …)` in 6. So an admin could pick a focus colour
+   * and change nothing, while every focused control showed a dead brand.
+   *
+   * Three tokens because the primitives use three genuinely different ring
+   * SHAPES, and the shapes are kept byte-for-byte as they were — only the
+   * colour is re-pointed, so this carries no visual risk beyond the hue:
+   *
+   *   -ring      text fields (Input, Select, Textarea): 3px + a 1px inset
+   *   -compact   buttons (Button, IconButton, TagInput): a flat 2px
+   *   -halo      Checkbox / Radio / Toggle: 2px, then a 4px surface-coloured
+   *              gap so the ring reads against the control it is hugging
+   *
+   * They resolve `--appkit-color-focus-ring` at USE time, so each theme's own
+   * value applies automatically and every `.dark` focus override in the
+   * primitives becomes dead weight — which is the structural half of the fix:
+   * light and dark can no longer disagree, because there is only one value.
+   *
+   * `color-mix` unguarded, matching `--appkit-gradient-glass` above and
+   * `--glow-color` in globals.css. */
+  --appkit-focus-ring:
+    0 0 0 3px color-mix(in srgb, var(--appkit-color-focus-ring) 25%, transparent),
+    inset 0 0 0 1px color-mix(in srgb, var(--appkit-color-focus-ring) 15%, transparent);
+  --appkit-focus-ring-compact:
+    0 0 0 2px color-mix(in srgb, var(--appkit-color-focus-ring) 20%, transparent);
+  --appkit-focus-ring-halo:
+    0 0 0 2px color-mix(in srgb, var(--appkit-color-focus-ring) 30%, transparent),
+    0 0 0 4px var(--appkit-color-surface);
+  /* Same shape as `--appkit-focus-ring`, keyed on the error colour — a field
+   * that failed validation keeps its red edge while focused instead of
+   * swapping to the focus hue and losing the only signal it had. Was
+   * `rgba(248, 113, 113, …)` (red-400) hardcoded in Input and Select: the
+   * right family, but fixed in every theme and deaf to `--appkit-color-error`. */
+  --appkit-focus-ring-error:
+    0 0 0 3px color-mix(in srgb, var(--appkit-color-error) 25%, transparent),
+    inset 0 0 0 1px color-mix(in srgb, var(--appkit-color-error) 15%, transparent);
 }
 
 /* --- Gradients — default-light defaults (overridden at runtime by ThemeProvider) - */
@@ -405,8 +454,23 @@
 
   --appkit-color-bg:               #020617;    /* slate-950 */
   --appkit-color-surface:          #0f172a;    /* slate-900 */
-  --appkit-color-surface-elevated: rgba(15, 23, 42, 0.9);
-  --appkit-color-surface-input:    rgba(30, 41, 59, 0.6);  /* slate-800/60 */
+  /* 🛑 ELEVATED WAS DARKER THAN SURFACE. `rgba(15, 23, 42, 0.9)` composites
+   * over the page to ~#0e1528, i.e. BELOW `surface` (#0f172a) — so in a dark
+   * theme, where elevation reads as "closer to the light", every elevated
+   * panel sank instead of rising. That is the audit's "the hero card is
+   * nearly invisible against the page".
+   *
+   * Opaque, not an alpha, and that is the actual lesson: a translucent
+   * elevation token composites against WHATEVER IS BEHIND IT, so the same
+   * "elevated" panel rendered one colour over the page and another over a
+   * card — which is how it ended up below `surface` in the first place
+   * without anyone choosing that. */
+  --appkit-color-surface-elevated: #1e293b;    /* slate-800 — one step UP from surface */
+  /* Recessed, and distinct from all three panel levels, because an input
+   * appears on the page, on a card and on an elevated panel. The old
+   * `rgba(30, 41, 59, 0.6)` composited to the panel's own colour on an
+   * elevated panel — an input that disappears into the thing it sits on. */
+  --appkit-color-surface-input:    #0b1220;    /* a well, below slate-900 */
 
   /* --- Interactive surfaces ------------------------------------------------
    * `-hover` is the neutral chrome hover fill; `-raised` is a resting panel one
@@ -499,16 +563,19 @@
   --appkit-space-20:   5rem;
   --appkit-space-24:   6rem;
 
-  --appkit-text-2xs:   0.625rem;
-  --appkit-text-xs:    0.6875rem;
-  --appkit-text-sm:    0.8125rem;
-  --appkit-text-base:  0.9375rem;
-  --appkit-text-lg:    1rem;
-  --appkit-text-xl:    1.125rem;
-  --appkit-text-2xl:   1.375rem;
-  --appkit-text-3xl:   1.625rem;
-  --appkit-text-4xl:   1.875rem;
-  --appkit-text-5xl:   2.5rem;
+  --appkit-text-2xs:   0.6875rem;
+  --appkit-text-xs:    0.75rem;
+  --appkit-text-sm:    0.875rem;
+  --appkit-text-base:  1rem;
+  --appkit-text-lg:    1.125rem;
+  --appkit-text-xl:    1.25rem;
+  --appkit-text-2xl:   1.5rem;
+  --appkit-text-3xl:   1.875rem;
+  --appkit-text-4xl:   2.25rem;
+  --appkit-text-5xl:   3rem;
+  --appkit-text-6xl:   3.75rem;
+  --appkit-text-7xl:   4.5rem;
+  --appkit-text-8xl:   6rem;
 }
 
 /* --- Theme — Cobalt Night ([data-theme="cobalt-night"]) ------------------- */
@@ -639,16 +706,19 @@
   --appkit-font-editorial: var(--font-editorial), "Georgia", serif;
   --appkit-font-mono:      ui-monospace, "SFMono-Regular", "Cascadia Mono", "Consolas", monospace;
 
-  --appkit-text-2xs:       0.625rem;   /* 10px */
-  --appkit-text-xs:        0.6875rem;  /* 11px */
-  --appkit-text-sm:        0.8125rem;  /* 13px */
-  --appkit-text-base:      0.9375rem;  /* 15px */
-  --appkit-text-lg:        1rem;       /* 16px */
-  --appkit-text-xl:        1.125rem;   /* 18px */
-  --appkit-text-2xl:       1.375rem;   /* 22px */
-  --appkit-text-3xl:       1.625rem;   /* 26px */
-  --appkit-text-4xl:       1.875rem;   /* 30px */
-  --appkit-text-5xl:       2.5rem;     /* 40px */
+  --appkit-text-2xs:       0.6875rem;
+  --appkit-text-xs:        0.75rem;
+  --appkit-text-sm:        0.875rem;
+  --appkit-text-base:      1rem;
+  --appkit-text-lg:        1.125rem;
+  --appkit-text-xl:        1.25rem;
+  --appkit-text-2xl:       1.5rem;
+  --appkit-text-3xl:       1.875rem;
+  --appkit-text-4xl:       2.25rem;
+  --appkit-text-5xl:       3rem;
+  --appkit-text-6xl:       3.75rem;
+  --appkit-text-7xl:       4.5rem;
+  --appkit-text-8xl:       6rem;
 
   --appkit-leading-tight:  1.15;
   --appkit-leading-snug:   1.375;
@@ -664,6 +734,19 @@
 
 /* --- Spacing -------------------------------------------------------------- */
 :root {
+  /* 🛑 THE SCALE HAD NO ZERO, and 18 call sites reached for it anyway.
+   *
+   * `p-[var(--appkit-space-0)]` on a control that wants no padding resolved
+   * to an undefined var, which drops the declaration — so every one of those
+   * controls kept its DEFAULT padding, the exact opposite of the intent. The
+   * tightest case is `AdminNavigationView`'s ▲/▼ reorder buttons, which pair
+   * it with `min-h-0 h-auto` to get a glyph-sized hit area and instead got a
+   * full-size button.
+   *
+   * Declared rather than rewritten to `p-0` at each site: 18 independent
+   * authors reaching for the same name is the scale's gap, not 18 mistakes,
+   * and a scale that starts at 2px cannot express "none". */
+  --appkit-space-0:    0rem;       /*  0px */
   --appkit-space-0-5:  0.125rem;   /*  2px */
   --appkit-space-1:    0.25rem;    /*  4px */
   --appkit-space-1-5:  0.375rem;   /*  6px */

package/dist/ui/DataTable.style.css

@@ -168,15 +168,15 @@
 }
 
 .appkit-data-table__view-btn--active {
-  background: rgba(80, 156, 2, 0.05);
+  background: color-mix(in srgb, var(--appkit-color-secondary) 5%, transparent);
   color: var(--appkit-color-secondary-600);
-  box-shadow: inset 0 0 0 1px rgba(80, 156, 2, 0.3);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--appkit-color-secondary) 30%, transparent);
 }
 
 :is(.dark) .appkit-data-table__view-btn--active {
-  background: rgba(233, 30, 140, 0.1);
+  background: color-mix(in srgb, var(--appkit-color-primary) 10%, transparent);
   color: var(--appkit-color-primary);
-  box-shadow: inset 0 0 0 1px rgba(233, 30, 140, 0.3);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--appkit-color-primary) 30%, transparent);
 }
 
 .appkit-data-table__mobile-cards {

package/dist/ui/columns/cell-renderers.d.ts

@@ -7,6 +7,26 @@ import { type StatusTone } from "./column-renderers";
  * and `AdminViewCards.tsx`. Both are now consumers of this one.
  */
 export declare const STATUS_TONE_CLASSES: Record<StatusTone, string>;
+/**
+ * A stored status value as something a person reads.
+ *
+ * 🛑 EVERY status chip in the product printed the raw enum. This renderer
+ * used `status` verbatim, so admin tables and cards showed `published`,
+ * `in_review`, `out_of_stock` — lowercase, underscored, in our vocabulary
+ * rather than the reader's. That is the audit's "status is plain lowercase
+ * text where every other surface uses badges": the chip was there, its
+ * CONTENT was the database value.
+ *
+ * 🛑 And `productTableColumns` hand-rolled `status.replace("_", " ")`, which
+ * is worse than doing nothing: a STRING pattern replaces only the FIRST
+ * occurrence, so `out_of_stock` rendered as "out of_stock". A regex with `g`
+ * is the fix, which is reason enough for one helper instead of a `.replace`
+ * at each call site.
+ *
+ * Sentence case, not Title Case: these sit in dense table cells beside real
+ * sentences, and "Out Of Stock" reads like a proper noun.
+ */
+export declare function statusLabel(status: string): string;
 /** A status string as a themed chip. Unknown statuses render neutral, not invisible. */
 export declare function renderStatusBadge(status: string | null | undefined, opts?: {
     emptyLabel?: string;

package/dist/ui/columns/cell-renderers.js

@@ -21,9 +21,34 @@ export const STATUS_TONE_CLASSES = {
     // Not a status colour — see the header.
     neutral: "bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text-muted)]",
 };
+/**
+ * A stored status value as something a person reads.
+ *
+ * 🛑 EVERY status chip in the product printed the raw enum. This renderer
+ * used `status` verbatim, so admin tables and cards showed `published`,
+ * `in_review`, `out_of_stock` — lowercase, underscored, in our vocabulary
+ * rather than the reader's. That is the audit's "status is plain lowercase
+ * text where every other surface uses badges": the chip was there, its
+ * CONTENT was the database value.
+ *
+ * 🛑 And `productTableColumns` hand-rolled `status.replace("_", " ")`, which
+ * is worse than doing nothing: a STRING pattern replaces only the FIRST
+ * occurrence, so `out_of_stock` rendered as "out of_stock". A regex with `g`
+ * is the fix, which is reason enough for one helper instead of a `.replace`
+ * at each call site.
+ *
+ * Sentence case, not Title Case: these sit in dense table cells beside real
+ * sentences, and "Out Of Stock" reads like a proper noun.
+ */
+export function statusLabel(status) {
+    const words = status.replace(/[_-]+/g, " ").trim();
+    if (!words)
+        return status;
+    return words.charAt(0).toUpperCase() + words.slice(1).toLowerCase();
+}
 /** A status string as a themed chip. Unknown statuses render neutral, not invisible. */
 export function renderStatusBadge(status, opts) {
-    const label = status ?? opts?.emptyLabel ?? "—";
+    const label = status ? statusLabel(status) : (opts?.emptyLabel ?? "—");
     const tone = getStatusTone(status);
     return (_jsx(Span, { size: "xs", weight: "medium", rounded: "full", padding: "pill-sm-tall", className: `inline-flex whitespace-nowrap ${STATUS_TONE_CLASSES[tone]}`, children: label }));
 }

package/dist/ui/columns/index.d.ts

@@ -4,4 +4,4 @@
 export { buildColumns, createColumnBuilder, resolveColumnPriority } from "./build-columns";
 export { renderBoolean, renderCurrency, renderCurrencyCompact, renderCount, renderNullable, renderRating, getStatusTone, getResourceIcon, } from "./column-renderers";
 export type { BooleanRenderOpts, RatingMode, RatingRenderOpts, StatusTone, } from "./column-renderers";
-export { STATUS_TONE_CLASSES, renderStatusBadge, renderThumbnail, renderAvatar, renderMoney, renderRelativeDate, renderBooleanIcon, renderCountPill, renderTypeChip, } from "./cell-renderers";
+export { STATUS_TONE_CLASSES, renderStatusBadge, renderThumbnail, renderAvatar, renderMoney, renderRelativeDate, renderBooleanIcon, renderCountPill, renderTypeChip, statusLabel, } from "./cell-renderers";

package/dist/ui/columns/index.js

@@ -6,4 +6,7 @@ export { renderBoolean, renderCurrency, renderCurrencyCompact, renderCount, rend
 // JSX renderers. Deliberately a separate module from `column-renderers.ts`:
 // that one is React-free so it can run in a server context, and mixing the two
 // would drag React into every consumer of a plain string formatter.
-export { STATUS_TONE_CLASSES, renderStatusBadge, renderThumbnail, renderAvatar, renderMoney, renderRelativeDate, renderBooleanIcon, renderCountPill, renderTypeChip, } from "./cell-renderers.js";
+export { STATUS_TONE_CLASSES, renderStatusBadge, renderThumbnail, renderAvatar, renderMoney, renderRelativeDate, renderBooleanIcon, renderCountPill, renderTypeChip, 
+// The status LABEL on its own, for the handful of cells that need this
+// feature's own tones but the shared wording — see productTableColumns.
+statusLabel, } from "./cell-renderers.js";

package/dist/ui/components/Badge.style.css

@@ -68,7 +68,7 @@
 .appkit-badge--secondary {
   background: var(--appkit-color-secondary-50);
   color: var(--appkit-color-secondary-700);
-  border-color: rgba(101, 196, 8, 0.25);
+  border-color: color-mix(in srgb, var(--appkit-color-secondary) 25%, transparent);
 }
 
 .dark .appkit-badge--active,

package/dist/ui/components/Breadcrumb.js

@@ -4,7 +4,25 @@ import { Nav, Ol, Li } from "./Semantic.js";
 import { Span } from "./Typography.js";
 import { TextLink } from "./TextLink.js";
 export function Breadcrumb({ items, className = "", tone = "default" }) {
-    return (_jsx(Nav, { "aria-label": "Breadcrumb", className: `${tone === "on-media" ? "appkit-breadcrumb--on-media" : ""} ${className}`, children: _jsx(Ol, { className: "appkit-breadcrumb__list", children: items.map((item, i) => {
+    return (
+    /*
+     * 🛑 `appkit-page-breadcrumb` IS A SIGNAL TO CSS, not a style hook — and
+     * it belongs on THIS primitive rather than on `BreadcrumbTrail`, because
+     * this is the one thing every page-level breadcrumb has in common.
+     * `BreadcrumbTrail` wraps it; the scam registry's three surfaces render it
+     * directly; and `AutoBreadcrumbs` — the automatic, pathname-derived trail
+     * the shell renders on every route — does NOT use it at all, building its
+     * own `<Nav><Ol>`. So this class means exactly "a page supplied its own
+     * breadcrumb", with one owner and nothing to keep in sync.
+     *
+     * `AutoBreadcrumbs.style.css` hides the automatic trail when this appears
+     * anywhere in the body. See that file for why the resolution is `:has()`
+     * and not React state: the shell renders before `{children}`, so a flag a
+     * page sets arrives a frame late, and hiding a full-width strip after
+     * paint is the top-of-page layout shift just fixed on the announcement
+     * bar.
+     */
+    _jsx(Nav, { "aria-label": "Breadcrumb", className: `appkit-page-breadcrumb ${tone === "on-media" ? "appkit-breadcrumb--on-media" : ""} ${className}`, children: _jsx(Ol, { className: "appkit-breadcrumb__list", children: items.map((item, i) => {
                 const isLast = i === items.length - 1;
                 return (_jsxs(Li, { className: "appkit-breadcrumb__item", children: [i > 0 && (_jsx(ChevronRight, { className: "appkit-breadcrumb__separator", "aria-hidden": "true" })), isLast || !item.href ? (_jsx(Span, { className: isLast
                                 ? "appkit-breadcrumb__current"

package/dist/ui/components/BulkActionBar.style.css

@@ -2,7 +2,7 @@
   position: relative;
   border-radius: 0.5rem;
   overflow: hidden;
-  border: 1px solid rgba(80, 156, 2, 0.2);
+  border: 1px solid color-mix(in srgb, var(--appkit-color-secondary) 20%, transparent);
   animation: appkit-slide-in 150ms ease;
 }
 
@@ -34,14 +34,14 @@
   height: 2rem;
   padding: 0 0.75rem 0 0.5rem;
   border-radius: 9999px;
-  border: 1px solid rgba(80, 156, 2, 0.3);
-  background: rgba(80, 156, 2, 0.07);
+  border: 1px solid color-mix(in srgb, var(--appkit-color-secondary) 30%, transparent);
+  background: color-mix(in srgb, var(--appkit-color-secondary) 7%, transparent);
   color: var(--appkit-color-secondary-700);
   transition: background-color 0.15s ease;
 }
 
 .appkit-bulk-bar__count-pill:hover {
-  background: rgba(80, 156, 2, 0.14);
+  background: color-mix(in srgb, var(--appkit-color-secondary) 14%, transparent);
 }
 
 .appkit-bulk-bar__count-icon {

package/dist/ui/components/Button.style.css

@@ -49,7 +49,7 @@
 
 .appkit-button:focus-visible {
   outline: none;
-  box-shadow: 0 0 0 2px rgba(101, 196, 8, 0.2);
+  box-shadow: var(--appkit-focus-ring-compact);
 }
 
 .appkit-button:disabled {

package/dist/ui/components/Checkbox.style.css

@@ -50,7 +50,7 @@
 }
 .appkit-checkbox__input:focus-visible {
   outline: none;
-  box-shadow: 0 0 0 2px rgba(101, 196, 8, 0.3), 0 0 0 4px var(--appkit-color-surface);
+  box-shadow: var(--appkit-focus-ring-halo);
 }
 .appkit-checkbox__input:not(:disabled):hover {
   border-color: var(--appkit-color-secondary);

package/dist/ui/components/FallbackShell.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const TONE_BG = {
-    neutral: "var(--appkit-color-surface-muted)",
+    neutral: "var(--appkit-color-bg)",
     danger: "var(--appkit-color-error-surface)",
     warning: "var(--appkit-color-warning-surface)",
 };

package/dist/ui/components/Form.d.ts

@@ -41,6 +41,19 @@ export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement
      * this in a modal is a no-op rather than a bug.
      */
     bottomBar?: FormBottomBarConfig;
+    /**
+     * Offer "Create & add another" — render `<AddAnotherToggle>` somewhere in
+     * the form and read `addAnother` from the render-prop helpers' `shellCtx`.
+     *
+     * 🛑 PASSING THIS IS AN OBLIGATION, not a flag. The submit handler must keep
+     * the user on the form with a fresh draft when `addAnother` is true;
+     * otherwise it ships a checkbox that does nothing, which is the shape this
+     * codebase has paid for most often. `audit-add-another-honoured` blocks it.
+     *
+     * Ignored when `shellCtx` is supplied — the parent that owns the state owns
+     * this decision too, and two sources would disagree the first time one moved.
+     */
+    allowAddAnother?: boolean;
     /** Cross-axis alignment of flex/grid children. Replaces raw `items-*` className. */
     align?: "start" | "center" | "end" | "stretch";
     /** Gap between children — use instead of raw `gap-*` className. */
@@ -55,7 +68,7 @@ export interface FormBottomBarConfig {
     isLoading?: boolean;
     disabled?: boolean;
 }
-export declare function Form({ children, spacing, schema, shellCtx: shellCtxProp, bottomBar, align, gap, surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, className, ...props }: FormProps): React.JSX.Element;
+export declare function Form({ children, spacing, schema, shellCtx: shellCtxProp, bottomBar, allowAddAnother, align, gap, surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, className, ...props }: FormProps): React.JSX.Element;
 export interface FormGroupProps {
     children: React.ReactNode;
     columns?: 1 | 2 | 3 | 4;

package/dist/ui/components/Form.js

@@ -45,8 +45,8 @@ const FORM_ALIGN_MAP = {
     end: "items-end",
     stretch: "items-stretch",
 };
-export function Form({ children, spacing, schema, shellCtx: shellCtxProp, bottomBar, align, gap, surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, className = "", ...props }) {
-    const helpers = useFormShellState(schema);
+export function Form({ children, spacing, schema, shellCtx: shellCtxProp, bottomBar, allowAddAnother, align, gap, surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, className = "", ...props }) {
+    const helpers = useFormShellState(schema, undefined, { allowAddAnother });
     const effectiveCtx = shellCtxProp ?? helpers.shellCtx;
     /*
      * Marking the attempt on the NATIVE submit event covers both shapes this

package/dist/ui/components/FormField.js

@@ -1,10 +1,11 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useContext } from "react";
+import { useContext, useId } from "react";
 import { Input } from "./Input.js";
 import { Select } from "./Select.js";
 import { Textarea } from "./Textarea.js";
-import { Label, Text, Span } from "./Typography.js";
+import { Text } from "./Typography.js";
+import { FieldLabel } from "../forms/FieldLabel.js";
 /*
  * 🛑 FROM THE DEFINING MODULES, NOT the `features/media` barrel.
  *
@@ -40,7 +41,20 @@ export function FormField({ label, name, card = false, type = "text", value = ""
             ? touched && !!error
             : !!error
         : false;
-    const inputId = `field-${name}`;
+    const reactId = useId();
+    /*
+     * 🛑 UNIQUE PER INSTANCE. This was `field-${name}`, so two fields sharing a
+     * name on one page produced two elements with the SAME id — `/auth/login`
+     * shipped two `id="field-email"` (the sign-in form and the footer
+     * newsletter).
+     *
+     * That is not cosmetic. `htmlFor` resolves to the FIRST element with the
+     * id, so the second field's label points at the first field's input: the
+     * label is present in the markup and the input has no accessible name, which
+     * is what an accessibility pass reports as an unlabelled field. Clicking the
+     * second label also focuses the first input.
+     */
+    const inputId = `field-${name}-${reactId}`;
     const errorId = `${inputId}-error`;
     const describedBy = showError ? errorId : undefined;
     function handleFieldChange(newValue) {
@@ -58,6 +72,6 @@ export function FormField({ label, name, card = false, type = "text", value = ""
     if (type === "media" && onUpload) {
         return (_jsxs("div", { className: card ? CARD_CLASS : BASE_CLASS, "data-section": "formfield-div-506", children: [_jsx(MediaUploadField, { label: `${label || name}${required ? " *" : ""}`, value: value, onChange: (url) => handleFieldChange(url), onUpload: onUpload, disabled: disabled, helperText: hint ?? helpText, captureSource: captureSource ?? "file-only", captureMode: captureMode ?? "both", accept: accept, maxSizeMB: maxSizeMB }), showError ? (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error })) : null] }));
     }
-    return (_jsxs("div", { className: card ? CARD_CLASS : BASE_CLASS, "data-section": "formfield-div-507", children: [label ? (_jsxs(Label, { htmlFor: inputId, className: "appkit-form-field__label", children: [label, required ? (_jsx(Span, { className: "appkit-form-field__required", children: "*" })) : null] })) : null, type === "select" ? (_jsx(Select, { id: inputId, name: name, value: value, onChange: (event) => handleFieldChange(event.target.value), onBlur: handleFieldBlur, disabled: disabled, options: options, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": describedBy })) : type === "textarea" ? (_jsx(Textarea, { id: inputId, name: name, value: value, onChange: (event) => handleFieldChange(event.target.value), onBlur: handleFieldBlur, placeholder: placeholder, disabled: disabled, rows: rows, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": describedBy })) : (_jsx(Input, { id: inputId, name: name, type: type, value: value, onChange: (event) => handleFieldChange(event.target.value), onBlur: handleFieldBlur, placeholder: placeholder, disabled: disabled, autoComplete: autoComplete, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": describedBy })), !showError && (hint || helpText) ? (_jsx(Text, { size: "sm", variant: "secondary", className: "appkit-form-field__hint", children: hint ?? helpText })) : null, showError ? (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error })) : null] }));
+    return (_jsxs("div", { className: card ? CARD_CLASS : BASE_CLASS, "data-section": "formfield-div-507", children: [label ? (_jsx(FieldLabel, { htmlFor: inputId, required: required, children: label })) : null, type === "select" ? (_jsx(Select, { id: inputId, name: name, value: value, onChange: (event) => handleFieldChange(event.target.value), onBlur: handleFieldBlur, disabled: disabled, options: options, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": describedBy })) : type === "textarea" ? (_jsx(Textarea, { id: inputId, name: name, value: value, onChange: (event) => handleFieldChange(event.target.value), onBlur: handleFieldBlur, placeholder: placeholder, disabled: disabled, rows: rows, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": describedBy })) : (_jsx(Input, { id: inputId, name: name, type: type, value: value, onChange: (event) => handleFieldChange(event.target.value), onBlur: handleFieldBlur, placeholder: placeholder, disabled: disabled, autoComplete: autoComplete, "aria-required": required || undefined, "aria-invalid": showError || undefined, "aria-describedby": describedBy })), !showError && (hint || helpText) ? (_jsx(Text, { size: "sm", variant: "secondary", className: "appkit-form-field__hint", children: hint ?? helpText })) : null, showError ? (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error })) : null] }));
 }
 export default FormField;

package/dist/ui/components/FormField.style.css

@@ -4,16 +4,49 @@
   width: 100%;
 }
 
+/*
+ * 🛑 ONE THEME-INVERTING TOKEN, NOT A LIGHT/DARK PAIR OF HARDCODED ZINCS.
+ *
+ * This was `--appkit-color-zinc-700` with an `:is(.dark)` override to
+ * `--appkit-color-zinc-300`. Both halves worked — `ThemeProvider` does add the
+ * `.dark` class — but the zinc scale is declared ONCE under `:root` and never
+ * inverts (Root Cause #79), so these were two fixed greys standing in for a
+ * theme decision. A custom admin theme with its own palette got zinc anyway,
+ * on every form label in the app.
+ *
+ * `--appkit-color-text` inverts per theme and carries a MEASURED contrast
+ * ratio in its own declaration (tokens.css notes `~7:1` and `~9:1` for the
+ * muted variants, and records that the faint one was darkened to clear WCAG AA
+ * for normal text). A hardcoded zinc carries no such guarantee and cannot,
+ * because it does not know what it is sitting on.
+ *
+ * So one declaration replaces two, and there is no longer a pairing to get
+ * wrong — the same reasoning that made the hover fix a REMOVAL rather than an
+ * addition.
+ */
 .appkit-form-field__label {
   display: block;
   margin-bottom: 0.375rem;
   font-size: 0.875rem;
   font-weight: 500;
-  color: var(--appkit-color-zinc-700);
+  color: var(--appkit-color-text);
 }
 
-:is(.dark) .appkit-form-field__label {
-  color: var(--appkit-color-zinc-300);
+/*
+ * Inline placement — the label sits beside its control rather than above it,
+ * for dense sections (a 12-field address block). Set once per section via
+ * `SectionDef.labelPlacement`, never per field: one field labelling above
+ * beside one labelling inline reads as broken rather than as varied.
+ *
+ * The margin is reset because `above` owns a bottom margin that becomes a gap
+ * in the wrong axis once the label is beside the control.
+ */
+.appkit-form-field__label--inline {
+  display: inline-block;
+  margin-bottom: 0;
+  margin-right: 0.5rem;
+  min-width: 8rem;
+  vertical-align: middle;
 }
 
 .appkit-form-field__required {
@@ -21,8 +54,15 @@
   color: var(--appkit-color-error);
 }
 
+/*
+ * The hint is MUTED, not faint. `--appkit-color-text-faint` exists and its own
+ * token comment records being darkened to clear AA for normal text at all —
+ * i.e. it is the bottom of the usable range. A hint explains a field's rules
+ * and is read by whoever is unsure, so it belongs a tier up.
+ */
 .appkit-form-field__hint {
   margin-top: 0.375rem;
+  color: var(--appkit-color-text-muted);
 }
 
 .appkit-form-field__error {

package/dist/ui/components/GatedPrice.style.css

@@ -11,7 +11,7 @@
   min-width: 5rem;
   height: 1.25rem;
   border-radius: 0.25rem;
-  /* 🛑 `--appkit-color-surface-muted` is NOT a token — 15 uses, 0 definitions,
+  /* 🛑 `--appkit-color-bg` is NOT a token — 15 uses, 0 definitions,
      and `audit-undefined-css-vars` ratchets it down. An undefined custom
      property with no fallback makes the whole declaration invalid, so this
      placeholder had no background at all and the grid still reflowed on

package/dist/ui/components/IconButton.style.css

@@ -10,7 +10,7 @@
 
 .appkit-icon-button:focus-visible {
   outline: none;
-  box-shadow: 0 0 0 2px rgba(101, 196, 8, 0.2);
+  box-shadow: var(--appkit-focus-ring-compact);
 }
 
 .appkit-icon-button:disabled {