@godxjp/ui 16.4.0 → 16.6.0

package/dist/components/data-display/card.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
+import type { LucideIcon } from "lucide-react";
 type CardSize = "md" | "compact";
 /** Semantic leading-edge accent stripe (border-inline-start; width via the
  *  --card-accent-rail-width token, default 6px). */
@@ -86,6 +87,9 @@ export type StatCardProps = React.HTMLAttributes<HTMLDivElement> & VariantProps<
     label: React.ReactNode;
     value: React.ReactNode;
     hint?: React.ReactNode;
+    /** Optional leading icon, rendered as a tinted medallion above the metric. Decorative
+     *  (aria-hidden) — the label carries the meaning. Tint via --stat-card-icon-* tokens. */
+    icon?: LucideIcon;
     /** Optional compact trend text beside the value. Avoid badge-like deltas. */
     delta?: React.ReactNode;
     /** KPI layout: stacked = design default, inline = label left / value right. */
@@ -98,7 +102,7 @@ export type StatCardProps = React.HTMLAttributes<HTMLDivElement> & VariantProps<
     accent?: CardAccent;
 };
 /** KPI / stat tile — token-driven layout aligned to dashboard KPI cards. */
-export declare function StatCard({ label, value, hint, delta, layout, align, inverse, accent, className, size, ...props }: StatCardProps): import("react/jsx-runtime").JSX.Element;
+export declare function StatCard({ label, value, hint, icon: Icon, delta, layout, align, inverse, accent, className, size, ...props }: StatCardProps): import("react/jsx-runtime").JSX.Element;
 /** Header actions slot — pair with `CardHeader className="flex flex-row …"`. */
 export declare const CardAction: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
 export {};

package/dist/components/data-display/card.js

