Theming
Learn how to customize Scaffald UI to match your brand and design system.
Theme Provider
Wrap your app with the ThemeProvider to enable theming. You can use it in uncontrolled mode (provider owns state and persistence) or controlled mode (your app owns state and passes theme + onThemeChange).
Uncontrolled (default)
import { ThemeProvider } from '@scaffald/ui';
export default function App() {
return (
<ThemeProvider initialTheme="system">
{/* Your app content */}
</ThemeProvider>
);
}
initialThemecan be'light' | 'dark' | 'system'. Default is'system'.- Theme is persisted (localStorage on web, AsyncStorage on native) under the key
beyond-ui-theme. - System appearance changes are respected when preference is
'system'.
Controlled mode (single source of truth)
When your app already has its own theme context, pass the current resolved theme and a change handler so the UI package follows your app's theme:
import { ThemeProvider } from '@scaffald/ui';
function AppWithOwnTheme() {
const { theme, setTheme } = useMyAppTheme();
const resolved = theme === 'earth' ? 'light' : theme;
return (
<ThemeProvider
theme={resolved}
onThemeChange={(pref) => setTheme(pref === 'system' ? getSystemTheme() : pref)}
>
{/* Your app content */}
</ThemeProvider>
);
}
- Use one theme source per app. Either the app drives theme (controlled) or
ThemeProviderdrives it (uncontrolled). - forsured-web: App
ThemeProvideris the source;BeyondUIProvideruses controlledThemeProvider(earth maps to light for UI). - scaffald app:
UniversalThemeProvider(scf-core) is the source; a bridge usesuseThemeSetting()and rendersThemeProviderwiththemeandonThemeChange.
Using the Theme
Access the current theme in any component:
import { useThemeContext } from '@scaffald/ui';
function MyComponent() {
const { theme, setTheme } = useThemeContext();
return (
<View>
<Text>Current theme: {theme}</Text>
<Button onPress={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
Toggle Theme
</Button>
</View>
);
}
Color Tokens
Scaffald UI uses semantic color tokens that automatically adapt to light/dark themes:
import { colors, useThemeContext } from '@scaffald/ui';
function ThemedComponent() {
const { theme } = useThemeContext();
return (
<View style={{
backgroundColor: colors.bg[theme].default,
borderColor: colors.border[theme].default,
}}>
<Text style={{ color: colors.text[theme].primary }}>
Themed Content
</Text>
</View>
);
}
Color Token Structure
colors.{semantic}.{theme}.{variant}
Semantic Categories:
bg- Backgroundstext- Text colorsborder- Bordersfg- Foregroundsicon- Icons
Themes:
lightdark
Variants:
defaultsubtlemutedprimarysecondarysuccesswarningerrorinfo
Examples
// Background colors
colors.bg[theme].default // Main background
colors.bg[theme].subtle // Subtle background
colors.bg[theme].primary // Primary brand background
// Text colors
colors.text[theme].primary // Primary text
colors.text[theme].secondary // Secondary text
colors.text[theme].muted // Muted text
// Border colors
colors.border[theme].default // Default borders
colors.border[theme].primary // Primary borders
Custom Themes
Create custom theme configurations:
import { colors } from '@scaffald/ui';
const customTheme = {
light: {
...colors.bg.light,
primary: '#FF6B6B', // Custom primary color
secondary: '#4ECDC4', // Custom secondary color
},
dark: {
...colors.bg.dark,
primary: '#FF6B6B',
secondary: '#4ECDC4',
},
};
Typography Tokens
Use typography tokens for consistent text styling:
import { typography } from '@scaffald/ui';
<Text style={typography.h1}>Heading 1</Text>
<Text style={typography.body}>Body text</Text>
<Text style={typography.caption}>Caption text</Text>
Available typography variants:
h1,h2,h3,h4,h5,h6- Headingsbody,bodyLarge,bodySmall- Body textcaption- Small textlabel- Form labels
Spacing Tokens
Use spacing tokens for consistent layouts:
import { spacing } from '@scaffald/ui';
<Stack gap={spacing[4]} padding={spacing[6]}>
{/* Content */}
</Stack>
Spacing scale (in pixels):
spacing[0]= 0spacing[1]= 4spacing[2]= 8spacing[3]= 12spacing[4]= 16spacing[5]= 20spacing[6]= 24spacing[8]= 32spacing[10]= 40spacing[12]= 48spacing[16]= 64
Shadow Tokens
Apply consistent shadows:
import { shadows } from '@scaffald/ui';
<Card style={shadows.md}>
{/* Content */}
</Card>
Shadow levels:
shadows.sm- Small shadowshadows.md- Medium shadowshadows.lg- Large shadowshadows.xl- Extra large shadow
Responsive Design
Use breakpoints for responsive layouts:
import { breakpoints } from '@scaffald/ui';
const styles = StyleSheet.create({
container: {
width: '100%',
maxWidth: breakpoints.lg, // 1024px
},
});
Breakpoints:
breakpoints.sm= 640pxbreakpoints.md= 768pxbreakpoints.lg= 1024pxbreakpoints.xl= 1280pxbreakpoints.2xl= 1536px
Dark Mode
Scaffald UI components automatically adapt to dark mode when you change the theme:
import { useThemeContext, Button } from '@scaffald/ui';
function ThemeToggle() {
const { theme, setTheme } = useThemeContext();
return (
<Button
onPress={() => setTheme(theme === 'light' ? 'dark' : 'light')}
iconStart={theme === 'light' ? <MoonIcon /> : <SunIcon />}
>
{theme === 'light' ? 'Dark' : 'Light'} Mode
</Button>
);
}
System Theme Detection
Respect user's system preferences:
import { useColorScheme } from 'react-native';
import { ThemeProvider } from '@scaffald/ui';
export default function App() {
const systemTheme = useColorScheme();
return (
<ThemeProvider initialTheme={systemTheme || 'light'}>
{/* Your app */}
</ThemeProvider>
);
}
Best Practices
- Always use theme tokens - Don't hardcode colors
- Test both themes - Ensure your UI works in light and dark modes
- Respect system preferences - Allow users to choose their preferred theme
- Use semantic tokens - Use
colors.text[theme].primaryinstead of#000000 - Consistent spacing - Use spacing tokens for all margins and padding