@idealyst/theme 1.2.29 → 1.2.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/theme",
-  "version": "1.2.29",
+  "version": "1.2.30",
   "description": "Theming system for Idealyst Framework",
   "readme": "README.md",
   "main": "src/index.ts",
@@ -50,6 +50,12 @@
       "import": "./src/darkTheme.ts",
       "require": "./src/darkTheme.ts",
       "types": "./src/darkTheme.ts"
+    },
+    "./animation": {
+      "native": "./src/animation/index.native.ts",
+      "import": "./src/animation/index.ts",
+      "require": "./src/animation/index.ts",
+      "types": "./src/animation/index.ts"
     }
   },
   "scripts": {

package/src/animation/index.native.ts

@@ -0,0 +1,62 @@
+/**
+ * Animation module for @idealyst/theme (Native)
+ *
+ * This module provides animation tokens and utilities for creating
+ * consistent animations across web and native platforms.
+ *
+ * Native-specific exports include Reanimated-compatible utilities.
+ *
+ * @example
+ * // Import tokens
+ * import { durations, easings, presets } from '@idealyst/theme/animation';
+ *
+ * // Import native utilities
+ * import { timingConfig, springConfig, animationConfig } from '@idealyst/theme/animation';
+ *
+ * // Use with Reanimated
+ * import { withTiming, withSpring, Easing } from 'react-native-reanimated';
+ *
+ * const config = timingConfig('normal', 'easeOut');
+ * value.value = withTiming(target, {
+ *   duration: config.duration,
+ *   easing: Easing.bezier(...config.easing),
+ * });
+ */
+
+// Export tokens
+export { durations, easings, presets } from './tokens';
+export type { DurationKey, EasingKey, PresetKey } from './tokens';
+
+// Export types
+export type {
+  Duration,
+  Easing,
+  BezierEasing,
+  SpringConfig,
+  CSSEasing,
+  AnimationConfig,
+  TransitionConfig,
+  Keyframes,
+  KeyframeAnimationConfig,
+  AnimationIterations,
+  AnimationDirection,
+  AnimationFillMode,
+  SpringType,
+  TimingAnimationConfig,
+  PlatformAnimationOptions,
+  GradientAnimation,
+  GradientBorderConfig,
+} from './types';
+
+// Export native utilities
+export {
+  resolveDuration,
+  resolveEasingBezier,
+  isSpringEasing,
+  timingConfig,
+  springConfig,
+  animationConfig,
+  presetConfig,
+  delayMs,
+  sequenceSteps,
+} from './transitions.native';

package/src/animation/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Animation module for @idealyst/theme
+ *
+ * This module provides animation tokens and utilities for creating
+ * consistent animations across web and native platforms.
+ *
+ * @example
+ * // Import tokens
+ * import { durations, easings, presets } from '@idealyst/theme/animation';
+ *
+ * // Import web utilities
+ * import { cssTransition, cssPreset, cssKeyframes } from '@idealyst/theme/animation';
+ *
+ * // Import native utilities (in .native.ts files)
+ * import { timingConfig, springConfig } from '@idealyst/theme/animation';
+ */
+
+// Export tokens
+export { durations, easings, presets } from './tokens';
+export type { DurationKey, EasingKey, PresetKey } from './tokens';
+
+// Export types
+export type {
+  Duration,
+  Easing,
+  BezierEasing,
+  SpringConfig,
+  CSSEasing,
+  AnimationConfig,
+  TransitionConfig,
+  Keyframes,
+  KeyframeAnimationConfig,
+  AnimationIterations,
+  AnimationDirection,
+  AnimationFillMode,
+  SpringType,
+  TimingAnimationConfig,
+  PlatformAnimationOptions,
+  GradientAnimation,
+  GradientBorderConfig,
+} from './types';
+
+// Export web utilities
+export {
+  resolveDuration,
+  resolveEasing,
+  cssTransition,
+  cssPreset,
+  cssKeyframes,
+  cssAnimation,
+  gradientPropertyCSS,
+  injectGradientCSS,
+  conicSpinnerStyle,
+  pulseGradientStyle,
+} from './transitions';
+
+// Export native utilities (these are also exported from index.native.ts)
+// Including here allows type-checking in monorepo without platform resolution
+export {
+  resolveEasingBezier,
+  isSpringEasing,
+  timingConfig,
+  springConfig,
+  animationConfig,
+  presetConfig,
+  delayMs,
+  sequenceSteps,
+} from './transitions.native';

package/src/animation/tokens.ts

@@ -0,0 +1,145 @@
+/**
+ * Animation tokens for @idealyst/theme
+ *
+ * These tokens provide consistent animation timing across the framework.
+ * Use these instead of hardcoded values for consistency and maintainability.
+ */
+
+/**
+ * Duration tokens in milliseconds
+ *
+ * @example
+ * import { durations } from '@idealyst/theme/animation';
+ *
+ * // Use in CSS transition
+ * transition: `opacity ${durations.normal}ms ease`
+ *
+ * // Use with Reanimated
+ * withTiming(value, { duration: durations.fast })
+ */
+export const durations = {
+  /** 0ms - No animation, instant change */
+  instant: 0,
+  /** 100ms - Micro-interactions: hover, focus, press feedback */
+  fast: 100,
+  /** 200ms - Standard state transitions: toggle, selection changes */
+  normal: 200,
+  /** 300ms - Complex transitions: expand/collapse, progress bars */
+  slow: 300,
+  /** 500ms - Entrance animations: modals, toasts appearing */
+  slower: 500,
+  /** 750ms - Extended animations: skeleton pulse, loading states */
+  slowest: 750,
+  /** 1000ms - Loop animations: spinners, continuous indicators */
+  loop: 1000,
+} as const;
+
+/**
+ * Easing tokens with both CSS string and bezier values
+ *
+ * CSS easings include both a CSS string for web transitions
+ * and bezier curve values for Reanimated's Easing.bezier()
+ *
+ * Spring easings are native-only and include damping/stiffness/mass
+ *
+ * @example
+ * import { easings } from '@idealyst/theme/animation';
+ *
+ * // Web: use CSS string
+ * transition: `opacity 200ms ${easings.easeOut.css}`
+ *
+ * // Native: use bezier values
+ * Easing.bezier(...easings.easeOut.bezier)
+ *
+ * // Native spring
+ * withSpring(value, easings.spring)
+ */
+export const easings = {
+  // Standard CSS easings
+  /** Linear - constant speed, no acceleration */
+  linear: { css: 'linear', bezier: [0, 0, 1, 1] as const },
+  /** Ease - slight acceleration at start, deceleration at end */
+  ease: { css: 'ease', bezier: [0.25, 0.1, 0.25, 1] as const },
+  /** Ease-in - starts slow, accelerates */
+  easeIn: { css: 'ease-in', bezier: [0.42, 0, 1, 1] as const },
+  /** Ease-out - starts fast, decelerates (most common for UI) */
+  easeOut: { css: 'ease-out', bezier: [0, 0, 0.58, 1] as const },
+  /** Ease-in-out - symmetric acceleration and deceleration */
+  easeInOut: { css: 'ease-in-out', bezier: [0.42, 0, 0.58, 1] as const },
+
+  // Material Design easings
+  /** Standard - Material Design standard easing, balanced feel */
+  standard: { css: 'cubic-bezier(0.4, 0, 0.2, 1)', bezier: [0.4, 0, 0.2, 1] as const },
+  /** Decelerate - Material Design deceleration, for entering elements */
+  decelerate: { css: 'cubic-bezier(0, 0, 0.2, 1)', bezier: [0, 0, 0.2, 1] as const },
+  /** Accelerate - Material Design acceleration, for exiting elements */
+  accelerate: { css: 'cubic-bezier(0.4, 0, 1, 1)', bezier: [0.4, 0, 1, 1] as const },
+
+  // Spring configurations (native only - used with withSpring)
+  /** Spring - balanced spring, good for toggles and state changes */
+  spring: { damping: 15, stiffness: 200, mass: 1 } as const,
+  /** Spring stiff - less bounce, snappier feel, good for switches */
+  springStiff: { damping: 40, stiffness: 200, mass: 1 } as const,
+  /** Spring bouncy - more bounce, playful feel, good for buttons */
+  springBouncy: { damping: 10, stiffness: 180, mass: 1 } as const,
+} as const;
+
+/**
+ * Animation presets for common use cases
+ *
+ * These combine duration and easing for specific interaction patterns.
+ *
+ * @example
+ * import { presets } from '@idealyst/theme/animation';
+ *
+ * // Use for hover effects
+ * _web: { transition: cssPreset(presets.hover) }
+ */
+export const presets = {
+  // Micro-interactions
+  /** Hover effect - fast, subtle */
+  hover: { duration: 'fast' as const, easing: 'ease' as const },
+  /** Press/active feedback - fast, ease-out */
+  press: { duration: 'fast' as const, easing: 'easeOut' as const },
+  /** Focus ring - normal speed */
+  focus: { duration: 'normal' as const, easing: 'ease' as const },
+
+  // State changes
+  /** Toggle/switch - normal with spring on native */
+  toggle: { duration: 'normal' as const, easing: 'spring' as const },
+  /** Selection change - normal, standard easing */
+  select: { duration: 'normal' as const, easing: 'standard' as const },
+
+  // Expand/collapse
+  /** Expand content - slow, standard easing */
+  expand: { duration: 'slow' as const, easing: 'standard' as const },
+  /** Collapse content - slightly faster than expand */
+  collapse: { duration: 'normal' as const, easing: 'accelerate' as const },
+
+  // Entrance/exit
+  /** Fade in - normal, decelerate */
+  fadeIn: { duration: 'normal' as const, easing: 'decelerate' as const },
+  /** Fade out - fast, accelerate */
+  fadeOut: { duration: 'fast' as const, easing: 'accelerate' as const },
+  /** Scale in (modal, dialog) - slower, decelerate */
+  scaleIn: { duration: 'slower' as const, easing: 'decelerate' as const },
+  /** Scale out - normal, accelerate */
+  scaleOut: { duration: 'normal' as const, easing: 'accelerate' as const },
+  /** Slide in - slow, standard */
+  slideIn: { duration: 'slow' as const, easing: 'standard' as const },
+  /** Slide out - normal, accelerate */
+  slideOut: { duration: 'normal' as const, easing: 'accelerate' as const },
+
+  // Loading/continuous
+  /** Spinner rotation - 1s linear loop */
+  spin: { duration: 'loop' as const, easing: 'linear' as const, iterations: 'infinite' as const },
+  /** Pulse effect - slowest, ease-in-out loop */
+  pulse: { duration: 'slowest' as const, easing: 'easeInOut' as const, iterations: 'infinite' as const },
+  /** Skeleton wave - slower than pulse */
+  wave: { duration: 1500 as const, easing: 'easeInOut' as const, iterations: 'infinite' as const },
+} as const;
+
+// Type exports for convenience
+export type DurationKey = keyof typeof durations;
+export type EasingKey = keyof typeof easings;
+export type PresetKey = keyof typeof presets;

package/src/animation/transitions.native.ts

@@ -0,0 +1,219 @@
+/**
+ * Native-specific animation utilities
+ *
+ * These utilities generate Reanimated-compatible configurations
+ * from animation tokens for use in React Native animations.
+ */
+
+import { durations, easings } from './tokens';
+import type { DurationKey, EasingKey, PresetKey } from './tokens';
+import type { Duration, SpringType, BezierEasing } from './types';
+
+/**
+ * Resolve a duration value to milliseconds
+ */
+export function resolveDuration(duration: Duration): number {
+  if (typeof duration === 'number') {
+    return duration;
+  }
+  return durations[duration];
+}
+
+/**
+ * Resolve an easing key to bezier curve values
+ * Returns bezier array for use with Easing.bezier()
+ *
+ * Note: Spring easings return a fallback bezier curve.
+ * For actual spring behavior, use springConfig() instead.
+ */
+export function resolveEasingBezier(easing: EasingKey): BezierEasing {
+  const easingConfig = easings[easing];
+  // Spring configs don't have bezier equivalent, fall back to ease-out
+  if ('damping' in easingConfig) {
+    return easings.easeOut.bezier;
+  }
+  return easingConfig.bezier;
+}
+
+/**
+ * Check if an easing is a spring configuration
+ */
+export function isSpringEasing(easing: EasingKey): easing is SpringType {
+  return easing === 'spring' || easing === 'springStiff' || easing === 'springBouncy';
+}
+
+/**
+ * Get Reanimated withTiming configuration from tokens
+ *
+ * Use with Reanimated's withTiming() function.
+ * The returned config includes duration and a bezier easing function creator.
+ *
+ * @param duration - Duration token key or milliseconds
+ * @param easing - Easing token key (spring easings fall back to easeOut)
+ * @returns Configuration object with duration and easing bezier values
+ *
+ * @example
+ * import { timingConfig } from '@idealyst/theme/animation';
+ * import { withTiming, Easing } from 'react-native-reanimated';
+ *
+ * const config = timingConfig('normal', 'easeOut');
+ * // => { duration: 200, easing: [0, 0, 0.58, 1] }
+ *
+ * // Use with Reanimated
+ * animatedValue.value = withTiming(targetValue, {
+ *   duration: config.duration,
+ *   easing: Easing.bezier(...config.easing),
+ * });
+ */
+export function timingConfig(
+  duration: Duration = 'normal',
+  easing: EasingKey = 'easeOut'
+): { duration: number; easing: BezierEasing } {
+  return {
+    duration: resolveDuration(duration),
+    easing: resolveEasingBezier(easing),
+  };
+}
+
+/**
+ * Get Reanimated withSpring configuration from tokens
+ *
+ * Use with Reanimated's withSpring() function.
+ *
+ * @param type - Spring type: 'spring', 'springStiff', or 'springBouncy'
+ * @returns Spring configuration object
+ *
+ * @example
+ * import { springConfig } from '@idealyst/theme/animation';
+ * import { withSpring } from 'react-native-reanimated';
+ *
+ * const config = springConfig('springStiff');
+ * // => { damping: 40, stiffness: 200, mass: 1 }
+ *
+ * // Use with Reanimated
+ * animatedValue.value = withSpring(targetValue, config);
+ */
+export function springConfig(
+  type: SpringType = 'spring'
+): { damping: number; stiffness: number; mass: number } {
+  const config = easings[type];
+  return {
+    damping: config.damping,
+    stiffness: config.stiffness,
+    mass: config.mass,
+  };
+}
+
+/**
+ * Get animation configuration based on easing type
+ *
+ * Automatically returns spring config for spring easings,
+ * or timing config for bezier easings.
+ *
+ * @param duration - Duration token key or milliseconds
+ * @param easing - Easing token key
+ * @returns Either spring config or timing config
+ *
+ * @example
+ * import { animationConfig } from '@idealyst/theme/animation';
+ *
+ * // Returns spring config
+ * animationConfig('normal', 'spring')
+ * // => { type: 'spring', config: { damping: 15, stiffness: 200, mass: 1 } }
+ *
+ * // Returns timing config
+ * animationConfig('normal', 'easeOut')
+ * // => { type: 'timing', config: { duration: 200, easing: [0, 0, 0.58, 1] } }
+ */
+export function animationConfig(
+  duration: Duration = 'normal',
+  easing: EasingKey = 'easeOut'
+):
+  | { type: 'spring'; config: ReturnType<typeof springConfig> }
+  | { type: 'timing'; config: ReturnType<typeof timingConfig> } {
+  if (isSpringEasing(easing)) {
+    return {
+      type: 'spring',
+      config: springConfig(easing),
+    };
+  }
+  return {
+    type: 'timing',
+    config: timingConfig(duration, easing),
+  };
+}
+
+/**
+ * Get preset animation configuration for native
+ *
+ * @param presetName - Preset key
+ * @returns Animation configuration for the preset
+ */
+export function presetConfig(presetName: keyof typeof import('./tokens').presets) {
+  const { presets } = require('./tokens');
+  const preset = presets[presetName];
+  return animationConfig(preset.duration, preset.easing);
+}
+
+/**
+ * Helper to create a delay configuration
+ *
+ * Use with Reanimated's withDelay() function.
+ *
+ * @param delay - Delay in milliseconds or duration token
+ * @returns Delay in milliseconds
+ *
+ * @example
+ * import { delayMs } from '@idealyst/theme/animation';
+ * import { withDelay, withTiming } from 'react-native-reanimated';
+ *
+ * // Using duration token
+ * animatedValue.value = withDelay(
+ *   delayMs('normal'),
+ *   withTiming(targetValue, timingConfig('fast', 'easeOut'))
+ * );
+ */
+export function delayMs(delay: Duration): number {
+  return resolveDuration(delay);
+}
+
+/**
+ * Create a sequence of timing animations
+ *
+ * Helper for creating withSequence() compatible values.
+ *
+ * @param steps - Array of { value, duration?, easing? } objects
+ * @returns Array of animation configurations
+ *
+ * @example
+ * import { sequenceSteps } from '@idealyst/theme/animation';
+ *
+ * const steps = sequenceSteps([
+ *   { value: 0 },
+ *   { value: 1, duration: 'normal', easing: 'easeOut' },
+ *   { value: 0.5, duration: 'fast' },
+ * ]);
+ *
+ * // Use with Reanimated
+ * animatedValue.value = withSequence(
+ *   ...steps.map(s => withTiming(s.value, {
+ *     duration: s.config.duration,
+ *     easing: Easing.bezier(...s.config.easing)
+ *   }))
+ * );
+ */
+export function sequenceSteps(
+  steps: Array<{
+    value: number;
+    duration?: Duration;
+    easing?: EasingKey;
+  }>
+): Array<{
+  value: number;
+  config: ReturnType<typeof timingConfig>;
+}> {
+  return steps.map((step) => ({
+    value: step.value,
+    config: timingConfig(step.duration ?? 'normal', step.easing ?? 'easeOut'),
+  }));
+}

package/src/animation/transitions.ts

@@ -0,0 +1,293 @@
+/**
+ * Web-specific animation utilities
+ *
+ * These utilities generate CSS transition and animation strings
+ * from animation tokens for use in web stylesheets.
+ */
+
+import { durations, easings, presets } from './tokens';
+import type { DurationKey, EasingKey, PresetKey } from './tokens';
+import type {
+  Duration,
+  Keyframes,
+  KeyframeAnimationConfig,
+  AnimationIterations,
+  AnimationDirection,
+  AnimationFillMode,
+} from './types';
+
+/**
+ * Resolve a duration value to milliseconds
+ */
+export function resolveDuration(duration: Duration): number {
+  if (typeof duration === 'number') {
+    return duration;
+  }
+  return durations[duration];
+}
+
+/**
+ * Resolve an easing key to CSS string
+ */
+export function resolveEasing(easing: EasingKey): string {
+  const easingConfig = easings[easing];
+  // Spring configs don't have CSS equivalent, fall back to ease-out
+  if ('damping' in easingConfig) {
+    return 'ease-out';
+  }
+  return easingConfig.css;
+}
+
+/**
+ * Generate a CSS transition string from tokens
+ *
+ * @param properties - CSS property or array of properties to transition
+ * @param duration - Duration token key or milliseconds
+ * @param easing - Easing token key
+ * @returns CSS transition string
+ *
+ * @example
+ * import { cssTransition } from '@idealyst/theme/animation';
+ *
+ * // Single property
+ * cssTransition('opacity', 'normal', 'easeOut')
+ * // => "opacity 200ms ease-out"
+ *
+ * // Multiple properties
+ * cssTransition(['opacity', 'transform'], 'fast', 'standard')
+ * // => "opacity 100ms cubic-bezier(0.4, 0, 0.2, 1), transform 100ms cubic-bezier(0.4, 0, 0.2, 1)"
+ *
+ * // With numeric duration
+ * cssTransition('background-color', 150, 'ease')
+ * // => "background-color 150ms ease"
+ */
+export function cssTransition(
+  properties: string | string[],
+  duration: Duration = 'normal',
+  easing: EasingKey = 'ease'
+): string {
+  const props = Array.isArray(properties) ? properties : [properties];
+  const durationMs = resolveDuration(duration);
+  const easingValue = resolveEasing(easing);
+
+  return props.map((prop) => `${prop} ${durationMs}ms ${easingValue}`).join(', ');
+}
+
+/**
+ * Generate a CSS transition string from a preset
+ *
+ * @param presetName - Preset key from presets
+ * @param properties - Optional CSS properties (defaults to 'all')
+ * @returns CSS transition string
+ *
+ * @example
+ * import { cssPreset } from '@idealyst/theme/animation';
+ *
+ * cssPreset('hover')
+ * // => "all 100ms ease"
+ *
+ * cssPreset('fadeIn', 'opacity')
+ * // => "opacity 200ms cubic-bezier(0, 0, 0.2, 1)"
+ */
+export function cssPreset(presetName: PresetKey, properties: string | string[] = 'all'): string {
+  const preset = presets[presetName];
+  return cssTransition(properties, preset.duration, preset.easing);
+}
+
+/**
+ * Generate CSS @keyframes string
+ *
+ * @param name - Unique name for the keyframes
+ * @param frames - Keyframe definitions
+ * @returns CSS @keyframes string
+ *
+ * @example
+ * import { cssKeyframes } from '@idealyst/theme/animation';
+ *
+ * const fadeIn = cssKeyframes('fadeIn', {
+ *   '0%': { opacity: 0 },
+ *   '100%': { opacity: 1 },
+ * });
+ * // => "@keyframes fadeIn { 0% { opacity: 0; } 100% { opacity: 1; } }"
+ */
+export function cssKeyframes(name: string, frames: Keyframes): string {
+  const frameStrings = Object.entries(frames)
+    .map(([key, styles]) => {
+      const styleString = Object.entries(styles || {})
+        .map(([prop, value]) => {
+          // Convert camelCase to kebab-case
+          const kebabProp = prop.replace(/([A-Z])/g, '-$1').toLowerCase();
+          return `${kebabProp}: ${value}`;
+        })
+        .join('; ');
+      return `${key} { ${styleString}; }`;
+    })
+    .join(' ');
+
+  return `@keyframes ${name} { ${frameStrings} }`;
+}
+
+/**
+ * Generate CSS animation shorthand string
+ *
+ * @param name - Animation name (must match @keyframes name)
+ * @param config - Animation configuration
+ * @returns CSS animation shorthand string
+ *
+ * @example
+ * import { cssAnimation } from '@idealyst/theme/animation';
+ *
+ * cssAnimation('fadeIn', { duration: 'normal', easing: 'easeOut' })
+ * // => "fadeIn 200ms ease-out"
+ *
+ * cssAnimation('spin', { duration: 'loop', easing: 'linear', iterations: 'infinite' })
+ * // => "spin 1000ms linear infinite"
+ */
+export function cssAnimation(name: string, config: KeyframeAnimationConfig = {}): string {
+  const {
+    duration = 'normal',
+    easing = 'ease',
+    delay = 0,
+    iterations = 1,
+    direction = 'normal',
+    fillMode = 'none',
+  } = config;
+
+  const durationMs = resolveDuration(duration);
+  const easingValue = resolveEasing(easing);
+
+  const parts = [
+    name,
+    `${durationMs}ms`,
+    easingValue,
+    delay > 0 ? `${delay}ms` : null,
+    iterations !== 1 ? iterations : null,
+    direction !== 'normal' ? direction : null,
+    fillMode !== 'none' ? fillMode : null,
+  ].filter(Boolean);
+
+  return parts.join(' ');
+}
+
+/**
+ * CSS @property registration for animatable custom properties
+ *
+ * This CSS should be injected once into the document head to enable
+ * smooth gradient animations using CSS custom properties.
+ *
+ * @example
+ * // Inject in your app's entry point
+ * import { gradientPropertyCSS, injectGradientCSS } from '@idealyst/theme/animation';
+ *
+ * // Option 1: Manual injection
+ * const style = document.createElement('style');
+ * style.textContent = gradientPropertyCSS;
+ * document.head.appendChild(style);
+ *
+ * // Option 2: Use helper
+ * injectGradientCSS();
+ */
+export const gradientPropertyCSS = `
+@property --gradient-angle {
+  syntax: '<angle>';
+  initial-value: 0deg;
+  inherits: false;
+}
+
+@property --gradient-position {
+  syntax: '<percentage>';
+  initial-value: 0%;
+  inherits: false;
+}
+
+@keyframes spin-gradient {
+  from { --gradient-angle: 0deg; }
+  to { --gradient-angle: 360deg; }
+}
+
+@keyframes pulse-gradient {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.5; }
+}
+
+@keyframes wave-gradient {
+  from { --gradient-position: -100%; }
+  to { --gradient-position: 200%; }
+}
+`;
+
+let gradientCSSInjected = false;
+
+/**
+ * Inject gradient CSS into document head (idempotent)
+ *
+ * Call this once in your app to enable gradient border animations.
+ * Safe to call multiple times - will only inject once.
+ */
+export function injectGradientCSS(): void {
+  if (typeof document === 'undefined' || gradientCSSInjected) {
+    return;
+  }
+
+  const style = document.createElement('style');
+  style.id = 'idealyst-gradient-animations';
+  style.textContent = gradientPropertyCSS;
+  document.head.appendChild(style);
+  gradientCSSInjected = true;
+}
+
+/**
+ * Generate conic gradient border spinner styles
+ *
+ * @param colors - Array of gradient colors
+ * @param borderWidth - Border thickness in pixels
+ * @param duration - Animation duration
+ * @returns Style object for animated gradient border
+ *
+ * @example
+ * import { conicSpinnerStyle } from '@idealyst/theme/animation';
+ *
+ * const spinnerStyle = conicSpinnerStyle(
+ *   ['#3b82f6', '#8b5cf6', '#ec4899'],
+ *   2,
+ *   2000
+ * );
+ */
+export function conicSpinnerStyle(
+  colors: string[],
+  borderWidth: number = 2,
+  duration: Duration = 2000
+): Record<string, string | number> {
+  const durationMs = resolveDuration(duration);
+  const colorString = colors.join(', ');
+
+  return {
+    background: `conic-gradient(from var(--gradient-angle), ${colorString})`,
+    animation: `spin-gradient ${durationMs}ms linear infinite`,
+    // Mask technique for border-only effect
+    WebkitMask: 'linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0)',
+    WebkitMaskComposite: 'xor',
+    maskComposite: 'exclude',
+    padding: borderWidth,
+  };
+}
+
+/**
+ * Generate pulse gradient styles
+ *
+ * @param colors - Array of gradient colors
+ * @param duration - Animation duration
+ * @returns Style object for pulsing gradient
+ */
+export function pulseGradientStyle(
+  colors: string[],
+  duration: Duration = 'slowest'
+): Record<string, string | number> {
+  const durationMs = resolveDuration(duration);
+  const colorString = colors.join(', ');
+
+  return {
+    background: `linear-gradient(135deg, ${colorString})`,
+    animation: `pulse-gradient ${durationMs}ms ease-in-out infinite`,
+  };
+}

package/src/animation/types.ts

@@ -0,0 +1,80 @@
+/**
+ * Animation type definitions for @idealyst/theme
+ */
+
+import type { durations, easings } from './tokens';
+
+// Duration types
+export type DurationKey = keyof typeof durations;
+export type Duration = DurationKey | number;
+
+// Easing types
+export type EasingKey = keyof typeof easings;
+export type BezierEasing = readonly [number, number, number, number];
+export type SpringConfig = {
+  readonly damping: number;
+  readonly stiffness: number;
+  readonly mass: number;
+};
+
+export type CSSEasing = {
+  readonly css: string;
+  readonly bezier: BezierEasing;
+};
+
+export type Easing = CSSEasing | SpringConfig;
+
+// Animation configuration
+export interface AnimationConfig {
+  duration?: Duration;
+  easing?: EasingKey;
+  delay?: number;
+}
+
+// Transition configuration for CSS
+export interface TransitionConfig extends AnimationConfig {
+  properties?: string | string[];
+}
+
+// Keyframe types
+export type KeyframeStyles = Record<string, React.CSSProperties>;
+export type KeyframePercentage = `${number}%` | 'from' | 'to';
+export type Keyframes = Partial<Record<KeyframePercentage, React.CSSProperties>>;
+
+// Animation iteration
+export type AnimationIterations = number | 'infinite';
+export type AnimationDirection = 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
+export type AnimationFillMode = 'none' | 'forwards' | 'backwards' | 'both';
+
+// Full animation configuration
+export interface KeyframeAnimationConfig extends AnimationConfig {
+  iterations?: AnimationIterations;
+  direction?: AnimationDirection;
+  fillMode?: AnimationFillMode;
+}
+
+// Spring types for native
+export type SpringType = 'spring' | 'springStiff' | 'springBouncy';
+
+// Timing config for Reanimated
+export interface TimingAnimationConfig {
+  duration: number;
+  easing: BezierEasing;
+}
+
+// Platform-specific options
+export interface PlatformAnimationOptions {
+  web?: Partial<TransitionConfig> & { transition?: string };
+  native?: Partial<AnimationConfig> & Partial<SpringConfig>;
+}
+
+// Gradient animation types
+export type GradientAnimation = 'spin' | 'pulse' | 'wave';
+
+export interface GradientBorderConfig {
+  colors: string[];
+  borderWidth?: number;
+  borderRadius?: number;
+  duration?: Duration;
+  animation?: GradientAnimation;
+}

package/src/builder.ts

@@ -20,6 +20,7 @@ import {
     ProgressSizeValue,
     AccordionSizeValue,
     ActivityIndicatorSizeValue,
+    AlertSizeValue,
     BreadcrumbSizeValue,
     ListSizeValue,
     MenuSizeValue,
@@ -68,6 +69,7 @@ export type BuiltTheme<
         progress: Record<TSize, ProgressSizeValue>;
         accordion: Record<TSize, AccordionSizeValue>;
         activityIndicator: Record<TSize, ActivityIndicatorSizeValue>;
+        alert: Record<TSize, AlertSizeValue>;
         breadcrumb: Record<TSize, BreadcrumbSizeValue>;
         list: Record<TSize, ListSizeValue>;
         menu: Record<TSize, MenuSizeValue>;
@@ -259,6 +261,7 @@ export class ThemeBuilder<
         progress: Record<S, ProgressSizeValue>;
         accordion: Record<S, AccordionSizeValue>;
         activityIndicator: Record<S, ActivityIndicatorSizeValue>;
+        alert: Record<S, AlertSizeValue>;
         breadcrumb: Record<S, BreadcrumbSizeValue>;
         list: Record<S, ListSizeValue>;
         menu: Record<S, MenuSizeValue>;

package/src/components/CLAUDE.md

@@ -141,7 +141,7 @@ function createSizeVariants(theme: Theme) {
 
 #### Colors
 - **Intents**: `theme.intents[intent].primary`, `.contrast`, `.light`, `.dark`
-  - Available intents: `primary`, `success`, `error`, `warning`, `neutral`, `info`
+  - Available intents: `primary`, `success`, `danger`, `warning`, `neutral`, `info`
 - **Surface**: `theme.colors.surface.primary`, `.secondary`, `.tertiary`, `.inverse`, etc.
 - **Text**: `theme.colors.text.primary`, `.secondary`, `.tertiary`, `.inverse`, etc.
 - **Border**: `theme.colors.border.primary`, `.secondary`, `.tertiary`, `.disabled`

package/src/config/generator.ts

@@ -636,7 +636,7 @@ function generateInputStyles(theme: Theme, extensions?: ComponentExtensions): Re
             },
             error: {
                 true: {
-                    borderColor: themeRef('intents.error.primary'),
+                    borderColor: themeRef('intents.danger.primary'),
                 },
                 false: {},
             },
@@ -666,7 +666,7 @@ function generateInputStyles(theme: Theme, extensions?: ComponentExtensions): Re
         fontSize: 12,
         variants: {
             error: {
-                true: { color: themeRef('intents.error.primary') },
+                true: { color: themeRef('intents.danger.primary') },
                 false: {},
             },
         },

package/src/darkTheme.ts

@@ -20,7 +20,7 @@ export const darkTheme = createTheme()
         light: '#6ee7b7',
         dark: '#047857',
     })