@@ -96,6 +96,7 @@ function StatCard({
   label,
   value,
   hint,
+  icon: Icon,
   delta,
   layout = "stacked",
   align = "start",
@@ -117,6 +118,7 @@ function StatCard({
       "data-stat-align": align,
       ...props,
       children: [
+        Icon ? /* @__PURE__ */ jsx("span", { "data-slot": "stat-card-icon", "aria-hidden": "true", children: /* @__PURE__ */ jsx(Icon, {}) }) : null,
         /* @__PURE__ */ jsxs("div", { "data-slot": "stat-card-body", children: [
           /* @__PURE__ */ jsx("div", { "data-slot": "stat-card-label", children: label }),
           hint && layout === "inline" ? /* @__PURE__ */ jsx("div", { "data-slot": "stat-card-hint", children: hint }) : null
@@ -130,8 +132,8 @@ function StatCard({
                 "data-slot": "stat-card-delta",
                 "data-delta-tone": deltaTone,
                 className: cn(
-                  deltaTone === "positive" && "text-success",
-                  deltaTone === "negative" && "text-destructive"
+                  deltaTone === "positive" && "text-success-strong",
+                  deltaTone === "negative" && "text-error-strong"
                 ),
                 children: delta
               }

package/dist/components/feedback/sheet.js

@@ -24,7 +24,9 @@ const SheetOverlay = React.forwardRef(({ className, ...props }, ref) => /* @__PU
     ref,
     "data-slot": "sheet-overlay",
     className: cn(
-      "data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/50",
+      // Scrim colour comes from the shared --overlay-background token (see dialog-layout.css),
+      // so a service tints every overlay's backdrop from one knob instead of a baked bg-black/50.
+      "data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0 fixed inset-0 z-50",
       className
     ),
     ...props

package/dist/components/navigation/steps.js

@@ -17,7 +17,7 @@ function StepIcon({
   if (icon)
     return /* @__PURE__ */ jsx("span", { className: cn("flex items-center justify-center", controlIconClass), children: icon });
   if (type === "dot") {
-    return /* @__PURE__ */ jsx(
+    return /* @__PURE__ */ jsx("span", { className: cn("flex items-center justify-center", controlIconClass), children: /* @__PURE__ */ jsx(
       "span",
       {
         className: cn(
@@ -28,7 +28,7 @@ function StepIcon({
           status === "wait" && "bg-muted-foreground/30"
         )
       }
-    );
+    ) });
   }
   return /* @__PURE__ */ jsxs(
     "span",

package/dist/lib/control-styles.d.ts

@@ -17,10 +17,12 @@ export declare const controlIconLeadingClass = "size-[length:var(--control-icon-
 export declare const tableRowHeightClass = "h-[length:var(--table-row-height)]";
 export declare const tableHeadHeightClass = "h-[length:var(--table-row-height)]";
 export declare const tableCellPaddingClass = "py-[length:var(--table-cell-padding-y)]";
-/** Semantic status / badge tones — always use tokens, never raw Tailwind palette. */
-export declare const toneSuccessClass = "border-success/30 bg-success/10 text-success";
-export declare const toneWarningClass = "border-warning/30 bg-warning/10 text-warning-foreground";
-export declare const toneInfoClass = "border-info/30 bg-info/10 text-info";
-export declare const toneDestructiveClass = "border-destructive/30 bg-destructive/10 text-destructive";
+/** Semantic status / badge tones — always use tokens, never raw Tailwind palette. The TEXT uses the
+ * AA-strong status colours (text-*-strong, darker than the fill) so a small status label clears
+ * WCAG AA on the soft tint; the border/fill keep the brighter wa-iro role. */
+export declare const toneSuccessClass = "border-success/30 bg-success/10 text-success-strong";
+export declare const toneWarningClass = "border-warning/30 bg-warning/10 text-warning-strong";
+export declare const toneInfoClass = "border-info/30 bg-info/10 text-info-strong";
+export declare const toneDestructiveClass = "border-destructive/30 bg-destructive/10 text-error-strong";
 export declare const toneMutedClass = "border-border bg-muted text-muted-foreground";
 export declare const toneNeutralClass = "border-border bg-muted text-muted-foreground";

package/dist/lib/control-styles.js

@@ -8,10 +8,10 @@ const controlIconLeadingClass = "size-[length:var(--control-icon-size)] shrink-0
 const tableRowHeightClass = "h-[length:var(--table-row-height)]";
 const tableHeadHeightClass = "h-[length:var(--table-row-height)]";
 const tableCellPaddingClass = "py-[length:var(--table-cell-padding-y)]";
-const toneSuccessClass = "border-success/30 bg-success/10 text-success";
-const toneWarningClass = "border-warning/30 bg-warning/10 text-warning-foreground";
-const toneInfoClass = "border-info/30 bg-info/10 text-info";
-const toneDestructiveClass = "border-destructive/30 bg-destructive/10 text-destructive";
+const toneSuccessClass = "border-success/30 bg-success/10 text-success-strong";
+const toneWarningClass = "border-warning/30 bg-warning/10 text-warning-strong";
+const toneInfoClass = "border-info/30 bg-info/10 text-info-strong";
+const toneDestructiveClass = "border-destructive/30 bg-destructive/10 text-error-strong";
 const toneMutedClass = "border-border bg-muted text-muted-foreground";
 const toneNeutralClass = "border-border bg-muted text-muted-foreground";
 export {

package/dist/props/registry.d.ts

@@ -1086,7 +1086,7 @@ export declare const COMPONENT_PROP_REGISTRY: {
     readonly StatCardProp: {
         readonly group: "data-display";
         readonly file: "components/data-display/card.tsx";
-        readonly vocabulary: readonly ["TitleProp", "ToneProp", "ClassNameProp"];
+        readonly vocabulary: readonly ["TitleProp", "ToneProp", "IconProp", "ClassNameProp"];
     };
     readonly ResponsiveGridProp: {
         readonly group: "layout";

package/dist/props/registry.js

@@ -1080,7 +1080,7 @@ const COMPONENT_PROP_REGISTRY = {
   StatCardProp: {
     group: "data-display",
     file: "components/data-display/card.tsx",
-    vocabulary: ["TitleProp", "ToneProp", "ClassNameProp"]
+    vocabulary: ["TitleProp", "ToneProp", "IconProp", "ClassNameProp"]
   },
   ResponsiveGridProp: {
     group: "layout",

package/dist/styles/alert-layout.css

@@ -120,20 +120,22 @@
     line-height: 1;
   }
 
+  /* Title text reads the AA-strong status colour (darker than the fill) so the coloured heading
+   * clears WCAG AA on the soft alert tint; the icon keeps the brighter role colour. */
   [data-slot="alert-title"][data-tone="destructive"] {
-    color: hsl(var(--destructive));
+    color: hsl(var(--text-error));
   }
 
   [data-slot="alert-title"][data-tone="warning"] {
-    color: hsl(var(--warning));
+    color: hsl(var(--text-warning));
   }
 
   [data-slot="alert-title"][data-tone="success"] {
-    color: hsl(var(--success));
+    color: hsl(var(--text-success));
   }
 
   [data-slot="alert-title"][data-tone="info"] {
-    color: hsl(var(--info));
+    color: hsl(var(--text-info));
   }
 
   [data-slot="alert-description"] {
@@ -168,7 +170,7 @@
 
   .ui-skeleton-block {
     border-radius: var(--skeleton-radius);
-    background: hsl(var(--muted));
+    background: var(--skeleton-background, hsl(var(--muted)));
     animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
   }
 

package/dist/styles/card-layout.css

@@ -27,10 +27,19 @@
      * `[data-accent]` rail-width override below can win within the same cascade layer. */
     border-width: 1px;
     border-style: solid;
-    border-color: hsl(var(--card-border));
+    border-color: hsl(var(--card-border, var(--border)));
     border-radius: var(--card-radius);
-    background: hsl(var(--card-background));
+    /* Fill = base card colour with an opt-in role tint washed over it (--card-tint default
+     * transparent → byte-identical at rest). Tint layer sits ABOVE the base colour.
+     * --card-background defaults to the LIVE --card role at the call site (re-resolves under a
+     * scoped theme); a service overrides --card-background to win. */
+    background:
+      linear-gradient(var(--card-tint), var(--card-tint)),
+      hsl(var(--card-background, var(--card)));
     color: hsl(var(--card-foreground));
+    /* Resting elevation + opt-in brand glow — both quiet no-ops by default so a service theme can
+     * lift (--card-shadow) and/or glow (--card-glow) every card with no markup change. */
+    box-shadow: var(--card-shadow), var(--card-glow);
     overflow: hidden;
   }
 
@@ -119,7 +128,7 @@
     align-items: center;
     gap: var(--space-inline-md);
     padding: var(--card-space-header-y) var(--card-space-inset);
-    border-block: 1px solid hsl(var(--card-border));
+    border-block: 1px solid hsl(var(--card-border, var(--border)));
   }
 
   [data-slot="card-bar"]:first-child {
@@ -147,8 +156,10 @@
   }
 
   .ui-card-header--banded {
-    border-bottom: var(--card-header-border-bottom);
-    background-color: hsl(var(--card-header-background) / var(--card-header-background-alpha));
+    border-bottom: var(--card-header-border-bottom, 1px solid hsl(var(--card-border, var(--border))));
+    background-color: hsl(
+      var(--card-header-background, var(--muted)) / var(--card-header-background-alpha)
+    );
   }
 
   [data-slot="card-header"][data-banded] {
@@ -336,7 +347,7 @@
   }
 
   [data-slot="card-footer"][data-separated] {
-    border-top: 1px solid hsl(var(--card-border));
+    border-top: 1px solid hsl(var(--card-border, var(--border)));
     /* Divided band → symmetric vertical padding (border-aware), in sync with a banded header. */
     padding-block: var(--card-space-divided-y);
     justify-content: flex-end;
@@ -384,6 +395,31 @@
     min-width: 0;
   }
 
+  /* Optional leading icon medallion — tinted box above the metric. Tone via tokens (default a
+   * soft brand-primary tint), so a service rethemes it with --primary or the icon tokens. */
+  [data-slot="stat-card-icon"] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: var(--stat-card-icon-size);
+    height: var(--stat-card-icon-size);
+    margin-bottom: var(--stat-card-gap);
+    border-radius: var(--stat-card-icon-radius);
+    background: var(--stat-card-icon-background, hsl(var(--primary) / 0.1));
+    color: var(--stat-card-icon-foreground, hsl(var(--primary)));
+  }
+
+  [data-slot="stat-card-icon"] svg {
+    width: var(--stat-card-icon-glyph-size);
+    height: var(--stat-card-icon-glyph-size);
+  }
+
+  /* Inline layout: medallion floats to the trailing edge so label/value keep the start column. */
+  [data-slot="card"][data-stat-layout="inline"] [data-slot="stat-card-icon"] {
+    margin-bottom: 0;
+    order: 1;
+  }
+
   [data-slot="stat-card-label"] {
     display: flex;
     align-items: center;

package/dist/styles/control.css

@@ -50,13 +50,13 @@
   }
 
   .ui-toggle[data-state="on"] {
-    background: hsl(var(--primary));
+    background: var(--toggle-on-background, hsl(var(--primary)));
     color: hsl(var(--primary-foreground));
   }
 
   .ui-toggle:focus-visible {
     outline: none;
-    box-shadow: 0 0 0 3px hsl(var(--ring) / 0.35);
+    box-shadow: 0 0 0 3px hsl(var(--focus-ring-color, var(--ring)) / 0.35);
   }
 
   .ui-toggle:disabled,
@@ -85,7 +85,7 @@
 
   .ui-button:focus-visible {
     outline: none;
-    box-shadow: 0 0 0 var(--control-focus-ring-width) hsl(var(--ring));
+    box-shadow: 0 0 0 var(--focus-ring-width) hsl(var(--focus-ring-color, var(--ring)));
   }
 
   .ui-button:disabled {
@@ -102,7 +102,9 @@
   .ui-button--default {
     background: hsl(var(--primary));
     color: hsl(var(--primary-foreground));
-    box-shadow: var(--shadow-sm);
+    /* Brand glow layers on top of the resting shadow; --shadow-glow is invisible by default
+     * (quiet) so a service opts the CTA halo in by setting the token alone. */
+    box-shadow: var(--shadow-sm), var(--shadow-glow);
   }
 
   .ui-button--default:hover {
@@ -119,9 +121,17 @@
     background: hsl(var(--destructive) / 0.9);
   }
 
+  /* Outline + ghost set their text colour EXPLICITLY (read --foreground) — never rely on inherited
+   * body colour. Inheriting breaks in a scoped dark region (e.g. an on-navy hero): the body's
+   * computed dark colour would carry in and the label goes near-invisible on the dark fill. */
   .ui-button--outline {
     border: 1px solid hsl(var(--input));
     background: hsl(var(--background));
+    color: hsl(var(--foreground));
+  }
+
+  .ui-button--ghost {
+    color: hsl(var(--foreground));
   }
 
   .ui-button--outline:hover,
@@ -277,7 +287,7 @@
   .ui-slider-thumb:focus-visible,
   .ui-switch:focus-visible {
     outline: none;
-    box-shadow: 0 0 0 var(--control-focus-ring-width) hsl(var(--ring));
+    box-shadow: 0 0 0 var(--focus-ring-width) hsl(var(--focus-ring-color, var(--ring)));
   }
 
   .ui-checkbox:disabled,
@@ -289,7 +299,7 @@
   }
 
   .ui-checkbox[data-state="checked"] {
-    background: hsl(var(--primary));
+    background: var(--checkbox-checked-background, hsl(var(--primary)));
     color: hsl(var(--primary-foreground));
   }
 
@@ -326,7 +336,7 @@
   }
 
   .ui-switch[data-state="checked"] {
-    background: hsl(var(--primary));
+    background: var(--switch-checked-background, hsl(var(--primary)));
   }
 
   .ui-switch[data-state="unchecked"] {
@@ -364,13 +374,13 @@
     flex-grow: 1;
     overflow: hidden;
     border-radius: var(--radius-pill);
-    background: hsl(var(--primary) / 0.2);
+    background: var(--slider-track-background, hsl(var(--primary) / 0.2));
   }
 
   .ui-slider-range {
     position: absolute;
     height: 100%;
-    background: hsl(var(--primary));
+    background: var(--slider-range-background, hsl(var(--primary)));
   }
 
   .ui-slider-thumb {
@@ -646,13 +656,13 @@
 }
 .ui-otp-slot[data-active="true"] {
   z-index: 1;
-  box-shadow: 0 0 0 2px hsl(var(--ring));
+  box-shadow: 0 0 0 var(--focus-ring-width) hsl(var(--focus-ring-color, var(--ring)));
 }
 .ui-otp-container:has(.ui-otp-input[aria-invalid="true"]) .ui-otp-slot {
   border-color: hsl(var(--destructive));
 }
 .ui-otp-container:has(.ui-otp-input[aria-invalid="true"]) .ui-otp-slot[data-active="true"] {
-  box-shadow: 0 0 0 2px hsl(var(--destructive));
+  box-shadow: 0 0 0 var(--focus-ring-width) hsl(var(--destructive));
 }
 .ui-otp-container:has(.ui-otp-input:disabled) .ui-otp-slot {
   cursor: not-allowed;
@@ -717,7 +727,7 @@
   fill: currentColor;
 }
 .ui-rating-star:focus-visible {
-  outline: 2px solid hsl(var(--ring));
+  outline: var(--focus-ring-width) solid hsl(var(--focus-ring-color, var(--ring)));
   outline-offset: 2px;
   border-radius: var(--radius-sm);
 }
@@ -735,8 +745,8 @@
   background: hsl(var(--background));
 }
 .ui-tag-input:focus-within {
-  box-shadow: 0 0 0 2px hsl(var(--ring));
-  border-color: hsl(var(--ring));
+  box-shadow: 0 0 0 var(--focus-ring-width) hsl(var(--focus-ring-color, var(--ring)));
+  border-color: hsl(var(--focus-ring-color, var(--ring)));
 }
 .ui-tag-input-disabled {
   opacity: 0.6;

package/dist/styles/data-display-layout.css

@@ -9,7 +9,10 @@
     justify-content: center;
     overflow: hidden;
     border-radius: var(--radius-pill);
-    background: hsl(var(--muted));
+    /* Tint washes over the role background (default transparent = no-op, rule #44). */
+    background:
+      linear-gradient(var(--avatar-tint), var(--avatar-tint)),
+      var(--avatar-background, hsl(var(--muted)));
     color: hsl(var(--muted-foreground));
     font-size: var(--font-size-base);
     font-weight: var(--font-weight-medium);
@@ -27,7 +30,7 @@
     height: 100%;
     align-items: center;
     justify-content: center;
-    background: hsl(var(--muted));
+    background: var(--avatar-background, hsl(var(--muted)));
   }
 
   .ui-progress {
@@ -40,13 +43,13 @@
     height: 0.5rem;
     overflow: hidden;
     border-radius: var(--radius-pill);
-    background: hsl(var(--secondary));
+    background: var(--progress-track-background, hsl(var(--secondary)));
   }
 
   .ui-progress-bar {
     height: 100%;
     border-radius: inherit;
-    background: hsl(var(--success));
+    background: var(--progress-fill-background, hsl(var(--success)));
   }
 
   .ui-progress[data-tone="warning"] .ui-progress-bar {
@@ -75,8 +78,8 @@
   }
 
   .ui-tree-item[data-active="true"] {
-    border-color: hsl(var(--primary) / 0.3);
-    background: hsl(var(--primary) / 0.05);
+    border-color: var(--tree-item-active-border, hsl(var(--primary) / 0.3));
+    background: var(--tree-item-active-background, hsl(var(--primary) / 0.05));
   }
 
   .ui-tree-item[data-depth="1"] {
@@ -151,7 +154,7 @@
     place-items: center;
     border: 1px solid transparent;
     border-radius: var(--radius-pill);
-    background: hsl(var(--success));
+    background: var(--timeline-dot-done-background, hsl(var(--success)));
     color: hsl(var(--success-foreground));
     font-size: var(--timeline-note-font-size);
     font-weight: var(--font-weight-medium);
@@ -160,14 +163,14 @@
 
   /* done → success fill. */
   .ui-timeline-dot[data-status="done"] {
-    background: hsl(var(--success));
+    background: var(--timeline-dot-done-background, hsl(var(--success)));
     color: hsl(var(--success-foreground));
   }
 
   /* current → primary fill + ring (also the legacy data-current shorthand). */
   .ui-timeline-dot[data-status="current"],
   .ui-timeline-dot[data-current="true"] {
-    background: hsl(var(--primary));
+    background: var(--timeline-dot-current-background, hsl(var(--primary)));
     color: hsl(var(--primary-foreground));
     box-shadow: 0 0 0 3px hsl(var(--primary) / 0.18);
   }
@@ -202,7 +205,7 @@
 
   /* The segment below a done/current step reads as travelled (completed). */
   .ui-timeline-line[data-completed="true"] {
-    background: hsl(var(--primary));
+    background: var(--timeline-line-completed-background, hsl(var(--primary)));
   }
 
   .ui-timeline-head {
@@ -256,7 +259,7 @@
   text-decoration: underline;
 }
 .ui-accordion-trigger:focus-visible {
-  outline: 2px solid hsl(var(--ring));
+  outline: var(--focus-ring-width) solid hsl(var(--focus-ring-color, var(--ring)));
   outline-offset: 2px;
   border-radius: var(--radius-sm);
 }
@@ -383,7 +386,7 @@
 }
 
 .ui-carousel-dot:focus-visible {
-  outline: 2px solid hsl(var(--ring));
+  outline: var(--focus-ring-width) solid hsl(var(--focus-ring-color, var(--ring)));
   outline-offset: 2px;
 }
 
@@ -441,7 +444,7 @@
     align-items: flex-start;
   }
   [data-slot="list-row"]:not(:last-child) {
-    border-block-end: var(--list-row-border);
+    border-block-end: var(--list-row-border, 1px solid hsl(var(--border)));
   }
   [data-slot="list-row-leading"] {
     display: inline-flex;

package/dist/styles/data-entry-layout.css

@@ -83,8 +83,8 @@
   }
 
   .ui-time-input:focus-visible {
-    border-color: hsl(var(--ring));
-    box-shadow: 0 0 0 3px hsl(var(--ring) / 0.3);
+    border-color: hsl(var(--focus-ring-color, var(--ring)));
+    box-shadow: 0 0 0 3px hsl(var(--focus-ring-color, var(--ring)) / 0.3);
   }
 
   .ui-time-input[aria-invalid="true"] {

package/dist/styles/dialog-layout.css

@@ -21,11 +21,15 @@
     border-top: 1px solid hsl(var(--border));
   }
 
+  .ui-dialog-overlay,
+  [data-slot="sheet-overlay"] {
+    background-color: var(--overlay-background);
+  }
+
   .ui-dialog-overlay {
     position: fixed;
     inset: 0;
     z-index: 50;
-    background-color: rgb(0 0 0 / 0.5);
   }
 
   [data-slot="dialog-content"] {
@@ -43,7 +47,7 @@
     padding: var(--dialog-space-inset);
     /* clip so the full-bleed header/footer bands round with the dialog corners (Ant Modal). */
     overflow: hidden;
-    box-shadow: var(--shadow-lg, 0 10px 15px -3px rgb(0 0 0 / 0.1));
+    box-shadow: var(--shadow-lg, 0 10px 15px -3px rgb(0 0 0 / 0.1)), var(--dialog-content-glow);
   }
 
   @media (min-width: 640px) {

package/dist/styles/index.css

@@ -41,6 +41,8 @@
  * `var(--radius-2xl)` directly; without a generated utility Tailwind drops the unused var). */
 @source inline("rounded-{xs,xl,2xl}");
 @source inline("text-2xs");
+@source inline("text-{3xl,4xl,5xl}");
+@source inline("text-{success,warning,info,error}-strong");
 /* `.js` matters: the published package ships only compiled JS under dist (no
  * .tsx sources), and this file is copied verbatim into dist/styles — without
  * it Tailwind finds no component classes in consumers (unstyled popovers and
@@ -64,7 +66,14 @@
 @import "./navigation-layout.css";
 @import "./chart-layout.css";
 
-@theme {
+/* `inline` (NOT a bare @theme): Tailwind inlines each expression — e.g. `hsl(var(--primary))` —
+ * directly into every utility (`bg-primary` becomes `background-color: hsl(var(--primary))`) instead
+ * of emitting `var(--color-primary)` computed once at :root. This is THE enabler for scoped /
+ * multi-tenant theming: a `[data-tenant]{ --primary: … }` override now re-resolves at the element,
+ * so colors and radius propagate into a subtree (a plain @theme froze them at :root, so scoped
+ * overrides never reached the color utilities). Components read raw tokens like `hsl(var(--primary))`
+ * directly in their own CSS, so they re-theme the same way. */
+@theme inline {
   --color-background: hsl(var(--background));
   --color-foreground: hsl(var(--foreground));
   --color-card: hsl(var(--card));
@@ -92,6 +101,12 @@
   --color-info-foreground: hsl(var(--info-foreground));
   --color-attention: hsl(var(--attention));
   --color-attention-foreground: hsl(var(--attention-foreground));
+  /* AA-strong status TEXT colours (text-{success,warning,info,error}-strong) — darker than the
+   * fills so small coloured labels clear WCAG AA on white; flip light on the dark theme. */
+  --color-success-strong: hsl(var(--text-success));
+  --color-warning-strong: hsl(var(--text-warning));
+  --color-info-strong: hsl(var(--text-info));
+  --color-error-strong: hsl(var(--text-error));
   --color-chart-1: var(--chart-1);
   --color-chart-2: var(--chart-2);
   --color-chart-3: var(--chart-3);
@@ -145,6 +160,10 @@
   --text-lg: var(--font-size-lg);
   --text-xl: var(--font-size-xl);
   --text-2xl: var(--font-size-2xl);
+  /* Opt-in DISPLAY ramp (marketing/hero) — wired to the display tokens, unused by the admin scale. */
+  --text-3xl: var(--font-size-3xl);
+  --text-4xl: var(--font-size-4xl);
+  --text-5xl: var(--font-size-5xl);
 }
 
 @layer base {
@@ -172,7 +191,9 @@
   body {
     background-color: hsl(var(--background));
     color: hsl(var(--foreground));
-    font-family: var(--font-family-sans);
+    /* Body reads --font-family-body (defaults to --font-family-sans → unchanged); a service that
+     * wants a dual-font brand (display + body face) overrides --font-family-body alone. */
+    font-family: var(--font-family-body);
     font-size: var(--font-size-base);
     line-height: var(--line-height-body);
     font-feature-settings:
@@ -186,7 +207,13 @@
 
   /* Semantic heading scale — SEO + accessibility: real <h1>–<h6> elements carry
    * the document outline (one <h1> per page, levels never skipped). Visual size
-   * follows the dxs-kintai scale; component titles override via their own class. */
+   * follows the dxs-kintai scale; component titles override via their own class.
+   * Headings read --font-family-display (defaults to --font-family-sans → unchanged) for dual-font
+   * brands (display face on headings, body face on prose). */
+  :where(h1, h2, h3, h4, h5, h6) {
+    font-family: var(--font-family-display);
+  }
+
   h1 {
     font-size: var(--heading-h1);
     font-weight: var(--font-weight-medium);

package/dist/styles/layout.css

@@ -345,6 +345,9 @@
     gap: var(--space-stack-sm);
     padding-bottom: var(--page-header-pad-bottom);
     border-bottom: var(--page-header-divider);
+    /* Hero banner hook — invisible by default (--gradient-hero: none); a service paints a hero
+     * gradient across the page header (full-bleed) by configuring the token alone. */
+    background-image: var(--gradient-hero);
   }
 
   .ui-page-header-row {
@@ -494,7 +497,10 @@
     width: 3rem;
     height: 3rem;
     border-radius: var(--radius-pill);
-    background-color: hsl(var(--muted));
+    /* Medallion fill + glyph colour read their knobs, defaulting to the LIVE --muted /
+     * --muted-foreground roles at the call site (re-resolves under a scoped theme). */
+    background-color: var(--empty-state-icon-tint, hsl(var(--muted)));
+    color: var(--empty-state-icon-foreground, hsl(var(--muted-foreground)));
   }
 }
 

package/dist/styles/navigation-layout.css

@@ -8,7 +8,7 @@
     background: hsl(var(--popover));
     color: hsl(var(--popover-foreground));
     padding: var(--space-1);
-    box-shadow: var(--shadow-md);
+    box-shadow: var(--shadow-md), var(--shadow-glow);
   }
 
   .ui-context-menu-item,
@@ -55,8 +55,8 @@
   .ui-menubar-sub-trigger:hover,
   .ui-navigation-menu-link:hover,
   .ui-navigation-menu-item:hover {
-    background: hsl(var(--accent));
-    color: hsl(var(--accent-foreground));
+    background: var(--menubar-item-hover-background, hsl(var(--accent)));
+    color: var(--menubar-item-hover-foreground, hsl(var(--accent-foreground)));
   }
 
   .ui-context-menu-item[data-state="open"],
@@ -68,8 +68,8 @@
   .ui-menubar-sub-trigger[data-state="open"],
   .ui-navigation-menu-link[data-highlighted],
   .ui-navigation-menu-item[data-focus-visible] {
-    background: hsl(var(--accent));
-    color: hsl(var(--accent-foreground));
+    background: var(--menubar-item-hover-background, hsl(var(--accent)));
+    color: var(--menubar-item-hover-foreground, hsl(var(--accent-foreground)));
   }
 
   .ui-context-menu-item[data-variant="destructive"],
@@ -146,7 +146,7 @@
     background: hsl(var(--popover));
     color: hsl(var(--popover-foreground));
     padding: var(--space-1);
-    box-shadow: var(--shadow-md);
+    box-shadow: var(--shadow-md), var(--shadow-glow);
   }
 
   .ui-context-menu-sub-trigger-icon,
@@ -179,13 +179,13 @@
     background: hsl(var(--popover));
     color: hsl(var(--popover-foreground));
     padding: var(--space-1);
-    box-shadow: var(--shadow-md);
+    box-shadow: var(--shadow-md), var(--shadow-glow);
   }
 
   .ui-menubar-trigger[data-state="open"],
   .ui-menubar-sub-trigger[data-state="open"] {
-    background: hsl(var(--accent));
-    color: hsl(var(--accent-foreground));
+    background: var(--menubar-item-hover-background, hsl(var(--accent)));
+    color: var(--menubar-item-hover-foreground, hsl(var(--accent-foreground)));
   }
 
   .ui-navigation-menu {
@@ -233,7 +233,7 @@
     background: hsl(var(--popover));
     color: hsl(var(--popover-foreground));
     padding: var(--space-1);
-    box-shadow: var(--shadow-md);
+    box-shadow: var(--shadow-md), var(--shadow-glow);
   }
 
   .ui-navigation-menu-link {

package/dist/styles/shell-layout.css

@@ -30,6 +30,8 @@
     overflow: hidden;
     border-inline-end: 1px solid hsl(var(--border));
     background: hsl(var(--card));
+    /* Opt-in brand-chrome wash — invisible by default (--sidebar-gradient: none). */
+    background-image: var(--sidebar-gradient);
     color: hsl(var(--foreground));
   }
 
@@ -45,6 +47,8 @@
     padding-inline: var(--space-4);
     border-bottom: 1px solid hsl(var(--border));
     background: hsl(var(--background) / 0.92);
+    /* Opt-in brand-chrome wash — invisible by default (--topbar-gradient: none). */
+    background-image: var(--topbar-gradient);
     backdrop-filter: blur(12px);
   }
 
@@ -52,6 +56,9 @@
     grid-area: main;
     min-width: 0;
     overflow: auto;
+    /* Ambient brand glow hook — invisible by default (--gradient-glow: none); a service paints a
+     * radial/linear brand wash behind the whole content area by configuring the token alone. */
+    background-image: var(--gradient-glow);
     /* Sole scroll/clip boundary for the page area. `overflow:auto` alone does NOT reliably
      * establish a paint-containment boundary in Chrome: tall nested scrollers (a two-pane
      * `grid` of long lists, a nested `overflow-y:auto` region) — or any absolutely-positioned
@@ -254,13 +261,17 @@
     text-align: start;
   }
 
-  .sb-nav-item:hover,
-  .sb-nav-item[data-active="true"] {
+  .sb-nav-item:hover {
     background: hsl(var(--accent));
     color: hsl(var(--foreground));
   }
 
+  /* Active item reads its own bg/fg tokens (defaults = the hover look) so a service can give the
+   * selected nav row a brand treatment — e.g. a gold tint + gold text on a navy sidebar — without
+   * forking CSS. Defaults are byte-identical to the hover state. */
   .sb-nav-item[data-active="true"] {
+    background: var(--sidebar-item-active-background, hsl(var(--accent)));
+    color: var(--sidebar-item-active-foreground, hsl(var(--foreground)));
     font-weight: var(--font-weight-medium);
   }
 
@@ -351,12 +362,12 @@
 
   .sb-nav-item--sub[data-active="true"] {
     background: transparent;
-    color: hsl(var(--primary));
+    color: var(--sidebar-item-active-color, hsl(var(--primary)));
     font-weight: 500;
   }
 
   .sb-nav-item--sub[data-active="true"]::before {
-    background: hsl(var(--primary));
+    background: var(--sidebar-item-active-tint, hsl(var(--primary)));
     opacity: 1;
   }
 
@@ -406,7 +417,7 @@
   }
 
   .sb-user:focus-visible {
-    box-shadow: 0 0 0 var(--control-focus-ring-width) hsl(var(--ring) / 0.45);
+    box-shadow: 0 0 0 var(--focus-ring-width) hsl(var(--focus-ring-color, var(--ring)) / 0.45);
   }
 
   .sb-user-avatar {
@@ -649,7 +660,7 @@
   }
 
   .tb-icon-btn:focus-visible {
-    box-shadow: 0 0 0 var(--control-focus-ring-width) hsl(var(--ring) / 0.45);
+    box-shadow: 0 0 0 var(--focus-ring-width) hsl(var(--focus-ring-color, var(--ring)) / 0.45);
   }
 
   .tb-bell {

package/dist/styles/table-layout.css

@@ -8,10 +8,10 @@
     padding: var(--table-cell-padding-y) var(--table-cell-space-x);
     text-align: start;
     vertical-align: middle;
-    background: hsl(var(--secondary));
+    background: var(--table-header-background, hsl(var(--muted)));
     font-size: var(--table-head-font-size);
     font-weight: var(--font-weight-medium);
-    color: hsl(var(--muted-foreground));
+    color: var(--table-header-foreground, hsl(var(--muted-foreground)));
     white-space: nowrap;
   }
 
@@ -97,7 +97,7 @@
   /* Zebra striping (opt-in via the `striped` prop). Selected rows keep their
    * own emphasis, so they are excluded from the stripe. */
   .ui-data-table-surface[data-striped] tbody tr:nth-child(even):not([data-state="selected"]) {
-    background-color: hsl(var(--muted) / 0.4);
+    background-color: var(--table-row-striped-background, hsl(var(--muted) / 0.4));
   }
 
   /* Empty-state cell hosts the built-in EmptyState (which brings its own padding). */
@@ -110,7 +110,7 @@
   }
 
   [data-slot="card-content"][data-flush] .ui-data-table-toolbar {
-    border-bottom: 1px solid hsl(var(--card-border));
+    border-bottom: 1px solid hsl(var(--card-border, var(--border)));
     padding: var(--card-space-header-y) var(--card-space-inset);
   }
 
@@ -195,10 +195,16 @@
   /* Mirror the row's hover / selected tint — a translucent muted wash layered
    * over the opaque base, so the pinned cell matches the rest of its row. */
   .ui-data-table-surface tbody tr:hover > .ui-data-table-pin-end {
-    background-image: linear-gradient(hsl(var(--muted) / 0.5), hsl(var(--muted) / 0.5));
+    background-image: linear-gradient(
+      var(--table-row-hover-background, hsl(var(--muted) / 0.5)),
+      var(--table-row-hover-background, hsl(var(--muted) / 0.5))
+    );
   }
 
   .ui-data-table-surface tbody tr[data-state="selected"] > .ui-data-table-pin-end {
-    background-image: linear-gradient(hsl(var(--muted) / 0.3), hsl(var(--muted) / 0.3));
+    background-image: linear-gradient(
+      var(--table-row-selected-background, hsl(var(--muted) / 0.3)),
+      var(--table-row-selected-background, hsl(var(--muted) / 0.3))
+    );
   }
 }

package/dist/tokens/components/card.css

@@ -24,15 +24,35 @@
   --card-title-font-weight: var(--font-weight-semibold);
   --card-description-font-size: var(--font-size-sm);
   --card-description-line-height: var(--line-height-normal);
-  --card-background: var(--card);
-  --card-border: var(--border);
-  --card-header-background: var(--muted);
+  /* Card fill + edge — opt-in knobs that DEFAULT to the live --card / --border roles. Declared
+   * `initial` (not `var(--card)`) so the default re-resolves at the call site under a scoped theme:
+   * a :root binding to a role var freezes at the :root value and a scoped `[data-tenant]` override of
+   * the role never reaches it (see docs/STANDARDS-vocabulary-tokens.md · "role-mirror knobs"). A
+   * service still overrides the knob directly (--card-background: …) to win over the role default. */
+  --card-background: initial; /* default = hsl(var(--card)) */
+  --card-border: initial; /* default = hsl(var(--border)) */
+  /* Banded-header fill — role-tintable (rule #45): a service points this at any role,
+   * e.g. --card-header-background: var(--primary), and tunes --card-header-background-alpha for
+   * the wash strength. Default = the live --muted role (resolved at the call site). */
+  --card-header-background: initial; /* default = hsl(var(--muted)) */
   --card-header-background-alpha: 0.55;
   /* Banded-header divider — tokenised (rule #44) so a service theme can make it
    * dashed / heavier / none without forking CSS. Pair with
-   * --card-header-background-alpha: 0 for a quiet borderless-band header. */
-  --card-header-border-bottom: 1px solid hsl(var(--card-border));
+   * --card-header-background-alpha: 0 for a quiet borderless-band header.
+   * Default = 1px solid hsl(var(--card-border)) (resolved at the call site). */
+  --card-header-border-bottom: initial;
   --card-radius: var(--radius);
+  /* Resting elevation — quiet by default (rule #44): cards are flat (1px border, no shadow) in the
+   * dxs-kintai baseline. A service that wants lifted cards sets this to an elevation token once,
+   * e.g. --card-shadow: var(--shadow-sm), and every Card picks up the shadow with no markup change. */
+  --card-shadow: 0 0 0 0 transparent;
+  /* Brand glow layer — invisible no-op at rest (rule #44). Paired AFTER --card-shadow in the
+   * surface box-shadow so a service can wash every card with the global glow, e.g.
+   * --card-glow: var(--shadow-glow), with no markup change. */
+  --card-glow: 0 0 0 0 transparent;
+  /* Fill tint — subtle role wash over the card background (default transparent = invisible).
+   * Painted as an overlay so a service sets --card-tint: hsl(var(--primary) / 0.04) once. */
+  --card-tint: transparent;
   /* Accent edge — width of the semantic leading-edge stripe (data-accent).
    * Tokenised (rule #44) so a service theme can re-tune it without forking CSS.
    * The slot padding compensation in card-layout.css subtracts the same token,
@@ -47,5 +67,13 @@
   --stat-card-hint-font-size: var(--font-size-xs);
   --stat-card-gap: var(--space-stack-xs);
   --stat-card-icon-size: 2.25rem;
+  --stat-card-icon-glyph-size: 1.25rem;
+  --stat-card-icon-radius: var(--radius-md);
+  /* Medallion tint — soft brand wash + brand glyph by default; a service retints by overriding
+   * --primary or these tokens directly (rule #44/#45). `initial` so the --primary default
+   * re-resolves at the call site under a scoped theme (no :root freeze).
+   * Defaults = hsl(var(--primary) / 0.1) fill · hsl(var(--primary)) glyph. */
+  --stat-card-icon-background: initial;
+  --stat-card-icon-foreground: initial;
   --stat-card-delta-font-size: var(--font-size-xs);
 }

package/dist/tokens/components/control.css

@@ -20,7 +20,7 @@
   --control-radius: var(--radius);
   --control-icon-size: calc(1rem * var(--scaling));
   --control-icon-size-sm: calc(0.875rem * var(--scaling));
-  --control-focus-ring-width: 2px;
+  --control-focus-ring-width: var(--focus-ring-width);
 
   --checkbox-size: calc(1rem * var(--scaling));
   --checkbox-size-compact: 0.875rem;
@@ -47,6 +47,16 @@
   --slider-track-height: 0.375rem;
   --slider-thumb-size: 1rem;
 
+  /* Checked/on/active fills — `initial` so the --primary default re-resolves at the call site
+   * under a scoped theme (a :root binding to var(--primary) freezes at the :root value and a scoped
+   * [data-tenant] override of --primary never reaches it). A service retints the "selected" state
+   * by overriding these directly. Defaults = hsl(var(--primary)) · slider track 0.2α. */
+  --checkbox-checked-background: initial;
+  --switch-checked-background: initial;
+  --toggle-on-background: initial;
+  --slider-track-background: initial;
+  --slider-range-background: initial;
+
   --color-picker-input-width: 6.5rem;
 
   --command-list-max-height: min(300px, 50vh);

package/dist/tokens/components/data-display.css

@@ -5,4 +5,30 @@
   --tree-item-title-font-size: var(--font-size-xs);
   --tree-item-description-font-size: var(--font-size-xs);
   --timeline-note-font-size: var(--font-size-xs);
+
+  /* Avatar surface — `initial` so the --muted default re-resolves at the call site under a scoped
+     theme (a :root binding to a role var freezes at :root; a scoped role override never reaches it).
+     A service re-tints the placeholder fill once (e.g. --avatar-background: hsl(var(--accent))).
+     Default = hsl(var(--muted)). */
+  --avatar-background: initial;
+  /* Optional role wash over the avatar (default transparent = invisible, rule #44).
+     Painted as an overlay so a service sets --avatar-tint: hsl(var(--primary) / 0.08). */
+  --avatar-tint: transparent;
+
+  /* Progress track + fill — `initial` so the role defaults re-resolve under a scoped theme.
+     Track reads --secondary, fill reads --success; a service re-tones once.
+     Defaults = hsl(var(--secondary)) track · hsl(var(--success)) fill. */
+  --progress-track-background: initial;
+  --progress-fill-background: initial;
+
+  /* Timeline accents — `initial` so the dot/line role defaults re-resolve under a scoped theme.
+     Defaults = hsl(var(--success)) done · hsl(var(--primary)) current/line. */
+  --timeline-dot-done-background: initial;
+  --timeline-dot-current-background: initial;
+  --timeline-line-completed-background: initial;
+
+  /* Tree active item — border + soft bg tint over the --primary role. `initial` so the default
+     re-resolves under a scoped theme. Defaults = hsl(var(--primary) / 0.3) border · 0.05 fill. */
+  --tree-item-active-border: initial;
+  --tree-item-active-background: initial;
 }

package/dist/tokens/components/feedback.css

@@ -16,10 +16,24 @@
    * (a brand's success-bg/-border are often more present than the faint 5%/30% default). */
   --alert-bg-alpha: 0.05;
   --alert-border-alpha: 0.3;
+  /* Brand glow layer for the raised dialog/sheet panel — invisible no-op at rest (rule #44).
+   * Paired AFTER --shadow-lg in the surface box-shadow so a service can wash the overlay with the
+   * global glow, e.g. --dialog-content-glow: var(--shadow-glow), with no markup change. */
+  --dialog-content-glow: 0 0 0 0 transparent;
   --empty-state-space-y: var(--space-10);
   --empty-state-space-x: var(--space-6);
+  /* EmptyState icon medallion colour — `initial` so the role defaults re-resolve at the call site
+   * under a scoped theme (rule #44). A service recolours the glyph (--empty-state-icon-foreground)
+   * or washes the medallion fill (--empty-state-icon-tint) without forking.
+   * Defaults = hsl(var(--muted-foreground)) glyph · hsl(var(--muted)) fill. */
+  --empty-state-icon-foreground: initial;
+  --empty-state-icon-tint: initial;
   --skeleton-row-gap: var(--space-stack-sm);
   --skeleton-cell-gap: var(--space-inline-lg);
   --skeleton-card-inset: var(--space-section-active);
   --skeleton-radius: var(--radius);
+  /* Skeleton placeholder fill — `initial` so the --muted default re-resolves at the call site under
+   * a scoped theme (a :root binding to a role var freezes at :root). A service tints the shimmer to
+   * its surface (rule #44) without forking the keyframes. Default = hsl(var(--muted)). */
+  --skeleton-background: initial;
 }

package/dist/tokens/components/list-row.css

@@ -5,5 +5,7 @@
   --list-row-padding-y: var(--space-3);
   --list-row-padding-x: var(--space-4);
   --list-row-gap: var(--space-3);
-  --list-row-border: 1px solid hsl(var(--border));
+  /* Row divider — `initial` so the --border default re-resolves at the call site under a scoped
+   * theme (a :root binding to a role var freezes at :root). Default = 1px solid hsl(var(--border)). */
+  --list-row-border: initial;
 }

package/dist/tokens/components/navigation.css

@@ -12,4 +12,10 @@
   --filter-picker-width-md: 14rem;
   --breadcrumb-font-size: var(--font-size-xs);
   --menubar-shortcut-font-size: var(--font-size-xs);
+
+  /* Menu item hover/highlight tint — `initial` so the --accent default re-resolves at the call site
+   * under a scoped theme (a :root binding to a role var freezes at :root).
+   * Defaults = hsl(var(--accent)) fill · hsl(var(--accent-foreground)) text. */
+  --menubar-item-hover-background: initial;
+  --menubar-item-hover-foreground: initial;
 }

package/dist/tokens/components/shell.css

@@ -14,4 +14,22 @@
   --sidebar-logo-mark-font-size: var(--font-size-xs);
   --sidebar-avatar-font-size: var(--font-size-2xs);
   --sidebar-user-name-font-size: var(--font-size-xs);
+
+  /* Brand-chrome gradient hooks — opt-in, invisible by default. A service paints
+   * the sidebar/topbar surface by setting these to a gradient (no-op = none). */
+  --sidebar-gradient: none;
+  --topbar-gradient: none;
+
+  /* Sidebar active-item tint/marker — `initial` so the role defaults re-resolve at the call site
+   * under a scoped theme (a :root binding to a role var freezes at :root; a scoped role override
+   * never reaches it). A service re-tunes the active sub-item accent without forking CSS.
+   * Defaults = hsl(var(--primary)) marker/tint. */
+  --sidebar-item-active-color: initial;
+  --sidebar-item-active-tint: initial;
+  /* Main nav-item active row — defaults mirror the hover state (accent bg, foreground text); a
+   * service overrides these to brand the selected row (e.g. a gold tint + gold text on a navy
+   * sidebar). `initial` so the defaults re-resolve under a scoped theme.
+   * Defaults = hsl(var(--accent)) fill · hsl(var(--foreground)) text. */
+  --sidebar-item-active-background: initial;
+  --sidebar-item-active-foreground: initial;
 }

package/dist/tokens/components/table.css

@@ -8,6 +8,19 @@
   --table-cell-padding-y: var(--space-2);
   --table-cell-space-x: var(--control-padding-x);
   --table-head-font-size: var(--font-size-xs);
+  /* Header band — its OWN bg + fg knobs (decoupled from --secondary). Declared `initial` so the
+   * default re-resolves to the LIVE --muted / --muted-foreground roles at the call site: a :root
+   * binding to a role var freezes at the :root value and a scoped [data-tenant] role override never
+   * reaches it. A brand sets both header tokens together to keep band/text contrast.
+   * Defaults = hsl(var(--muted)) band · hsl(var(--muted-foreground)) text. */
+  --table-header-background: initial;
+  --table-header-foreground: initial;
   /* Inline-end shadow that lifts a pinned (sticky) action column off the body it scrolls over. */
   --table-pin-shadow: -6px 0 6px -5px hsl(var(--foreground) / 0.12);
+  /* Row-state tint washes — translucent muted over the opaque base. `initial` so the --muted
+   * default re-resolves under a scoped theme; a service retints by reading another role (e.g.
+   * --primary). Defaults = hsl(var(--muted) / 0.4 striped · 0.5 hover · 0.3 selected). */
+  --table-row-striped-background: initial;
+  --table-row-hover-background: initial;
+  --table-row-selected-background: initial;
 }

