mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 21:52:54 +00:00
Max PeintnerandGitHub
434aeb275a
# Which Problems Are Solved This PR introduces a comprehensive theme customization system for the login application with responsive behavior and enhanced visual options. <img width="1122" height="578" alt="Screenshot 2025-08-19 at 09 55 24" src="https://github.com/user-attachments/assets/cdcc8948-533d-4e13-bf45-fdcc24acfb2b" /> # How the Problems Are Solved ## ✨ Features Added - **🔄 Responsive Layout System**: Automatic switching between side-by-side and top-to-bottom layouts based on screen size - **🖼️ Background Image Support**: Custom background images configurable via environment variables - **⚙️ Theme Configuration**: Complete theme system with roundness, spacing, appearance, and layout options - **📱 Mobile-First Design**: Intelligent layout adaptation for different screen sizes - **🎯 Enhanced Typography**: Improved visual hierarchy with larger titles in side-by-side mode ## 🏗️ Architecture - **Server-Safe Theme Functions**: Theme configuration accessible on both server and client - **SSR-Safe Hooks**: Proper hydration handling for responsive layouts - **Component Separation**: Clear boundaries between server and client components - **Two-Section Layout**: Consistent content structure across all login pages ## 🔧 Configuration Options All theme options are configurable via environment variables: - `NEXT_PUBLIC_THEME_ROUNDNESS`: `edgy` | `mid` | `full` - `NEXT_PUBLIC_THEME_LAYOUT`: `side-by-side` | `top-to-bottom` - `NEXT_PUBLIC_THEME_APPEARANCE`: `flat` | `material` - `NEXT_PUBLIC_THEME_SPACING`: `regular` | `compact` - `NEXT_PUBLIC_THEME_BACKGROUND_IMAGE`: Custom background image URL ## 📄 Pages Updated Updated all major login pages to use the new two-section responsive layout: - Login name entry - Password verification - MFA verification - User registration - Account selection - Device authorization - Logout confirmation ## 📚 Documentation - **THEME_ARCHITECTURE.md**: Complete technical documentation of the theme system - **THEME_CUSTOMIZATION.md**: User-friendly guide with examples and troubleshooting ## 🚀 Benefits - **Better UX**: Responsive design that works seamlessly across all devices - **Brand Flexibility**: Easy customization to match any brand identity - **Maintainable Code**: Clean separation of concerns and well-documented architecture - **Future-Proof**: Extensible system for additional theme options <img width="580" height="680" alt="Screenshot 2025-08-19 at 09 22 23" src="https://github.com/user-attachments/assets/9de8da37-6d56-4fe9-b337-5d8ad2a3ba59" /> <img width="599" height="689" alt="Screenshot 2025-08-19 at 09 23 45" src="https://github.com/user-attachments/assets/26a30cc7-4017-4f4b-8b87-a49466c42b94" /> <img width="595" height="681" alt="Screenshot 2025-08-19 at 09 23 17" src="https://github.com/user-attachments/assets/a3d31088-4545-4f36-aafe-1aae1253d677" />
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 Configurations
|
|
|
|
### 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 configuration 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.
|