blinc_theme/lib.rs
1//! Blinc Theme System
2//!
3//! A comprehensive theming system with design tokens, platform-native themes,
4//! and system dark/light mode detection.
5//!
6//! # Overview
7//!
8//! The theme system provides:
9//! - **Design tokens**: Colors, typography, spacing, radii, shadows, animations
10//! - **Platform themes**: Native look and feel for macOS, Windows, Linux, iOS, Android
11//! - **Color scheme detection**: Automatic detection of system dark/light mode
12//! - **Dynamic overrides**: Runtime customization without layout rebuilds
13//!
14//! # Quick Start
15//!
16//! ```rust,ignore
17//! use blinc_theme::{ThemeState, ColorToken};
18//!
19//! // Initialize theme at app startup
20//! ThemeState::init_default();
21//!
22//! // Access theme in widgets
23//! let theme = ThemeState::get();
24//! let primary_color = theme.color(ColorToken::Primary);
25//! let spacing = theme.spacing();
26//! ```
27//!
28//! # Architecture
29//!
30//! The theme system is designed to minimize UI rebuilds:
31//!
32//! - **Visual tokens** (colors, shadows): Changes trigger repaint only
33//! - **Layout tokens** (spacing, typography): Changes trigger partial layout
34//!
35//! # Tokens
36//!
37//! Tokens are the atomic values that make up the design system:
38//!
39//! - [`ColorTokens`]: Semantic colors (primary, error, background, text, etc.)
40//! - [`TypographyTokens`]: Font families, sizes, weights, line heights
41//! - [`SpacingTokens`]: 4px-based spacing scale
42//! - [`RadiusTokens`]: Border radii
43//! - [`ShadowTokens`]: Box shadows
44//! - [`AnimationTokens`]: Durations and easings
45//!
46//! # Themes
47//!
48//! Built-in themes:
49//!
50//! - [`BlincTheme`]: Default theme derived from Catppuccin design system
51//! - Platform-specific themes for macOS, Windows, Linux, iOS, Android
52//!
53//! # Dynamic Overrides
54//!
55//! Override tokens at runtime without full rebuilds:
56//!
57//! ```rust,ignore
58//! let theme = ThemeState::get();
59//!
60//! // Override a color (repaint only, no layout)
61//! theme.set_color_override(ColorToken::Primary, Color::from_hex(0xFF5500));
62//!
63//! // Override spacing (triggers partial layout)
64//! theme.set_spacing_override(SpacingToken::Space4, 20.0);
65//!
66//! // Clear all overrides
67//! theme.clear_overrides();
68//! ```
69
70pub mod platform;
71pub mod state;
72pub mod theme;
73pub mod themes;
74pub mod tokens;
75
76#[cfg(feature = "watcher")]
77pub mod watcher;
78
79// Re-export commonly used types
80pub use platform::{detect_system_color_scheme, Platform};
81pub use state::{set_redraw_callback, ThemeState};
82pub use theme::{ColorScheme, Theme, ThemeBundle};
83pub use themes::{platform::platform_theme_bundle, BlincTheme};
84pub use tokens::*;
85
86#[cfg(feature = "watcher")]
87pub use watcher::{SystemSchemeWatcher, WatcherConfig};