package/dist/tokens/foundation.css

@@ -37,6 +37,13 @@
   --text-disabled: 40 6% 68%; /* disabled control text */
   --text-link: 204 100% 39%; /* inline link — defaults to brand blue */
   --text-brand: 204 100% 39%; /* brand-colored text / numerals */
+  /* Status TEXT colours — darker than the fill roles so small coloured text (a StatCard delta, an
+   * outline status badge label) clears WCAG AA 4.5:1 on white. The fill roles (--success/--warning/
+   * --info) stay the brighter wa-iro for badges/bars; only TEXT reads these via text-*-strong. */
+  --text-success: 152 84% 22%; /* deep 若竹 — AA green text on white */
+  --text-warning: 36 100% 28%; /* dark 山吹 amber — yellow can never pass as text */
+  --text-info: 221 70% 38%; /* deep 群青 — AA blue text on white */
+  --text-error: 357 75% 38%; /* deep 茜 — AA red text on white */
 
   /* Interaction ramp — hover / active steps (services override to their own brand ramp). */
   --primary-hover: 204 100% 33%;
@@ -93,6 +100,35 @@
     0 20px 25px -5px rgb(var(--shadow-color) / 0.1), 0 8px 10px -6px rgb(var(--shadow-color) / 0.1);
   --shadow-2xl: 0 25px 50px -12px rgb(var(--shadow-color) / 0.25);
 
