august-design-system
Version:
A comprehensive React Native design system following Apple Human Interface Guidelines
316 lines (309 loc) • 8.6 kB
text/typescript
import { T as Theme, b as ThemeConfig, d as CustomThemeConfig, c as ThemeExtension, e as ThemeContextValue, f as ThemeProviderProps, C as ColorMode } from '../theme.types-BF73i5o1.mjs';
import { C as ColorTokens, S as SpacingTokens, b as TypographyTokens } from '../tokens.types-kLhwMiT-.mjs';
import React from 'react';
/**
* AugustDesignSystem - Default Theme
*
* Complete theme definitions for light and dark modes.
* This file assembles all tokens into cohesive theme objects.
*/
/**
* Default light theme.
* Primary theme for standard iOS appearance.
*/
declare const lightTheme: Theme;
/**
* Default dark theme.
* Dark mode appearance following iOS dark mode conventions.
*/
declare const darkTheme: Theme;
/**
* Complete theme configuration containing both modes.
*/
declare const defaultThemeConfig: ThemeConfig;
/**
* Creates a theme by selecting the appropriate mode.
* @param mode - Color mode to use
*/
declare function getTheme(mode: 'light' | 'dark'): Theme;
/**
* AugustDesignSystem - Theme Creation Utilities
*
* Functions for creating custom themes by extending the default theme.
* Supports deep merging of partial theme overrides.
*/
/**
* Creates a custom theme by extending the default light theme.
*
* @param name - Name identifier for the theme
* @param extension - Partial theme overrides
* @returns Complete theme with overrides applied
*
* @example
* ```typescript
* const brandTheme = createLightTheme('Brand Light', {
* colors: {
* interactive: {
* tint: '#FF6B00',
* },
* },
* });
* ```
*/
declare function createLightTheme(name: string, extension?: ThemeExtension): Theme;
/**
* Creates a custom dark theme by extending the default dark theme.
*
* @param name - Name identifier for the theme
* @param extension - Partial theme overrides
* @returns Complete theme with overrides applied
*
* @example
* ```typescript
* const brandDarkTheme = createDarkTheme('Brand Dark', {
* colors: {
* interactive: {
* tint: '#FF8533',
* },
* },
* });
* ```
*/
declare function createDarkTheme(name: string, extension?: ThemeExtension): Theme;
/**
* Creates a complete theme configuration with both light and dark modes.
*
* @param config - Custom theme configuration
* @returns Complete theme config with both modes
*
* @example
* ```typescript
* const brandTheme = createTheme({
* name: 'Brand',
* light: {
* colors: {
* interactive: { tint: '#FF6B00' },
* },
* },
* dark: {
* colors: {
* interactive: { tint: '#FF8533' },
* },
* },
* });
* ```
*/
declare function createTheme(config: CustomThemeConfig): ThemeConfig;
/**
* Creates color overrides for a theme.
* Useful for applying brand colors consistently.
*
* @param primary - Primary brand color
* @param options - Additional color options
*/
declare function createBrandColors(primary: string, options?: {
primaryPressed?: string;
primaryDisabled?: string;
secondary?: string;
}): ThemeExtension;
/**
* Creates typography overrides for a theme.
* Useful for applying custom fonts.
*
* @param fontFamilies - Font family overrides
*/
declare function createCustomTypography(fontFamilies: {
regular?: string;
medium?: string;
semibold?: string;
bold?: string;
}): ThemeExtension;
/**
* Merges multiple theme extensions into one.
*
* @param extensions - Theme extensions to merge
*/
declare function mergeExtensions(...extensions: ThemeExtension[]): ThemeExtension;
/**
* Validates that a theme object has all required properties.
* Useful for runtime theme validation.
*
* @param theme - Theme object to validate
* @returns True if theme is valid
*/
declare function isValidTheme(theme: unknown): theme is Theme;
/**
* Gets a specific token value from a theme using a path string.
*
* @param theme - Theme to extract from
* @param path - Dot-notation path (e.g., 'colors.background.primary')
* @returns Token value or undefined
*
* @example
* ```typescript
* const bgColor = getTokenValue(theme, 'colors.background.primary');
* // Returns '#FFFFFF' for light theme
* ```
*/
declare function getTokenValue<T = unknown>(theme: Theme, path: string): T | undefined;
/**
* Theme context for providing theme values to components.
*/
declare const ThemeContext: React.Context<ThemeContextValue>;
/**
* ThemeProvider component that manages theme state and provides it to children.
*
* Features:
* - Automatic system color scheme detection
* - Light/dark mode toggle
* - Custom theme extension support
* - Memoized theme object for performance
*
* @example
* ```tsx
* // Basic usage
* <ThemeProvider>
* <App />
* </ThemeProvider>
*
* // With custom theme
* <ThemeProvider
* defaultColorMode="dark"
* theme={{
* name: 'Brand',
* light: { colors: { interactive: { tint: '#FF6B00' } } },
* dark: { colors: { interactive: { tint: '#FF8533' } } },
* }}
* >
* <App />
* </ThemeProvider>
* ```
*/
declare function ThemeProvider({ children, defaultColorMode, theme: customTheme, storageKey, }: ThemeProviderProps): React.ReactElement;
/**
* Hook to access the current theme context.
*
* @returns Theme context value including theme object and mode controls
* @throws Warning if used outside ThemeProvider
*
* @example
* ```tsx
* function MyComponent() {
* const { theme, isDark, toggleColorMode } = useTheme();
*
* return (
* <View style={{ backgroundColor: theme.colors.background.primary }}>
* <Text style={{ color: theme.colors.label.primary }}>
* Current mode: {isDark ? 'Dark' : 'Light'}
* </Text>
* <Button title="Toggle" onPress={toggleColorMode} />
* </View>
* );
* }
* ```
*/
declare function useTheme(): ThemeContextValue;
/**
* Hook to access only the theme object (without mode controls).
* Useful when you only need token values.
*
* @returns Current theme object
*
* @example
* ```tsx
* function MyComponent() {
* const theme = useThemeTokens();
*
* return (
* <View style={{
* backgroundColor: theme.colors.background.primary,
* padding: theme.spacing.lg,
* }}>
* <Text style={theme.typography.body}>Hello</Text>
* </View>
* );
* }
* ```
*/
declare function useThemeTokens(): Theme;
/**
* Hook to access the current color mode.
*
* @returns Current color mode ('light' | 'dark')
*
* @example
* ```tsx
* function MyComponent() {
* const colorMode = useColorMode();
* const Icon = colorMode === 'dark' ? MoonIcon : SunIcon;
* return <Icon />;
* }
* ```
*/
declare function useColorMode(): ColorMode;
/**
* Hook that returns true if current mode is dark.
*
* @returns Boolean indicating dark mode
*
* @example
* ```tsx
* function MyComponent() {
* const isDark = useIsDarkMode();
* return <Text>{isDark ? 'Dark mode active' : 'Light mode active'}</Text>;
* }
* ```
*/
declare function useIsDarkMode(): boolean;
/**
* Hook to get a specific token value from the current theme.
*
* @param selector - Function to select token from theme
* @returns Selected token value
*
* @example
* ```tsx
* function MyComponent() {
* const primaryBg = useToken(t => t.colors.background.primary);
* const bodyStyle = useToken(t => t.typography.body);
*
* return (
* <View style={{ backgroundColor: primaryBg }}>
* <Text style={bodyStyle}>Hello</Text>
* </View>
* );
* }
* ```
*/
declare function useToken<T>(selector: (theme: Theme) => T): T;
/**
* Hook to get color tokens from the current theme.
*
* @returns Color tokens object
*
* @example
* ```tsx
* function MyComponent() {
* const colors = useColors();
* return (
* <View style={{ backgroundColor: colors.background.primary }}>
* <Text style={{ color: colors.label.primary }}>Hello</Text>
* </View>
* );
* }
* ```
*/
declare function useColors(): ColorTokens;
/**
* Hook to get spacing tokens from the current theme.
*
* @returns Spacing tokens object
*/
declare function useSpacing(): SpacingTokens;
/**
* Hook to get typography tokens from the current theme.
*
* @returns Typography tokens object
*/
declare function useTypography(): TypographyTokens;
export { ThemeContext, ThemeProvider, createBrandColors, createCustomTypography, createDarkTheme, createLightTheme, createTheme, darkTheme, defaultThemeConfig, getTheme, getTokenValue, isValidTheme, lightTheme, mergeExtensions, useColorMode, useColors, useIsDarkMode, useSpacing, useTheme, useThemeTokens, useToken, useTypography };