@mohasinac/appkit 2.8.9 → 3.0.0

package/dist/tokens/index.js

@@ -138,8 +138,8 @@ import { getDefaultCurrency, getDefaultLocale, getDefaultCountry, getDefaultTime
  * import { LOCALE_CONFIG } from "@mohasinac/appkit/tokens";
  *
  * const price = new Intl.NumberFormat(LOCALE_CONFIG.defaultLocale, {
- *   style: "currency",
- *   currency: LOCALE_CONFIG.defaultCurrency,
+ * style: "currency",
+ * currency: LOCALE_CONFIG.defaultCurrency,
  * }).format(1299);
  * // => "\u20b91,299.00"
  * ```
@@ -602,11 +602,11 @@ const TRANSITIONS = {
  * - `shimmer` — left-to-right highlight sweep. Requires `animate-shimmer`
  *   keyframe defined in tailwind.config.js:
  *   ```js
- *   // tailwind.config.js
- *   theme: { extend: { animation: { shimmer: "shimmer 1.5s infinite" },
- *     keyframes: { shimmer: { "0%": { backgroundPosition: "-400% 0" },
- *                              "100%": { backgroundPosition: "400% 0" } } } } }
- *   ```
+ * // tailwind.config.js
+ * theme: { extend: { animation: { shimmer: "shimmer 1.5s infinite" },
+ * keyframes: { shimmer: { "0%": { backgroundPosition: "-400% 0" },
+ * "100%": { backgroundPosition: "400% 0" } } } } }
+ * ```
  */
 const SKELETON = {
     // - Pulse (fade) variant ----------------------------------------------------------------
@@ -728,105 +728,12 @@ const RATING = {
     filled: "text-yellow-400",
     empty: "text-zinc-300 dark:text-zinc-600",
 };
-/**
- * THEME_CONSTANTS
- *
- * The complete, responsive-first design system constant map.
- * Import in your project's `constants/theme.ts` and extend with
- * brand-specific values (accentBanner gradients, badge role variants, etc.).
- *
- * @example
- * ```ts
- * // In your project constants/theme.ts:
- * import { THEME_CONSTANTS } from "./";
- *
- * export { THEME_CONSTANTS };        // re-export as-is
- *
- * // or merge with project-specific extensions:
- * export const THEME_CONSTANTS = {
- *   ...baseTheme,
- *   accentBanner: { ... },           // project-specific
- * };
- * ```
- */
-export const THEME_CONSTANTS = {
-    themed: THEMED,
-    layout: LAYOUT,
-    typography: TYPOGRAPHY,
-    spacing: SPACING,
-    grid: GRID,
-    page: PAGE,
-    input: INPUT,
-    card: CARD,
-    flex: FLEX,
-    position: POSITION,
-    states: STATES,
-    transitions: TRANSITIONS,
-    skeleton: SKELETON,
-    motion: MOTION,
-    text: TEXT,
-    touch: TOUCH,
-    fluidGrid: FLUID_GRID,
-    /** Form layout tokens — pair with FormGrid / FormField components */
-    form: {
-        grid: "flex flex-wrap gap-4",
-        field: "flex-1 min-w-[280px] flex flex-col gap-1.5",
-        fieldWide: "w-full flex flex-col gap-1.5",
-        fieldHalf: "w-1/2 min-w-[280px] flex flex-col gap-1.5",
-        label: "text-sm font-medium text-zinc-700 dark:text-zinc-300",
-        hint: "text-xs text-zinc-500 dark:text-zinc-400",
-        error: "text-xs text-red-600 dark:text-red-400",
-        section: "space-y-6",
-        sectionHead: "text-base font-semibold text-zinc-900 dark:text-zinc-100 border-b pb-2 mb-2 border-zinc-200 dark:border-zinc-700",
-    },
-    /** Tooltip bubble styles — used by the <Tooltip> component. */
-    tooltip: {
-        content: "z-50 px-2 py-1 text-xs font-medium rounded bg-zinc-900 dark:bg-zinc-100 text-white dark:text-zinc-900 shadow-sm",
-        arrow: "fill-zinc-900 dark:fill-zinc-100",
-    },
-    utilities: UTILITIES,
-    patterns: PATTERNS,
-    icon: ICON,
-    tab: TAB,
-    rating: RATING,
-    /** Breakpoints for reference (matches Tailwind defaults). */
-    breakpoints: {
-        sm: "640px",
-        md: "768px",
-        lg: "1024px",
-        xl: "1280px",
-        "2xl": "1536px",
-        "3xl": "1920px",
-    },
-    /** Global body/html base classes. */
-    base: {
-        body: 'bg-white dark:bg-slate-950 text-zinc-900 dark:text-zinc-100 antialiased font-[Inter,ui-sans-serif,system-ui,-apple-system,"Segoe_UI",Roboto,"Helvetica_Neue",Arial,sans-serif]',
-        html: "scroll-smooth",
-    },
-    /** Hero / homepage section layout tokens. */
-    homepage: {
-        heroMinH: "min-h-[clamp(420px,72vh,680px)]",
-        heroMinHMobile: "min-h-[clamp(120px,14vh,200px)]",
-    },
-    /** Carousel navigation tokens — shared by HeroCarousel and SectionCarousel. */
-    carousel: {
-        /** Standard responsive per-view configs for carousels */
-        perView: {
-            /** Default: 1 on mobile, 2 on sm, 3 on md+ */
-            default: { base: 1, sm: 2, md: 3 },
-            /** Standard: 1 on mobile, 3 on md, 4 on lg+ — the canonical homepage carousel preset */
-            standard: { base: 1, md: 3, lg: 4 },
-            /** Cards: 1 on mobile, 2 on sm, 3 on md, 4 on lg+ */
-            cards: { base: 1, sm: 2, md: 3, lg: 4 },
-            /** Compact cards: 2 on mobile, 3 on sm, 4 on md, 5 on xl+ */
-            compact: { base: 2, sm: 3, md: 4, xl: 5 },
-            /** Reviews: 1 on mobile, 2 on sm, 3 on md/lg, 4 on 2xl+ */
-            reviews: { base: 1, sm: 2, md: 3, lg: 3, "2xl": 4 },
-            /** Events: 1 on mobile, 2 on sm, 3 on md/lg */
-            events: { base: 1, sm: 2, md: 3, lg: 3 },
-        },
-        arrow: "w-10 h-10 rounded-2xl bg-white/85 dark:bg-slate-800/90 backdrop-blur-sm shadow-lg border border-zinc-300/70 dark:border-slate-600 text-zinc-800 dark:text-zinc-200 hover:-translate-y-0.5 hover:bg-white hover:shadow-xl hover:border-zinc-400 dark:hover:border-slate-500 active:scale-95 transition-all duration-200 flex items-center justify-center",
-        dotActive: "w-8 h-2 !min-h-0 rounded-full bg-white shadow-sm transition-all duration-500",
-        dotInactive: "w-2 h-2 !min-h-0 rounded-full bg-white/55 shadow-sm transition-all duration-500",
-    },
-};
+// THEME_CONSTANTS deleted 2026-06-17 in Phase 8 of the Three-Layer Style
+// System refactor. Use primitive variant props (<Card>, <Section>, <Stack>,
+// <Text>, <Heading>, <Badge>, …) for every styling intent. The handful of
+// legacy raw-className tokens still needed live in typed feature files
+// under `_internal/shared/styles/{page,themed,grid,skeleton}.ts`. The
+// individual token groups (THEMED, LAYOUT, TYPOGRAPHY, SPACING, GRID, PAGE,
+// INPUT, CARD, FLEX, POSITION, STATES, TRANSITIONS, SKELETON, MOTION, TEXT,
+// TOUCH, FLUID_GRID, UTILITIES, PATTERNS, ICON, TAB, RATING) remain exported
+// individually above for any caller that still needs a slice of the old map.

package/dist/tokens/themes/default-dark.d.ts

@@ -0,0 +1,10 @@
+import type { ThemeRecord } from "./types";
+/**
+ * Built-in dark theme — hot pink unified primary + slate surfaces.
+ * Mirrors the `[data-theme="dark"]` block in `appkit/src/tokens/tokens.css`.
+ * Cannot be deleted; can be cloned by the admin into a new theme.
+ *
+ * Drift between this file and `tokens.css` is detected by
+ * `scripts/audit-theme-drift.mjs`.
+ */
+export declare const DEFAULT_DARK_THEME: ThemeRecord;

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

@@ -0,0 +1,84 @@
+/**
+ * Built-in dark theme — hot pink unified primary + slate surfaces.
+ * Mirrors the `[data-theme="dark"]` block in `appkit/src/tokens/tokens.css`.
+ * Cannot be deleted; can be cloned by the admin into a new theme.
+ *
+ * Drift between this file and `tokens.css` is detected by
+ * `scripts/audit-theme-drift.mjs`.
+ */
+export const DEFAULT_DARK_THEME = {
+    id: "default-dark",
+    name: "Default Dark (Hot Pink)",
+    mode: "dark",
+    builtIn: true,
+    tokens: {
+        "appkit-color-primary": "#e91e8c",
+        "appkit-color-primary-50": "#fdf0f8",
+        "appkit-color-primary-100": "#fce2f2",
+        "appkit-color-primary-200": "#fac6e6",
+        "appkit-color-primary-300": "#f79dd2",
+        "appkit-color-primary-400": "#f063b9",
+        "appkit-color-primary-500": "#e91e8c",
+        "appkit-color-primary-600": "#d4107a",
+        "appkit-color-primary-700": "#b00d66",
+        "appkit-color-primary-800": "#900f56",
+        "appkit-color-primary-900": "#771249",
+        "appkit-color-primary-950": "#480525",
+        "appkit-color-secondary": "#e91e8c",
+        "appkit-color-secondary-50": "#fdf0f8",
+        "appkit-color-secondary-100": "#fce2f2",
+        "appkit-color-secondary-200": "#fac6e6",
+        "appkit-color-secondary-300": "#f79dd2",
+        "appkit-color-secondary-400": "#f063b9",
+        "appkit-color-secondary-500": "#e91e8c",
+        "appkit-color-secondary-600": "#d4107a",
+        "appkit-color-secondary-700": "#b00d66",
+        "appkit-color-secondary-800": "#900f56",
+        "appkit-color-secondary-900": "#771249",
+        "appkit-color-secondary-950": "#480525",
+        "appkit-color-bg": "#020617",
+        "appkit-color-surface": "#0f172a",
+        "appkit-color-surface-elevated": "rgba(15, 23, 42, 0.9)",
+        "appkit-color-surface-input": "rgba(30, 41, 59, 0.6)",
+        "appkit-color-border": "#334155",
+        "appkit-color-border-subtle": "rgba(30, 41, 59, 0.6)",
+        "appkit-color-text": "#fafafa",
+        "appkit-color-text-muted": "#a1a1aa",
+        "appkit-color-text-faint": "#71717a",
+        "appkit-color-success": "#34d399",
+        "appkit-color-success-surface": "rgba(6, 78, 59, 0.25)",
+        "appkit-color-warning": "#fbbf24",
+        "appkit-color-warning-surface": "#1c1508",
+        "appkit-color-error": "#f87171",
+        "appkit-color-error-surface": "rgba(127, 29, 29, 0.25)",
+        "appkit-color-info": "#38bdf8",
+        "appkit-color-info-surface": "rgba(12, 74, 110, 0.25)",
+        "appkit-color-focus-ring": "#f063b9",
+        "appkit-shadow-glow": "0 0 0 1px rgba(233,30,140,0.12), 0 4px 16px -4px rgba(233,30,140,0.22)",
+        "appkit-shadow-glow-pink": "0 0 0 1px rgba(233,30,140,0.14), 0 4px 20px -4px rgba(233,30,140,0.28)",
+        "appkit-font-display": "var(--font-display), \"Poppins\", ui-sans-serif, system-ui, sans-serif",
+        "appkit-font-sans": "var(--font-body), ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif",
+        "appkit-font-editorial": "var(--font-editorial), \"Georgia\", serif",
+        "appkit-font-mono": "ui-monospace, \"SFMono-Regular\", \"Cascadia Mono\", \"Consolas\", monospace",
+    },
+    gradients: {
+        brand: "linear-gradient(to right, var(--appkit-color-primary), var(--appkit-color-primary-400))",
+        "brand-tri": "linear-gradient(to right, var(--appkit-color-primary), var(--appkit-color-secondary), var(--appkit-color-info))",
+        accent: "linear-gradient(to right, var(--appkit-color-info), var(--appkit-color-primary))",
+        "accent-divider": "linear-gradient(to right, transparent, var(--appkit-color-primary), transparent)",
+        "page-header": "linear-gradient(to bottom right, rgba(233,30,140,0.10), transparent 60%, transparent)",
+        "section-warm": "linear-gradient(to bottom right, var(--appkit-color-warning-surface), transparent)",
+        "section-cool": "linear-gradient(to bottom right, rgba(56,189,248,0.10), transparent)",
+        "section-mesh": "radial-gradient(ellipse at top, rgba(233,30,140,0.10), var(--appkit-color-surface), rgba(56,189,248,0.08))",
+        "accent-banner": "linear-gradient(to right, var(--appkit-color-primary), var(--appkit-color-info))",
+        promotion: "linear-gradient(to bottom right, var(--appkit-color-error), var(--appkit-color-primary), var(--appkit-color-warning))",
+        spotlight: "linear-gradient(to bottom right, rgba(56,189,248,0.10), var(--appkit-color-bg), rgba(56,189,248,0.10))",
+        "whatsapp-card": "linear-gradient(to bottom right, var(--appkit-color-success), var(--appkit-color-success))",
+        glass: "linear-gradient(to bottom right, color-mix(in srgb, var(--appkit-color-surface) 85%, transparent), color-mix(in srgb, var(--appkit-color-surface) 65%, transparent))",
+        "card-indigo": "linear-gradient(to bottom right, rgba(233,30,140,0.10), var(--appkit-color-surface), var(--appkit-color-surface))",
+        "card-teal": "linear-gradient(to bottom right, rgba(56,189,248,0.10), var(--appkit-color-surface), var(--appkit-color-surface))",
+        "card-amber": "linear-gradient(to bottom right, var(--appkit-color-warning-surface), var(--appkit-color-surface), var(--appkit-color-surface))",
+        "card-rose": "linear-gradient(to bottom right, var(--appkit-color-error-surface), var(--appkit-color-surface), var(--appkit-color-surface))",
+        logo: "linear-gradient(to right, var(--appkit-color-primary-700) 0%, var(--appkit-color-primary-500) 55%, var(--appkit-color-secondary-400) 100%)",
+    },
+};

package/dist/tokens/themes/default-light.d.ts

@@ -0,0 +1,10 @@
+import type { ThemeRecord } from "./types";
+/**
+ * Built-in light theme — cobalt blue primary + lime green secondary.
+ * Mirrors the `:root` block in `appkit/src/tokens/tokens.css`.
+ * Cannot be deleted; can be cloned by the admin into a new theme.
+ *
+ * Drift between this file and `tokens.css` is detected by
+ * `scripts/audit-theme-drift.mjs`.
+ */
+export declare const DEFAULT_LIGHT_THEME: ThemeRecord;

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

@@ -0,0 +1,87 @@
+/**
+ * Built-in light theme — cobalt blue primary + lime green secondary.
+ * Mirrors the `:root` block in `appkit/src/tokens/tokens.css`.
+ * Cannot be deleted; can be cloned by the admin into a new theme.
+ *
+ * Drift between this file and `tokens.css` is detected by
+ * `scripts/audit-theme-drift.mjs`.
+ */
+export const DEFAULT_LIGHT_THEME = {
+    id: "default-light",
+    name: "Default Light (Cobalt + Lime)",
+    mode: "light",
+    builtIn: true,
+    tokens: {
+        "appkit-color-primary": "#3570fc",
+        "appkit-color-primary-50": "#eef5ff",
+        "appkit-color-primary-100": "#d9e8ff",
+        "appkit-color-primary-200": "#bcd4ff",
+        "appkit-color-primary-300": "#8eb9ff",
+        "appkit-color-primary-400": "#5992ff",
+        "appkit-color-primary-500": "#3570fc",
+        "appkit-color-primary-600": "#1a55f2",
+        "appkit-color-primary-700": "#1343de",
+        "appkit-color-primary-800": "#1536b4",
+        "appkit-color-primary-900": "#18318e",
+        "appkit-color-primary-950": "#111e58",
+        "appkit-color-secondary": "#65c408",
+        "appkit-color-secondary-50": "#f3ffe3",
+        "appkit-color-secondary-100": "#e4ffc5",
+        "appkit-color-secondary-200": "#c8ff90",
+        "appkit-color-secondary-300": "#a3f550",
+        "appkit-color-secondary-400": "#84e122",
+        "appkit-color-secondary-500": "#65c408",
+        "appkit-color-secondary-600": "#509c02",
+        "appkit-color-secondary-700": "#3e7708",
+        "appkit-color-secondary-800": "#345e0d",
+        "appkit-color-secondary-900": "#2c5011",
+        "appkit-color-secondary-950": "#142d03",
+        "appkit-color-cobalt": "#3570fc",
+        "appkit-color-accent": "#8393b2",
+        "appkit-color-bg": "#fafafa",
+        "appkit-color-surface": "#ffffff",
+        "appkit-color-surface-elevated": "#ffffff",
+        "appkit-color-surface-input": "#ffffff",
+        "appkit-color-border": "#e4e4e7",
+        "appkit-color-border-subtle": "#f4f4f5",
+        "appkit-color-text": "#18181b",
+        "appkit-color-text-muted": "#71717a",
+        "appkit-color-text-faint": "#a1a1aa",
+        "appkit-color-text-on-primary": "#ffffff",
+        "appkit-color-success": "#059669",
+        "appkit-color-success-surface": "#ecfdf5",
+        "appkit-color-warning": "#d97706",
+        "appkit-color-warning-surface": "#fffbeb",
+        "appkit-color-error": "#dc2626",
+        "appkit-color-error-surface": "#fef2f2",
+        "appkit-color-info": "#0284c7",
+        "appkit-color-info-surface": "#f0f9ff",
+        "appkit-color-focus-ring": "#3570fc",
+        "appkit-shadow-glow": "0 0 0 1px rgba(53,112,252,0.10), 0 4px 16px -4px rgba(53,112,252,0.20)",
+        "appkit-shadow-glow-pink": "0 0 0 1px rgba(233,30,140,0.12), 0 4px 16px -4px rgba(233,30,140,0.22)",
+        "appkit-font-display": "var(--font-display), \"Poppins\", ui-sans-serif, system-ui, sans-serif",
+        "appkit-font-sans": "var(--font-body), ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif",
+        "appkit-font-editorial": "var(--font-editorial), \"Georgia\", serif",
+        "appkit-font-mono": "ui-monospace, \"SFMono-Regular\", \"Cascadia Mono\", \"Consolas\", monospace",
+    },
+    gradients: {
+        brand: "linear-gradient(to right, var(--appkit-color-primary), var(--appkit-color-secondary))",
+        "brand-tri": "linear-gradient(to right, var(--appkit-color-primary), var(--appkit-color-secondary), var(--appkit-color-accent))",
+        accent: "linear-gradient(to right, var(--appkit-color-cobalt-500, var(--appkit-color-primary)), var(--appkit-color-secondary-500, var(--appkit-color-secondary)))",
+        "accent-divider": "linear-gradient(to right, transparent, var(--appkit-color-primary), transparent)",
+        "page-header": "linear-gradient(to bottom right, var(--appkit-color-primary-50), transparent 60%, transparent)",
+        "section-warm": "linear-gradient(to bottom right, var(--appkit-color-warning-surface), var(--appkit-color-surface))",
+        "section-cool": "linear-gradient(to bottom right, var(--appkit-color-primary-50), var(--appkit-color-info-surface))",
+        "section-mesh": "radial-gradient(ellipse at top, var(--appkit-color-primary-50), var(--appkit-color-surface), var(--appkit-color-secondary-50))",
+        "accent-banner": "linear-gradient(to right, var(--appkit-color-primary), var(--appkit-color-secondary))",
+        promotion: "linear-gradient(to bottom right, var(--appkit-color-error), var(--appkit-color-primary), var(--appkit-color-warning))",
+        spotlight: "linear-gradient(to bottom right, var(--appkit-color-info-surface), var(--appkit-color-bg), var(--appkit-color-info-surface))",
+        "whatsapp-card": "linear-gradient(to bottom right, var(--appkit-color-success), var(--appkit-color-success))",
+        glass: "linear-gradient(to bottom right, color-mix(in srgb, var(--appkit-color-surface) 85%, transparent), color-mix(in srgb, var(--appkit-color-surface) 65%, transparent))",
+        "card-indigo": "linear-gradient(to bottom right, var(--appkit-color-primary-50), var(--appkit-color-surface), var(--appkit-color-surface))",
+        "card-teal": "linear-gradient(to bottom right, var(--appkit-color-secondary-50), var(--appkit-color-surface), var(--appkit-color-surface))",
+        "card-amber": "linear-gradient(to bottom right, var(--appkit-color-warning-surface), var(--appkit-color-surface), var(--appkit-color-surface))",
+        "card-rose": "linear-gradient(to bottom right, var(--appkit-color-error-surface), var(--appkit-color-surface), var(--appkit-color-surface))",
+        logo: "linear-gradient(to right, var(--appkit-color-primary-700) 0%, var(--appkit-color-primary-500) 55%, var(--appkit-color-secondary-400) 100%)",
+    },
+};

package/dist/tokens/themes/index.d.ts

@@ -0,0 +1,15 @@
+import { DEFAULT_DARK_THEME } from "./default-dark";
+import { DEFAULT_LIGHT_THEME } from "./default-light";
+import type { ThemeMode, ThemeRecord } from "./types";
+export { DEFAULT_LIGHT_THEME, DEFAULT_DARK_THEME };
+export { REQUIRED_GRADIENT_KEYS, REQUIRED_THEME_TOKENS } from "./required";
+export type { RequiredThemeToken } from "./required";
+export type { GradientKey, ThemeMode, ThemeRecord } from "./types";
+/** Built-in themes that ship with appkit; admin cannot delete these. */
+export declare const BUILT_IN_THEMES: readonly ThemeRecord[];
+/**
+ * Find the default built-in theme for a given mode.
+ * Used as a fallback when `siteSettings.theme.default{Light,Dark}ThemeId`
+ * points at a deleted record.
+ */
+export declare function getDefaultBuiltInTheme(mode: ThemeMode): ThemeRecord;

package/dist/tokens/themes/index.js

@@ -0,0 +1,17 @@
+import { DEFAULT_DARK_THEME } from "./default-dark";
+import { DEFAULT_LIGHT_THEME } from "./default-light";
+export { DEFAULT_LIGHT_THEME, DEFAULT_DARK_THEME };
+export { REQUIRED_GRADIENT_KEYS, REQUIRED_THEME_TOKENS } from "./required";
+/** Built-in themes that ship with appkit; admin cannot delete these. */
+export const BUILT_IN_THEMES = [
+    DEFAULT_LIGHT_THEME,
+    DEFAULT_DARK_THEME,
+];
+/**
+ * Find the default built-in theme for a given mode.
+ * Used as a fallback when `siteSettings.theme.default{Light,Dark}ThemeId`
+ * points at a deleted record.
+ */
+export function getDefaultBuiltInTheme(mode) {
+    return mode === "dark" ? DEFAULT_DARK_THEME : DEFAULT_LIGHT_THEME;
+}

package/dist/tokens/themes/required.d.ts

@@ -0,0 +1,15 @@
+import type { GradientKey } from "./types";
+/**
+ * Catalogue of every CSS custom property a theme record may set.
+ *
+ * The `audit-theme-drift` audit verifies that `default-light.ts` and
+ * `default-dark.ts` declare every required token, and that every value in
+ * their `tokens` map matches the corresponding block in `tokens.css`.
+ *
+ * Admin-authored themes are validated against this list via a Zod schema —
+ * unknown keys are rejected; missing keys fall back to the active mode's
+ * default theme value (so a theme can override only a subset).
+ */
+export declare const REQUIRED_THEME_TOKENS: readonly ["appkit-color-primary", "appkit-color-primary-50", "appkit-color-primary-100", "appkit-color-primary-200", "appkit-color-primary-300", "appkit-color-primary-400", "appkit-color-primary-500", "appkit-color-primary-600", "appkit-color-primary-700", "appkit-color-primary-800", "appkit-color-primary-900", "appkit-color-primary-950", "appkit-color-secondary", "appkit-color-secondary-50", "appkit-color-secondary-100", "appkit-color-secondary-200", "appkit-color-secondary-300", "appkit-color-secondary-400", "appkit-color-secondary-500", "appkit-color-secondary-600", "appkit-color-secondary-700", "appkit-color-secondary-800", "appkit-color-secondary-900", "appkit-color-secondary-950", "appkit-color-bg", "appkit-color-surface", "appkit-color-surface-elevated", "appkit-color-surface-input", "appkit-color-border", "appkit-color-border-subtle", "appkit-color-text", "appkit-color-text-muted", "appkit-color-text-faint", "appkit-color-text-on-primary", "appkit-color-success", "appkit-color-success-surface", "appkit-color-warning", "appkit-color-warning-surface", "appkit-color-error", "appkit-color-error-surface", "appkit-color-info", "appkit-color-info-surface", "appkit-color-focus-ring", "appkit-shadow-glow", "appkit-shadow-glow-pink", "appkit-font-display", "appkit-font-sans", "appkit-font-editorial", "appkit-font-mono"];
+export type RequiredThemeToken = (typeof REQUIRED_THEME_TOKENS)[number];
+export declare const REQUIRED_GRADIENT_KEYS: readonly GradientKey[];

package/dist/tokens/themes/required.js

@@ -0,0 +1,89 @@
+/**
+ * Catalogue of every CSS custom property a theme record may set.
+ *
+ * The `audit-theme-drift` audit verifies that `default-light.ts` and
+ * `default-dark.ts` declare every required token, and that every value in
+ * their `tokens` map matches the corresponding block in `tokens.css`.
+ *
+ * Admin-authored themes are validated against this list via a Zod schema —
+ * unknown keys are rejected; missing keys fall back to the active mode's
+ * default theme value (so a theme can override only a subset).
+ */
+export const REQUIRED_THEME_TOKENS = [
+    // Brand
+    "appkit-color-primary",
+    "appkit-color-primary-50",
+    "appkit-color-primary-100",
+    "appkit-color-primary-200",
+    "appkit-color-primary-300",
+    "appkit-color-primary-400",
+    "appkit-color-primary-500",
+    "appkit-color-primary-600",
+    "appkit-color-primary-700",
+    "appkit-color-primary-800",
+    "appkit-color-primary-900",
+    "appkit-color-primary-950",
+    "appkit-color-secondary",
+    "appkit-color-secondary-50",
+    "appkit-color-secondary-100",
+    "appkit-color-secondary-200",
+    "appkit-color-secondary-300",
+    "appkit-color-secondary-400",
+    "appkit-color-secondary-500",
+    "appkit-color-secondary-600",
+    "appkit-color-secondary-700",
+    "appkit-color-secondary-800",
+    "appkit-color-secondary-900",
+    "appkit-color-secondary-950",
+    // Semantic surface
+    "appkit-color-bg",
+    "appkit-color-surface",
+    "appkit-color-surface-elevated",
+    "appkit-color-surface-input",
+    "appkit-color-border",
+    "appkit-color-border-subtle",
+    // Semantic text
+    "appkit-color-text",
+    "appkit-color-text-muted",
+    "appkit-color-text-faint",
+    "appkit-color-text-on-primary",
+    // Status
+    "appkit-color-success",
+    "appkit-color-success-surface",
+    "appkit-color-warning",
+    "appkit-color-warning-surface",
+    "appkit-color-error",
+    "appkit-color-error-surface",
+    "appkit-color-info",
+    "appkit-color-info-surface",
+    // Focus
+    "appkit-color-focus-ring",
+    // Glow shadow (theme-tinted; dimensional shadow stays in tokens layer)
+    "appkit-shadow-glow",
+    "appkit-shadow-glow-pink",
+    // Fonts
+    "appkit-font-display",
+    "appkit-font-sans",
+    "appkit-font-editorial",
+    "appkit-font-mono",
+];
+export const REQUIRED_GRADIENT_KEYS = [
+    "brand",
+    "brand-tri",
+    "accent",
+    "accent-divider",
+    "page-header",
+    "section-warm",
+    "section-cool",
+    "section-mesh",
+    "accent-banner",
+    "promotion",
+    "spotlight",
+    "whatsapp-card",
+    "glass",
+    "card-indigo",
+    "card-teal",
+    "card-amber",
+    "card-rose",
+    "logo",
+];

package/dist/tokens/themes/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Theme preset shape.
+ *
+ * A theme record is a token override map applied at runtime by `ThemeProvider`.
+ * Every theme declares its `mode` (light / dark — picked by the user's preference)
+ * and a `tokens` map keyed by CSS custom-property name (without the `--` prefix).
+ *
+ * Theme records are admin-configurable via Site Settings → Themes. The two
+ * built-in themes (`default-light`, `default-dark`) are pinned and cannot be
+ * deleted; they are the source of truth for the existing brand palette.
+ */
+export type ThemeMode = "light" | "dark";
+export interface ThemeRecord {
+    /** Stable id used as `<html data-theme={id}>` and as the persisted reference. */
+    id: string;
+    /** Human-readable name surfaced in the admin editor. */
+    name: string;
+    /** Which user-facing mode this theme applies to. */
+    mode: ThemeMode;
+    /** `true` for `default-light` / `default-dark`; admin cannot delete or edit colour-by-colour. */
+    builtIn: boolean;
+    /**
+     * CSS-variable overrides, keyed by token name (without leading `--`).
+     * Example key: `"appkit-color-primary"` → value: `"#3570fc"`.
+     *
+     * Keys MUST come from the catalogue declared in `./required.ts`.
+     */
+    tokens: Readonly<Record<string, string>>;
+    /**
+     * Gradient overrides keyed by gradient slot id.
+     * Each value is a complete CSS gradient expression so the admin can vary
+     * direction, stops, opacity, and easing — not just stop colours.
+     */
+    gradients: Readonly<Record<GradientKey, string>>;
+}
+/** The named gradient slots every theme must declare. */
+export type GradientKey = "brand" | "brand-tri" | "accent" | "accent-divider" | "page-header" | "section-warm" | "section-cool" | "section-mesh" | "accent-banner" | "promotion" | "spotlight" | "whatsapp-card" | "glass" | "card-indigo" | "card-teal" | "card-amber" | "card-rose" | "logo";

package/dist/tokens/themes/types.js

@@ -0,0 +1 @@
+export {};