@snowcone-app/ui 0.1.43 → 0.2.1

package/src/themes/types.ts

@@ -0,0 +1,386 @@
+/**
+ * Theme Configuration Types
+ *
+ * This is the single source of truth for theme types.
+ * Both snowcone-canvas and next-ecommerce use these same types.
+ *
+ * OKLCH-BASED THEME SYSTEM:
+ * -------------------------
+ * Themes are defined with just a few parameters (hue, chroma, isDark) and
+ * all colors are generated algorithmically. This ensures:
+ * - Consistent foreground colors (no more accidentally tinted text)
+ * - Easy theme creation (just pick a hue)
+ * - Mathematically correct color relationships
+ */
+
+// =============================================================================
+// OKLCH THEME CONFIGURATION (Modern approach)
+// =============================================================================
+
+/**
+ * OKLCH-based theme configuration
+ *
+ * Define themes with just hue + chroma, and all colors are generated automatically.
+ * This is the recommended way to create new themes.
+ *
+ * @example
+ * {
+ *   name: 'Purple',
+ *   hue: 270,        // Purple hue (0-360)
+ *   chroma: 0.18,    // Saturation (0-0.4)
+ *   isDark: false,
+ *   radiusPreset: 'soft',
+ * }
+ */
+export interface OklchThemeConfig {
+  /** Theme name for display */
+  name: string;
+
+  /** Primary hue (0-360). Examples: 270=purple, 220=blue, 145=green, 30=orange, 350=pink */
+  hue: number;
+
+  /** Chroma/saturation (0-0.4). Higher = more vivid. Typical: 0.12-0.22 */
+  chroma?: number;
+
+  /** Whether this is a dark theme */
+  isDark: boolean;
+
+  /** Semantic radius preset */
+  radiusPreset?: RadiusPresetId;
+
+  /** Icon stroke width preset */
+  iconStrokeWidth?: 'thin' | 'normal' | 'thick' | 'extra-thick';
+
+  /** Font family preset */
+  fontFamily?: 'sans' | 'serif' | 'mono' | 'display' | 'handwriting' | 'mixed' |
+    'montserrat-combo' | 'playfair-combo' | 'helvetica-combo';
+
+  /** Advanced font pairing configuration */
+  fontPairing?: FontPairing;
+
+  /** Override the primary color lightness (0-1). Defaults to LIGHTNESS.light.primary (0.55) or LIGHTNESS.dark.primary (0.70). Use 0.0 for pure black, 1.0 for pure white. */
+  primaryLightness?: number;
+
+  /** Name of the light variant (for dark themes) */
+  lightVariant?: string;
+
+  /** Name of the dark variant (for light themes) */
+  darkVariant?: string;
+}
+
+// =============================================================================
+// LEGACY THEME CONFIGURATION (for backwards compatibility)
+// =============================================================================
+
+export interface ThemeConfig {
+  /** Theme name for display */
+  name?: string;
+
+  /** Page background color (hex) */
+  backgroundColor?: string;
+
+  /** Primary accent color (hex) - used for buttons, links, focus states */
+  primaryColor?: string;
+
+  /** Secondary accent color (hex) - optional, defaults to primaryColor */
+  secondaryColor?: string;
+
+  /** Main text color (hex) */
+  textColor?: string;
+
+  /** Vibrant color for icons (hex) - optional, defaults to primaryColor */
+  iconColor?: string;
+
+  /** Accent text for light backgrounds (e.g., product detail pages) */
+  accentTextLight?: string;
+
+  /** Accent text for dark backgrounds (e.g., overlays) */
+  accentTextDark?: string;
+
+  /**
+   * Border radius preset (legacy simple preset)
+   * @deprecated Use `radiusPreset` for semantic radius control
+   */
+  borderRadius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+
+  /**
+   * Semantic radius preset - defines the "shape personality" of the theme
+   * Controls border-radius for buttons, inputs, cards, modals, etc.
+   */
+  radiusPreset?: RadiusPresetId | RadiusConfig;
+
+  /** Icon stroke width preset */
+  iconStrokeWidth?: 'thin' | 'normal' | 'thick' | 'extra-thick';
+
+  /** Whether this is a dark theme */
+  isDark?: boolean;
+
+  /** Name of the light variant of this theme (for dark themes) */
+  lightVariant?: string;
+
+  /** Name of the dark variant of this theme (for light themes) */
+  darkVariant?: string;
+
+  /** Font family preset */
+  fontFamily?:
+    | 'sans'
+    | 'serif'
+    | 'mono'
+    | 'display'
+    | 'handwriting'
+    | 'mixed'
+    | 'montserrat-combo'
+    | 'playfair-combo'
+    | 'helvetica-combo';
+
+  /** Advanced font pairing configuration */
+  fontPairing?: FontPairing;
+}
+
+/**
+ * Font Pairing Configuration
+ *
+ * Defines the complete typography system for a theme. Theme designers can
+ * customize fonts at multiple levels of granularity:
+ *
+ * 1. **Core fonts** (required): `headingFont` and `bodyFont`
+ * 2. **Semantic roles** (optional): Override specific UI contexts
+ * 3. **Weights** (optional): Fine-tune font weights per role
+ *
+ * @example
+ * // Minimal configuration - uses defaults for semantic roles
+ * {
+ *   id: 'classic-serif',
+ *   headingFont: 'Playfair Display, serif',
+ *   bodyFont: 'Open Sans, sans-serif',
+ * }
+ *
+ * @example
+ * // Full customization - luxury brand with distinct fonts per role
+ * {
+ *   id: 'luxury-retail',
+ *   headingFont: 'Playfair Display, serif',
+ *   bodyFont: 'Cormorant, serif',
+ *   labelFont: 'Montserrat, sans-serif',
+ *   buttonFont: 'Montserrat, sans-serif',
+ *   captionFont: 'Open Sans, sans-serif',
+ *   displayFont: 'Playfair Display, serif',
+ *   weights: {
+ *     headingWeight: '500',
+ *     displayWeight: '700',
+ *   },
+ * }
+ */
+export interface FontPairing {
+  /** Unique identifier for this font pairing */
+  id: string;
+
+  /** Font stack for headings (h1-h6, titles) */
+  headingFont: string;
+
+  /** Font stack for body text (paragraphs, default text) */
+  bodyFont: string;
+
+  /**
+   * Semantic Font Roles
+   * Override specific UI contexts with custom fonts.
+   * If not specified, defaults to bodyFont or headingFont as appropriate.
+   */
+
+  /** Font for form labels and field names. Defaults to bodyFont. */
+  labelFont?: string;
+
+  /** Font for button text and CTAs. Defaults to bodyFont. */
+  buttonFont?: string;
+
+  /** Font for small text, descriptions, helper text. Defaults to bodyFont. */
+  captionFont?: string;
+
+  /** Font for hero text, prices, prominent numbers. Defaults to headingFont. */
+  displayFont?: string;
+
+  /** Font for emphasis, blockquotes, pullquotes. Defaults to headingFont. */
+  accentFont?: string;
+
+  /** Font weights per role */
+  weights?: FontWeights;
+}
+
+/**
+ * Font Weights Configuration
+ *
+ * Fine-tune font weights for different text roles.
+ * All values should be valid CSS font-weight values (100-900 or keywords).
+ */
+export interface FontWeights {
+  /** Weight for body text. Default: '400' */
+  bodyWeight?: string;
+
+  /** Weight for headings. Default: '600' */
+  headingWeight?: string;
+
+  /** Weight for button text. Default: '500' */
+  buttonWeight?: string;
+
+  /** Weight for form labels. Default: '500' */
+  labelWeight?: string;
+
+  /** Weight for captions and small text. Default: '400' */
+  captionWeight?: string;
+
+  /** Weight for display/hero text. Default: '700' */
+  displayWeight?: string;
+}
+
+/** Theme preset with required name */
+export type ThemePreset = ThemeConfig & { name: string };
+
+/* =============================================================================
+ * SEMANTIC RADIUS SYSTEM
+ * =============================================================================
+ * Defines how border-radius is applied to different component types.
+ * Themes can use a preset ID (string) or a full RadiusConfig object.
+ *
+ * Built-in presets: 'default' | 'sharp' | 'soft' | 'brutalist' | 'playful'
+ */
+
+/**
+ * Radius size tokens that can be assigned to semantic roles
+ *
+ * Maps to CSS variables:
+ * - 'none' → 0
+ * - 'sm' → var(--radius-sm) = 2px
+ * - 'md' → var(--radius-md) = 4px
+ * - 'lg' → var(--radius-lg) = 6px
+ * - 'xl' → var(--radius-xl) = 8px
+ * - '2xl' → var(--radius-2xl) = 12px
+ * - '3xl' → var(--radius-3xl) = 20px
+ * - '4xl' → var(--radius-4xl) = 24px
+ * - 'full' → var(--radius-full) = 50% (pill shape)
+ */
+export type RadiusSize = 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | 'full';
+
+/**
+ * Built-in radius preset identifiers
+ *
+ * Each preset defines a complete "shape personality":
+ * - **default**: Balanced, professional appearance
+ * - **sharp**: Technical, precise, minimal rounding
+ * - **soft**: Friendly, approachable, heavily rounded
+ * - **brutalist**: Raw, bold, no rounding at all
+ * - **playful**: Fun, casual, varied rounding
+ */
+export type RadiusPresetId = 'default' | 'sharp' | 'soft' | 'brutalist' | 'playful';
+
+/**
+ * Semantic Radius Configuration
+ *
+ * Defines border-radius for each component type. Theme designers can
+ * customize any role independently for fine-grained shape control.
+ *
+ * @example
+ * // Custom e-commerce theme with pill buttons but square cards
+ * {
+ *   button: 'full',    // Pill-shaped buttons (trendy)
+ *   input: 'lg',       // Rounded inputs
+ *   card: 'sm',        // Subtle card rounding
+ *   modal: 'lg',       // Friendly modals
+ *   badge: 'full',     // Classic pill badges
+ *   avatar: 'full',    // Circular avatars
+ *   tooltip: 'md',     // Subtle tooltip rounding
+ *   image: 'lg',       // Product image rounding
+ * }
+ */
+export interface RadiusConfig {
+  /** Buttons, chips, toggles, action elements */
+  button?: RadiusSize;
+
+  /** Text inputs, selects, textareas, form controls */
+  input?: RadiusSize;
+
+  /** Cards, panels, surfaces, containers */
+  card?: RadiusSize;
+
+  /** Modals, dialogs, sheets, drawers */
+  modal?: RadiusSize;
+
+  /** Badges, tags, status indicators, labels */
+  badge?: RadiusSize;
+
+  /** Avatars, profile images, user icons */
+  avatar?: RadiusSize;
+
+  /** Tooltips, popovers, dropdown menus */
+  tooltip?: RadiusSize;
+
+  /** Product images, thumbnails, media containers */
+  image?: RadiusSize;
+}
+
+/**
+ * Built-in radius presets
+ *
+ * These define complete "shape personalities" that can be applied
+ * with a single string identifier.
+ */
+export const RADIUS_PRESETS: Record<RadiusPresetId, Required<RadiusConfig>> = {
+  /** Balanced, professional - the safe default */
+  default: {
+    button: 'md',
+    input: 'md',
+    card: 'lg',
+    modal: 'xl',
+    badge: 'full',
+    avatar: 'full',
+    tooltip: 'lg', // Visible rounding for tooltips, popovers, dropdown menus
+    image: 'md',
+  },
+
+  /** Technical, precise - minimal rounding for professional tools */
+  sharp: {
+    button: 'sm',
+    input: 'sm',
+    card: 'sm',
+    modal: 'md',
+    badge: 'sm',
+    avatar: 'md',
+    tooltip: 'none',
+    image: 'sm',
+  },
+
+  /** Friendly, approachable - heavy rounding for consumer apps */
+  soft: {
+    button: 'full',
+    input: 'xl',
+    card: '2xl',
+    modal: '3xl',
+    badge: 'full',
+    avatar: 'full',
+    tooltip: 'lg',
+    image: 'xl',
+  },
+
+  /** Raw, bold - no rounding for maximum impact */
+  brutalist: {
+    button: 'none',
+    input: 'none',
+    card: 'none',
+    modal: 'none',
+    badge: 'none',
+    avatar: 'none',
+    tooltip: 'none',
+    image: 'none',
+  },
+
+  /** Fun, casual - varied rounding for personality */
+  playful: {
+    button: '2xl',
+    input: 'xl',
+    card: '3xl',
+    modal: '3xl',
+    badge: 'full',
+    avatar: 'full',
+    tooltip: 'xl',
+    image: '2xl',
+  },
+};