+  /* Brand GLOW — an opt-in coloured halo for the primary CTA (and any surface that opts in).
+   * Quiet by default (cardinal rule #44): a zero-size transparent shadow, which is invalid as a
+   * bare `none` inside a comma shadow list but valid as `0 0 0 0 transparent`. A service turns it
+   * on by overriding the whole value once, e.g. `--shadow-glow: 0 8px 20px hsl(var(--primary) / .32)`
+   * — the CTA then carries a brand glow with no component change. */
+  --shadow-glow: 0 0 0 0 transparent;
+
+  /* FOCUS RING — the two global knobs for the keyboard-focus affordance (WCAG 2.4.7 / 2.4.11).
+   * `--focus-ring-color` is the themeable hue (HSL components, defaults to --ring) and
+   * `--focus-ring-width` the standard thickness; override either ONCE — even scoped under a
+   * `[data-tenant]` — to retint or resize EVERY focus ring. `--focus-ring-color` is declared
+   * `initial` (NOT `var(--ring)`): a :root binding to a role var would freeze at the :root --ring
+   * and a scoped [data-tenant] override of --ring alone would never reach it. Every :focus-visible
+   * rule reads it with the live-role fallback `hsl(var(--focus-ring-color, var(--ring)))`, so the
+   * default re-resolves at the element that paints the ring while an explicit override still wins. */
+  --focus-ring-color: initial; /* default = the live --ring role */
+  --focus-ring-width: 2px;
+
+  /* GRADIENTS — opt-in decorative fills exposed at the token layer so a service can paint a hero
+   * banner, a brand wash, or a radial brand glow purely by configuring tokens (cardinal rule #45).
+   * All default to a transparent no-op so nothing renders until a theme opts in; a surface that
+   * supports a gradient reads one of these as its background-image. Examples a service might set:
+   *   --gradient-brand: linear-gradient(135deg, hsl(var(--primary)), hsl(var(--accent)));
+   *   --gradient-hero:  linear-gradient(180deg, hsl(var(--secondary)), hsl(var(--background)));
+   *   --gradient-glow:  radial-gradient(60% 80% at 50% 0%, hsl(var(--primary) / .25), transparent); */
+  --gradient-brand: none;
+  --gradient-hero: none;
+  --gradient-glow: none;
+
   /* Sans stack — script-aware per the international convention for mixed
    * Latin/CJK UI: native Latin system fonts FIRST (clean, familiar English &
    * DEFAULT face is the bundled "Noto Sans JP" (Japanese + clean Latin), with system sans as
@@ -103,6 +139,12 @@
     "Noto Sans JP", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial,
     system-ui, "Hiragino Sans", sans-serif;
   --font-family-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  /* Dual-font split (opt-in) — many brand designs pair a DISPLAY face for headings with a separate
+   * BODY face (e.g. Source Sans 3 display + Inter body). Both default to --font-family-sans, so a
+   * single-font system is unchanged; a service overrides one or both. Headings read
+   * --font-family-display, body reads --font-family-body (wired in styles/index.css @layer base). */
+  --font-family-display: var(--font-family-sans);
+  --font-family-body: var(--font-family-sans);
   /* ── Type scale — GOLDEN-RATIO modular scale (Ant/Tailwind model). ONE base + ONE ratio; every
    * step is base × ratioⁿ, so the whole scale stays in golden proportion. `--font-size-ratio` is
    * φ^¼ (the golden ratio's quarter-step ≈ 1.1227) — a TRUE golden ratio yet dense enough that
@@ -122,6 +164,19 @@
   --font-size-xl: calc(var(--font-size-lg) * var(--font-size-ratio)); /* ratio³ ≈ 19.8px */
   --font-size-2xl: calc(var(--font-size-xl) * var(--font-size-ratio)); /* ratio⁴ ≈ 22.3px */
 
