astralkit 0.5.0 → 0.7.0

package/lib/presets/theme-palettes.js

@@ -0,0 +1,720 @@
+/**
+ * Curated 60-30-10 Theme Palettes for AstralKit Theme Builder
+ *
+ * Each palette follows the 60-30-10 rule:
+ * - 60% Dominant: background, surface (large areas)
+ * - 30% Secondary: cards, sidebar, secondary surfaces
+ * - 10% Accent: CTAs, links, highlights, primary actions
+ *
+ * Token mapping:
+ * - background: Page background (60%)
+ * - surface: Card/panel backgrounds (60% variant)
+ * - foreground: Primary text color
+ * - foregroundMuted: Secondary/body text
+ * - primary: Main accent / CTA color (10%)
+ * - secondary: Supporting color (30%)
+ * - accent: Highlight / tertiary color
+ * - border: Divider and border color
+ * - ring: Focus ring color (usually primary-based)
+ * - muted: Muted/disabled backgrounds
+ * - destructive: Error/danger color
+ */
+const MODE_BASE_COLORS = {
+    light: {
+        background: '#FAFAFA',
+        surface: '#FFFFFF',
+        foreground: '#171717',
+        foregroundMuted: '#525252',
+        border: '#DEE2E6',
+        muted: '#F5F5F5',
+    },
+    dark: {
+        background: '#18191B',
+        surface: '#111113',
+        foreground: '#F4F4F5',
+        foregroundMuted: '#A1A1AA',
+        border: '#2C2D30',
+        muted: '#1E1F21',
+    },
+};
+export const THEME_PALETTES = [
+    /* ─── Light Palettes ─── */
+    {
+        id: 'astral-default',
+        name: 'AstralKit',
+        description: 'The default AstralKit violet theme',
+        mode: 'light',
+        colors: {
+            background: '#FAF9F7',
+            surface: '#FFFFFF',
+            foreground: '#150A35',
+            foregroundMuted: '#544D6B',
+            primary: '#6933FF',
+            secondary: '#7C3AED',
+            accent: '#3523BD',
+            onAccent: '#FFFFFF',
+            border: '#E6E3EE',
+            ring: '#A585FF',
+            muted: '#F4F2F9',
+            destructive: '#DC2626',
+            brandGradient: {
+                from: '#A585FF',
+                via: '#6933FF',
+                to: '#3523BD',
+                hoverFrom: '#C4B5FD',
+                hoverVia: '#875CFF',
+                hoverTo: '#2C1CB3',
+            },
+        },
+    },
+    {
+        id: 'warm-earth',
+        name: 'Warm Earth',
+        description: 'Teal primary with coral-red highlights — Happy Hues #8',
+        mode: 'light',
+        colors: {
+            background: '#F8F5F2',
+            surface: '#FFFFFF',
+            foreground: '#232323',
+            foregroundMuted: '#222525',
+            primary: '#078080',
+            secondary: '#F45D48',
+            accent: '#F45D48',
+            border: '#E8E2DB',
+            ring: '#078080',
+            muted: '#FEEFE8',
+            destructive: '#F45D48',
+        },
+    },
+    {
+        id: 'slate-pro',
+        name: 'Slate Pro',
+        description: 'Professional gray with blue accent',
+        mode: 'light',
+        colors: {
+            background: '#F8FAFC',
+            surface: '#FFFFFF',
+            foreground: '#0F172A',
+            foregroundMuted: '#64748B',
+            primary: '#2563EB',
+            secondary: '#E2E8F0',
+            accent: '#7C3AED',
+            border: '#E2E8F0',
+            ring: '#2563EB',
+            muted: '#F1F5F9',
+            destructive: '#DC2626',
+        },
+    },
+    {
+        id: 'indigo-craft',
+        name: 'Indigo Craft',
+        description: 'Warm neutral with indigo primary',
+        mode: 'light',
+        colors: {
+            background: '#FAFAF9',
+            surface: '#FFFFFF',
+            foreground: '#1C1917',
+            foregroundMuted: '#78716C',
+            primary: '#4F46E5',
+            secondary: '#EEF2FF',
+            accent: '#EC4899',
+            border: '#E7E5E4',
+            ring: '#4F46E5',
+            muted: '#F5F5F4',
+            destructive: '#DC2626',
+        },
+    },
+    {
+        id: 'medtrackr',
+        name: 'MedTrackr Green',
+        description: 'Clean white with emerald primary and mint washes — healthcare CRM',
+        mode: 'light',
+        colors: {
+            background: '#F7F9F8',
+            surface: '#FFFFFF',
+            foreground: '#17211D',
+            foregroundMuted: '#5B6661',
+            primary: '#0FA47A',
+            secondary: '#0FA47A',
+            accent: '#0FA47A',
+            border: '#E2E8E5',
+            ring: '#0FA47A',
+            muted: '#ECF2EF',
+            destructive: '#E5484D',
+        },
+    },
+    {
+        id: 'periwinkle',
+        name: 'Periwinkle',
+        description: 'Lavender-white canvas with vivid periwinkle — fitness SaaS',
+        mode: 'light',
+        colors: {
+            background: '#F4F3FB',
+            surface: '#FFFFFF',
+            foreground: '#1B1A2E',
+            foregroundMuted: '#5A5874',
+            primary: '#6F5CF1',
+            secondary: '#6F5CF1',
+            accent: '#6F5CF1',
+            border: '#E4E2F0',
+            ring: '#6F5CF1',
+            muted: '#ECEAF8',
+            destructive: '#E5484D',
+        },
+    },
+    {
+        id: 'scout-cyan',
+        name: 'Scout Cyan',
+        description: 'Crisp white with deep sky-cyan — referral dashboard',
+        mode: 'light',
+        colors: {
+            background: '#F6FAFC',
+            surface: '#FFFFFF',
+            foreground: '#14262D',
+            foregroundMuted: '#587077',
+            primary: '#0E96C4',
+            secondary: '#0E96C4',
+            accent: '#0E96C4',
+            border: '#DEE9EE',
+            ring: '#0E96C4',
+            muted: '#EAF3F7',
+            destructive: '#E5484D',
+        },
+    },
+    /* ─── Brand Design System Palettes ─── */
+    {
+        id: 'pulse',
+        name: 'Pulse',
+        description: 'Bone neutrals, ink CTAs, volt-lime selection — fitness app energy',
+        mode: 'light',
+        colors: {
+            background: '#F3F3EF',
+            surface: '#FFFFFF',
+            foreground: '#0B0B0B',
+            foregroundMuted: '#55564F',
+            primary: '#D7FA4B',
+            secondary: '#D7FA4B',
+            accent: '#D7FA4B',
+            border: '#E4E4DC',
+            ring: '#D7FA4B',
+            muted: '#ECEDE5',
+            destructive: '#F04438',
+            sliderFill: '#0B0B0B',
+            sliderRing: '#0B0B0B',
+        },
+    },
+    {
+        id: 'logozap',
+        name: 'LogoZap',
+        description: 'Warm paper with Zap Blue accent — brand design system experiment',
+        mode: 'light',
+        colors: {
+            background: '#FAFAF7',
+            surface: '#FFFFFF',
+            foreground: '#0A0A0A',
+            foregroundMuted: '#5A5A5A',
+            primary: '#1E7BFF',
+            secondary: '#CFE3FF',
+            accent: '#0B4FD9',
+            border: '#E4E2DA',
+            ring: '#1E7BFF',
+            muted: '#F0EFEA',
+            destructive: '#EF4444',
+        },
+    },
+    /* ─── Dark Palettes ─── */
+    {
+        id: 'volt-noir',
+        name: 'Volt Noir',
+        description: 'True black with volt-lime CTAs — dark sibling of Pulse',
+        mode: 'dark',
+        colors: {
+            background: '#0A0A0A',
+            surface: '#161616',
+            foreground: '#F2F2EF',
+            foregroundMuted: '#A6A6A0',
+            primary: '#D7F94C',
+            secondary: '#D7F94C',
+            accent: '#D7F94C',
+            border: '#262626',
+            ring: '#D7F94C',
+            muted: '#1F1F1F',
+            destructive: '#FF5A48',
+        },
+    },
+    {
+        id: 'neon-noir',
+        name: 'Neon Noir',
+        description: 'Deep violet-black with periwinkle glow — neon casino energy',
+        mode: 'dark',
+        colors: {
+            background: '#0D0B16',
+            surface: '#171327',
+            foreground: '#EDEAF6',
+            foregroundMuted: '#9D97B8',
+            primary: '#8B7CF7',
+            secondary: '#8B7CF7',
+            accent: '#8B7CF7',
+            border: '#2B2542',
+            ring: '#8B7CF7',
+            muted: '#1E1936',
+            destructive: '#FF4D6A',
+        },
+    },
+    {
+        id: 'astral-ultraviolet',
+        name: 'Astral Ultraviolet',
+        description: 'Deep violet-black with rich purple gradients and a small coral pulse',
+        mode: 'dark',
+        colors: {
+            background: '#070510',
+            surface: '#111024',
+            foreground: '#F8F5FF',
+            foregroundMuted: '#AAA2C8',
+            primary: '#6D5DFF',
+            secondary: '#A855F7',
+            accent: '#FF7A5C',
+            border: '#2B2545',
+            ring: '#6D5DFF',
+            muted: '#1B1830',
+            destructive: '#FF5A6E',
+            brandGradient: {
+                from: '#A78BFA',
+                via: '#6D5DFF',
+                to: '#5B21B6',
+                hoverFrom: '#C4B5FD',
+                hoverVia: '#8B7CFF',
+                hoverTo: '#6D28D9',
+            },
+        },
+        effects: {
+            glowPrimary: '#6D5DFF',
+            glowSecondary: '#A855F7',
+            glowTertiary: '#7C3AED',
+            glowWarm: '#FF7A5C',
+            meshBase: '#070510',
+        },
+    },
+    {
+        id: 'plasma-orbit',
+        name: 'Plasma Orbit',
+        description: 'Black-blue dashboard dark with electric indigo, cyan, and violet glow',
+        mode: 'dark',
+        colors: {
+            background: '#030712',
+            surface: '#0B1020',
+            foreground: '#F4F8FF',
+            foregroundMuted: '#9AA8C7',
+            primary: '#16A3FF',
+            secondary: '#6D5DFF',
+            accent: '#22D3EE',
+            border: '#1A2440',
+            ring: '#16A3FF',
+            muted: '#101831',
+            destructive: '#FF5A7A',
+            brandGradient: {
+                from: '#22D3EE',
+                via: '#16A3FF',
+                to: '#6D5DFF',
+                hoverFrom: '#67E8F9',
+                hoverVia: '#38BDF8',
+                hoverTo: '#8B7CFF',
+            },
+        },
+        effects: {
+            glowPrimary: '#16A3FF',
+            glowSecondary: '#22D3EE',
+            glowTertiary: '#6D5DFF',
+            glowWarm: '#8B5CF6',
+            meshBase: '#030712',
+        },
+    },
+    {
+        id: 'lunar-citron',
+        name: 'Lunar Citron',
+        description: 'Obsidian surfaces with soft lavender depth and sharp citron energy',
+        mode: 'dark',
+        colors: {
+            background: '#090A0D',
+            surface: '#15141B',
+            foreground: '#F7F7EC',
+            foregroundMuted: '#A8A49A',
+            primary: '#E9FF5B',
+            secondary: '#8B7CF7',
+            accent: '#E9FF5B',
+            border: '#2C2A33',
+            ring: '#E9FF5B',
+            muted: '#1E1D24',
+            destructive: '#FF6B5F',
+            brandGradient: {
+                from: '#F4FF8C',
+                via: '#E9FF5B',
+                to: '#B6D932',
+                hoverFrom: '#F8FFAD',
+                hoverVia: '#EEFF72',
+                hoverTo: '#CBEA44',
+            },
+        },
+        effects: {
+            glowPrimary: '#E9FF5B',
+            glowSecondary: '#8B7CF7',
+            glowTertiary: '#C084FC',
+            glowWarm: '#FF9F68',
+            meshBase: '#090A0D',
+        },
+    },
+    {
+        id: 'magenta-circuit',
+        name: 'Magenta Circuit',
+        description: 'Charcoal-black with hot magenta, violet circuitry, and small data-green hits',
+        mode: 'dark',
+        colors: {
+            background: '#08070A',
+            surface: '#141016',
+            foreground: '#FFF7FB',
+            foregroundMuted: '#B7A9B7',
+            primary: '#E43DDC',
+            secondary: '#8B5CF6',
+            accent: '#FF5AA8',
+            border: '#2C1C2E',
+            ring: '#E43DDC',
+            muted: '#1F1721',
+            destructive: '#FF4D6D',
+            brandGradient: {
+                from: '#FF5FE7',
+                via: '#D946EF',
+                to: '#7C3AED',
+                hoverFrom: '#FF8CF0',
+                hoverVia: '#E879F9',
+                hoverTo: '#8B5CF6',
+            },
+        },
+        effects: {
+            glowPrimary: '#E43DDC',
+            glowSecondary: '#8B5CF6',
+            glowTertiary: '#FF5AA8',
+            glowWarm: '#22C55E',
+            meshBase: '#08070A',
+        },
+    },
+    {
+        id: 'deep-teal',
+        name: 'Deep Teal',
+        description: 'Dark ocean teal with golden accent — Happy Hues #10',
+        mode: 'dark',
+        colors: {
+            background: '#004643',
+            surface: '#001E1D',
+            foreground: '#FFFFFE',
+            foregroundMuted: '#ABD1C6',
+            primary: '#F9BC60',
+            secondary: '#ABD1C6',
+            accent: '#E16162',
+            border: '#0A5854',
+            ring: '#F9BC60',
+            muted: '#0A5854',
+            destructive: '#E16162',
+        },
+    },
+];
+/* ─── Color utility: lighten/darken hex ─── */
+function hexToRgb(hex) {
+    const h = hex.replace('#', '');
+    return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+}
+function rgbToHex(r, g, b) {
+    return '#' + [r, g, b].map(v => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0')).join('');
+}
+function mixColor(hex, target, amount) {
+    const [r1, g1, b1] = hexToRgb(hex);
+    const [r2, g2, b2] = hexToRgb(target);
+    return rgbToHex(r1 + (r2 - r1) * amount, g1 + (g2 - g1) * amount, b1 + (b2 - b1) * amount);
+}
+function lighten(hex, amount) { return mixColor(hex, '#FFFFFF', amount); }
+function darken(hex, amount) { return mixColor(hex, '#000000', amount); }
+/** Relative luminance (0 dark – 1 light) for picking readable "on" colors. */
+function luminance(hex) {
+    const [r, g, b] = hexToRgb(hex).map((v) => {
+        const s = v / 255;
+        return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+/** WCAG contrast ratio between two hex colors. */
+function contrastRatio(a, b) {
+    const l1 = luminance(a);
+    const l2 = luminance(b);
+    return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+}
+/** Ink-or-paper text for an arbitrary fill: dark text on light fills, light text on dark fills. */
+function onColor(fill, darkOption, lightOption) {
+    return luminance(fill) > 0.45 ? darkOption : lightOption;
+}
+/**
+ * Keeps the chosen brand colors while swapping surface, text, border, and muted
+ * scaffolding to the current UI mode.
+ */
+export function resolvePaletteForMode(palette, mode) {
+    if (palette.mode === mode)
+        return palette;
+    const base = MODE_BASE_COLORS[mode];
+    return {
+        ...palette,
+        mode,
+        colors: {
+            ...palette.colors,
+            background: base.background,
+            surface: base.surface,
+            foreground: base.foreground,
+            foregroundMuted: base.foregroundMuted,
+            border: base.border,
+            muted: base.muted,
+        },
+    };
+}
+/**
+ * Maps a ThemePalette to the actual --color-ak-* CSS variables
+ * that AstralKit components consume.
+ *
+ * This is the critical bridge between our 60-30-10 palette
+ * and the component design token system.
+ */
+export function paletteToAkVariables(palette, options) {
+    const resolvedPalette = options?.mode ? resolvePaletteForMode(palette, options.mode) : palette;
+    const c = resolvedPalette.colors;
+    const p = c.primary;
+    const isDark = resolvedPalette.mode === 'dark';
+    // Readable text on primary/accent fills regardless of how light they are
+    // (volt lime, yellow, etc. need ink text — not the background color).
+    const ink = isDark ? c.background : c.foreground;
+    const paper = isDark ? c.foreground : c.surface;
+    const onPrimary = onColor(p, ink, paper);
+    const secondary = c.secondary || c.accent;
+    const onAccent = c.onAccent ?? onColor(c.accent, ink, paper);
+    const onSecondary = onColor(secondary, ink, paper);
+    const accentSoft = mixColor(c.accent, c.surface, isDark ? 0.78 : 0.82);
+    const secondaryContainer = mixColor(secondary, c.surface, isDark ? 0.78 : 0.82);
+    const primaryContainer = isDark ? mixColor(p, c.surface, 0.76) : lighten(p, 0.88);
+    const onAccentSoft = onColor(accentSoft, ink, paper);
+    const onSecondaryContainer = onColor(secondaryContainer, ink, paper);
+    const onPrimaryContainer = onColor(primaryContainer, ink, paper);
+    const selectionInk = contrastRatio(p, primaryContainer) >= 4.5 ? p : onPrimaryContainer;
+    const gradientFrom = c.brandGradient?.from ?? (isDark ? lighten(p, 0.18) : lighten(p, 0.32));
+    const gradientVia = c.brandGradient?.via ?? p;
+    const gradientTo = c.brandGradient?.to ?? (isDark ? darken(p, 0.08) : darken(p, 0.26));
+    const gradientHoverFrom = c.brandGradient?.hoverFrom ?? (isDark ? lighten(p, 0.28) : lighten(p, 0.42));
+    const gradientHoverVia = c.brandGradient?.hoverVia ?? (isDark ? lighten(p, 0.08) : lighten(p, 0.12));
+    const gradientHoverTo = c.brandGradient?.hoverTo ?? (isDark ? darken(p, 0.02) : darken(p, 0.34));
+    const glowPrimary = resolvedPalette.effects?.glowPrimary ?? (isDark ? lighten(p, 0.18) : p);
+    const glowSecondary = resolvedPalette.effects?.glowSecondary ?? secondary;
+    const glowTertiary = resolvedPalette.effects?.glowTertiary ?? c.accent;
+    const glowWarm = resolvedPalette.effects?.glowWarm ?? c.accent;
+    const meshBase = resolvedPalette.effects?.meshBase ?? c.background;
+    const surface2 = c.muted || mixColor(c.background, c.foreground, 0.035);
+    const surface3 = mixColor(c.background, c.foreground, isDark ? 0.11 : 0.07);
+    const surface4 = mixColor(c.background, c.foreground, isDark ? 0.16 : 0.105);
+    const border = isDark ? 'rgba(255,255,255,0.10)' : c.border;
+    const borderSubtle = isDark ? 'rgba(255,255,255,0.06)' : mixColor(c.border, c.background, 0.5);
+    const borderStrong = isDark ? 'rgba(255,255,255,0.16)' : mixColor(c.border, c.foreground, 0.2);
+    const errorContainer = isDark ? mixColor(c.destructive, c.surface, 0.78) : lighten(c.destructive, 0.88);
+    const onErrorContainer = onColor(errorContainer, ink, paper);
+    // Links must read on the page background: too-light primaries fall back to ink.
+    const linkColor = !isDark && luminance(p) > 0.6 ? c.foreground : p;
+    return {
+        // Selection accent (10%): marks active/selected state in components.
+        // Components fall back to the ink system when these are absent.
+        '--color-ak-accent': c.accent,
+        '--color-ak-on-accent': onAccent,
+        '--color-ak-accent-soft': accentSoft,
+        '--color-ak-gradient-start': gradientFrom,
+        '--color-ak-gradient-mid': gradientVia,
+        '--color-ak-gradient-end': gradientTo,
+        '--gradient-ak-primary': `linear-gradient(135deg, ${gradientFrom} 0%, ${gradientVia} 52%, ${gradientTo} 100%)`,
+        '--gradient-ak-primary-hover': `linear-gradient(135deg, ${gradientHoverFrom} 0%, ${gradientHoverVia} 48%, ${gradientHoverTo} 100%)`,
+        '--color-ak-glow-primary': glowPrimary,
+        // Hero media: palettes lift the default grayscale so photography takes color.
+        '--ak-hero-media-filter': 'none',
+        // Hero accent: the raw brand primary — stars/ratings/indicators on dark heroes
+        // match the vivid color CTAs use (volt lime, bright purple), never a washed tint.
+        '--color-ak-hero-accent': p,
+        '--color-ak-glow-secondary': glowSecondary,
+        '--color-ak-glow-tertiary': glowTertiary,
+        '--color-ak-glow-warm': glowWarm,
+        '--color-ak-mesh-base': meshBase,
+        '--gradient-ak-neon-border': `conic-gradient(from var(--ak-border-angle, 180deg) at 50% 50%, transparent 0 18%, color-mix(in srgb, ${glowPrimary} 90%, transparent) 34%, color-mix(in srgb, ${glowSecondary} 78%, transparent) 50%, color-mix(in srgb, ${glowTertiary} 70%, transparent) 64%, transparent 78% 100%)`,
+        ...(c.sliderFill ? { '--color-ak-slider-fill': c.sliderFill } : {}),
+        ...(c.sliderRing ? { '--color-ak-slider-ring': c.sliderRing } : {}),
+        // Primary scale (generated from the primary color)
+        '--color-ak-primary-50': lighten(p, 0.92),
+        '--color-ak-primary-100': lighten(p, 0.84),
+        '--color-ak-primary-200': lighten(p, 0.68),
+        '--color-ak-primary-300': lighten(p, 0.48),
+        '--color-ak-primary-400': lighten(p, 0.28),
+        '--color-ak-primary-500': p,
+        '--color-ak-primary-600': darken(p, 0.12),
+        '--color-ak-primary-700': darken(p, 0.24),
+        '--color-ak-primary-800': darken(p, 0.36),
+        '--color-ak-primary-900': darken(p, 0.52),
+        '--color-ak-primary-950': darken(p, 0.68),
+        // Semantic text
+        '--color-ak-text': c.foreground,
+        '--color-ak-text-secondary': c.foregroundMuted,
+        '--color-ak-text-muted': mixColor(c.foregroundMuted, c.background, 0.3),
+        '--color-ak-text-disabled': mixColor(c.foregroundMuted, c.background, 0.6),
+        '--color-ak-text-link': linkColor,
+        '--color-ak-text-inverse': c.surface,
+        '--color-ak-on-surface': c.foreground,
+        '--color-ak-on-surface-variant': c.foregroundMuted,
+        // Text extras
+        '--color-ak-text-placeholder': mixColor(c.foregroundMuted, c.background, 0.4),
+        // Semantic surfaces
+        // Kit reality: ak-bg is PAPER (cards/inputs painted with it historically);
+        // ak-surface is the muted APP CANVAS (showcase background, banded sections).
+        '--color-ak-bg': c.surface,
+        '--color-ak-surface': c.background,
+        // Inset surfaces derive from the palette's *surface* color (seated slightly
+        // into the page) so tracks/panels keep the surface's definition — e.g. white
+        // panels on a bone page — instead of muddying toward the foreground.
+        '--color-ak-surface-2': surface2,
+        '--color-ak-surface-3': surface3,
+        '--color-ak-surface-4': surface4,
+        '--color-ak-surface-container-lowest': c.surface,
+        '--color-ak-surface-container-low': c.background,
+        '--color-ak-surface-container': surface2,
+        '--color-ak-surface-container-high': surface3,
+        '--color-ak-surface-container-highest': surface4,
+        '--color-ak-surface-raised-soft': mixColor(c.background, c.foreground, 0.02),
+        '--color-ak-hover': isDark ? 'rgba(255,255,255,0.04)' : mixColor(c.surface, c.foreground, 0.05),
+        '--color-ak-active': isDark ? 'rgba(255,255,255,0.08)' : mixColor(c.surface, c.foreground, 0.08),
+        '--color-ak-elevated': c.surface,
+        // Inverted panels (terminals, dark rails) — M3 inverse-surface
+        '--color-ak-inverse-surface': c.foreground,
+        '--color-ak-inverse-on-surface': onColor(c.foreground, c.background, c.surface),
+        // Semantic borders
+        '--color-ak-border': border,
+        '--color-ak-border-subtle': borderSubtle,
+        '--color-ak-border-strong': borderStrong,
+        '--color-ak-outline': borderStrong,
+        '--color-ak-outline-variant': borderSubtle,
+        // Focus follows the selection color when the palette splits primary/accent,
+        // and the explicit `ring` field wins over both.
+        '--color-ak-border-focus': c.ring && c.ring.toLowerCase() !== p.toLowerCase() ? c.ring : (c.accent && c.accent.toLowerCase() !== p.toLowerCase() ? c.accent : p),
+        // Neutral scale (derived from foreground/background mix)
+        '--color-ak-neutral-50': mixColor(c.background, c.foreground, 0.02),
+        '--color-ak-neutral-100': mixColor(c.background, c.foreground, 0.04),
+        '--color-ak-neutral-200': mixColor(c.background, c.foreground, 0.08),
+        '--color-ak-neutral-300': mixColor(c.background, c.foreground, 0.15),
+        '--color-ak-neutral-400': mixColor(c.background, c.foreground, 0.3),
+        '--color-ak-neutral-500': mixColor(c.background, c.foreground, 0.45),
+        '--color-ak-neutral-600': mixColor(c.background, c.foreground, 0.6),
+        '--color-ak-neutral-700': mixColor(c.background, c.foreground, 0.72),
+        '--color-ak-neutral-800': mixColor(c.background, c.foreground, 0.84),
+        '--color-ak-neutral-900': mixColor(c.background, c.foreground, 0.92),
+        '--color-ak-neutral-950': mixColor(c.background, c.foreground, 0.96),
+        // Primary as component tokens
+        '--color-ak-primary': p,
+        '--color-ak-primary-hover': isDark ? lighten(p, 0.15) : darken(p, 0.1),
+        '--color-ak-primary-active': isDark ? lighten(p, 0.25) : darken(p, 0.2),
+        '--color-ak-primary-outline': p,
+        '--color-ak-secondary-outline': secondary,
+        '--color-ak-primary-selection': p,
+        '--color-ak-on-primary-selection': onPrimary,
+        '--color-ak-on-primary': onPrimary,
+        '--color-ak-primary-subtle': primaryContainer,
+        '--color-ak-primary-container': primaryContainer,
+        '--color-ak-on-primary-container': onPrimaryContainer,
+        '--color-ak-selection-ink': selectionInk,
+        '--color-ak-primary-container-emphasis': selectionInk,
+        '--color-ak-secondary': secondary,
+        '--color-ak-on-secondary': onSecondary,
+        '--color-ak-secondary-container': secondaryContainer,
+        '--color-ak-on-secondary-container': onSecondaryContainer,
+        '--color-ak-tertiary': c.accent,
+        '--color-ak-on-tertiary': onAccent,
+        '--color-ak-tertiary-container': accentSoft,
+        '--color-ak-on-tertiary-container': onAccentSoft,
+        // Status colors
+        '--color-ak-success': '#22C55E',
+        '--color-ak-success-subtle': lighten('#22C55E', 0.88),
+        '--color-ak-success-text': darken('#22C55E', 0.2),
+        '--color-ak-warning': '#F59E0B',
+        '--color-ak-warning-subtle': lighten('#F59E0B', 0.88),
+        '--color-ak-warning-text': darken('#F59E0B', 0.2),
+        '--color-ak-danger': c.destructive,
+        '--color-ak-on-error': onColor(c.destructive, isDark ? c.background : c.foreground, isDark ? c.foreground : c.surface),
+        ...(isDark ? { '--color-ak-pink': '#f472b6', '--color-ak-pink-subtle': 'rgba(244,114,182,.12)' } : {}),
+        '--color-ak-danger-subtle': errorContainer,
+        '--color-ak-danger-text': darken(c.destructive, 0.2),
+        '--color-ak-error': c.destructive,
+        '--color-ak-error-container': errorContainer,
+        '--color-ak-on-error-container': onErrorContainer,
+        '--color-ak-info': '#3B82F6',
+        '--color-ak-info-subtle': lighten('#3B82F6', 0.88),
+        '--color-ak-info-text': darken('#3B82F6', 0.2),
+        // Overlay
+        '--color-ak-overlay': isDark ? 'rgba(0,0,0,0.7)' : 'rgba(0,0,0,0.5)',
+        // Dark mode: disable shadows (they don't read on dark surfaces)
+        ...(isDark ? { '--shadow-ak-xs': 'none', '--shadow-ak-sm': 'none' } : {}),
+        // Neobrutalist tokens (derived from PRIMARY for visible color shifts)
+        '--color-ak-brutal-ink': isDark ? p : darken(p, 0.3),
+        '--color-ak-brutal-face': isDark ? c.background : c.surface,
+        '--color-ak-brutal-face-dark': isDark ? lighten(p, 0.15) : darken(p, 0.35),
+        '--color-ak-brutal-on-face': isDark ? p : darken(p, 0.3),
+        '--color-ak-brutal-on-face-dark': isDark ? c.background : c.background,
+        '--shadow-ak-brutal-xs': `2px 2px 0 0 ${isDark ? lighten(p, 0.2) : darken(p, 0.4)}`,
+        '--shadow-ak-brutal-sm': `3px 3px 0 0 ${isDark ? lighten(p, 0.2) : darken(p, 0.4)}`,
+        '--shadow-ak-brutal': `4px 4px 0 0 ${isDark ? lighten(p, 0.2) : darken(p, 0.4)}`,
+        '--shadow-ak-brutal-lg': `6px 6px 0 0 ${isDark ? lighten(p, 0.2) : darken(p, 0.4)}`,
+        '--shadow-ak-brutal-xl': `8px 8px 0 0 ${isDark ? lighten(p, 0.2) : darken(p, 0.4)}`,
+        // Status badge colors
+        '--color-ak-status-beta-bg': lighten('#8B5CF6', 0.88),
+        '--color-ak-status-beta-text': '#7C3AED',
+        '--color-ak-status-beta-border': lighten('#8B5CF6', 0.7),
+        '--color-ak-status-new-bg': lighten('#22C55E', 0.88),
+        '--color-ak-status-new-text': '#16A34A',
+        '--color-ak-status-new-border': lighten('#22C55E', 0.7),
+        '--color-ak-status-stable-bg': lighten('#3B82F6', 0.88),
+        '--color-ak-status-stable-text': '#2563EB',
+        '--color-ak-status-stable-border': lighten('#3B82F6', 0.7),
+        '--color-ak-status-deprecated-bg': lighten('#EF4444', 0.88),
+        '--color-ak-status-deprecated-text': '#DC2626',
+        '--color-ak-status-deprecated-border': lighten('#EF4444', 0.7),
+    };
+}
+/**
+ * Palette authorship lint — encodes the recipe learned from curation:
+ * keepers share a near-neutral foreground, neutral light surfaces, and a
+ * mid-luminance primary (or an explicit accent split for light primaries).
+ * Returns human-readable warnings; empty array = palette is well-formed.
+ */
+export function validatePalette(palette) {
+    const c = palette.colors;
+    const warnings = [];
+    const sat = (hex) => {
+        const h = hex.replace('#', '');
+        const r = parseInt(h.slice(0, 2), 16), g = parseInt(h.slice(2, 4), 16), b = parseInt(h.slice(4, 6), 16);
+        return Math.max(r, g, b) - Math.min(r, g, b);
+    };
+    const isDark = palette.mode === 'dark';
+    if (sat(c.foreground) > 45)
+        warnings.push(`foreground ${c.foreground} is heavily tinted (sat ${sat(c.foreground)}) — text washes the whole page`);
+    if (!isDark && sat(c.surface) > 10)
+        warnings.push(`surface ${c.surface} is tinted (sat ${sat(c.surface)}) — paper should stay near-neutral in light mode`);
+    if (!isDark && luminance(c.primary) > 0.85)
+        warnings.push(`primary ${c.primary} is near-white (lum ${luminance(c.primary).toFixed(2)}) — CTAs will vanish on paper`);
+    if (c.background.toLowerCase() === c.surface.toLowerCase())
+        warnings.push('background == surface — no canvas/paper separation');
+    return warnings;
+}
+/**
+ * Generates CSS :root block from a palette using the ak variable names.
+ */
+export function paletteToCSS(palette) {
+    const vars = paletteToAkVariables(palette);
+    let css = `/* ${palette.name} — ${palette.description} */\n:root {\n`;
+    for (const [key, value] of Object.entries(vars)) {
+        css += `  ${key}: ${value};\n`;
+    }
+    css += '}\n';
+    return css;
+}