@snowcone-app/ui 0.1.43 → 0.2.0

package/src/themes/oklch-theme.ts

@@ -0,0 +1,283 @@
+/**
+ * ============================================================================
+ * OKLCH THEME SYSTEM - Quick Reference
+ * ============================================================================
+ *
+ * This module generates all theme colors from a hue + chroma definition.
+ * Colors are computed algorithmically for consistent contrast and readability.
+ *
+ * ┌─────────────────────────────────────────────────────────────────────────┐
+ * │ SEMANTIC VARIABLES                                                       │
+ * ├─────────────────────────────────────────────────────────────────────────┤
+ * │                                                                          │
+ * │ SURFACES (neutral backgrounds)                                           │
+ * │ ──────────────────────────────                                           │
+ * │ --color-background      Page background (darkest in dark mode)           │
+ * │ --color-surface         Cards, panels, modals                            │
+ * │ --color-surface-raised  Popovers, dropdowns (on top of surface)          │
+ * │ --color-muted           Muted areas, switch/slider tracks                │
+ * │                                                                          │
+ * │ FIELDS (form inputs - context-aware)                                     │
+ * │ ────────────────────────────────────                                     │
+ * │ --color-field            Field on page/transparent bg                    │
+ * │ --color-field-on-surface Field inside Surface/Card (auto-detected)       │
+ * │                                                                          │
+ * │ TEXT (always neutral - no color tint)                                    │
+ * │ ─────────────────────────────────────                                    │
+ * │ --color-foreground       Primary text                                    │
+ * │ --color-muted-foreground Secondary/muted text                            │
+ * │                                                                          │
+ * │ ACCENTS (uses theme hue + chroma)                                        │
+ * │ ────────────────────────────────                                         │
+ * │ --color-primary          Brand accent color                              │
+ * │ --color-secondary        Secondary accent                                │
+ * │ --color-border           Dividers and borders                            │
+ * │                                                                          │
+ * └─────────────────────────────────────────────────────────────────────────┘
+ *
+ * USAGE IN COMPONENTS:
+ * - Use `bg-surface` for Card/Surface backgrounds
+ * - Use `bg-muted` for hover states, tracks, muted areas
+ * - Use `bg-[var(--color-field-on-surface)]` for fields inside surfaces
+ * - Use `useSurface()` hook to detect surface context automatically
+ *
+ * DO NOT USE: content1, content2, content3, content4 (legacy, removed)
+ */
+
+import type { OklchThemeConfig } from './types';
+
+// =============================================================================
+// SEMANTIC LIGHTNESS VALUES
+// =============================================================================
+
+/**
+ * Lightness values with semantic names.
+ * Each value describes WHAT it's for, not an abstract "level".
+ */
+export const LIGHTNESS = {
+  dark: {
+    // Page & Surfaces
+    background: 0.12,        // Page background (darkest)
+    surface: 0.16,           // Cards, panels (~#18181b)
+    surfaceRaised: 0.25,     // Popovers, dropdowns, muted backgrounds
+    surfaceHover: 0.25,      // Hover state for surfaces
+
+    // Form Fields
+    field: 0.16,             // Field bg on transparent/page (same as surface)
+    fieldOnSurface: 0.20,    // Field bg inside Surface/Card (~#252528)
+
+    // Text
+    foreground: 0.96,        // Primary text (near white)
+    foregroundMuted: 0.65,   // Secondary text
+
+    // Accents
+    primary: 0.70,           // Primary brand color
+    primaryHover: 0.75,      // Primary hover state
+    secondary: 0.68,         // Secondary accent
+
+    // Borders
+    border: 0.25,            // Dividers, borders
+  },
+  light: {
+    // Page & Surfaces
+    background: 0.97,        // Page background (near white)
+    surface: 1.0,            // Cards, panels (pure white)
+    surfaceRaised: 0.94,     // Popovers, dropdowns, muted backgrounds
+    surfaceHover: 0.94,      // Hover state
+
+    // Form Fields
+    field: 1.0,              // Field bg on transparent/page (white)
+    fieldOnSurface: 0.96,    // Field bg inside Surface/Card (subtle gray)
+
+    // Text
+    foreground: 0.15,        // Primary text (near black)
+    foregroundMuted: 0.45,   // Secondary text
+
+    // Accents
+    primary: 0.55,           // Primary brand color
+    primaryHover: 0.50,      // Primary hover (darker)
+    secondary: 0.45,         // Secondary accent
+
+    // Borders
+    border: 0.85,            // Dividers, borders
+  },
+};
+
+/**
+ * Chroma values - how much color tint to add
+ *
+ * DESIGN PRINCIPLE: Text is always neutral, theme color is for accents only.
+ * - Text (foreground, heading, muted) = 0 chroma (pure grayscale)
+ * - Backgrounds/surfaces = 0 chroma (neutral)
+ * - Accents (primary, icons, links) = full theme chroma
+ */
+export const CHROMA = {
+  neutral: 0,  // For all non-accent colors (text, surfaces, borders)
+};
+
+// =============================================================================
+// COLOR GENERATION FUNCTIONS
+// =============================================================================
+
+/**
+ * Generate an OKLCH color string
+ */
+export function oklch(lightness: number, chroma: number, hue: number): string {
+  const l = Math.max(0, Math.min(1, lightness));
+  const c = Math.max(0, Math.min(0.4, chroma));
+  const h = ((hue % 360) + 360) % 360;
+  return `oklch(${(l * 100).toFixed(1)}% ${c.toFixed(4)} ${h.toFixed(1)})`;
+}
+
+/**
+ * Generate all CSS color variables for a theme
+ *
+ * Variable naming convention:
+ * - `--color-{name}` is the canonical form
+ * - `--{name}` is an alias for convenience
+ */
+export function generateThemeVariables(config: OklchThemeConfig): Record<string, string> {
+  const { hue, isDark, chroma: primaryChroma = 0.18, primaryLightness } = config;
+  const L = isDark ? LIGHTNESS.dark : LIGHTNESS.light;
+
+  // Allow per-theme override of primary lightness
+  const effectivePrimaryL = primaryLightness ?? L.primary;
+
+  // Calculate primary foreground based on primary lightness
+  const primaryFgLightness = effectivePrimaryL > 0.6 ? 0.12 : 0.96;
+
+  const vars: Record<string, string> = {
+    // =========================================================================
+    // BACKGROUND - Page level
+    // =========================================================================
+    '--color-background': oklch(L.background, CHROMA.neutral, hue),
+    '--background': oklch(L.background, CHROMA.neutral, hue),
+
+    // =========================================================================
+    // SURFACE - Cards, panels, modals
+    // =========================================================================
+    '--color-surface': oklch(L.surface, CHROMA.neutral, hue),
+    '--color-card': oklch(L.surface, CHROMA.neutral, hue),
+    '--surface': oklch(L.surface, CHROMA.neutral, hue),
+
+    // Raised surface (popovers, dropdowns on top of surface)
+    '--color-surface-raised': oklch(L.surfaceRaised, CHROMA.neutral, hue),
+    '--color-popover': oklch(L.surfaceRaised, CHROMA.neutral, hue),
+
+    // =========================================================================
+    // FIELDS - Form inputs
+    // =========================================================================
+    // Field on transparent/page background
+    '--color-field': oklch(L.field, CHROMA.neutral, hue),
+
+    // Field inside Surface/Card (needs contrast with surface)
+    '--color-field-on-surface': oklch(L.fieldOnSurface, CHROMA.neutral, hue),
+
+    // =========================================================================
+    // FOREGROUND - Text colors
+    // =========================================================================
+    '--color-foreground': oklch(L.foreground, CHROMA.neutral, hue),
+    '--foreground': oklch(L.foreground, CHROMA.neutral, hue),
+    '--color-heading': oklch(L.foreground, CHROMA.neutral, hue),
+    '--color-card-foreground': oklch(L.foreground, CHROMA.neutral, hue),
+    '--color-popover-foreground': oklch(L.foreground, CHROMA.neutral, hue),
+
+    // Muted text
+    '--color-muted-foreground': oklch(L.foregroundMuted, CHROMA.neutral, hue),
+    '--muted-foreground': oklch(L.foregroundMuted, CHROMA.neutral, hue),
+
+    // =========================================================================
+    // PRIMARY - Brand accent
+    // =========================================================================
+    '--color-primary': oklch(effectivePrimaryL, primaryChroma, hue),
+    '--primary': oklch(effectivePrimaryL, primaryChroma, hue),
+    '--color-accent': oklch(effectivePrimaryL, primaryChroma, hue),
+    '--accent': oklch(effectivePrimaryL, primaryChroma, hue),
+    '--color-ring': oklch(effectivePrimaryL, primaryChroma, hue),
+    '--focus': oklch(effectivePrimaryL, primaryChroma, hue),
+
+    // Primary foreground (text on primary bg)
+    '--color-primary-foreground': oklch(primaryFgLightness, CHROMA.neutral, hue),
+    '--primary-foreground': oklch(primaryFgLightness, CHROMA.neutral, hue),
+    '--color-accent-foreground': oklch(primaryFgLightness, CHROMA.neutral, hue),
+
+    // =========================================================================
+    // SECONDARY - Secondary accent
+    // =========================================================================
+    '--color-secondary': oklch(L.secondary, primaryChroma * 0.8, hue),
+    '--secondary': oklch(L.secondary, primaryChroma * 0.8, hue),
+    '--color-secondary-foreground': oklch(L.foreground, CHROMA.neutral, hue),
+    '--secondary-foreground': oklch(L.foreground, CHROMA.neutral, hue),
+
+    // =========================================================================
+    // BORDER - Dividers, borders
+    // =========================================================================
+    '--color-border': oklch(L.border, CHROMA.neutral, hue),
+    '--border': oklch(L.border, CHROMA.neutral, hue),
+    '--color-divider': oklch(L.border, CHROMA.neutral, hue),
+    '--divider': oklch(L.border, CHROMA.neutral, hue),
+
+    // =========================================================================
+    // MUTED - Muted backgrounds
+    // =========================================================================
+    '--color-muted': oklch(L.surfaceRaised, CHROMA.neutral, hue),
+    '--muted': oklch(L.surfaceRaised, CHROMA.neutral, hue),
+
+    // =========================================================================
+    // ICON - Icon colors (uses primary with reduced chroma)
+    // =========================================================================
+    '--color-icon': oklch(isDark ? 0.75 : 0.55, primaryChroma * 0.7, hue),
+
+    // =========================================================================
+    // ACCENT TEXT - For overlays and labels
+    // =========================================================================
+    '--color-accent-text-overlay': oklch(isDark ? 0.75 : 0.45, primaryChroma * 0.5, hue),
+    '--color-accent-text-page': oklch(isDark ? 0.60 : 0.50, primaryChroma * 0.5, hue),
+  };
+
+  return vars;
+}
+
+/**
+ * Apply OKLCH theme to DOM
+ */
+export function applyOklchTheme(
+  config: OklchThemeConfig,
+  root: HTMLElement = document.documentElement
+): void {
+  const vars = generateThemeVariables(config);
+
+  // Apply all CSS variables
+  for (const [key, value] of Object.entries(vars)) {
+    root.style.setProperty(key, value);
+  }
+
+  // Apply dark mode class and color scheme
+  if (config.isDark) {
+    root.classList.add('dark');
+    root.classList.remove('light');
+    root.style.colorScheme = 'dark';
+  } else {
+    root.classList.remove('dark');
+    root.classList.add('light');
+    root.style.colorScheme = 'light';
+  }
+
+  // Set data-theme attribute for CSS selectors
+  const themeId = `ne-${config.name.toLowerCase().replace(/[^a-z0-9]/g, '-')}`;
+  root.setAttribute('data-theme', themeId);
+}
+
+/**
+ * Get theme styles as an object (for SSR/React style prop)
+ */
+export function getOklchThemeStyles(config: OklchThemeConfig): Record<string, string> {
+  const vars = generateThemeVariables(config);
+
+  return {
+    ...vars,
+    colorScheme: config.isDark ? 'dark' : 'light',
+    backgroundColor: vars['--background'],
+    color: vars['--foreground'],
+  };
+}