nextsaas.ai Logo
KitCore
Kit-Dokumentation

Anpassung

Tailwind-CSS-Konfiguration, semantisches Farbsystem, eigene Animationen und globale CSS-Architektur

tailwindcsscustomization
Das Kit verwendet Tailwind CSS 3.4 mit einem semantischen Farbsystem, das auf CSS Custom Properties aufbaut. Statt hartkodierter Farbwerte wie bg-blue-500 verwendet die gesamte Anwendung theme-bewusste Klassen wie bg-primary, die sich automatisch an das aktive Farbthema und den Dark Mode anpassen. Diese Seite behandelt die Tailwind-Konfiguration, wie man sie erweitert, und die globale CSS-Architektur.
Für das Wechseln zwischen Themes, siehe Farbthemen & Dark Mode. Für Komponenten-Styling-Muster, siehe UI-Komponenten.

Tailwind-Konfiguration

Die Tailwind-Konfiguration ordnet jede semantische Farbe ihrer CSS Custom Property zu und definiert eigene Schriftarten, Animationen und Layout-Utilities:
tailwind.config.js — Vollständige Konfiguration
/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: ['class'],
  content: [
    './src/pages/**/*.{js,ts,jsx,tsx,mdx}',
    './src/components/**/*.{js,ts,jsx,tsx,mdx}',
    './src/app/**/*.{js,ts,jsx,tsx,mdx}',
    '../../packages/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    container: {
      center: true,
      padding: '2rem',
      screens: {
        '2xl': '1400px',
      },
    },
    extend: {
      fontFamily: {
        sans: ['var(--font-inter)', 'system-ui', 'sans-serif'],
        mono: ['var(--font-jetbrains-mono)', 'ui-monospace', 'monospace'],
      },
      borderRadius: {
        lg: 'var(--radius)',
        md: 'calc(var(--radius) - 2px)',
        sm: 'calc(var(--radius) - 4px)',
      },
      colors: {
        background: 'hsl(var(--background))',
        foreground: 'hsl(var(--foreground))',
        card: {
          DEFAULT: 'hsl(var(--card))',
          foreground: 'hsl(var(--card-foreground))',
        },
        popover: {
          DEFAULT: 'hsl(var(--popover))',
          foreground: 'hsl(var(--popover-foreground))',
        },
        primary: {
          DEFAULT: 'hsl(var(--primary))',
          foreground: 'hsl(var(--primary-foreground))',
        },
        secondary: {
          DEFAULT: 'hsl(var(--secondary))',
          foreground: 'hsl(var(--secondary-foreground))',
        },
        muted: {
          DEFAULT: 'hsl(var(--muted))',
          foreground: 'hsl(var(--muted-foreground))',
        },
        accent: {
          DEFAULT: 'hsl(var(--accent))',
          foreground: 'hsl(var(--accent-foreground))',
        },
        destructive: {
          DEFAULT: 'hsl(var(--destructive))',
          foreground: 'hsl(var(--destructive-foreground))',
        },
        success: {
          DEFAULT: 'hsl(var(--success))',
          foreground: 'hsl(var(--success-foreground))',
        },
        warning: {
          DEFAULT: 'hsl(var(--warning))',
          foreground: 'hsl(var(--warning-foreground))',
        },
        info: {
          DEFAULT: 'hsl(var(--info))',
          foreground: 'hsl(var(--info-foreground))',
        },
        border: 'hsl(var(--border))',
        input: 'hsl(var(--input))',
        ring: 'hsl(var(--ring))',
      },
    },
  },
  plugins: [require('tailwindcss-animate'), require('@tailwindcss/typography')],
}
Wichtige Konfigurationspunkte:
  • darkMode: ['class'] — Dark Mode wird über die .dark-Klasse umgeschaltet (verwaltet von next-themes), nicht über Media Queries
  • content-Pfade — Durchsucht sowohl die src/-Verzeichnisse als auch packages/ui/, damit gemeinsame Komponenten Tailwind-Klassen erhalten
  • container — Zentriert mit 2rem Innenabstand und einem 1400px Maximum-Width beim 2xl-Breakpoint
  • colors — Jede Farbe referenziert eine CSS-Variable über hsl(var(--name)), was alle Farben theme-bewusst macht
  • plugins — tailwindcss-animate für Animations-Utilities und @tailwindcss/typography für Prosa-Styling

Semantisches Farbsystem

Das Farbsystem funktioniert über drei Ebenen:
Theme-CSS-Datei (default.css)            →  --primary: 221 83% 53%;
    |
Tailwind-Konfiguration (tailwind.config.js)  →  primary: 'hsl(var(--primary))'
    |
Deine Komponenten                        →  className="bg-primary text-primary-foreground"
Wenn du bg-primary verwendest, generiert Tailwind background-color: hsl(var(--primary)). Der tatsächliche Farbwert stammt aus der jeweils aktiven Theme-CSS-Datei.

