Overview
The global.css file is the main entry point for Uniwind’s styling system. It’s where you import Tailwind and Uniwind, define theme-specific CSS variables, customize Tailwind’s configuration, and add global styles for your entire application.
The global.css file must be imported in your app’s entry point (usually App.tsx) for Uniwind to work correctly.
Required Imports
Every global.css file must include these two essential imports:
/* Required: Import Tailwind CSS */
@import 'tailwindcss';
/* Required: Import Uniwind */
@import 'uniwind';
- All Tailwind utility classes
- Uniwind’s React Native compatibility layer
- Theme-based variants (
dark:, light)
- Platform-specific variants (
ios:, android:, web:)
Customizing Tailwind Configuration
Use the @theme directive to customize Tailwind’s default configuration values:
Modifying Design Tokens
@import 'tailwindcss';
@import 'uniwind';
@theme {
/* Customize base font size */
--font-size-base: 15px;
/* Customize spacing scale */
--spacing-1: 4px;
--spacing-2: 8px;
--spacing-3: 12px;
--spacing-4: 16px;
/* Customize border radius */
--radius-sm: 4px;
--radius-md: 8px;
--radius-lg: 12px;
--radius-xl: 16px;
/* Add custom colors */
--color-primary: #3b82f6;
--color-secondary: #8b5cf6;
--color-accent: #ec4899;
}
Extending the Color Palette
@theme {
/* Add brand colors */
--color-brand-50: #eff6ff;
--color-brand-100: #dbeafe;
--color-brand-200: #bfdbfe;
--color-brand-300: #93c5fd;
--color-brand-400: #60a5fa;
--color-brand-500: #3b82f6;
--color-brand-600: #2563eb;
--color-brand-700: #1d4ed8;
--color-brand-800: #1e40af;
--color-brand-900: #1e3a8a;
}
<View className="bg-brand-500 text-white p-4" />
Theme-Specific Variables
Define different CSS variable values for each theme using the @layer theme directive with @variant:
Basic Theme Variables
@import 'tailwindcss';
@import 'uniwind';
@layer theme {
:root {
/* Dark theme variables */
@variant dark {
--color-background: #000000;
--color-foreground: #ffffff;
--color-muted: #374151;
--color-border: #1f2937;
}
/* Light theme variables */
@variant light {
--color-background: #ffffff;
--color-foreground: #000000;
--color-muted: #f3f4f6;
--color-border: #e5e7eb;
}
}
}
Complete Theme System
@import 'tailwindcss';
@import 'uniwind';
@layer theme {
:root {
@variant dark {
/* Backgrounds */
--color-background: #000000;
--color-background-secondary: #111827;
--color-card: #1f2937;
/* Text colors */
--color-foreground: #ffffff;
--color-foreground-secondary: #9ca3af;
--color-muted: #6b7280;
/* Borders */
--color-border: #374151;
--color-border-subtle: #1f2937;
/* Interactive elements */
--color-primary: #3b82f6;
--color-primary-hover: #2563eb;
--color-danger: #ef4444;
--color-success: #10b981;
--color-warning: #f59e0b;
}
@variant light {
/* Backgrounds */
--color-background: #ffffff;
--color-background-secondary: #f9fafb;
--color-card: #ffffff;
/* Text colors */
--color-foreground: #111827;
--color-foreground-secondary: #6b7280;
--color-muted: #9ca3af;
/* Borders */
--color-border: #e5e7eb;
--color-border-subtle: #f3f4f6;
/* Interactive elements */
--color-primary: #3b82f6;
--color-primary-hover: #2563eb;
--color-danger: #ef4444;
--color-success: #10b981;
--color-warning: #f59e0b;
}
}
}
OKLCH Color Support
Uniwind supports modern OKLCH color space, which provides more perceptually uniform colors and better color manipulation compared to traditional RGB/HSL:
@layer theme {
:root {
@variant dark {
--color-background: oklch(0.1316 0.0041 17.69);
--color-foreground: oklch(0.18 0.0033 17.46);
--color-primary: oklch(0 0 0);
--color-inverted: oklch(1 0 0);
--color-gray: oklch(0.452 0.0042 39.45);
}
@variant light {
--color-background: oklch(1 0 0);
--color-foreground: oklch(96.715% 0.00011 271.152);
--color-primary: oklch(1 0 0);
--color-inverted: oklch(0 0 0);
--color-gray: oklch(0.9612 0 0);
}
}
}
- Perceptually uniform: Colors that look equally bright to the human eye
- Wider color gamut: Access to more vibrant colors on modern displays
- Better interpolation: Smooth color transitions without muddy intermediate colors
- Consistent lightness: Easier to create accessible color palettes
Using Theme Variables
Once defined, reference your CSS variables directly as Tailwind utilities:
import { View, Text } from 'react-native'
export const ThemedCard = () => (
<View className="bg-card border border-border p-4 rounded-lg">
<Text className="text-foreground text-lg font-bold">
Card Title
</Text>
<Text className="text-foreground-secondary mt-2">
This card automatically adapts to the current theme
</Text>
</View>
)
No need to use var() or brackets! Simply use the variable name without the --color- prefix. For example, --color-primary becomes bg-primary or text-primary.
Custom Themes
Define variables for custom themes beyond light and dark:
@layer theme {
:root {
@variant dark {
--color-background: #000000;
--color-foreground: #ffffff;
}
@variant light {
--color-background: #ffffff;
--color-foreground: #000000;
}
/* Custom ocean theme */
@variant ocean {
--color-background: #0c4a6e;
--color-foreground: #e0f2fe;
--color-primary: #06b6d4;
--color-accent: #67e8f9;
}
/* Custom sunset theme */
@variant sunset {
--color-background: #7c2d12;
--color-foreground: #fef3c7;
--color-primary: #f59e0b;
--color-accent: #fb923c;
}
}
}
You can use any valid CSS in global.css. For more information, check the CSS Parser documentation. Best Practices
Use semantic variable names: Name variables based on their purpose (e.g., --color-background, --color-primary) rather than their value (e.g., --color-blue-500).
Keep theme variables consistent: Ensure all themes define the same set of variables. If you miss a variable in one theme, we will warn you about it in __DEV__ mode.
Avoid hard-coded colors in components: Use CSS variables for colors that should adapt to themes. This ensures your UI remains consistent across theme changes.
