From 770a30d7b8d0c802a67ea8c5bcc880744b8a442b Mon Sep 17 00:00:00 2001
From: Gerard Kavanagh <gerard161@gmail.com>
Date: Mon, 7 Sep 2026 14:45:11 +0100
Subject: [PATCH 1/2] fix(theme): complete the tenant token contract with a
 legibility floor

Tenants set eight colours but the provider mapped only five shadcn tokens,
leaving card, popover, muted, border, input, ring and every *-foreground at
the light root defaults. Dark palettes rendered white text on white cards
(LekkerWeed dashboard/orders) and pages that hardcoded grey text only worked
because cards happened to be white.

- lib/theme/tenant-tokens.ts derives the full token set from the palette,
  fills unset colours, computes button foregrounds by luminance and swaps
  any foreground below 3:1 for black or white. Unit-tested against the
  LekkerWeed, HealingBuds and white-on-white palettes.
- Provider computes the variables in render and inlines them on the
  container, so they are server-rendered (no first-paint flash) and the
  editor preview matches live.
- Nav, footer and section colour overrides (store layout + template
  renderer) go through the same check, re-validating inherited text when a
  section changes its background.
- Input, Textarea, Select, Dialog and Sheet carry text-foreground.
- Consultation steps, ID upload, settings, order detail, register, login and
  how-it-works use semantic tokens instead of text-gray-*/bg-white.
- Branding form warns below 4.5:1 and says when the storefront will
  substitute.
---
 .../how-it-works/how-it-works-client.tsx      |   4 +-
 nextjs_space/app/store/[slug]/layout.tsx      |  36 ++-
 .../app/store/[slug]/login/login-form.tsx     |   2 +-
 .../store/[slug]/orders/[orderId]/page.tsx    |  10 +-
 .../app/store/[slug]/register/page.tsx        |   4 +-
 .../app/store/[slug]/settings/page.tsx        |  56 ++--
 .../branding/tabs/colours-tab.tsx             |  17 ++
 .../branding/tabs/contrast-hint.tsx           |  87 ++++++
 .../branding/tabs/section-colour-panel.tsx    |   2 +
 .../consultation/consultation-form.tsx        |   4 +-
 .../consultation/id-upload-form.tsx           |   4 +-
 .../consultation/steps/address-step.tsx       |  10 +-
 .../consultation/steps/business-info-step.tsx |   4 +-
 .../steps/contact-details-step.tsx            |   8 +-
 .../consultation/steps/id-upload-step.tsx     |  10 +-
 .../steps/medical-conditions-step.tsx         |   4 +-
 .../steps/medical-history-part1-step.tsx      |  16 +-
 .../steps/medical-history-part2-step.tsx      |  16 +-
 .../steps/shipping-address-step.tsx           |   4 +-
 nextjs_space/components/template-renderer.tsx |  67 ++---
 .../components/tenant-theme-provider.tsx      | 210 +++----------
 nextjs_space/components/ui/dialog.tsx         |   2 +-
 nextjs_space/components/ui/input.tsx          |   2 +-
 nextjs_space/components/ui/select.tsx         |   2 +-
 nextjs_space/components/ui/sheet.tsx          |   2 +-
 nextjs_space/components/ui/textarea.tsx       |   2 +-
 nextjs_space/lib/theme/tenant-tokens.ts       | 278 ++++++++++++++++++
 nextjs_space/tests/unit/tenant-tokens.test.ts | 190 ++++++++++++
 28 files changed, 740 insertions(+), 313 deletions(-)
 create mode 100644 nextjs_space/app/tenant-admin/branding/tabs/contrast-hint.tsx
 create mode 100644 nextjs_space/lib/theme/tenant-tokens.ts
 create mode 100644 nextjs_space/tests/unit/tenant-tokens.test.ts