Opacity-Modifikatoren

Da CSS-Variablen rohe HSL-Werte speichern (nicht in hsl() eingewickelt), funktioniert Tailwinds Opacity-Modifier-Syntax direkt:
tsx
// 50% Deckkraft der Primärfarbe
<div className="bg-primary/50" />
// Generiert: background-color: hsl(221 83% 53% / 0.5)

// 80% Deckkraft des Vordergund-Textes
<p className="text-foreground/80" />
// Generiert: color: hsl(0 0% 3.9% / 0.8)

Farb-Verwendungsreferenz

Tailwind-KlasseCSS-VariableWann verwenden
bg-background--backgroundSeitenhintergrund
text-foreground--foregroundPrimärer Fließtext
bg-card--cardKarten- und Oberflächen-Hintergründe
bg-primary--primaryPrimäre Buttons, Links, Markenelemente
text-primary-foreground--primary-foregroundText auf primärfarbigen Hintergründen
bg-secondary--secondarySekundäre Buttons, weniger prominente Elemente
bg-muted--mutedDezente Hintergrundbereiche, deaktivierte Zustände
text-muted-foreground--muted-foregroundHilfetext, Platzhalter, Zeitstempel
bg-accent--accentHover-Zustände, ausgewählte Elemente
bg-destructive--destructiveFehlerzustände, Lösch-Buttons
border-border--borderAlle Rahmen und Trennlinien
border-input--inputFormularfeld-Rahmen
ring-ring--ringFokus-Ring-Umrisse

Konfiguration erweitern

Eigene Schriftarten

Die Konfiguration definiert zwei Schriftfamilien über CSS-Variablen, die von next/font gesetzt werden:
typescript
fontFamily: {
  sans: ['var(--font-inter)', 'system-ui', 'sans-serif'],
  mono: ['var(--font-jetbrains-mono)', 'ui-monospace', 'monospace'],
}
Um Schriftarten zu ändern, aktualisiere die next/font-Imports in apps/boilerplate/src/app/layout.tsx — die Variablennamen werden automatisch weitergereicht. Die font-sans-Klasse verwendet Inter und font-mono verwendet JetBrains Mono.

Rahmenradius

Rahmenradius-Werte werden aus der --radius-CSS-Custom-Property abgeleitet (Standard: 0.5rem):
typescript
borderRadius: {
  lg: 'var(--radius)',          // 0.5rem
  md: 'calc(var(--radius) - 2px)', // ~0.375rem
  sm: 'calc(var(--radius) - 4px)', // ~0.25rem
}
Das Ändern von --radius in einer Theme-CSS-Datei passt alle abgerundeten Ecken in der gesamten Anwendung an.

Eigene Animationen

Um eigene Animationen hinzuzufügen, definiere einen keyframes-Eintrag und einen passenden animation-Eintrag im extend-Bereich von tailwind.config.js:
javascript
keyframes: {
  'slide-in': {
    '0%': { transform: 'translateX(-100%)', opacity: '0' },
    '100%': { transform: 'translateX(0)', opacity: '1' },
  },
},
animation: {
  'slide-in': 'slide-in 0.3s ease-out',
},

Globale CSS-Architektur

Das globale Stylesheet legt das Basis-Styling für die gesamte Anwendung fest. Es ist in Ebenen gegliedert:
src/app/globals.css — Theme-Imports, Tailwind-Direktiven & Base-Layer
/* Import all available color themes - MUST be first! */
@import '../styles/themes/default.css';
@import '../styles/themes/ocean.css';
@import '../styles/themes/forest.css';
@import '../styles/themes/sunset.css';
@import '../styles/themes/midnight.css';
@import '../styles/themes/coral.css';
@import '../styles/themes/slate.css';
@import '../styles/themes/aurora.css';
@import '../styles/themes/crimson.css';

/* Syntax highlighting (extracted for maintainability) */
@import '../styles/syntax-highlighting.css';

/* Universal status colors — theme-independent */
:root {
  --success: 142 76% 36%;
  --success-foreground: 0 0% 100%;
  --warning: 32 95% 44%;
  --warning-foreground: 0 0% 100%;
  --info: 199 89% 48%;
  --info-foreground: 0 0% 100%;

  /* Opaque content surface: muted/80 composited over background.
     Used on <main> and sticky overlays to avoid opacity stacking. */
  --main-surface: hsl(var(--muted));
  --main-surface: color-mix(in srgb, hsl(var(--muted)) 80%, hsl(var(--background)));
}

