Theme Customization Guide¶

Welcome to the django-admin-deux theme customization guide! This guide will help you create custom themes for your django-admin-deux installation.

Table of Contents¶

Architecture Overview - Understanding the semantic HTML + structural CSS approach
Dark Mode Implementation - How to implement dark mode in your theme
Creating a Custom Theme - Step-by-step guide to creating your own theme
CSS Reference - Complete CSS selector reference
Examples - Example custom themes

Quick Start¶

The default theme uses a semantic HTML + structural CSS architecture that makes theming extremely simple:

No utility classes in templates - Templates use pure HTML5 semantic elements
One template override - Theme plugin only needs to override _navigation.html (if adding dark mode)
CSS-only theming - Most themes can be created by just providing a CSS file

Creating a Simple Theme (No Dark Mode)¶

Create a Django app for your theme:
```
python manage.py startapp mytheme
```

Create mytheme/djadmin_hooks.py:

from djadmin.plugins import hookimpl
from djadmin.actions.base import BaseAction

@hookimpl
def djadmin_provides_features():
    """Advertise that this plugin provides a theme"""
    return ['theme']

@hookimpl
def djadmin_get_action_view_assets(action):
    """Provide your custom CSS"""
    return {
        BaseAction: {
            'css': ['mytheme/custom.css'],
        }
    }

Create mytheme/static/mytheme/custom.css:

/* Override the default colors and styles */
.admin > header {
  background-color: #1e40af;  /* Blue instead of green */
  border-bottom-color: #1e3a8a;
}

.admin > header > nav > a {
  color: white;
}

/* Customize tables */
.admin table thead {
  background-color: #dbeafe;
}

/* ... more customizations */

Add to INSTALLED_APPS before djadmin.plugins.theme:

INSTALLED_APPS = [
    'mytheme',  # Your theme loads first
    'djadmin.plugins.theme',  # Default theme loads after
    'djadmin',
    # ...
]

That's it! Your theme is now active.

Key Concepts¶

Semantic HTML¶

Templates use pure semantic HTML5 elements with minimal classes:

<div class="admin">
    <header>
        <nav>
            <a href="...">Django Admin</a>
            <menu>
                <li><a href="...">Dashboard</a></li>
            </menu>
        </nav>
    </header>
    <main>
        <table>...</table>
    </main>
</div>

Structural CSS Selectors¶

CSS targets the HTML structure instead of utility classes:

/* Target semantic structure */
.admin > header {
  /* Header styles */
}

.admin header nav {
  /* Navigation styles */
}

.admin main table {
  /* Table styles */
}

Minimal Class Usage¶

Only a few classes are used: - .admin - Root wrapper (scoping all styles) - .primary, .danger - Button/link variants - .success, .error, .warning, .info - Message types - .dark - Dark mode (applied to <html> element)

Architecture Benefits¶

✅ Zero template changes needed - Themes are pure CSS ✅ Swap CSS file = complete restyle - No template modifications ✅ No class naming conflicts - Semantic selectors only ✅ Future-proof - HTML structure rarely changes ✅ Accessible - Semantic HTML is inherently accessible

Next Steps¶

Read the Architecture Overview to understand the design philosophy
Learn about Dark Mode Implementation if you want to support dark mode
Follow the Custom Theme Guide to create your first theme
Browse the Examples for inspiration

Getting Help¶

Check the CSS Reference for a complete list of selectors
Look at the default theme source: djadmin/plugins/theme/static_src/input.css
Join our community discussions (link TBD)
Report issues on GitHub (link TBD)