diff --git a/nextjs_space/app/store/[slug]/how-it-works/how-it-works-client.tsx b/nextjs_space/app/store/[slug]/how-it-works/how-it-works-client.tsx
index 3a6a6e99..5feb4df1 100644
--- a/nextjs_space/app/store/[slug]/how-it-works/how-it-works-client.tsx
+++ b/nextjs_space/app/store/[slug]/how-it-works/how-it-works-client.tsx
@@ -30,8 +30,8 @@ export function HowItWorksClient() {
 
   if (loading) {
     return (
-      <div className="min-h-screen bg-white flex items-center justify-center">
-        <p className="text-lg text-gray-600">{t("common.loading")}</p>
+      <div className="min-h-screen bg-background flex items-center justify-center">
+        <p className="text-lg text-muted-foreground">{t("common.loading")}</p>
       </div>
     );
   }
diff --git a/nextjs_space/app/store/[slug]/layout.tsx b/nextjs_space/app/store/[slug]/layout.tsx
index 179b11a9..574a1845 100644
--- a/nextjs_space/app/store/[slug]/layout.tsx
+++ b/nextjs_space/app/store/[slug]/layout.tsx
@@ -20,7 +20,7 @@ import { AutomatosWidgetWrapper } from "@/components/admin/AutomatosWidgetWrappe
 import { Ga4Tag } from "@/components/seo/ga4-tag";
 import { parseTenantSettings } from "@/lib/tenant/tenant-settings";
 import { sanitizeCss, extractGoogleFontsImports } from "@/lib/security/css-utils";
-import { hexToHsl } from "@/lib/color-utils";
+import { buildColorOverrideVars } from "@/lib/theme/tenant-tokens";
 import type { Metadata } from "next";
 import {
   buildStoreMetadata,
@@ -263,20 +263,21 @@ async function renderTenantStore(
     pageContent: (activeTemplate?.pageContent as any) || defaults?.pageContent || {},
   };
 
+  // The palette the nav/footer override legibility check is made against —
+  // the same designSystem fallback order TenantThemeProvider uses.
+  const paletteBase = designSystem?.colors || settings.designSystem?.colors;
+
   // Render navigation
   const renderNavigation = () => {
     // Data-driven: use section component from layout.json
     if (layout?.navigation) {
       const NavComponent = getSectionComponent(layout.navigation);
       if (NavComponent) {
-        const navOverrides = layout.navigationConfig?.colorOverrides;
-        const navStyle: CSSProperties | undefined = navOverrides
-          ? (Object.fromEntries(
-              Object.entries(navOverrides)
-                .filter(([, v]) => v && typeof v === 'string' && v.trim())
-                .map(([k, v]) => [`--tenant-color-${k}`, (v as string).startsWith('#') ? hexToHsl(v as string) : v])
-            ) as CSSProperties)
-          : undefined;
+        // Legibility-checked against the tenant palette (lib/theme/tenant-tokens)
+        const navVars = buildColorOverrideVars(layout.navigationConfig?.colorOverrides, {
+          base: paletteBase,
+        });
+        const navStyle = Object.keys(navVars).length > 0 ? (navVars as CSSProperties) : undefined;
         return (
           <div style={navStyle}>
             <NavComponent {...sectionProps} sectionConfig={layout.navigationConfig} />
@@ -312,17 +313,14 @@ async function renderTenantStore(
       if (FooterComponent) {
         const isDarkFooter = layout.footer === 'FooterBrand' || layout.footer === 'FooterFull';
         const darkDefaults: Record<string, string> = isDarkFooter
-          ? { '--tenant-color-background': '220 15% 10%', '--tenant-color-text': '0 0% 100%', '--tenant-color-heading': '0 0% 100%', '--tenant-color-border': '0 0% 100%' }
-          : {};
-        const footerOverrides = layout.footerConfig?.colorOverrides;
-        const overrideEntries = footerOverrides
-          ? Object.fromEntries(
-              Object.entries(footerOverrides)
-                .filter(([, v]) => v && typeof v === 'string' && v.trim())
-                .map(([k, v]) => [`--tenant-color-${k}`, (v as string).startsWith('#') ? hexToHsl(v as string) : v])
-            )
+          ? { background: '220 15% 10%', text: '0 0% 100%', heading: '0 0% 100%', border: '0 0% 100%' }
           : {};
-        const footerStyle = { ...darkDefaults, ...overrideEntries } as CSSProperties;
+        // Overrides layer on the dark defaults; both are legibility-checked
+        // against the tenant palette (lib/theme/tenant-tokens).
+        const footerStyle = buildColorOverrideVars(layout.footerConfig?.colorOverrides, {
+          defaults: darkDefaults,
+          base: paletteBase,
+        }) as CSSProperties;
         return (
           <div style={Object.keys(footerStyle).length > 0 ? footerStyle : undefined}>
             <FooterComponent {...sectionProps} sectionConfig={layout.footerConfig} />
diff --git a/nextjs_space/app/store/[slug]/login/login-form.tsx b/nextjs_space/app/store/[slug]/login/login-form.tsx
index d1c4f651..982097e6 100644
--- a/nextjs_space/app/store/[slug]/login/login-form.tsx
+++ b/nextjs_space/app/store/[slug]/login/login-form.tsx
@@ -22,7 +22,7 @@ function LoginFormInner({ businessName, logoUrl, basePath }: TenantLoginFormProp
           />
         )}
         <h1 className="text-2xl font-bold mb-1">Sign in to {businessName}</h1>
-        <p className="text-gray-500 text-sm mb-6">Welcome back! Please sign in to continue</p>
+        <p className="text-muted-foreground text-sm mb-6">Welcome back! Please sign in to continue</p>
 
         <SignIn
           appearance={{
diff --git a/nextjs_space/app/store/[slug]/orders/[orderId]/page.tsx b/nextjs_space/app/store/[slug]/orders/[orderId]/page.tsx
index 8ceab198..49759b53 100644
--- a/nextjs_space/app/store/[slug]/orders/[orderId]/page.tsx
+++ b/nextjs_space/app/store/[slug]/orders/[orderId]/page.tsx
@@ -53,7 +53,7 @@ export default async function OrderConfirmationPage({
       case "CANCELLED":
         return <Package className="h-16 w-16 text-red-500" />;
       default:
-        return <Clock className="h-16 w-16 text-gray-400" />;
+        return <Clock className="h-16 w-16 text-muted-foreground" />;
     }
   };
 
@@ -91,8 +91,8 @@ export default async function OrderConfirmationPage({
         <CardContent className="flex flex-col items-center text-center py-12">
           {getStatusIcon(order.paymentStatus)}
           <h1 className="text-3xl font-bold mt-6 mb-2">{status.title}</h1>
-          <p className="text-gray-600 mb-4">{status.message}</p>
-          <p className="text-sm text-gray-500">
+          <p className="text-muted-foreground mb-4">{status.message}</p>
+          <p className="text-sm text-muted-foreground">
             Order Number:{" "}
             <span className="font-mono font-semibold">{order.drGreenInvoiceNum || order.orderNumber}</span>
           </p>
@@ -149,11 +149,11 @@ export default async function OrderConfirmationPage({
                 return (
                   <>
                     <div className="flex justify-between text-sm">
-                      <span className="text-gray-600">Subtotal</span>
+                      <span className="text-muted-foreground">Subtotal</span>
                       <span>{currency} {order.subtotal.toFixed(2)}</span>
                     </div>
                     <div className="flex justify-between text-sm">
-                      <span className="text-gray-600">Shipping</span>
+                      <span className="text-muted-foreground">Shipping</span>
                       <span>{currency} {order.shippingCost.toFixed(2)}</span>
                     </div>
                     <div className="flex justify-between text-lg font-bold border-t pt-2">
diff --git a/nextjs_space/app/store/[slug]/register/page.tsx b/nextjs_space/app/store/[slug]/register/page.tsx
index 658a7ee5..436e855d 100644
--- a/nextjs_space/app/store/[slug]/register/page.tsx
+++ b/nextjs_space/app/store/[slug]/register/page.tsx
@@ -24,10 +24,10 @@ export default function RegisterRedirectPage() {
   }, [slug, router]);
 
   return (
-    <div className="min-h-screen flex items-center justify-center bg-gray-50">
+    <div className="min-h-screen flex items-center justify-center bg-background">
       <div className="text-center">
         <Loader2 className="h-8 w-8 animate-spin text-green-600 mx-auto mb-4" />
-        <p className="text-gray-600">Redirecting to eligibility check...</p>
+        <p className="text-muted-foreground">Redirecting to eligibility check...</p>
       </div>
     </div>
   );
diff --git a/nextjs_space/app/store/[slug]/settings/page.tsx b/nextjs_space/app/store/[slug]/settings/page.tsx
index fe46d6a7..c37eacb1 100644
--- a/nextjs_space/app/store/[slug]/settings/page.tsx
+++ b/nextjs_space/app/store/[slug]/settings/page.tsx
@@ -98,7 +98,7 @@ export default function SettingsPage() {
       <div className="min-h-screen flex items-center justify-center">
         <div className="text-center">
           <div className="w-16 h-16 border-4 border-green-600 border-t-transparent rounded-full animate-spin mx-auto mb-4"></div>
-          <p className="text-gray-600">Loading...</p>
+          <p className="text-muted-foreground">Loading...</p>
         </div>
       </div>
     );
@@ -109,21 +109,20 @@ export default function SettingsPage() {
   }
 
   return (
-    <div className="min-h-screen saas-shell pt-24 pb-20">
+    <div className="min-h-screen bg-background pt-24 pb-20">
       <main className="max-w-4xl mx-auto px-4 sm:px-6 lg:px-8 py-12">
         {/* Header */}
         <div className="mb-8 flex items-center justify-between">
           <div>
-            <span className="saas-pill text-slate-600">Customer Dashboard</span>
-            <h1 className="mt-4 text-3xl font-semibold text-slate-900 mb-2">
+            <span className="inline-flex items-center rounded-full border border-border bg-card px-3 py-1 text-xs font-medium text-muted-foreground">Customer Dashboard</span>
+            <h1 className="mt-4 text-3xl font-semibold text-foreground mb-2">
               Account Settings
             </h1>
-            <p className="text-slate-500">Manage your account information</p>
+            <p className="text-muted-foreground">Manage your account information</p>
           </div>
           {!isEditing && (
             <Button
               onClick={() => setIsEditing(true)}
-              className="bg-slate-900 text-white hover:bg-slate-800"
             >
               Edit Profile
             </Button>
@@ -131,9 +130,9 @@ export default function SettingsPage() {
         </div>
 
         {/* Profile Information */}
-        <div className="saas-card border-0 p-6 mb-6">
-          <h2 className="text-xl font-semibold text-slate-900 mb-6 flex items-center gap-2">
-            <User className="w-5 h-5 text-slate-500" />
+        <div className="rounded-2xl border border-border bg-card p-6 mb-6 text-card-foreground shadow-sm">
+          <h2 className="text-xl font-semibold text-card-foreground mb-6 flex items-center gap-2">
+            <User className="w-5 h-5 text-muted-foreground" />
             Personal Information
           </h2>
 
@@ -151,7 +150,7 @@ export default function SettingsPage() {
                     className="mt-1"
                   />
                 ) : (
-                  <div className="px-4 py-2 bg-gray-50 border border-gray-200 rounded-lg mt-1">
+                  <div className="px-4 py-2 bg-muted border border-border rounded-lg mt-1">
                     {formData.firstName || "Not set"}
                   </div>
                 )}
@@ -169,7 +168,7 @@ export default function SettingsPage() {
                     className="mt-1"
                   />
                 ) : (
-                  <div className="px-4 py-2 bg-gray-50 border border-gray-200 rounded-lg mt-1">
+                  <div className="px-4 py-2 bg-muted border border-border rounded-lg mt-1">
                     {formData.lastName || "Not set"}
                   </div>
                 )}
@@ -179,11 +178,11 @@ export default function SettingsPage() {
             <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
               <div>
                 <Label htmlFor="email">Email Address</Label>
-                <div className="px-4 py-2 bg-gray-100 border border-gray-200 rounded-lg flex items-center gap-2 mt-1">
-                  <Mail className="w-4 h-4 text-gray-400" />
+                <div className="px-4 py-2 bg-muted border border-border rounded-lg flex items-center gap-2 mt-1">
+                  <Mail className="w-4 h-4 text-muted-foreground" />
                   {user.primaryEmailAddress?.emailAddress}
                 </div>
-                <p className="text-xs text-gray-500 mt-1">
+                <p className="text-xs text-muted-foreground mt-1">
                   Email cannot be changed
                 </p>
               </div>
@@ -192,7 +191,7 @@ export default function SettingsPage() {
                 <Label htmlFor="phone">Phone Number</Label>
                 {isEditing ? (
                   <div className="relative mt-1">
-                    <Phone className="absolute left-3 top-3 w-4 h-4 text-gray-400" />
+                    <Phone className="absolute left-3 top-3 w-4 h-4 text-muted-foreground" />
                     <Input
                       id="phone"
                       type="tel"
@@ -205,8 +204,8 @@ export default function SettingsPage() {
                     />
                   </div>
                 ) : (
-                  <div className="px-4 py-2 bg-gray-50 border border-gray-200 rounded-lg flex items-center gap-2 mt-1">
-                    <Phone className="w-4 h-4 text-gray-400" />
+                  <div className="px-4 py-2 bg-muted border border-border rounded-lg flex items-center gap-2 mt-1">
+                    <Phone className="w-4 h-4 text-muted-foreground" />
                     {formData.phone || "Not set"}
                   </div>
                 )}
@@ -216,8 +215,8 @@ export default function SettingsPage() {
             <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
               <div>
                 <Label>Account Role</Label>
-                <div className="px-4 py-2 bg-gray-50 border border-gray-200 rounded-lg flex items-center gap-2 mt-1">
-                  <Shield className="w-4 h-4 text-gray-400" />
+                <div className="px-4 py-2 bg-muted border border-border rounded-lg flex items-center gap-2 mt-1">
+                  <Shield className="w-4 h-4 text-muted-foreground" />
                   {(user.publicMetadata?.role as string) || "PATIENT"}
                 </div>
               </div>
@@ -247,9 +246,9 @@ export default function SettingsPage() {
         </div>
 
         {/* Address Information */}
-        <div className="saas-card border-0 p-6 mb-6">
-          <h2 className="text-xl font-semibold text-slate-900 mb-6 flex items-center gap-2">
-            <MapPin className="w-5 h-5 text-slate-500" />
+        <div className="rounded-2xl border border-border bg-card p-6 mb-6 text-card-foreground shadow-sm">
+          <h2 className="text-xl font-semibold text-card-foreground mb-6 flex items-center gap-2">
+            <MapPin className="w-5 h-5 text-muted-foreground" />
             Address
           </h2>
 
@@ -267,7 +266,7 @@ export default function SettingsPage() {
                   placeholder="Street address"
                 />
               ) : (
-                <div className="px-4 py-2 bg-gray-50 border border-gray-200 rounded-lg mt-1">
+                <div className="px-4 py-2 bg-muted border border-border rounded-lg mt-1">
                   {formData.addressLine1 || "Not set"}
                 </div>
               )}
@@ -286,7 +285,7 @@ export default function SettingsPage() {
                   placeholder="Apartment, suite, etc."
                 />
               ) : (
-                <div className="px-4 py-2 bg-gray-50 border border-gray-200 rounded-lg mt-1">
+                <div className="px-4 py-2 bg-muted border border-border rounded-lg mt-1">
                   {formData.addressLine2 || "Not set"}
                 </div>
               )}
@@ -305,7 +304,7 @@ export default function SettingsPage() {
                     className="mt-1"
                   />
                 ) : (
-                  <div className="px-4 py-2 bg-gray-50 border border-gray-200 rounded-lg mt-1">
+                  <div className="px-4 py-2 bg-muted border border-border rounded-lg mt-1">
                     {formData.city || "Not set"}
                   </div>
                 )}
@@ -323,7 +322,7 @@ export default function SettingsPage() {
                     className="mt-1"
                   />
                 ) : (
-                  <div className="px-4 py-2 bg-gray-50 border border-gray-200 rounded-lg mt-1">
+                  <div className="px-4 py-2 bg-muted border border-border rounded-lg mt-1">
                     {formData.state || "Not set"}
                   </div>
                 )}
@@ -341,7 +340,7 @@ export default function SettingsPage() {
                     className="mt-1"
                   />
                 ) : (
-                  <div className="px-4 py-2 bg-gray-50 border border-gray-200 rounded-lg mt-1">
+                  <div className="px-4 py-2 bg-muted border border-border rounded-lg mt-1">
                     {formData.postalCode || "Not set"}
                   </div>
                 )}
@@ -360,7 +359,7 @@ export default function SettingsPage() {
                   className="mt-1"
                 />
               ) : (
-                <div className="px-4 py-2 bg-gray-50 border border-gray-200 rounded-lg mt-1">
+                <div className="px-4 py-2 bg-muted border border-border rounded-lg mt-1">
                   {formData.country || "Not set"}
                 </div>
               )}
@@ -371,7 +370,6 @@ export default function SettingsPage() {
                 <Button
                   onClick={handleSave}
                   disabled={isSaving}
-                  className="bg-slate-900 text-white hover:bg-slate-800"
                 >
                   <Save className="w-4 h-4 mr-2" />
                   {isSaving ? "Saving..." : "Save Changes"}
diff --git a/nextjs_space/app/tenant-admin/branding/tabs/colours-tab.tsx b/nextjs_space/app/tenant-admin/branding/tabs/colours-tab.tsx
index 678d0215..8fbca6ce 100644
--- a/nextjs_space/app/tenant-admin/branding/tabs/colours-tab.tsx
+++ b/nextjs_space/app/tenant-admin/branding/tabs/colours-tab.tsx
@@ -8,6 +8,7 @@ import {
 } from "@/components/ui/accordion";
 import { X } from "lucide-react";
 import { ColorPicker } from "./shared";
+import { ContrastHint, overridePairs } from "./contrast-hint";
 import type { EditorFormData, SetFormData } from "./types";
 
 const sectionTitleStyle = {
@@ -139,6 +140,20 @@ export function ColoursTab({
             onChange={(v) => setGlobalColor("textColor", v)}
           />
         </div>
+        <ContrastHint
+          pairs={[
+            {
+              label: "Body text on page background",
+              foreground: formData.textColor,
+              background: formData.backgroundColor,
+            },
+            {
+              label: "Heading text on page background",
+              foreground: formData.headingColor,
+              background: formData.backgroundColor,
+            },
+          ]}
+        />
       </section>
 
       {/* Navigation & Footer Color Overrides */}
@@ -214,6 +229,7 @@ export function ColoursTab({
                       </div>
                     ))}
                   </div>
+                  <ContrastHint pairs={overridePairs(formData.navColorOverrides, formData, "Navigation")} />
                 </div>
               </AccordionContent>
             </AccordionItem>
@@ -278,6 +294,7 @@ export function ColoursTab({
                       </div>
                     ))}
                   </div>
+                  <ContrastHint pairs={overridePairs(formData.footerColorOverrides, formData, "Footer")} />
                 </div>
               </AccordionContent>
             </AccordionItem>
diff --git a/nextjs_space/app/tenant-admin/branding/tabs/contrast-hint.tsx b/nextjs_space/app/tenant-admin/branding/tabs/contrast-hint.tsx
new file mode 100644
index 00000000..647d2ffc
--- /dev/null
+++ b/nextjs_space/app/tenant-admin/branding/tabs/contrast-hint.tsx
@@ -0,0 +1,87 @@
+"use client";
+
+import { AlertTriangle } from "lucide-react";
+import {
+  MIN_CONTRAST,
+  WARN_CONTRAST,
+  contrastRatio,
+  toHslChannels,
+} from "@/lib/theme/tenant-tokens";
+
+export interface ContrastPair {
+  label: string;
+  foreground?: string | null;
+  background?: string | null;
+}
+
+interface ContrastWarning {
+  label: string;
+  ratio: number;
+  substituted: boolean;
+}
+
+/**
+ * The pairs that fall below the readability guideline, and whether the
+ * storefront will substitute black or white for them (the legibility floor in
+ * lib/theme/tenant-tokens). Pairs with an unparseable colour are skipped.
+ */
+export function contrastWarnings(pairs: ContrastPair[]): ContrastWarning[] {
+  return pairs.flatMap(({ label, foreground, background }) => {
+    const fg = toHslChannels(foreground);
+    const bg = toHslChannels(background);
+    if (!fg || !bg) return [];
+    const ratio = contrastRatio(fg, bg);
+    return ratio < WARN_CONTRAST
+      ? [{ label, ratio, substituted: ratio < MIN_CONTRAST }]
+      : [];
+  });
+}
+
+/**
+ * The text-on-background pairs a nav, footer or section override changes.
+ * Colours the override leaves unset inherit from the brand palette, exactly as
+ * the storefront resolves them. Overrides that touch none of the three colours
+ * produce no pairs, so the brand-level warning is not repeated.
+ */
+export function overridePairs(
+  overrides: Record<string, string> | undefined,
+  base: { textColor: string; headingColor: string; backgroundColor: string },
+  scope: string,
+): ContrastPair[] {
+  if (!overrides) return [];
+  const touched = ["background", "text", "heading"].some((key) => overrides[key]);
+  if (!touched) return [];
+  const background = overrides.background || base.backgroundColor;
+  return [
+    {
+      label: `${scope} body text on its background`,
+      foreground: overrides.text || base.textColor,
+      background,
+    },
+    {
+      label: `${scope} heading text on its background`,
+      foreground: overrides.heading || base.headingColor,
+      background,
+    },
+  ];
+}
+
+export function ContrastHint({ pairs }: { pairs: ContrastPair[] }) {
+  const warnings = contrastWarnings(pairs);
+  if (warnings.length === 0) return null;
+  return (
+    <ul className="space-y-1.5 text-xs text-bs-warn" role="status">
+      {warnings.map((warning) => (
+        <li key={warning.label} className="flex items-start gap-1.5">
+          <AlertTriangle className="mt-0.5 h-3.5 w-3.5 shrink-0" aria-hidden="true" />
+          <span>
+            {warning.label}: {warning.ratio.toFixed(1)}:1, below the {WARN_CONTRAST}:1
+            readability guideline.
+            {warning.substituted &&
+              " The storefront will show this text in black or white until it is fixed."}
+          </span>
+        </li>
+      ))}
+    </ul>
+  );
+}
diff --git a/nextjs_space/app/tenant-admin/branding/tabs/section-colour-panel.tsx b/nextjs_space/app/tenant-admin/branding/tabs/section-colour-panel.tsx
index 49fa3a68..d296aefc 100644
--- a/nextjs_space/app/tenant-admin/branding/tabs/section-colour-panel.tsx
+++ b/nextjs_space/app/tenant-admin/branding/tabs/section-colour-panel.tsx
@@ -2,6 +2,7 @@
 
 import { X } from "lucide-react";
 import { ColorPicker } from "./shared";
+import { ContrastHint, overridePairs } from "./contrast-hint";
 import type { EditorFormData, SetFormData } from "./types";
 
 /** Colour override groups — shared with ColoursTab global palette. Kept here
@@ -134,6 +135,7 @@ export function SectionColourPanel({
           </div>
         ))}
       </div>
+      <ContrastHint pairs={overridePairs(overrides, formData, "Section")} />
     </div>
   );
 }
diff --git a/nextjs_space/components/consultation/consultation-form.tsx b/nextjs_space/components/consultation/consultation-form.tsx
index a3542813..86114b54 100644
--- a/nextjs_space/components/consultation/consultation-form.tsx
+++ b/nextjs_space/components/consultation/consultation-form.tsx
@@ -213,10 +213,10 @@ export function ConsultationForm({
           {/* Progress Bar */}
           <div className="mb-8">
             <div className="flex justify-between mb-2">
-              <span className="text-sm font-medium text-gray-700">
+              <span className="text-sm font-medium text-card-foreground">
                 Step {currentStep} of {TOTAL_STEPS}
               </span>
-              <span className="text-sm font-medium text-gray-700">
+              <span className="text-sm font-medium text-card-foreground">
                 {STEP_NAMES[currentStep - 1]}
               </span>
             </div>
diff --git a/nextjs_space/components/consultation/id-upload-form.tsx b/nextjs_space/components/consultation/id-upload-form.tsx
index 16d74be6..b4361fac 100644
--- a/nextjs_space/components/consultation/id-upload-form.tsx
+++ b/nextjs_space/components/consultation/id-upload-form.tsx
@@ -211,10 +211,10 @@ export function IdUploadForm({ tenantSlug }: IdUploadFormProps) {
           {/* Progress Bar */}
           <div className="mb-8">
             <div className="flex justify-between mb-2">
-              <span className="text-sm font-medium text-gray-700">
+              <span className="text-sm font-medium text-card-foreground">
                 Step {currentStep} of {TOTAL_STEPS}
               </span>
-              <span className="text-sm font-medium text-gray-700">
+              <span className="text-sm font-medium text-card-foreground">
                 {STEP_NAMES[currentStep - 1]}
               </span>
             </div>
diff --git a/nextjs_space/components/consultation/steps/address-step.tsx b/nextjs_space/components/consultation/steps/address-step.tsx
index 2ac8c3b8..438f10b2 100644
--- a/nextjs_space/components/consultation/steps/address-step.tsx
+++ b/nextjs_space/components/consultation/steps/address-step.tsx
@@ -56,10 +56,10 @@ export function AddressStep({
       {/* Shipping Address Section */}
       <div className="space-y-6">
         <div>
-          <h2 className="text-2xl font-bold text-gray-900 mb-2">
+          <h2 className="text-2xl font-bold text-card-foreground mb-2">
             Shipping Address
           </h2>
-          <p className="text-gray-600">Where should we deliver your order?</p>
+          <p className="text-muted-foreground">Where should we deliver your order?</p>
         </div>
 
         <div>
@@ -158,15 +158,15 @@ export function AddressStep({
       </div>
 
       {/* Divider */}
-      <div className="border-t border-gray-200 my-8"></div>
+      <div className="border-t border-border my-8"></div>
 
       {/* Business Address Section */}
       <div className="space-y-6">
         <div>
-          <h2 className="text-2xl font-bold text-gray-900 mb-2">
+          <h2 className="text-2xl font-bold text-card-foreground mb-2">
             Business Information
           </h2>
-          <p className="text-gray-600">
+          <p className="text-muted-foreground">
             Optional - Only complete if ordering for a business
           </p>
         </div>
diff --git a/nextjs_space/components/consultation/steps/business-info-step.tsx b/nextjs_space/components/consultation/steps/business-info-step.tsx
index c54873bd..99817d95 100644
--- a/nextjs_space/components/consultation/steps/business-info-step.tsx
+++ b/nextjs_space/components/consultation/steps/business-info-step.tsx
@@ -34,10 +34,10 @@ export function BusinessInfoStep({
   return (
     <form onSubmit={handleSubmit} className="space-y-6">
       <div>
-        <h2 className="text-2xl font-bold text-gray-900 mb-2">
+        <h2 className="text-2xl font-bold text-card-foreground mb-2">
           Type of Business
         </h2>
-        <p className="text-gray-600">
+        <p className="text-muted-foreground">
           Optional - Only complete if ordering for a business
         </p>
       </div>
diff --git a/nextjs_space/components/consultation/steps/contact-details-step.tsx b/nextjs_space/components/consultation/steps/contact-details-step.tsx
index e7fc5e2e..eb849d5d 100644
--- a/nextjs_space/components/consultation/steps/contact-details-step.tsx
+++ b/nextjs_space/components/consultation/steps/contact-details-step.tsx
@@ -72,10 +72,10 @@ export function ContactDetailsStep({
   return (
     <form onSubmit={handleSubmit} className="space-y-6">
       <div>
-        <h2 className="text-2xl font-bold text-gray-900 mb-2">
+        <h2 className="text-2xl font-bold text-card-foreground mb-2">
           Contact Details
         </h2>
-        <p className="text-gray-600">
+        <p className="text-muted-foreground">
           Please provide your personal information
         </p>
       </div>
@@ -304,7 +304,7 @@ export function ContactDetailsStep({
           <button
             type="button"
             onClick={() => setShowPassword(!showPassword)}
-            className="absolute right-3 top-1/2 -translate-y-1/2 text-gray-500 hover:text-gray-700"
+            className="absolute right-3 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-card-foreground"
           >
             {showPassword ? <EyeOff size={16} /> : <Eye size={16} />}
           </button>
@@ -327,7 +327,7 @@ export function ContactDetailsStep({
           <button
             type="button"
             onClick={() => setShowConfirmPassword(!showConfirmPassword)}
-            className="absolute right-3 top-1/2 -translate-y-1/2 text-gray-500 hover:text-gray-700"
+            className="absolute right-3 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-card-foreground"
           >
             {showConfirmPassword ? <EyeOff size={16} /> : <Eye size={16} />}
           </button>
diff --git a/nextjs_space/components/consultation/steps/id-upload-step.tsx b/nextjs_space/components/consultation/steps/id-upload-step.tsx
index 8aee35eb..67a85ddb 100644
--- a/nextjs_space/components/consultation/steps/id-upload-step.tsx
+++ b/nextjs_space/components/consultation/steps/id-upload-step.tsx
@@ -66,10 +66,10 @@ export function IdUploadStep({
   return (
     <div className="space-y-6">
       <div>
-        <h2 className="text-2xl font-bold text-gray-900 mb-2">
+        <h2 className="text-2xl font-bold text-card-foreground mb-2">
           Verify your identity
         </h2>
-        <p className="text-gray-600">
+        <p className="text-muted-foreground">
           Upload a clear photo of a <strong>valid government ID</strong> (National
           ID, passport or driving licence). It must be your actual ID
           document&nbsp;— <strong>selfies or other photos will be rejected</strong>.
@@ -110,16 +110,16 @@ export function IdUploadStep({
         <button
           type="button"
           onClick={() => inputRef.current?.click()}
-          className="w-full rounded-lg border-2 border-dashed border-gray-300 bg-gray-50 px-4 py-8 text-center transition-colors hover:border-emerald-400 hover:bg-emerald-50"
+          className="w-full rounded-lg border-2 border-dashed border-border bg-muted px-4 py-8 text-center transition-colors hover:border-emerald-400 hover:bg-emerald-50"
         >
           {file ? (
             <span className="flex flex-col items-center gap-2 text-emerald-700">
               <FileCheck2 className="h-8 w-8" />
               <span className="font-medium">{file.name}</span>
-              <span className="text-xs text-gray-500">Tap to replace</span>
+              <span className="text-xs text-muted-foreground">Tap to replace</span>
             </span>
           ) : (
-            <span className="flex flex-col items-center gap-2 text-gray-500">
+            <span className="flex flex-col items-center gap-2 text-muted-foreground">
               <UploadCloud className="h-8 w-8" />
               <span className="font-medium">Tap to upload your ID</span>
               <span className="text-xs">JPG, PNG or PDF · up to 10 MB</span>
diff --git a/nextjs_space/components/consultation/steps/medical-conditions-step.tsx b/nextjs_space/components/consultation/steps/medical-conditions-step.tsx
index 9bb63cbc..4e055b22 100644
--- a/nextjs_space/components/consultation/steps/medical-conditions-step.tsx
+++ b/nextjs_space/components/consultation/steps/medical-conditions-step.tsx
@@ -60,10 +60,10 @@ export function MedicalConditionsStep({
   return (
     <form onSubmit={handleSubmit} className="space-y-6">
       <div>
-        <h2 className="text-2xl font-bold text-gray-900 mb-2">
+        <h2 className="text-2xl font-bold text-card-foreground mb-2">
           Medical Conditions
         </h2>
-        <p className="text-gray-600">Please tick all that apply</p>
+        <p className="text-muted-foreground">Please tick all that apply</p>
       </div>
 
       <div>
diff --git a/nextjs_space/components/consultation/steps/medical-history-part1-step.tsx b/nextjs_space/components/consultation/steps/medical-history-part1-step.tsx
index d4ad45ce..d9f38a57 100644
--- a/nextjs_space/components/consultation/steps/medical-history-part1-step.tsx
+++ b/nextjs_space/components/consultation/steps/medical-history-part1-step.tsx
@@ -26,19 +26,19 @@ export function MedicalHistoryPart1Step({
   return (
     <form onSubmit={handleSubmit} className="space-y-6">
       <div>
-        <h2 className="text-2xl font-bold text-gray-900 mb-2">
+        <h2 className="text-2xl font-bold text-card-foreground mb-2">
           Medical History (Part One)
         </h2>
-        <p className="text-gray-600">Please answer the following questions</p>
+        <p className="text-muted-foreground">Please answer the following questions</p>
       </div>
 
       <div className="space-y-6">
         {/* Heart Problems */}
-        <div className="border rounded-lg p-4 bg-gray-50">
+        <div className="border rounded-lg p-4 bg-muted">
           <Label className="text-base font-semibold mb-3 block">
             Do you have a history of heart problems?*
           </Label>
-          <p className="text-sm text-gray-600 mb-3">
+          <p className="text-sm text-muted-foreground mb-3">
             Including palpitations, heart attack (MI), stroke, angina, chest
             pain, shortness of breath, arrhythmias (funny heart beats),
             pacemaker, or taking any heart medications
@@ -71,7 +71,7 @@ export function MedicalHistoryPart1Step({
         </div>
 
         {/* Cancer Treatment */}
-        <div className="border rounded-lg p-4 bg-gray-50">
+        <div className="border rounded-lg p-4 bg-muted">
           <Label className="text-base font-semibold mb-3 block">
             Are you currently being treated for cancer or undergoing any cancer
             treatments?*
@@ -101,7 +101,7 @@ export function MedicalHistoryPart1Step({
         </div>
 
         {/* Immunosuppressants */}
-        <div className="border rounded-lg p-4 bg-gray-50">
+        <div className="border rounded-lg p-4 bg-muted">
           <Label className="text-base font-semibold mb-3 block">
             Are you currently taking Immunosuppressants or Immunotherapy
             medication?*
@@ -134,7 +134,7 @@ export function MedicalHistoryPart1Step({
         </div>
 
         {/* Liver Disease */}
-        <div className="border rounded-lg p-4 bg-gray-50">
+        <div className="border rounded-lg p-4 bg-muted">
           <Label className="text-base font-semibold mb-3 block">
             Do you have any history of Liver Disease including hepatitis,
             elevated liver enzyme function blood tests, fatty liver cirrhosis?*
@@ -167,7 +167,7 @@ export function MedicalHistoryPart1Step({
         </div>
 
         {/* Psychiatric History */}
-        <div className="border rounded-lg p-4 bg-gray-50">
+        <div className="border rounded-lg p-4 bg-muted">
           <Label className="text-base font-semibold mb-3 block">
             Psychiatric history - Have you ever been referred to a psychiatrist
             health service?*
diff --git a/nextjs_space/components/consultation/steps/medical-history-part2-step.tsx b/nextjs_space/components/consultation/steps/medical-history-part2-step.tsx
index ff3d584c..e4c70309 100644
--- a/nextjs_space/components/consultation/steps/medical-history-part2-step.tsx
+++ b/nextjs_space/components/consultation/steps/medical-history-part2-step.tsx
@@ -38,17 +38,17 @@ export function MedicalHistoryPart2Step({
   return (
     <form onSubmit={handleSubmit} className="space-y-6">
       <div>
-        <h2 className="text-2xl font-bold text-gray-900 mb-2">
+        <h2 className="text-2xl font-bold text-card-foreground mb-2">
           Medical History (Part Two)
         </h2>
-        <p className="text-gray-600">
+        <p className="text-muted-foreground">
           Final questions about your medical history
         </p>
       </div>
 
       <div className="space-y-6">
         {/* Alcohol Abuse */}
-        <div className="border rounded-lg p-4 bg-gray-50">
+        <div className="border rounded-lg p-4 bg-muted">
           <Label className="text-base font-semibold mb-3 block">
             Do you have a history of alcohol abuse or dependency?*
           </Label>
@@ -80,7 +80,7 @@ export function MedicalHistoryPart2Step({
         </div>
 
         {/* Drug Services */}
-        <div className="border rounded-lg p-4 bg-gray-50">
+        <div className="border rounded-lg p-4 bg-muted">
           <Label className="text-base font-semibold mb-3 block">
             Have you ever been under the care of drug and alcohol services?*
           </Label>
@@ -106,7 +106,7 @@ export function MedicalHistoryPart2Step({
         </div>
 
         {/* Alcohol Units Per Week */}
-        <div className="border rounded-lg p-4 bg-gray-50">
+        <div className="border rounded-lg p-4 bg-muted">
           <Label
             htmlFor="alcoholUnitsPerWeek"
             className="text-base font-semibold mb-3 block"
@@ -124,7 +124,7 @@ export function MedicalHistoryPart2Step({
         </div>
 
         {/* Cannabis Reduces Meds */}
-        <div className="border rounded-lg p-4 bg-gray-50">
+        <div className="border rounded-lg p-4 bg-muted">
           <Label className="text-base font-semibold mb-3 block">
             Do you use cannabis to reduce or eliminate the use of any
             medications that have been prescribed for your medical condition?*
@@ -157,7 +157,7 @@ export function MedicalHistoryPart2Step({
         </div>
 
         {/* Cannabis Frequency */}
-        <div className="border rounded-lg p-4 bg-gray-50">
+        <div className="border rounded-lg p-4 bg-muted">
           <Label
             htmlFor="cannabisFrequency"
             className="text-base font-semibold mb-3 block"
@@ -183,7 +183,7 @@ export function MedicalHistoryPart2Step({
         </div>
 
         {/* Cannabis Amount Per Day */}
-        <div className="border rounded-lg p-4 bg-gray-50">
+        <div className="border rounded-lg p-4 bg-muted">
           <Label
             htmlFor="cannabisAmountPerDay"
             className="text-base font-semibold mb-3 block"
diff --git a/nextjs_space/components/consultation/steps/shipping-address-step.tsx b/nextjs_space/components/consultation/steps/shipping-address-step.tsx
index dc9e4899..4e9bed3c 100644
--- a/nextjs_space/components/consultation/steps/shipping-address-step.tsx
+++ b/nextjs_space/components/consultation/steps/shipping-address-step.tsx
@@ -54,10 +54,10 @@ export function ShippingAddressStep({
   return (
     <form onSubmit={handleSubmit} className="space-y-6">
       <div>
-        <h2 className="text-2xl font-bold text-gray-900 mb-2">
+        <h2 className="text-2xl font-bold text-card-foreground mb-2">
           Shipping Address
         </h2>
-        <p className="text-gray-600">Where should we deliver your order?</p>
+        <p className="text-muted-foreground">Where should we deliver your order?</p>
       </div>
 
       <div>
diff --git a/nextjs_space/components/template-renderer.tsx b/nextjs_space/components/template-renderer.tsx
index ff529bf4..32e5b56d 100644
--- a/nextjs_space/components/template-renderer.tsx
+++ b/nextjs_space/components/template-renderer.tsx
@@ -6,7 +6,7 @@ import type { SectionProps } from '@/lib/types/section-props';
 import type { TemplateLayout } from '@/lib/types/template-layout';
 import { motion, type Transition } from 'framer-motion';
 import { sanitizeCss, extractGoogleFontsImports } from '@/lib/security/css-utils';
-import { hexToHsl } from '@/lib/color-utils';
+import { buildColorOverrideVars } from '@/lib/theme/tenant-tokens';
 
 interface Props {
   layout: TemplateLayout;
@@ -50,29 +50,15 @@ function CurveDivider({ fill = "var(--tenant-bg, #ffffff)", className = "" }: {
 // --- End SVG Helpers ---
 
 
-/** Build inline CSS variable overrides from a colorOverrides object.
- *  Optional `defaults` are applied first, then overrides layer on top. */
-function buildColorOverrideStyle(
-  overrides?: Record<string, string>,
+/** Inline CSS variable overrides for a nav, footer or section, checked for
+ *  legibility against the tenant palette (see lib/theme/tenant-tokens). */
+function overrideStyle(
+  overrides: object | null | undefined,
+  base: object | null | undefined,
   defaults?: Record<string, string>,
-): React.CSSProperties {
-  const style: Record<string, string> = {};
-  // Apply defaults first
-  if (defaults) {
-    for (const [k, v] of Object.entries(defaults)) {
-      if (v) style[`--tenant-color-${k}`] = v;
-    }
-  }
-  // Apply explicit overrides on top
-  if (overrides) {
-    for (const [k, v] of Object.entries(overrides)) {
-      if (v && typeof v === 'string' && v.trim()) {
-        const hslValue = v.startsWith('#') ? hexToHsl(v) : v;
-        style[`--tenant-color-${k}`] = hslValue;
-      }
-    }
-  }
-  return style;
+): React.CSSProperties | undefined {
+  const vars = buildColorOverrideVars(overrides, { defaults, base });
+  return Object.keys(vars).length > 0 ? (vars as React.CSSProperties) : undefined;
 }
 
 /** Dark defaults for FooterBrand / FooterFull — prevents white-on-white
@@ -98,14 +84,12 @@ export function TemplateRenderer({ layout, sectionProps, customCss, renderChrome
     return layout.sections
       .filter(s => s.id && s.colorOverrides)
       .map(s => {
-        const declarations = Object.entries(s.colorOverrides!)
-          .filter(([, v]) => v?.trim())
-          .map(([k, v]) => {
-            // Convert hex (#abc123) to HSL channel format (H S% L%) so
-            // hsl(var(--tenant-color-*)) works in section components.
-            const hslValue = v!.startsWith('#') ? hexToHsl(v!) : v;
-            return `--tenant-color-${k}: ${hslValue}`;
-          })
+        // Hex is converted to HSL channels and inherited text/heading colours
+        // are re-checked against an overridden background (lib/theme/tenant-tokens).
+        const declarations = Object.entries(
+          buildColorOverrideVars(s.colorOverrides, { base: sectionProps.designSystem?.colors }),
+        )
+          .map(([name, value]) => `${name}: ${value}`)
           .join('; ');
         if (!declarations) return '';
         // Use CSS.escape when available (browser), fallback to simple escaping (SSR)
@@ -116,7 +100,7 @@ export function TemplateRenderer({ layout, sectionProps, customCss, renderChrome
       })
       .filter(Boolean)
       .join('\n');
-  }, [layout.sections]);
+  }, [layout.sections, sectionProps.designSystem]);
 
   // Generate section padding overrides from layout.settings.sectionPadding
   // This is rendered server-side so it doesn't depend on S3 CSS loading
@@ -165,7 +149,7 @@ export function TemplateRenderer({ layout, sectionProps, customCss, renderChrome
         <style dangerouslySetInnerHTML={{ __html: sanitizeCss(sectionColorCss) || '' }} />
       )}
       {NavComponent && (
-        <div style={buildColorOverrideStyle(layout.navigationConfig?.colorOverrides)}>
+        <div style={overrideStyle(layout.navigationConfig?.colorOverrides, sectionProps.designSystem?.colors)}>
           <NavComponent {...sectionProps} sectionConfig={layout.navigationConfig || sectionProps.sectionConfig} />
         </div>
       )}
@@ -205,23 +189,15 @@ export function TemplateRenderer({ layout, sectionProps, customCss, renderChrome
             ? configImage
             : undefined;
 
-          // Build inline CSS variable overrides for per-section colors
-          const colorOverrideStyle: React.CSSProperties = {};
-          if (section.colorOverrides) {
-            for (const [k, v] of Object.entries(section.colorOverrides)) {
-              if (v && typeof v === 'string' && v.trim()) {
-                const hslValue = v.startsWith('#') ? hexToHsl(v) : v;
-                (colorOverrideStyle as any)[`--tenant-color-${k}`] = hslValue;
-              }
-            }
-          }
+          // Inline CSS variable overrides for per-section colours, legibility-checked
+          const colorOverrideStyle = overrideStyle(section.colorOverrides, sectionProps.designSystem?.colors);
 
           const sectionElement = (
             <section
               key={section.id || `section-${i}`}
               id={section.id}
               className="relative"
-              style={Object.keys(colorOverrideStyle).length > 0 ? colorOverrideStyle : undefined}
+              style={colorOverrideStyle}
             >
               <Component
                 {...sectionProps}
@@ -274,8 +250,9 @@ export function TemplateRenderer({ layout, sectionProps, customCss, renderChrome
           return wrapper;
         })}
       {FooterComponent && (
-        <div style={buildColorOverrideStyle(
+        <div style={overrideStyle(
           layout.footerConfig?.colorOverrides,
+          sectionProps.designSystem?.colors,
           (footerType === 'FooterBrand' || footerType === 'FooterFull') ? DARK_FOOTER_DEFAULTS : undefined,
         )}>
           <FooterComponent {...sectionProps} sectionConfig={layout.footerConfig || sectionProps.sectionConfig} />
diff --git a/nextjs_space/components/tenant-theme-provider.tsx b/nextjs_space/components/tenant-theme-provider.tsx
index cfcb23ab..842a052e 100644
--- a/nextjs_space/components/tenant-theme-provider.tsx
+++ b/nextjs_space/components/tenant-theme-provider.tsx
@@ -1,6 +1,7 @@
 "use client";
 
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useMemo, type CSSProperties } from "react";
+import { deriveTenantTokens } from "@/lib/theme/tenant-tokens";
 import { Tenant } from "@/types/client";
 import { TenantSettings } from "@/lib/types";
 import { sanitizeCss } from "@/lib/security/css-utils";
@@ -49,14 +50,13 @@ export function TenantThemeProvider({
     () => sanitizeCss(customCss),
     [customCss],
   );
-  const containerRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    // Apply theme to SCOPED container only (not document root)
-    if (containerRef.current) {
-      applyThemeToContainer(containerRef.current, designSystem, settings);
-    }
-  }, [settings, designSystem]);
+  // Theme variables are computed in render, not in an effect: the server then
+  // paints the tenant palette on first load (no flash of the platform defaults)
+  // and the branding editor preview updates in the same render as the form.
+  const themeVars = useMemo(
+    () => buildTenantThemeVars(designSystem, settings),
+    [designSystem, settings],
+  );
 
   // Build data-attributes for conditional CSS effects
   const hoverEffect = designSystem?.buttonHoverEffect || settings.buttonHoverEffect || "none";
@@ -78,7 +78,7 @@ export function TenantThemeProvider({
   };
   const autoFontsUrl = useMemo(() => {
     if (googleFontsUrl) return null; // explicit URL takes precedence
-    // Accept both designSystem shapes (see applyThemeToContainer for context)
+    // Accept both designSystem shapes (see buildTenantThemeVars for context)
     const dsTypo = designSystem?.typography?.fontFamily;
     const dsTypoFlat = designSystem?.typography;
     const bodyId = dsTypo?.body || dsTypo?.base || dsTypoFlat?.fontBody || dsTypoFlat?.fontBase || (settings as any).fontFamily;
@@ -100,7 +100,7 @@ export function TenantThemeProvider({
         <link href={googleFontsUrl || autoFontsUrl!} rel="stylesheet" />
       )}
 
-      {/* Scoped design system CSS — static rules that read CSS variables set by applyThemeToContainer.
+      {/* Scoped design system CSS — static rules that read CSS variables set on the container by buildTenantThemeVars.
           TENANT_SCOPED_CSS is a compile-time constant (not user input), safe for injection. */}
       <style dangerouslySetInnerHTML={{ __html: TENANT_SCOPED_CSS }} />
 
@@ -112,12 +112,11 @@ export function TenantThemeProvider({
 
       {/* Apply theme class to scoped container */}
       <div
-        ref={containerRef}
         className={`tenant-theme-container ${getTenantThemeClasses(settings)}`}
         data-hover={hoverEffect}
         data-glass={glassEffectVal}
         data-padding={useTemplatePadding ? "custom" : "auto"}
-        style={{ minHeight: "100vh" }}
+        style={{ minHeight: "100vh", ...themeVars } as CSSProperties}
       >
         {children}
       </div>
@@ -251,14 +250,14 @@ const TENANT_SCOPED_CSS = `
 
    COLOURS FOLLOW .legal-document (app/globals.css), the existing storefront
    long-form precedent, which reads the --tenant-color-* namespace that
-   applyThemeToContainer populates from designSystem.colors below. The one
+   lib/theme/tenant-tokens populates from designSystem.colors. The one
    departure: every value here carries a fallback to the equivalent shadcn
    token. Those keys only exist if the tenant's design system defines them —
    and the namespace is not uniform (store/[slug]/layout.tsx sets
    --tenant-color-text where .legal-document reads --tenant-color-foreground),
    so an unfallen-back var would resolve to an invalid colour on some tenants.
    The shadcn tokens are always defined and are themselves remapped per tenant
-   in applyThemeToContainer below (--primary/--secondary/--accent/--foreground),
+   by lib/theme/tenant-tokens (the complete set, card and muted included),
    which makes them a correct second choice rather than a default.
 
    HEADINGS ARE DELIBERATELY FONT-LESS HERE. .tenant-theme-container h1-h6
@@ -374,66 +373,26 @@ const TENANT_SCOPED_CSS = `
 `;
 
 /**
- * Apply theme CSS variables to SCOPED container (not document root)
+ * Every CSS custom property the tenant's design system implies, as one object
+ * for the container's inline style. Colours come from lib/theme/tenant-tokens
+ * (the complete shadcn + --tenant-color-* contract with its legibility floor);
+ * typography, radius, spacing, shadow, glass and button sizing are resolved
+ * here from the design system with the legacy tenant.settings as fallback.
  */
-function applyThemeToContainer(
-  container: HTMLElement,
+export function buildTenantThemeVars(
   designSystem: any,
   settings: TenantSettings,
-) {
-  const root = container;
+): Record<string, string> {
+  const vars: Record<string, string> = {};
+  const set = (name: string, value: string | null | undefined) => {
+    if (value) vars[name] = value;
+  };
 
   // === COMPREHENSIVE DESIGN SYSTEM ===
   if (designSystem) {
-    // Apply colors
-    if (designSystem.colors) {
-      // 1. Set specific tenant variables using formatColorValue
-      // Skip nested objects (color scales like sage.50, teal.100, etc.)
-      Object.entries(designSystem.colors).forEach(([key, value]) => {
-        if (value && typeof value === 'string' && value.trim() !== '') {
-          const colorValue = formatColorValue(value);
-          if (colorValue && colorValue.trim() !== '') {
-            root.style.setProperty(
-              `--tenant-color-${camelToKebab(key)}`,
-              colorValue,
-            );
-          }
-        }
-      });
-
-      // 2. Set CORE Tailwind/Shadcn variables using the RAW HSL value if available
-      const primary = designSystem.colors.primary;
-      const secondary = designSystem.colors.secondary;
-      const accent = designSystem.colors.accent;
-      const background = designSystem.colors.background;
-      const text = designSystem.colors.text;
-
-      // Normalize to raw HSL channels. Accepts hex (#rgb / #rrggbb),
-      // `hsl(...)` wrappers, or raw channels. shadcn components consume
-      // these via `hsl(var(--primary))`, so anything else breaks.
-      const toChannels = (val: string) => {
-        if (!val) return null;
-        if (val.startsWith("#")) return hexToHslChannels(val);
-        if (val.startsWith("hsl("))
-          return val.replace("hsl(", "").replace(")", "");
-        return val;
-      };
-
-      if (primary && (primary as string).trim())
-        root.style.setProperty("--primary", toChannels(primary as string));
-      if (secondary && (secondary as string).trim())
-        root.style.setProperty("--secondary", toChannels(secondary as string));
-      if (accent && (accent as string).trim())
-        root.style.setProperty("--accent", toChannels(accent as string));
-      if (background && (background as string).trim())
-        root.style.setProperty(
-          "--background",
-          toChannels(background as string),
-        );
-      // Map text color to foreground
-      if (text && (text as string).trim())
-        root.style.setProperty("--foreground", toChannels(text as string));
-    }
+    // Colours: the complete token contract (tenant variables, shadcn tokens,
+    // legibility floor) lives in lib/theme/tenant-tokens.ts.
+    Object.assign(vars, deriveTenantTokens(designSystem.colors));
 
     // === TYPOGRAPHY ===
     const fontMap: Record<string, string> = {
@@ -495,19 +454,19 @@ function applyThemeToContainer(
     const bodyFont = resolveFont(dsFontBody, settings.fontFamily || "inter");
     const headingFont = resolveFont(dsFontHeading, settings.headingFontFamily || settings.fontFamily || "inter");
 
-    root.style.setProperty("--tenant-font-body", bodyFont);
-    root.style.setProperty("--tenant-font-heading", headingFont);
+    set("--tenant-font-body", bodyFont);
+    set("--tenant-font-heading", headingFont);
 
     // Font weight
     const fontWeightMap: Record<string, string> = { "300": "300", "400": "400", "500": "500", "700": "700" };
     const headingWeightMap: Record<string, string> = { "400": "400", "500": "500", "600": "600", "700": "700", "800": "800" };
     const dsFontWeight = designSystem.typography?.fontWeight?.body;
     const dsHeadingWeight = designSystem.typography?.fontWeight?.heading;
-    root.style.setProperty(
+    set(
       "--tenant-font-weight",
       fontWeightMap[dsFontWeight] || fontWeightMap[settings.fontWeight || "400"] || "400",
     );
-    root.style.setProperty(
+    set(
       "--tenant-font-weight-heading",
       headingWeightMap[dsHeadingWeight] || headingWeightMap[settings.headingFontWeight || "700"] || "700",
     );
@@ -520,7 +479,7 @@ function applyThemeToContainer(
       wider: "0.05em",
     };
     const dsLetterSpacing = designSystem.typography?.letterSpacing;
-    root.style.setProperty(
+    set(
       "--tenant-letter-spacing",
       letterSpacingMap[dsLetterSpacing] || letterSpacingMap[settings.letterSpacingPreset || "normal"] || "0",
     );
@@ -530,21 +489,21 @@ function applyThemeToContainer(
     const dsFontSize = designSystem.typography?.fontSize?.base;
     const rawBodySize = dsFontSize || settings.fontSize || "16";
     const bodyPx = fontSizePresetMap[rawBodySize] || (isNaN(Number(rawBodySize)) ? "16" : rawBodySize);
-    root.style.setProperty("--tenant-font-size-base", `${bodyPx}px`);
+    set("--tenant-font-size-base", `${bodyPx}px`);
 
     // Hero title size (h1) — accepts px number or legacy preset
     const heroPresetMap: Record<string, string> = { small: "30", medium: "36", large: "42", xlarge: "48" };
     const dsHeroFontSize = designSystem.typography?.fontSize?.hero || designSystem.typography?.fontSize?.heading;
     const rawHeroSize = dsHeroFontSize || settings.heroFontSize || settings.headingFontSize || "36";
     const heroPx = heroPresetMap[rawHeroSize] || (isNaN(Number(rawHeroSize)) ? "36" : rawHeroSize);
-    root.style.setProperty("--tenant-hero-scale", String(Number(heroPx) / 36));
+    set("--tenant-hero-scale", String(Number(heroPx) / 36));
 
     // Section heading size (h2–h6) — independent from hero
     const sectionPresetMap: Record<string, string> = { small: "24", medium: "30", large: "36", xlarge: "42" };
     const dsSectionFontSize = designSystem.typography?.fontSize?.section;
     const rawSectionSize = dsSectionFontSize || settings.sectionFontSize || "30";
     const sectionPx = sectionPresetMap[rawSectionSize] || (isNaN(Number(rawSectionSize)) ? "30" : rawSectionSize);
-    root.style.setProperty("--tenant-section-heading-scale", String(Number(sectionPx) / 30));
+    set("--tenant-section-heading-scale", String(Number(sectionPx) / 30));
 
     // === BORDER RADIUS ===
     const borderRadiusMap: Record<string, string> = {
@@ -554,7 +513,7 @@ function applyThemeToContainer(
       large: "1rem",
     };
     const dsBorderRadius = designSystem.borderRadius?.container;
-    root.style.setProperty(
+    set(
       "--tenant-border-radius",
       borderRadiusMap[dsBorderRadius] || borderRadiusMap[settings.borderRadius || "medium"] || "0.5rem",
     );
@@ -566,7 +525,7 @@ function applyThemeToContainer(
       pill: "9999px",
     };
     const dsButtonStyle = designSystem.borderRadius?.button;
-    root.style.setProperty(
+    set(
       "--tenant-button-radius",
       buttonStyleMap[dsButtonStyle] || buttonStyleMap[settings.buttonStyle || "rounded"] || "0.5rem",
     );
@@ -578,7 +537,7 @@ function applyThemeToContainer(
       comfortable: "1.5",
     };
     const dsSpacing = designSystem.spacing?.scale;
-    root.style.setProperty(
+    set(
       "--tenant-spacing-scale",
       spacingMap[dsSpacing] || spacingMap[settings.spacing || "normal"] || "1",
     );
@@ -591,7 +550,7 @@ function applyThemeToContainer(
       bold: "0 10px 15px -3px rgb(0 0 0 / 0.1)",
     };
     const dsShadow = designSystem.shadows?.card;
-    root.style.setProperty(
+    set(
       "--tenant-shadow",
       shadowMap[dsShadow] || shadowMap[settings.shadowStyle || "soft"] || "0 1px 3px 0 rgb(0 0 0 / 0.1)",
     );
@@ -604,8 +563,8 @@ function applyThemeToContainer(
     };
     const dsGlass = designSystem.glassEffect;
     const glassConfig = glassMap[dsGlass] || glassMap[settings.glassEffect || "none"] || glassMap["none"];
-    root.style.setProperty("--tenant-backdrop-blur", glassConfig.blur);
-    root.style.setProperty("--tenant-card-opacity", glassConfig.opacity);
+    set("--tenant-backdrop-blur", glassConfig.blur);
+    set("--tenant-card-opacity", glassConfig.opacity);
 
 
     // === BUTTON SIZE ===
@@ -617,90 +576,11 @@ function applyThemeToContainer(
     };
     const dsButtonSize = designSystem.button?.size;
     const buttonSize = buttonSizeMap[dsButtonSize] || buttonSizeMap[settings.buttonSize || "medium"] || buttonSizeMap["medium"];
-    root.style.setProperty("--tenant-button-padding", buttonSize.padding);
-    root.style.setProperty("--tenant-button-font-size", buttonSize.fontSize);
-
-    // === BUTTON HOVER EFFECT ===
-    // Consumed via data-hover attribute on container, CSS rules defined in TENANT_SCOPED_CSS
-    const hoverEffect = designSystem.buttonHoverEffect || (settings as any).buttonHoverEffect || "none";
-    root.setAttribute("data-hover", hoverEffect);
-
-    // === GLASS EFFECT (data-attr for CSS) ===
-    const glass = designSystem.glassEffect || settings.glassEffect || "none";
-    root.setAttribute("data-glass", glass);
-  }
-}
-
-/**
- * Convert camelCase to kebab-case
- */
-function camelToKebab(str: string): string {
-  return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-}
-
-/**
- * Format color value to RAW HSL channels for CSS variables.
- * Components wrap with hsl(): `hsl(var(--tenant-color-primary))`
- * So variables MUST store raw channels: `178 48% 21%`
- * If we stored `hsl(178 48% 21%)`, components would produce `hsl(hsl(...))` = INVALID.
- * If we stored `#ffffff`, components would produce `hsl(#ffffff)` = INVALID.
- */
-function formatColorValue(value: string | null | undefined): string {
-  if (!value || typeof value !== "string") {
-    return "";
-  }
-
-  // Strip hsl() wrapper if present — we need raw channels only
-  if (value.startsWith("hsl(") && value.endsWith(")")) {
-    return value.slice(4, -1).trim();
-  }
-
-  // Raw HSL channels like "178 48% 21%" — pass through
-  if (value.includes("%") && !value.includes("(") && !value.includes("#")) {
-    return value;
-  }
-
-  // Convert hex to HSL channels (prevents invalid `hsl(#hex)` in templates)
-  if (value.startsWith("#")) {
-    return hexToHslChannels(value);
-  }
+    set("--tenant-button-padding", buttonSize.padding);
+    set("--tenant-button-font-size", buttonSize.fontSize);
 
-  return value;
-}
-
-/**
- * Convert hex color (#rrggbb or #rgb) to raw HSL channel string "H S% L%"
- */
-function hexToHslChannels(hex: string): string {
-  let r = 0, g = 0, b = 0;
-  if (hex.length === 4) {
-    r = parseInt(hex[1] + hex[1], 16);
-    g = parseInt(hex[2] + hex[2], 16);
-    b = parseInt(hex[3] + hex[3], 16);
-  } else if (hex.length === 7) {
-    r = parseInt(hex.slice(1, 3), 16);
-    g = parseInt(hex.slice(3, 5), 16);
-    b = parseInt(hex.slice(5, 7), 16);
-  } else {
-    return "";
   }
-
-  r /= 255; g /= 255; b /= 255;
-  const max = Math.max(r, g, b), min = Math.min(r, g, b);
-  let h = 0, s = 0;
-  const l = (max + min) / 2;
-
-  if (max !== min) {
-    const d = max - min;
-    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
-    switch (max) {
-      case r: h = ((g - b) / d + (g < b ? 6 : 0)) / 6; break;
-      case g: h = ((b - r) / d + 2) / 6; break;
-      case b: h = ((r - g) / d + 4) / 6; break;
-    }
-  }
-
-  return `${Math.round(h * 360)} ${Math.round(s * 100)}% ${Math.round(l * 100)}%`;
+  return vars;
 }
 
 /**
diff --git a/nextjs_space/components/ui/dialog.tsx b/nextjs_space/components/ui/dialog.tsx
index 85d4fafb..8b9ad662 100644
--- a/nextjs_space/components/ui/dialog.tsx
+++ b/nextjs_space/components/ui/dialog.tsx
@@ -38,7 +38,7 @@ const DialogContent = React.forwardRef<
     <DialogPrimitive.Content
       ref={ref}
       className={cn(
-        "bs-overlay fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:rounded-lg",
+        "bs-overlay fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 text-foreground shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:rounded-lg",
         className,
       )}
       {...props}
diff --git a/nextjs_space/components/ui/input.tsx b/nextjs_space/components/ui/input.tsx
index 84da2c01..093f5fad 100644
--- a/nextjs_space/components/ui/input.tsx
+++ b/nextjs_space/components/ui/input.tsx
@@ -10,7 +10,7 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
       <input
         type={type}
         className={cn(
-          "flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+          "flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm text-foreground ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
           className,
         )}
         ref={ref}
diff --git a/nextjs_space/components/ui/select.tsx b/nextjs_space/components/ui/select.tsx
index 9218f68b..37b94f79 100644
--- a/nextjs_space/components/ui/select.tsx
+++ b/nextjs_space/components/ui/select.tsx
@@ -19,7 +19,7 @@ const SelectTrigger = React.forwardRef<
   <SelectPrimitive.Trigger
     ref={ref}
     className={cn(
-      "flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1",
+      "flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm text-foreground ring-offset-background placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1",
       className,
     )}
     {...props}
diff --git a/nextjs_space/components/ui/sheet.tsx b/nextjs_space/components/ui/sheet.tsx
index 4d631767..ba81946d 100644
--- a/nextjs_space/components/ui/sheet.tsx
+++ b/nextjs_space/components/ui/sheet.tsx
@@ -31,7 +31,7 @@ const SheetOverlay = React.forwardRef<
 SheetOverlay.displayName = SheetPrimitive.Overlay.displayName;
 
 const sheetVariants = cva(
-  "fixed z-50 gap-4 bg-background p-6 shadow-lg transition ease-in-out data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:duration-500",
+  "fixed z-50 gap-4 bg-background p-6 text-foreground shadow-lg transition ease-in-out data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:duration-500",
   {
     variants: {
       side: {
diff --git a/nextjs_space/components/ui/textarea.tsx b/nextjs_space/components/ui/textarea.tsx
index d513f359..81d6dd03 100644
--- a/nextjs_space/components/ui/textarea.tsx
+++ b/nextjs_space/components/ui/textarea.tsx
@@ -9,7 +9,7 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
     return (
       <textarea
         className={cn(
-          "flex min-h-[80px] w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+          "flex min-h-[80px] w-full rounded-md border border-input bg-background px-3 py-2 text-sm text-foreground ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
           className,
         )}
         ref={ref}
diff --git a/nextjs_space/lib/theme/tenant-tokens.ts b/nextjs_space/lib/theme/tenant-tokens.ts
new file mode 100644
index 00000000..8ddf3f80
--- /dev/null
+++ b/nextjs_space/lib/theme/tenant-tokens.ts
@@ -0,0 +1,278 @@
+import { hexToHsl } from "@/lib/color-utils";
+
+/**
+ * Tenant colour → CSS token derivation: the storefront theming contract.
+ *
+ * A tenant sets up to eight colours in the branding form (primary, secondary,
+ * accent, background, surface, text, heading, border). Storefront code consumes
+ * them two ways: the `--tenant-color-*` variables (inline styles in store pages
+ * and section components) and the shadcn tokens (`bg-card`, `text-foreground`,
+ * `text-muted-foreground`, …) that every `components/ui` primitive is built on.
+ *
+ * Before this module only five shadcn tokens were remapped per tenant
+ * (primary, secondary, accent, background, foreground). Card, popover, muted,
+ * border, input, ring and every `*-foreground` stayed at the light `:root`
+ * defaults, so a dark palette rendered white cards with white text (LekkerWeed
+ * dashboard and orders pages, September 2026). This module derives the COMPLETE
+ * set from the tenant palette, fills in the colours a tenant did not set, and
+ * applies a legibility floor: a foreground that falls below MIN_CONTRAST against
+ * the surface it sits on is replaced by black or white, whichever reads.
+ *
+ * Pure and framework-free so the same numbers are produced on the server (the
+ * container's inline style, hence no first-paint flash), in the browser, and in
+ * the branding editor preview.
+ */
+
+/** Below this ratio the storefront substitutes black or white (WCAG large-text AA). */
+export const MIN_CONTRAST = 3;
+/** Below this ratio the branding form warns the operator (WCAG body-text AA). */
+export const WARN_CONTRAST = 4.5;
+
+/** The `:root` values in app/globals.css — the partner of a colour the tenant left unset. */
+const ROOT_BACKGROUND = "216 20% 95%";
+const ROOT_FOREGROUND = "222 47% 11%";
+const WHITE = "0 0% 100%";
+const BLACK = "0 0% 0%";
+
+/** Luminance at which black-on-colour and white-on-colour contrast equally. */
+const LUMINANCE_SWITCH = 0.179;
+
+const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+const CHANNELS = /^(\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)%\s+(\d+(?:\.\d+)?)%$/;
+
+/**
+ * Normalise anything an operator or a template may have stored — `#abc`,
+ * `#aabbcc`, `hsl(280, 45%, 8%)`, `280 45% 8%` — to raw HSL channels, the only
+ * form `hsl(var(--x))` accepts. Anything else (named colours, nested colour
+ * scales, blanks) is `null` and the caller skips it.
+ */
+export function toHslChannels(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  let v = value.trim();
+  if (!v) return null;
+  if (/^hsla?\(/i.test(v) && v.endsWith(")")) {
+    v = v
+      .slice(v.indexOf("(") + 1, -1)
+      .split("/")[0]
+      .replace(/,/g, " ")
+      .trim();
+  }
+  if (HEX.test(v)) return hexToHsl(v);
+  const m = v.replace(/\s+/g, " ").match(CHANNELS);
+  return m ? `${m[1]} ${m[2]}% ${m[3]}%` : null;
+}
+
+function parseChannels(channels: string): [number, number, number] {
+  const m = channels.match(CHANNELS);
+  if (!m) return [0, 0, 0];
+  return [parseFloat(m[1]), parseFloat(m[2]) / 100, parseFloat(m[3]) / 100];
+}
+
+function toRgb(channels: string): [number, number, number] {
+  const [h, s, l] = parseChannels(channels);
+  const a = s * Math.min(l, 1 - l);
+  const f = (n: number) => {
+    const k = (n + h / 30) % 12;
+    return 255 * (l - a * Math.max(Math.min(k - 3, 9 - k, 1), -1));
+  };
+  return [f(0), f(8), f(4)];
+}
+
+function rgbToChannels(r: number, g: number, b: number): string {
+  const rr = r / 255;
+  const gg = g / 255;
+  const bb = b / 255;
+  const max = Math.max(rr, gg, bb);
+  const min = Math.min(rr, gg, bb);
+  const l = (max + min) / 2;
+  let h = 0;
+  let s = 0;
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    if (max === rr) h = (gg - bb) / d + (gg < bb ? 6 : 0);
+    else if (max === gg) h = (bb - rr) / d + 2;
+    else h = (rr - gg) / d + 4;
+    h /= 6;
+  }
+  return `${Math.round(h * 360)} ${Math.round(s * 100)}% ${Math.round(l * 100)}%`;
+}
+
+function linearChannel(value: number): number {
+  const c = value / 255;
+  return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+/** WCAG relative luminance of an HSL channel string. */
+export function relativeLuminance(channels: string): number {
+  const [r, g, b] = toRgb(channels);
+  return 0.2126 * linearChannel(r) + 0.7152 * linearChannel(g) + 0.0722 * linearChannel(b);
+}
+
+/** WCAG contrast ratio between two HSL channel strings, 1 (identical) to 21. */
+export function contrastRatio(a: string, b: string): number {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  const [hi, lo] = la > lb ? [la, lb] : [lb, la];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** Black or white, whichever a reader can see on `background`. */
+export function readableOn(background: string): string {
+  return relativeLuminance(background) > LUMINANCE_SWITCH ? BLACK : WHITE;
+}
+
+/** Mix two colours in RGB space; `weight` is the share of `b` (0..1). */
+export function mixChannels(a: string, b: string, weight: number): string {
+  const w = Math.min(1, Math.max(0, weight));
+  const [ar, ag, ab] = toRgb(a);
+  const [br, bg, bb] = toRgb(b);
+  return rgbToChannels(
+    ar + (br - ar) * w,
+    ag + (bg - ag) * w,
+    ab + (bb - ab) * w,
+  );
+}
+
+function isDark(channels: string): boolean {
+  return relativeLuminance(channels) <= LUMINANCE_SWITCH;
+}
+
+function ensureContrast(foreground: string, background: string): string {
+  return contrastRatio(foreground, background) >= MIN_CONTRAST
+    ? foreground
+    : readableOn(background);
+}
+
+function camelToKebab(key: string): string {
+  return key.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+/**
+ * The full set of CSS custom properties for a tenant's `designSystem.colors`.
+ *
+ * Returned keys:
+ * - `--tenant-color-<key>` for every colour the tenant stored (verbatim, as
+ *   before), plus derived `surface`, `border`, `muted`, `muted-foreground`
+ *   when they were not stored, so section fallbacks always resolve;
+ * - the shadcn tokens: background/foreground, card, popover, muted, border,
+ *   input, ring, and primary/secondary/accent with a computed foreground.
+ *
+ * Guarantees: `--foreground` and `--tenant-color-text` read against
+ * `--background`; `--card-foreground` and `--muted-foreground` read against
+ * `--card`; `--primary-foreground` (and secondary/accent) read against their
+ * colour. Everything else is the tenant's choice untouched.
+ */
+export function deriveTenantTokens(
+  colors: object | null | undefined,
+): Record<string, string> {
+  if (!colors || typeof colors !== "object") return {};
+  const source = colors as Record<string, unknown>;
+  const tokens: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(source)) {
+    const channels = toHslChannels(value);
+    if (channels) tokens[`--tenant-color-${camelToKebab(key)}`] = channels;
+  }
+  if (Object.keys(tokens).length === 0) return {};
+
+  const pick = (key: string) => toHslChannels(source[key]);
+
+  const background = pick("background") ?? ROOT_BACKGROUND;
+  const chosenText = pick("text") ?? ROOT_FOREGROUND;
+  const text = ensureContrast(chosenText, background);
+  const heading = ensureContrast(pick("heading") ?? chosenText, background);
+  // An unset surface is white on a light page (today's default) and a slightly
+  // lifted shade of the page on a dark one — the usual "elevated" dark surface.
+  const surface = pick("surface") ?? (isDark(background) ? mixChannels(background, WHITE, 0.07) : WHITE);
+  const cardForeground = ensureContrast(chosenText, surface);
+  const border = pick("border") ?? mixChannels(surface, cardForeground, 0.12);
+  const muted = mixChannels(surface, cardForeground, 0.06);
+  // Checked against `muted`, the surface `text-muted-foreground` actually sits on.
+  const mutedForeground = ensureContrast(mixChannels(cardForeground, surface, 0.4), muted);
+
+  Object.assign(tokens, {
+    "--tenant-color-background": background,
+    "--tenant-color-text": text,
+    "--tenant-color-heading": heading,
+    "--tenant-color-surface": surface,
+    "--tenant-color-border": border,
+    "--tenant-color-muted": muted,
+    "--tenant-color-muted-foreground": mutedForeground,
+    "--background": background,
+    "--foreground": text,
+    "--card": surface,
+    "--card-foreground": cardForeground,
+    "--popover": surface,
+    "--popover-foreground": cardForeground,
+    "--muted": muted,
+    "--muted-foreground": mutedForeground,
+    "--border": border,
+    "--input": border,
+  });
+
+  const primary = pick("primary");
+  if (primary) {
+    tokens["--primary"] = primary;
+    tokens["--primary-foreground"] = readableOn(primary);
+    tokens["--ring"] = primary;
+  }
+  const secondary = pick("secondary");
+  if (secondary) {
+    tokens["--secondary"] = secondary;
+    tokens["--secondary-foreground"] = readableOn(secondary);
+  }
+  const accent = pick("accent");
+  if (accent) {
+    tokens["--accent"] = accent;
+    tokens["--accent-foreground"] = readableOn(accent);
+  }
+
+  return tokens;
+}
+
+/**
+ * Inline `--tenant-color-*` variables for a nav, footer or section colour
+ * override, with the same legibility floor as the page palette.
+ *
+ * `defaults` are applied first (the dark footer presets), `overrides` on top.
+ * `base` is the tenant's page palette: when an override changes the background
+ * but inherits the text or heading, the inherited colour is checked against
+ * the NEW background and replaced if it no longer reads — the case where a
+ * dark-theme tenant gives one section a white background.
+ */
+export function buildColorOverrideVars(
+  overrides: object | null | undefined,
+  options: {
+    defaults?: object | null;
+    base?: object | null;
+  } = {},
+): Record<string, string> {
+  const merged: Record<string, string> = {};
+  for (const source of [options.defaults, overrides]) {
+    if (!source) continue;
+    for (const [key, value] of Object.entries(source as Record<string, unknown>)) {
+      const channels = toHslChannels(value);
+      if (channels) merged[key] = channels;
+    }
+  }
+  if (Object.keys(merged).length === 0) return {};
+
+  const base = (options.base ?? {}) as Record<string, unknown>;
+  const baseColor = (key: string) => toHslChannels(base[key]);
+  const background = merged.background ?? baseColor("background");
+  if (background) {
+    const text = merged.text ?? baseColor("text");
+    if (text && contrastRatio(text, background) < MIN_CONTRAST) {
+      merged.text = readableOn(background);
+    }
+    const heading = merged.heading ?? baseColor("heading");
+    if (heading && contrastRatio(heading, background) < MIN_CONTRAST) {
+      merged.heading = readableOn(background);
+    }
+  }
+
+  return Object.fromEntries(
+    Object.entries(merged).map(([key, value]) => [`--tenant-color-${key}`, value]),
+  );
+}
diff --git a/nextjs_space/tests/unit/tenant-tokens.test.ts b/nextjs_space/tests/unit/tenant-tokens.test.ts
new file mode 100644
index 00000000..67da7c46
--- /dev/null
+++ b/nextjs_space/tests/unit/tenant-tokens.test.ts
@@ -0,0 +1,190 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  MIN_CONTRAST,
+  buildColorOverrideVars,
+  contrastRatio,
+  deriveTenantTokens,
+  mixChannels,
+  readableOn,
+  toHslChannels,
+} from "@/lib/theme/tenant-tokens";
+
+/**
+ * The storefront theming contract (lib/theme/tenant-tokens.ts).
+ *
+ * Two live palettes anchor these tests. LekkerWeed is the dark pilot tenant
+ * whose dashboard rendered white text on white cards because only five shadcn
+ * tokens were remapped; HealingBuds is the light first partner whose rendering
+ * must not move. The third palette is the one an operator can always produce
+ * with the colour pickers: text and background the same colour.
+ */
+const LEKKERWEED = {
+  primary: "175 70% 42%",
+  secondary: "175 70% 42%",
+  accent: "335 81% 45%",
+  background: "280 45% 8%",
+  surface: "280 35% 14%",
+  text: "0 0% 100%",
+  heading: "0 0% 100%",
+  border: "280 30% 25%",
+  "primary-scale": { "500": "335 85% 55%" },
+};
+
+const HEALINGBUDS = {
+  primary: "178 48% 21%",
+  secondary: "178 48% 33%",
+  accent: "164 48% 53%",
+  background: "150 12% 97%",
+  surface: "155 10% 99%",
+  text: "172 32% 20%",
+  heading: "172 32% 20%",
+  border: "165 18% 86%",
+};
+
+describe("toHslChannels", () => {
+  it("accepts hex, hsl() wrappers and raw channels", () => {
+    expect(toHslChannels("#ffffff")).toBe("0 0% 100%");
+    expect(toHslChannels("#fff")).toBe("0 0% 100%");
+    expect(toHslChannels("hsl(280, 45%, 8%)")).toBe("280 45% 8%");
+    expect(toHslChannels("hsl(280 45% 8% / 0.5)")).toBe("280 45% 8%");
+    expect(toHslChannels("  280   45%  8% ")).toBe("280 45% 8%");
+  });
+
+  it("rejects everything hsl(var(--x)) could not consume", () => {
+    expect(toHslChannels("red")).toBeNull();
+    expect(toHslChannels("")).toBeNull();
+    expect(toHslChannels(null)).toBeNull();
+    expect(toHslChannels({ "500": "335 85% 55%" })).toBeNull();
+    expect(toHslChannels("rgb(1,2,3)")).toBeNull();
+  });
+});
+
+describe("contrast helpers", () => {
+  it("measures WCAG contrast", () => {
+    expect(contrastRatio("0 0% 100%", "0 0% 0%")).toBeCloseTo(21, 1);
+    expect(contrastRatio("0 0% 100%", "0 0% 100%")).toBeCloseTo(1, 5);
+  });
+
+  it("picks black on pale colours and white on dark ones", () => {
+    expect(readableOn("280 45% 8%")).toBe("0 0% 100%");
+    expect(readableOn("0 0% 100%")).toBe("0 0% 0%");
+    // LekkerWeed's teal button: white fails AA on it, black clears it.
+    expect(readableOn("175 70% 42%")).toBe("0 0% 0%");
+  });
+
+  it("mixes in RGB space", () => {
+    expect(mixChannels("0 0% 0%", "0 0% 100%", 0.5)).toBe("0 0% 50%");
+    expect(mixChannels("0 0% 0%", "0 0% 100%", 0)).toBe("0 0% 0%");
+  });
+});
+
+describe("deriveTenantTokens — dark palette (LekkerWeed)", () => {
+  const tokens = deriveTenantTokens(LEKKERWEED);
+
+  it("pairs every shadcn surface with a foreground that reads on it", () => {
+    expect(tokens["--card"]).toBe("280 35% 14%");
+    expect(tokens["--card-foreground"]).toBe("0 0% 100%");
+    expect(tokens["--popover"]).toBe("280 35% 14%");
+    expect(tokens["--popover-foreground"]).toBe("0 0% 100%");
+    expect(tokens["--background"]).toBe("280 45% 8%");
+    expect(tokens["--foreground"]).toBe("0 0% 100%");
+    expect(contrastRatio(tokens["--muted-foreground"], tokens["--card"])).toBeGreaterThanOrEqual(MIN_CONTRAST);
+    expect(contrastRatio(tokens["--muted-foreground"], tokens["--muted"])).toBeGreaterThanOrEqual(MIN_CONTRAST);
+  });
+
+  it("computes button foregrounds from the button colour instead of assuming white", () => {
+    expect(tokens["--primary"]).toBe("175 70% 42%");
+    expect(tokens["--primary-foreground"]).toBe("0 0% 0%");
+    expect(tokens["--accent-foreground"]).toBe("0 0% 100%");
+    expect(tokens["--ring"]).toBe("175 70% 42%");
+  });
+
+  it("keeps the tenant's own variables and skips nested colour scales", () => {
+    expect(tokens["--tenant-color-primary"]).toBe("175 70% 42%");
+    expect(tokens["--tenant-color-border"]).toBe("280 30% 25%");
+    expect(tokens["--input"]).toBe("280 30% 25%");
+    expect(tokens["--tenant-color-primary-scale"]).toBeUndefined();
+  });
+});
+
+describe("deriveTenantTokens — light palette (HealingBuds)", () => {
+  const tokens = deriveTenantTokens(HEALINGBUDS);
+
+  it("leaves the operator's readable choices untouched", () => {
+    expect(tokens["--foreground"]).toBe("172 32% 20%");
+    expect(tokens["--card"]).toBe("155 10% 99%");
+    expect(tokens["--card-foreground"]).toBe("172 32% 20%");
+    expect(tokens["--border"]).toBe("165 18% 86%");
+    expect(tokens["--primary-foreground"]).toBe("0 0% 100%");
+  });
+
+  it("derives a muted foreground that still reads on the card", () => {
+    expect(contrastRatio(tokens["--muted-foreground"], tokens["--card"])).toBeGreaterThanOrEqual(MIN_CONTRAST);
+  });
+});
+
+describe("deriveTenantTokens — legibility floor", () => {
+  it("substitutes black when an operator picks white text on a white page", () => {
+    const tokens = deriveTenantTokens({ background: "#ffffff", text: "#ffffff", heading: "#fefefe" });
+    expect(tokens["--foreground"]).toBe("0 0% 0%");
+    expect(tokens["--tenant-color-text"]).toBe("0 0% 0%");
+    expect(tokens["--tenant-color-heading"]).toBe("0 0% 0%");
+    expect(tokens["--card-foreground"]).toBe("0 0% 0%");
+  });
+
+  it("substitutes white when the text vanishes into a dark page", () => {
+    const tokens = deriveTenantTokens({ background: "#111111", text: "#222222" });
+    expect(tokens["--foreground"]).toBe("0 0% 100%");
+  });
+
+  it("fills an unset surface: white on a light page, a lifted shade on a dark one", () => {
+    expect(deriveTenantTokens({ background: "#ffffff", text: "#111111" })["--card"]).toBe("0 0% 100%");
+    const dark = deriveTenantTokens({ background: "280 45% 8%", text: "#ffffff" });
+    expect(dark["--card"]).not.toBe("280 45% 8%");
+    expect(contrastRatio(dark["--card-foreground"], dark["--card"])).toBeGreaterThanOrEqual(MIN_CONTRAST);
+  });
+
+  it("emits nothing for tenants without colours", () => {
+    expect(deriveTenantTokens(undefined)).toEqual({});
+    expect(deriveTenantTokens({})).toEqual({});
+    expect(deriveTenantTokens({ primary: "" })).toEqual({});
+  });
+});
+
+describe("buildColorOverrideVars", () => {
+  it("returns nothing when there is nothing to override", () => {
+    expect(buildColorOverrideVars(undefined)).toEqual({});
+    expect(buildColorOverrideVars({ text: "" })).toEqual({});
+  });
+
+  it("layers overrides over defaults and converts hex", () => {
+    const vars = buildColorOverrideVars(
+      { text: "#ffffff" },
+      { defaults: { background: "220 15% 10%", text: "0 0% 90%" } },
+    );
+    expect(vars).toEqual({
+      "--tenant-color-background": "220 15% 10%",
+      "--tenant-color-text": "0 0% 100%",
+    });
+  });
+
+  it("re-checks inherited text when a section changes its background", () => {
+    const vars = buildColorOverrideVars(
+      { background: "#ffffff" },
+      { base: LEKKERWEED },
+    );
+    expect(vars["--tenant-color-background"]).toBe("0 0% 100%");
+    expect(vars["--tenant-color-text"]).toBe("0 0% 0%");
+    expect(vars["--tenant-color-heading"]).toBe("0 0% 0%");
+  });
+
+  it("leaves a readable override alone", () => {
+    const vars = buildColorOverrideVars(
+      { background: "#7d7878", text: "#ffffff", heading: "#ffffff" },
+      { base: LEKKERWEED },
+    );
+    expect(vars["--tenant-color-text"]).toBe("0 0% 100%");
+    expect(vars["--tenant-color-heading"]).toBe("0 0% 100%");
+  });
+});

From 9748dae2db9cc295bbc3a146d8c83dd0c6086fd9 Mon Sep 17 00:00:00 2001
From: Gerard Kavanagh <gerard161@gmail.com>
Date: Mon, 7 Sep 2026 15:43:54 +0100
Subject: [PATCH 2/2] fix(theme): accept comma-alpha hsla() and warn on
 low-contrast surface overrides

---
 .../branding/tabs/contrast-hint.tsx           | 43 ++++++++++++-------
 nextjs_space/lib/theme/tenant-tokens.ts       |  6 ++-
 nextjs_space/tests/unit/tenant-tokens.test.ts |  1 +
 3 files changed, 33 insertions(+), 17 deletions(-)

diff --git a/nextjs_space/app/tenant-admin/branding/tabs/contrast-hint.tsx b/nextjs_space/app/tenant-admin/branding/tabs/contrast-hint.tsx
index 647d2ffc..029edbf8 100644
--- a/nextjs_space/app/tenant-admin/branding/tabs/contrast-hint.tsx
+++ b/nextjs_space/app/tenant-admin/branding/tabs/contrast-hint.tsx
@@ -40,8 +40,8 @@ export function contrastWarnings(pairs: ContrastPair[]): ContrastWarning[] {
 /**
  * The text-on-background pairs a nav, footer or section override changes.
  * Colours the override leaves unset inherit from the brand palette, exactly as
- * the storefront resolves them. Overrides that touch none of the three colours
- * produce no pairs, so the brand-level warning is not repeated.
+ * the storefront resolves them. Overrides that touch none of the relevant
+ * colours produce no pairs, so the brand-level warning is not repeated.
  */
 export function overridePairs(
   overrides: Record<string, string> | undefined,
@@ -49,21 +49,32 @@ export function overridePairs(
   scope: string,
 ): ContrastPair[] {
   if (!overrides) return [];
-  const touched = ["background", "text", "heading"].some((key) => overrides[key]);
-  if (!touched) return [];
-  const background = overrides.background || base.backgroundColor;
-  return [
-    {
-      label: `${scope} body text on its background`,
+  const pairs: ContrastPair[] = [];
+  if (["background", "text", "heading"].some((key) => overrides[key])) {
+    const background = overrides.background || base.backgroundColor;
+    pairs.push(
+      {
+        label: `${scope} body text on its background`,
+        foreground: overrides.text || base.textColor,
+        background,
+      },
+      {
+        label: `${scope} heading text on its background`,
+        foreground: overrides.heading || base.headingColor,
+        background,
+      },
+    );
+  }
+  // Cards inside the section take the override's surface; the storefront
+  // substitutes black/white there too when the text no longer reads.
+  if (overrides.surface) {
+    pairs.push({
+      label: `${scope} body text on its card background`,
       foreground: overrides.text || base.textColor,
-      background,
-    },
-    {
-      label: `${scope} heading text on its background`,
-      foreground: overrides.heading || base.headingColor,
-      background,
-    },
-  ];
+      background: overrides.surface,
+    });
+  }
+  return pairs;
 }
 
 export function ContrastHint({ pairs }: { pairs: ContrastPair[] }) {
diff --git a/nextjs_space/lib/theme/tenant-tokens.ts b/nextjs_space/lib/theme/tenant-tokens.ts
index 8ddf3f80..adfb1623 100644
--- a/nextjs_space/lib/theme/tenant-tokens.ts
+++ b/nextjs_space/lib/theme/tenant-tokens.ts
@@ -51,11 +51,15 @@ export function toHslChannels(value: unknown): string | null {
   let v = value.trim();
   if (!v) return null;
   if (/^hsla?\(/i.test(v) && v.endsWith(")")) {
+    // Drop the alpha channel in either syntax: "h s% l% / a" or "h, s%, l%, a".
     v = v
       .slice(v.indexOf("(") + 1, -1)
       .split("/")[0]
       .replace(/,/g, " ")
-      .trim();
+      .trim()
+      .split(/\s+/)
+      .slice(0, 3)
+      .join(" ");
   }
   if (HEX.test(v)) return hexToHsl(v);
   const m = v.replace(/\s+/g, " ").match(CHANNELS);
diff --git a/nextjs_space/tests/unit/tenant-tokens.test.ts b/nextjs_space/tests/unit/tenant-tokens.test.ts
index 67da7c46..a04efc46 100644
--- a/nextjs_space/tests/unit/tenant-tokens.test.ts
+++ b/nextjs_space/tests/unit/tenant-tokens.test.ts
@@ -48,6 +48,7 @@ describe("toHslChannels", () => {
     expect(toHslChannels("#fff")).toBe("0 0% 100%");
     expect(toHslChannels("hsl(280, 45%, 8%)")).toBe("280 45% 8%");
     expect(toHslChannels("hsl(280 45% 8% / 0.5)")).toBe("280 45% 8%");
+    expect(toHslChannels("hsla(280, 45%, 8%, 0.5)")).toBe("280 45% 8%");
     expect(toHslChannels("  280   45%  8% ")).toBe("280 45% 8%");
   });