.dark {
  --success: 142 76% 50%;
  --success-foreground: 0 0% 100%;
  --warning: 32 95% 54%;
  --warning-foreground: 0 0% 100%;
  --info: 199 89% 58%;
  --info-foreground: 0 0% 100%;

  --main-surface: hsl(var(--background));
  --main-surface: color-mix(in srgb, hsl(var(--muted)) 20%, hsl(var(--background)));
}

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  * {
    @apply border-border;
  }
  body {
    @apply bg-background text-foreground;
  }

  /* Prevent body scrollbar in dashboard layout — only <main> should scroll */
  html:has([data-dashboard-layout]) {
    overflow: hidden;
  }

  /* Typography System
     Heading styles (h1-h4) are set via explicit className on each element.
     Prose typography (legal pages) is handled by @tailwindcss/typography plugin. */
  .prose h2 {
    @apply border-b pb-2;
  }
  p {
    @apply leading-7;
  }

  /* Dashboard heading spacing — vertical rhythm within sections
     H3-H6 get top margin when preceded by other content (not when first child).
     H1/H2 spacing is handled by .db-page-sections and component containers. */
  [data-dashboard-layout] h3:not(:first-child) {
    @apply mt-6 sm:mt-8;
  }
  [data-dashboard-layout] h4:not(:first-child) {
    @apply mt-5 sm:mt-6;
  }
  [data-dashboard-layout] h5:not(:first-child),
  [data-dashboard-layout] h6:not(:first-child) {
    @apply mt-4;
  }

  code {
    @apply relative rounded bg-muted px-[0.3rem] py-[0.2rem] font-mono text-sm font-semibold;
  }
}
Die Datei ist in 4 klar abgegrenzte Abschnitte unterteilt:
  1. Theme-Imports — Alle 9 Theme-CSS-Dateien sowie Syntax-Highlighting müssen zuerst importiert werden, bevor Tailwind-Direktiven folgen. Das stellt sicher, dass CSS Custom Properties verfügbar sind, wenn Tailwind Utility-Klassen generiert.
  2. Tailwind-Direktiven — @tailwind base, @tailwind components, @tailwind utilities fügen Tailwinds generierte Stile an der richtigen Ebene ein. Universelle Statusfarben (success, warning, info) werden zwischen den Importen und den Direktiven definiert.
  3. Base-Layer — @layer base setzt globale Standardwerte: Rahmenfarbe für alle Elemente, Hintergrund-/Textfarbe am Body, Absatz-Zeilenhöhe, Inline-code-Styling und Dashboard-spezifische Überschriften-Abstände. Überschriften-Stile (h1–h4) werden über explizite className-Attribute an jedem Element angewendet; Prosa-Typografie (rechtliche Seiten) wird vom @tailwindcss/typography-Plugin übernommen.
  4. Components-Layer (weiter unten in der Datei) — @layer components definiert wiederverwendbare Muster wie Code-Block-Styling für Prosa-Inhalte mit Dark-Mode-Anpassungen.

Eigene Utilities hinzufügen

CSS-Utilities

Füge eigene Utility-Klassen mit Tailwinds @layer utilities-Direktive in globals.css hinzu:
css
@layer utilities {
  .text-balance {
    text-wrap: balance;
  }

  .scrollbar-hide {
    -ms-overflow-style: none;
    scrollbar-width: none;
  }
  .scrollbar-hide::-webkit-scrollbar {
    display: none;
  }
}

Tailwind-Konfiguration erweitern

Für Utilities, die responsive Varianten oder andere Tailwind-Modifikatoren benötigen, füge sie zur Konfiguration hinzu:
javascript
// tailwind.config.js — extend-Bereich
extend: {
  spacing: {
    '18': '4.5rem',
    '88': '22rem',
  },
  maxWidth: {
    'prose-wide': '85ch',
  },
  zIndex: {
    '60': '60',
    '70': '70',
  },
}
Konfigurationsbasierte Erweiterungen erhalten automatisch responsive (md:max-w-prose-wide), Hover- (hover:z-60) und andere Modifikator-Unterstützung.

Wichtige Dateien

DateiZweck
apps/boilerplate/tailwind.config.jsTailwind-Konfiguration — Farben, Schriftarten, Animationen, Plugins
apps/boilerplate/src/app/globals.cssGlobale Stile — Theme-Imports, Base-Layer, Typografie, eigene Utilities
apps/boilerplate/src/styles/themes/*.css9 Theme-CSS-Dateien mit CSS Custom Properties (hell + dunkel)
apps/boilerplate/postcss.config.jsPostCSS-Konfiguration für Tailwind und Autoprefixer
packages/utils/src/index.tscn()-Utility — kombiniert Tailwind-Klassen mit Konfliktauflösung

Related

Konfiguration
Umgebungsvariablen, Feature Flags, Themes und Branding in nextsaas.ai Kit konfigurieren
Previous
UI-Komponenten
Next
Sicherheitsübersicht