+  /* DISPLAY type — OPT-IN large sizes for MARKETING / hero surfaces (landing pages, CTA banners).
+   * The enterprise heading scale stays small by design (h1 = 20px, 渋み restraint); these are a
+   * SEPARATE bolder ramp a marketing surface opts into via the text-3xl/-4xl/-5xl utilities (wired
+   * in styles/index.css @theme). A service rescales the whole display ramp from --font-size-display
+   * (its own base). Nothing in the admin system uses them, so defaults are unchanged. */
+  --font-size-display: 3.375rem; /* 54px — hero display (the single display knob) */
+  --font-size-display-ratio: 1.28; /* bolder step than the body φ^¼ — marketing wants more contrast */
+  --font-size-3xl: calc(
+    var(--font-size-display) / var(--font-size-display-ratio) / var(--font-size-display-ratio)
+  ); /* ≈ 33 → 28px feature heading */
+  --font-size-4xl: calc(var(--font-size-display) / var(--font-size-display-ratio)); /* ≈ 36px section */
+  --font-size-5xl: var(--font-size-display); /* 54px hero */
+
   /* Headings — also golden-derived. h1=ratio³, h2=ratio²; h3/h4 reuse body sizes (single source). */
   --heading-h1: calc(
     var(--font-size-base) * var(--font-size-ratio) * var(--font-size-ratio) * var(--font-size-ratio)
@@ -139,6 +194,10 @@
    * so any remaining reference renders at 500. `bold` is the 700 emphasis weight. */
   --font-weight-semibold: 500;
   --font-weight-bold: 700;
+  /* Display/black weight — OPT-IN for marketing display type (hero/CTA). The enterprise system caps
+   * at 700 (簡素 restraint); this is only reached via the .font-display-weight utility / a service
+   * setting it on a display surface, so admin text is unchanged. */
+  --font-weight-black: 800;
   --line-height-tight: 1.25;
   --line-height-normal: 1.5;
   --line-height-body: 1.7;
@@ -285,6 +344,11 @@
   --text-disabled: 45 6% 40%;
   --text-link: 204 90% 66%;
   --text-brand: 204 90% 66%;
+  /* Status text on the dark spine reads LIGHT (AA on dark surfaces). */
+  --text-success: 146 55% 64%;
+  --text-warning: 44 95% 62%;
+  --text-info: 221 70% 72%;
+  --text-error: 357 75% 68%;
   --primary-hover: 204 90% 66%;
   --primary-active: 204 90% 72%;
   --secondary-hover: 45 6% 22%;

package/dist/tokens/semantic/layout.css

@@ -22,6 +22,11 @@
   --space-page-active-y: var(--space-page-y);
   --space-section-active: var(--space-section);
 
+  /* Modal scrim — the single backdrop colour shared by EVERY overlay (Dialog, AlertDialog, Sheet,
+   * Drawer). Themeable (rule #44) so a service tints the wash to its brand once, e.g. a navy
+   * `--overlay-background: rgb(12 26 49 / .55)`, instead of forking each overlay. */
+  --overlay-background: rgb(0 0 0 / 0.5);
+
   /* Full-bleed rule under the PageContainer header. OFF by default — the title/body
    * gap already separates them; a divider is a service-theme opt-in:
    * `--page-header-divider: 1px solid hsl(var(--border));` */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@godxjp/ui",
-  "version": "16.4.0",
+  "version": "16.6.0",
   "type": "module",
   "packageManager": "pnpm@10.29.1",
   "sideEffects": false,
@@ -275,7 +275,7 @@
     "test:coverage": "vitest run --coverage",
     "check:example-imports": "node scripts/check-example-imports.mjs",
     "verify": "pnpm typecheck && pnpm lint && pnpm format && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-token-sync && pnpm check:mcp-sync && pnpm check:mcp-orphans && pnpm check:audit-sync && pnpm test",
-    "verify:release": "pnpm typecheck && pnpm typecheck:docs && pnpm lint && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-token-sync && pnpm check:mcp-sync && pnpm check:mcp-orphans && pnpm check:audit-sync && pnpm check:mcp-prop-sync && pnpm test",
+    "verify:release": "pnpm typecheck && pnpm typecheck:docs && pnpm lint && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-token-sync && pnpm check:mcp-sync && pnpm check:mcp-orphans && pnpm check:audit-sync && pnpm check:mcp-prop-sync && pnpm check:contrast && pnpm test",
     "check:mcp-sync": "node scripts/check-mcp-sync.mjs",
     "check:mcp-orphans": "node scripts/check-mcp-orphans.mjs",
     "check:mcp-prop-sync": "node scripts/check-mcp-prop-sync.mjs",
@@ -297,6 +297,7 @@
     "dev": "node scripts/dev.mjs",
     "prepublishOnly": "pnpm run build",
     "check:audit-sync": "node scripts/check-audit-sync.mjs",
+    "check:contrast": "node scripts/check-contrast.mjs",
     "visual-audit": "node scripts/visual-audit.mjs",
     "postinstall": "node scripts/postinstall.mjs",
     "init-agent": "node scripts/init-agent-kit.mjs"