Anpassung Erste Schritte

Passe die Benutzeroberfläche von Insight mithilfe von Design-Tokens, Komponenten-Themes und Vorlagen-Überschreibungen an deine Marke an.

Insight UI nutzt ein tokenbasiertes Designsystem, welches auf Tailwind CSS aufbaut. Farben, Abstände oder die Typografie können an einer Stelle angepasst werden, und die gesamte Benutzeroberfläche passt sich entsprechend an. Es gibt vier Ebenen der Anpassung:

Konfiguration

Favicons, Meta-Tags, Feature-Flags über settings.py

Design-Tokens

Farben, Abstände, Radien, Schatten über input.css

Templates

Überschreiben des HTML-Codes einer Komponente für strukturelle Änderungen

Icons

Benutzerdefinierte Symbole hinzufügen oder vorhandene ersetzen

1. Konfiguration über settings.py

Das INSIGHT_UI-Dictionary in den Django-Einstellungen steuert Optionen auf App-Ebene wie Branding-Elemente, SEO-Metadaten und Feature-Flags.

INSIGHT_UI = { # Branding "webmanifest": "insight_ui/favicon/site.webmanifest", "favicon": "insight_ui/favicon/favicon.ico", "favicon_32": "insight_ui/favicon/favicon-32x32.png", "favicon_16": "insight_ui/favicon/favicon-16x16.png", "apple_touch_icon": "insight_ui/favicon/apple-touch-icon.png", "safari_mask_icon": "insight_ui/svg/logo.svg", "safari_mask_icon_color": "#5bbad5", "msapplication_TileColor": "#da532c", "theme_color": "#ffffff", # Layout "title": "My App", "navbar_fixed": True, # SEO "meta": { "seo": { "description": "My application description", "keywords": "Django, Insight UI", "author": "Your Name", } }, # Feature flags "load_prism": False, # Syntax highlighting "load_leaflet": False, # Geo maps "load_echarts": False, # Charts "JS_DEBUG": False, # Console logging "use_tailwind_cli": False # Live CSS compilation }

Laden der Konfiguration in Views

Um die Konfiguration in den Templates verfügbar zu machen, importiere get_config aus insight_ui.config und füge es diese View-Kontext hinzu.

from insight_ui.config import get_config def my_view(request): context = { **get_config(), # Adds INSIGHT_UI to context # ... your other context variables } return render(request, "my_template.html", context)

Die Funktion get_config() führt deine settings.INSIGHT_UI mit den Standardwerten der Bibliothek zusammen und gibt ein Dictionary mit dem Schlüssel INSIGHT_UI zurück. Die Templates können dann über {{ INSIGHT_UI.title }} usw. auf die Konfiguration zugreifen.

2. Design-Tokens (input.css)

Die Datei input.css ist die einzige verlässliche Quelle für das visuelles Design. Alle Tokens werden im Block @theme definiert und gelten automatisch für alle Komponenten.

Einrichtung: Tailwind-CLI

Um das Theme anzupassen, wird der Tailwind-Compiler benötigt. Wir empfehlen django-tailwind-cli.

Schnellstart

Paket installieren: uv add django-tailwind-cli
Zu INSTALLED_APPS hinzufügen: "django_tailwind_cli"
Die „input.css“ Datein in das Projekt kopieren (siehe unten)
Setup ausführen: python manage.py tailwind setup
Entwicklungsserver starten: python manage.py tailwind runserver

INSTALLED_APPS = [ # ... "django_tailwind_cli", ] # Point to your custom input.css TAILWIND_CLI_SRC_CSS = BASE_DIR / "my_app/static/css/input.css" TAILWIND_CLI_DIST_CSS = "css/tailwind.css" TAILWIND_CLI_AUTOMATIC_DOWNLOAD = False

input.css kopieren

Kopiere die Standarddatei input.css aus dem installierten Insight-UI-Paket in das Verzeichnis „static“ deines Projekts.

# Find the source file in your virtual environment # Linux/macOS: cp .venv/lib/python3.*/site-packages/insight_ui/utils/input.css \ my_app/static/css/input.css # Windows (PowerShell): copy .venv\Lib\site-packages\insight_ui\utils\input.css ` my_app\static\css\input.css

Passe anschließend die Anweisung @source am Anfang der kopierten Datei so an, dass sowohl deine Templates als auch die Insight-UI-Templates einbezogen werden:

/* Your project templates */ @source "../../templates"; /* Insight UI templates (adjust path to your venv) */ /* Linux/macOS: */ @source "../../../.venv/lib/python3.12/site-packages/insight_ui/templates/insight_ui"; /* Windows: */ @source "../../../.venv/Lib/site-packages/insight_ui/templates/insight_ui";

INFO:

Die Anweisung @source teilt Tailwind mit, welche Dateien nach Hilfsklassen durchsucht werden sollen. Ohne diese Anweisung werden nicht verwendete Klassen aus dem endgültigen CSS entfernt.

Farbsystem

Das Farbsystem umfasst Markenfarben, Statusfarben, Oberflächenfarben und Textfarben. Jede Farbe verfügt über Zustände für Hover- und aktive Interaktionen.

Markenfarben

Primary --color-insight-primary

Secondary --color-insight-secondary

Statusfarben

Success --color-insight-success

Warning --color-insight-warning

Danger --color-insight-danger

Info --color-insight-info

Oberflächen- und Umrandungsfarben

Flächen schaffen eine visuelle Hierarchie. Jede Ebene hat eine passende Umrandungsfarbe.

base

bg-insight-base

surface

bg-insight-surface border-insight-surface

raised

bg-insight-raised border-insight-raised

overlay

bg-insight-overlay border-insight-overlay

INFO:

Diese Hilfsklassen können direkt verwendet werden oder du nutzt unsere kombinierten Oberflächenklassen, um Container schnell zu gestalten.

Textfarben

Headline text text-insight-headline

Body text text-insight-body

Caption text text-insight-muted

Disabled text text-insight-disabled

Link text text-link

@theme { /* Brand colors */ --color-insight-primary: #4183EA; --color-insight-primary-soft: #E3EFFF; --color-insight-primary-hover: #256CD8; --color-insight-primary-active: #0856C0; --color-insight-secondary: #1B9388; --color-insight-secondary-soft: #DDF4F1; --color-insight-secondary-hover: #008074; --color-insight-secondary-active: #006B60; /* Status colors (each has base, soft, hover, active) */ --color-insight-success: #2EA55C; --color-insight-warning: #E8A127; --color-insight-danger: #E6443D; --color-insight-info: #00A3CB; /* Surfaces */ --color-insight-bg-base: #FFFFFF; --color-insight-bg-surface: #FFFFFF; --color-insight-bg-raised: #EEF0F3; --color-insight-bg-overlay: #E9EAEB; /* Borders */ --color-insight-border-surface: #E5E7EB; --color-insight-border-raised: #E5E7EB; --color-insight-border-overlay: #E5E7EB; /* Text */ --color-insight-text-headline: #1C1C1E; --color-insight-text-body: #364153; --color-insight-text-muted: #6B7280; --color-insight-text-link: #256CD8; }

Typografie

Insight UI verwendet eine benutzerdefinierte Schriftart, welche über @font-face geladen wird. Um eine eigene Schriftart zu verwenden, muss die Schriftartdatei ersetzt und die Verweise in input.css aktualisiert werden.

Schritt 1: Die Schriftart laden

Füge eine @font-face-Deklaration mit dem Pfad zu deiner Schriftartdatei hinzu (relativ zu input.css).

@font-face { font-family: "my-brand-font"; src: url("../font/MyBrandFont.woff2") format("woff2"), url("../font/MyBrandFont.ttf") format("truetype"); font-weight: 100 900; /* Variable font weight range */ font-display: swap; }

Schritt 2: Als Standard festlegen

Aktualisiere die Variable „--font-sans“ im @theme-Block, um deine Schriftart zu verwenden.

@theme { --font-sans: "my-brand-font", system-ui, sans-serif; }

INFO:

Die Standardschriftart Atkinson Hyperlegible Next ist auf Lesbarkeit und Barrierefreiheit optimiert. Achte bei der Auswahl einer Ersatzschriftart auf die Lesbarkeit in verschiedenen Schriftgrößen und -stärken.

Verwendung mehrerer Schriftarten

Es können mehrere Schriftfamilien für unterschiedliche Zwecke definiert werden. Tailwind bietet integrierte Variablen für serifenlose, serifenbehaftete und monospaced Schriftarten. Außerdem können benutzerdefinierte Schriftfamilien für bestimmte Anwendungsfälle wie Überschriften festlegen werden.

/* Load multiple fonts */ @font-face { font-family: "brand-sans"; src: url("../font/BrandSans.woff2") format("woff2"); font-weight: 100 900; font-display: swap; } @font-face { font-family: "brand-heading"; src: url("../font/BrandHeading.woff2") format("woff2"); font-weight: 400 700; font-display: swap; } @font-face { font-family: "brand-mono"; src: url("../font/BrandMono.woff2") format("woff2"); font-weight: 400; font-display: swap; } @theme { /* Body text */ --font-sans: "brand-sans", system-ui, sans-serif; /* Code blocks */ --font-mono: "brand-mono", ui-monospace, monospace; /* Custom: Headings (use with font-heading class) */ --font-heading: "brand-heading", serif; }

Verwende die Schriftarten in den Templates mit Tailwind-Klassen:

<p class="font-sans">Regular body text</p>  <code class="font-mono">const x = 42;</code>  <h1 class="font-heading">Page Title</h1>

Textgröße und Zeilenabstand

INFO:

Tokens für Textgröße und Zeilenabstand sind geplant, aber noch nicht verfügbar. Verwende bis dahin die Standard-Text-Utilities von Tailwind (text-sm, text-base, text-lg usw.).

Abstandsskala

Ein einheitliches Abstandsschema für Ränder, Innenabstände und Lücken.

xs

0.25rem (4px)

s

0.5rem (8px)

m

1rem (16px)

l

2rem (32px)

xl

4rem (64px)

@theme { --spacing-insight-xs: 0.25rem; --spacing-insight-s: 0.5rem; --spacing-insight-m: 1rem; --spacing-insight-l: 2rem; --spacing-insight-xl: 4rem; }

Randradius

Radiuswerte für Ecken, von dezent bis vollständig abgerundet.

xs

s

m

l

xl

full

Semantische Radius-Token lassen sich bestimmten Anwendungsfällen zuordnen:

rounded-insight-control für Schaltflächen, Eingabefelder
rounded-insight-surface für Karten, Panel
rounded-insight-raised für erhöhte Elemente
rounded-insight-overlay für Modalfenster, Dropdown-Menüs

Schatten

Schattierungen erzeugen Tiefe und eine visuelle Hierarchie.

subtle

surface

raised

overlay

Dunkelmodus

Jedes Farb-Token verfügt über eine dunkle Variante. Das Design wechselt automatisch basierend auf dem Attribut data-theme=„dark“ am Stammelement.

@theme { /* Light mode (default) */ --color-insight-bg-base: #FFFFFF; --color-insight-text-headline: #1C1C1E; /* Dark mode variants (applied via @layer base) */ --color-insight-bg-base-dark: #030712; --color-insight-text-headline-dark: #F5F8FC; } @layer base { [data-theme="dark"] { --color-insight-bg-base: var(--color-insight-bg-base-dark); --color-insight-text-headline: var(--color-insight-text-headline-dark); } }

Dunkelmodus aktivieren

Set the data-theme attribute on the <html> element. You can use JavaScript to toggle it or respect the user's system preference.

// Toggle dark mode manually function toggleTheme() { const html = document.documentElement; const current = html.dataset.theme; html.dataset.theme = current === "dark" ? "light" : "dark"; localStorage.setItem("theme", html.dataset.theme); } // Respect system preference on load function initTheme() { const saved = localStorage.getItem("theme"); if (saved) { document.documentElement.dataset.theme = saved; } else if (window.matchMedia("(prefers-color-scheme: dark)").matches) { document.documentElement.dataset.theme = "dark"; } } // Listen for system preference changes window.matchMedia("(prefers-color-scheme: dark)") .addEventListener("change", (e) => { if (!localStorage.getItem("theme")) { document.documentElement.dataset.theme = e.matches ? "dark" : "light"; } });

Insight UI includes a theme_toggle component that handles this automatically. See the component documentation for usage.

Komponentenklassen

Der Block @layer components definiert wiederverwendbare CSS-Klassen für Schaltflächen, Badges, Eingabefelder und mehr. Diese Klassen nutzen die Design-Tokens.

Button-Varianten

Badge-Varianten

Primary Success Warning Danger Info

@layer components { .btn { @apply flex gap-2 items-center justify-center border-2 border-transparent rounded-insight-control px-5 py-1.5 text-white transition-colors; } .btn-primary { @apply bg-insight-primary border-insight-primary hover:bg-insight-primary-hover active:bg-insight-primary-active; } .badge { @apply inline-flex items-center gap-2 px-4 py-1.5 rounded-insight-full shadow-insight-subtle; } .badge-primary { @apply bg-insight-primary/10 text-insight-primary; } }

Oberflächenklassen

Kombinierte Klassen, welche für jede Höhenstufe Hintergrund, Rahmen, Schatten und Rahmenradius anwenden. Verwende diese für eine schnelle und einheitliche Gestaltung von Containern.

.insight-surface

.insight-raised

.insight-overlay

@layer utilities { /* Background utilities */ .bg-insight-base { background-color: var(--color-insight-bg-base); } .bg-insight-surface { background-color: var(--color-insight-bg-surface); } .bg-insight-raised { background-color: var(--color-insight-bg-raised); } .bg-insight-overlay { background-color: var(--color-insight-bg-overlay); } /* Border color utilities */ .border-insight-surface { border-color: var(--color-insight-border-surface); } .border-insight-raised { border-color: var(--color-insight-border-raised); } .border-insight-overlay { border-color: var(--color-insight-border-overlay); } } @layer components { /* Combined surface classes */ .insight-surface { background-color: var(--color-insight-bg-surface); border: 1px solid var(--color-insight-border-surface); box-shadow: var(--shadow-insight-surface); border-radius: var(--radius-insight-surface); } .insight-raised { /* ... */ } .insight-overlay { /* ... */ } }

Du kannst einzelne Eigenschaften mithilfe von Utility-Klassen überschreiben:

<div class="insight-surface p-4">...</div>  <div class="insight-surface p-4 shadow-insight-overlay">...</div>  <div class="p-4 bg-insight-surface border border-insight-surface rounded-lg">...</div>

3. Vorlagen überschreiben

Für strukturelle Änderungen, welche über das Styling hinausgehen, überschreibe die Komponentenvorlagen in deinem Projekt. Der Template-Loader von Django räumt deine Templates Vorrang vor den Standardvorlagen des Pakets ein.

WARNING:

Verwende vorzugsweise Tokens statt Template-Überschreibungen. Die meisten Anforderungen an das Branding lassen sich durch Anpassungen in der Datei „input.css“ erfüllen. Überschreibe die Templates nur, wenn sich die HTML-Struktur ändern soll, ARIA-Attribute hinzufügen werden oder das Verhalten von Komponenten anpassen werden muss.

myapp/ └── templates/ └── insight_ui/ └── components/ └── navbar.html

Der Pfad zum Template muss genau übereinstimmen: templates/insight_ui/components/<component>.html

4. Benutzerdefinierte Icons

Insight UI enthält über 280 Icons von Heroicons. Mit dem Verwaltungsbefehl compile_icons können eigene Symbole hinzufügt oder vorhandene ersetzt werden.

# Add icons from a directory python manage.py compile_icons --dir path/to/my-icons/ # Add icons from an SVG sprite sheet python manage.py compile_icons --sprite path/to/sprite.svg # Combine both sources python manage.py compile_icons --dir path/to/icons/ --sprite path/to/sprite.svg

Benutzerdefinierte Icons überschreiben mitgelieferte Icons mit demselben Namen. Die Namen der Icons werden aus den Dateinamen abgeleitet und normalisiert (Kleinbuchstaben, Bindestriche statt Unterstriche).

Sie dir alle verfügbaren Icons und die ausführliche Dokumentation an →

Kurzübersicht

Alle verfügbaren Design-Tokens auf einen Blick.

Kategorie	Tokens	Muster für CSS-Variablen
Colors	primary, secondary, success, warning, danger, info	`--color-insight-{name}`
Surfaces	base, surface, raised, overlay	`--color-insight-bg-{level}`
Borders	surface, raised, overlay	`--color-insight-border-{level}`
Text	text-insight-headline, text-insight-body, text-insight-muted, text-insight-link	`--color-insight-text-{role}`
Spacing	xs, s, m, l, xl	`--spacing-insight-{size}`
Radii	xs, s, m, l, xl, full, control, surface, raised, overlay	`--radius-insight-{size}`
Shadows	subtle, surface, raised, overlay, focus	`--shadow-insight-{level}`

Hilfsklassen

Vereinfachte Utility-Klassen für gängige Styling-Aufgaben.

Kategorie	Klassen	Beschreibung
Background	`bg-insight-{base\|surface\|raised\|overlay}`	Hintergrundfarben der Oberflächen
Border	`border-insight-{surface\|raised\|overlay}`	Farben der Oberflächenränder
Text	`text-insight-headline`, `text-insight-body`	Kurzschreibweise für Textfarben
Combined	`insight-{surface\|raised\|overlay}`	Alles in einem: Hintergrund + Rahmen + Schatten + Radius