-    .addIntent('error', {
+    .addIntent('danger', {
         primary: '#f87171',
         contrast: '#0f172a',
         light: '#fca5a5',

package/src/index.ts

@@ -23,4 +23,8 @@ export * from './componentStyles';
 // Responsive utilities
 export * from './responsive';
 export * from './breakpoints';
-export * from './useResponsiveStyle';
+export * from './useResponsiveStyle';
+
+// Animation tokens and utilities
+// Note: Use '@idealyst/theme/animation' for full animation API
+export { durations, easings, presets } from './animation/tokens';

package/src/lightTheme.ts

@@ -19,7 +19,7 @@ export const lightTheme = createTheme()
         light: '#a7f3d0',
         dark: '#165e29',
     })
-    .addIntent('error', {
+    .addIntent('danger', {
         primary: '#ef4444',
         contrast: '#ffffff',
         light: '#fca5a1',
@@ -211,6 +211,13 @@ export const lightTheme = createTheme()
             lg: { size: 48, borderWidth: 4 },
             xl: { size: 64, borderWidth: 5 },
         },
+        alert: {
+            xs: { padding: 8, gap: 6, borderRadius: 4, titleFontSize: 12, titleLineHeight: 16, messageFontSize: 11, messageLineHeight: 14, iconSize: 16, closeIconSize: 12 },
+            sm: { padding: 12, gap: 8, borderRadius: 6, titleFontSize: 14, titleLineHeight: 20, messageFontSize: 12, messageLineHeight: 16, iconSize: 20, closeIconSize: 14 },
+            md: { padding: 16, gap: 10, borderRadius: 8, titleFontSize: 16, titleLineHeight: 24, messageFontSize: 14, messageLineHeight: 20, iconSize: 24, closeIconSize: 16 },
+            lg: { padding: 20, gap: 12, borderRadius: 10, titleFontSize: 18, titleLineHeight: 28, messageFontSize: 16, messageLineHeight: 24, iconSize: 28, closeIconSize: 18 },
+            xl: { padding: 24, gap: 14, borderRadius: 12, titleFontSize: 20, titleLineHeight: 32, messageFontSize: 18, messageLineHeight: 28, iconSize: 32, closeIconSize: 20 },
+        },
         breadcrumb: {
             xs: { fontSize: 10, lineHeight: 14, iconSize: 12 },
             sm: { fontSize: 12, lineHeight: 16, iconSize: 14 },

package/src/styleBuilder.ts

@@ -54,6 +54,7 @@ export type ComponentName =
   | 'Table'
   | 'Text'
   | 'TextArea'
+  | 'TextInput'
   | 'TimePicker'
   | 'Tooltip'
   | 'Video'

package/src/theme/extensions.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-empty-object-type */
 
-import type { IntentValue, ShadowValue, Shade, ColorValue, InteractionConfig, ButtonSizeValue, ChipSizeValue, BadgeSizeValue, IconSizeValue, InputSizeValue, RadioButtonSizeValue, SelectSizeValue, SliderSizeValue, SwitchSizeValue, TextAreaSizeValue, AvatarSizeValue, ProgressSizeValue, AccordionSizeValue, ActivityIndicatorSizeValue, BreadcrumbSizeValue, ListSizeValue, MenuSizeValue, TextSizeValue, TabBarSizeValue, TableSizeValue, TooltipSizeValue, ViewSizeValue, Typography, TypographyValue } from './structures';
+import type { IntentValue, ShadowValue, Shade, ColorValue, InteractionConfig, ButtonSizeValue, ChipSizeValue, BadgeSizeValue, IconSizeValue, InputSizeValue, RadioButtonSizeValue, SelectSizeValue, SliderSizeValue, SwitchSizeValue, TextAreaSizeValue, AvatarSizeValue, ProgressSizeValue, AccordionSizeValue, ActivityIndicatorSizeValue, AlertSizeValue, BreadcrumbSizeValue, ListSizeValue, MenuSizeValue, TextSizeValue, TabBarSizeValue, TableSizeValue, TooltipSizeValue, ViewSizeValue, Typography, TypographyValue } from './structures';
 
 /**
  * Default fallback theme structure.
@@ -32,6 +32,7 @@ export interface DefaultTheme {
         progress: Record<string, ProgressSizeValue>;
         accordion: Record<string, AccordionSizeValue>;
         activityIndicator: Record<string, ActivityIndicatorSizeValue>;
+        alert: Record<string, AlertSizeValue>;
         breadcrumb: Record<string, BreadcrumbSizeValue>;
         list: Record<string, ListSizeValue>;
         menu: Record<string, MenuSizeValue>;

package/src/theme/structures.ts

@@ -194,6 +194,18 @@ export type ActivityIndicatorSizeValue = {
     borderWidth: SizeValue;
 };
 
+export type AlertSizeValue = {
+    padding: SizeValue;
+    gap: SizeValue;
+    borderRadius: SizeValue;
+    titleFontSize: SizeValue;
+    titleLineHeight: SizeValue;
+    messageFontSize: SizeValue;
+    messageLineHeight: SizeValue;
+    iconSize: SizeValue;
+    closeIconSize: SizeValue;
+};
+
 export type BreadcrumbSizeValue = {
     fontSize: SizeValue;
     lineHeight: SizeValue;