mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-24 16:22:16 +00:00
Wim Van LaerandGitHub
699ed17918
# Which Problems Are Solved naming inconsistencies: Configuration <-> Settings # How the Problems Are Solved # Additional Changes # Additional Context - Closes #11282
139 lines
4.0 KiB
Markdown
139 lines
4.0 KiB
Markdown
# Login App Theme Customization Guide
|
|
|
|
This guide helps you customize the appearance of your ZITADEL login application for a personalized user experience.
|
|
|
|
## Quick Start
|
|
|
|
1. Copy the theme variables you want to customize from `.env.theme.example` to your `.env.local` file
|
|
2. Restart your application
|
|
3. Your theme changes will be applied automatically
|
|
|
|
## Theme Options
|
|
|
|
### 🔄 Roundness (`NEXT_PUBLIC_THEME_ROUNDNESS`)
|
|
|
|
Controls how rounded the UI elements appear:
|
|
|
|
- **`edgy`** - Sharp, rectangular corners (modern tech, corporate)
|
|
- **`mid`** - Medium rounded corners (balanced, professional)
|
|
- **`full`** - Fully rounded corners (friendly, approachable)
|
|
|
|
### 📱 Layout (`NEXT_PUBLIC_THEME_LAYOUT`)
|
|
|
|
Controls the overall page structure:
|
|
|
|
- **`side-by-side`** - Brand section on left, form on right (desktop view)
|
|
- **`top-to-bottom`** - Brand section on top, form below (mobile-first)
|
|
|
|
### 📏 Spacing (`NEXT_PUBLIC_THEME_SPACING`)
|
|
|
|
Controls spacing and padding throughout the interface:
|
|
|
|
- **`regular`** - Standard spacing with comfortable padding (p-6, space-y-6)
|
|
- **`compact`** - Tighter spacing for information-dense layouts (p-4, space-y-4)
|
|
|
|
### 🎨 Appearance (`NEXT_PUBLIC_THEME_APPEARANCE`)
|
|
|
|
Complete design philosophies:
|
|
|
|
- **`flat`** - Minimal flat design with cards matching background color, subtle borders, and normal typography
|
|
- **`material`** - Material Design inspired with elevated cards, proper contrast, and medium typography
|
|
|
|
### 🖼️ Background Image (`NEXT_PUBLIC_THEME_BACKGROUND_IMAGE`)
|
|
|
|
Add a custom background image:
|
|
|
|
- Use local images: `/images/my-background.jpg` (place in `public/images/`)
|
|
- Use external URLs: `https://example.com/background.jpg`
|
|
- Leave empty for solid color backgrounds
|
|
|
|
## Example Settings
|
|
|
|
### Tech Startup
|
|
|
|
```env
|
|
NEXT_PUBLIC_THEME_ROUNDNESS=full
|
|
NEXT_PUBLIC_THEME_LAYOUT=side-by-side
|
|
NEXT_PUBLIC_THEME_SPACING=regular
|
|
NEXT_PUBLIC_THEME_APPEARANCE=material
|
|
NEXT_PUBLIC_THEME_BACKGROUND_IMAGE=/images/tech-gradient.jpg
|
|
```
|
|
|
|
### Corporate Bank
|
|
|
|
```env
|
|
NEXT_PUBLIC_THEME_ROUNDNESS=edgy
|
|
NEXT_PUBLIC_THEME_LAYOUT=top-to-bottom
|
|
NEXT_PUBLIC_THEME_SPACING=regular
|
|
NEXT_PUBLIC_THEME_APPEARANCE=material
|
|
```
|
|
|
|
### Minimal SaaS
|
|
|
|
```env
|
|
NEXT_PUBLIC_THEME_ROUNDNESS=mid
|
|
NEXT_PUBLIC_THEME_LAYOUT=side-by-side
|
|
NEXT_PUBLIC_THEME_SPACING=compact
|
|
NEXT_PUBLIC_THEME_APPEARANCE=flat
|
|
```
|
|
|
|
### Creative Agency
|
|
|
|
```env
|
|
NEXT_PUBLIC_THEME_ROUNDNESS=full
|
|
NEXT_PUBLIC_THEME_LAYOUT=top-to-bottom
|
|
NEXT_PUBLIC_THEME_SPACING=regular
|
|
NEXT_PUBLIC_THEME_APPEARANCE=material
|
|
NEXT_PUBLIC_THEME_BACKGROUND_IMAGE=/images/creative-workspace.jpg
|
|
```
|
|
|
|
### Flat Design App
|
|
|
|
```env
|
|
NEXT_PUBLIC_THEME_ROUNDNESS=mid
|
|
NEXT_PUBLIC_THEME_LAYOUT=side-by-side
|
|
NEXT_PUBLIC_THEME_SPACING=compact
|
|
NEXT_PUBLIC_THEME_APPEARANCE=flat
|
|
```
|
|
|
|
### Material Design System
|
|
|
|
```env
|
|
NEXT_PUBLIC_THEME_ROUNDNESS=mid
|
|
NEXT_PUBLIC_THEME_LAYOUT=side-by-side
|
|
NEXT_PUBLIC_THEME_SPACING=regular
|
|
NEXT_PUBLIC_THEME_APPEARANCE=material
|
|
```
|
|
|
|
## Advanced Customization
|
|
|
|
For more detailed customization beyond these presets, you can:
|
|
|
|
1. **Custom CSS**: Add your own CSS files in the `src/styles/` directory
|
|
2. **Component Override**: Modify the theme settings in `src/lib/theme.ts`
|
|
3. **Custom Appearances**: Add new appearance options to the `APPEARANCE_STYLES` or `SPACING_STYLES` objects
|
|
|
|
## Troubleshooting
|
|
|
|
### Theme not applying
|
|
|
|
- Ensure you're using `NEXT_PUBLIC_` prefix for all theme variables (`NEXT_PUBLIC_THEME_ROUNDNESS`, `NEXT_PUBLIC_THEME_SPACING`, `NEXT_PUBLIC_THEME_APPEARANCE`, etc.)
|
|
- Restart your development server after changing environment variables
|
|
- Check that your `.env.local` file is in the root of the login app directory
|
|
|
|
### Background image not loading
|
|
|
|
- Verify the image path is correct
|
|
- For external URLs, ensure the domain is accessible
|
|
- Check browser console for any loading errors
|
|
|
|
### Layout issues on mobile
|
|
|
|
- Test your theme on different screen sizes
|
|
- The `top-to-bottom` layout is generally more mobile-friendly
|
|
- Some combinations work better on certain screen sizes
|
|
|
|
## Support
|
|
|
|
For additional customization needs or questions, please refer to the ZITADEL documentation or community forums.
|