Produktthema

Einrichtung und Konfiguration

Lesen Sie vor jedem Schritt Bevor Sie beginnen und Terminal-Grundlagen. Bei diesen Anweisungen wird davon ausgegangen, dass Sie das vollständige Supastack-Monorepo in VS Code geöffnet haben. Sein Stamm package.json markiert den Repository-Stamm. In pnpm-Befehlen ist ein Arbeitsbereichspaket eine App oder ein Ordner mit gemeinsam genutztem Code. Im Produkt ist ein Arbeitsbereich der Datencontainer und die Sicherheitsgrenze eines Teams. corepack pnpm --filter ... wählt ein Paket aus dem Monorepo aus, während Befehle von seinem Stammverzeichnis aus ausgeführt werden. Wenn Sie nur einen synchronisierten Mobil- oder Desktop-Ordner geöffnet haben, enthält dieser weder das Web-Backend, Docker-Setup noch Root-Skripte: Führen Sie das Backend von diesem Monorepo oder einem erreichbaren gehosteten Server aus und verwenden Sie die eigenen Skripte des Plattformordners. Eine Umgebungsvariable ist eine benannte Einstellung, die in einer lokalen .env-Datei oder Ihrem Hosting-Dashboard gespeichert ist; Starten Sie die entsprechende App neu, nachdem Sie sie geändert haben, und halten Sie Servergeheimnisse von den Werten NEXT_PUBLIC_ und EXPO_PUBLIC_ fern.

1. Öffnen Sie in VS Code apps/web/app/app-theme.css für angemeldete Produktbildschirme und apps/web/src/theme/catalog.ts, um ein Farbpaket hinzuzufügen. Bearbeiten Sie apps/web/app/theme.css nicht für Produktfarben. Es kontrolliert die Marketingmarke.

2. Führen Sie im Repository-Root den Befehl corepack pnpm --filter @supastack/web dev aus und besuchen Sie dann http://localhost:3000/settings/appearance.

3. Ändern Sie ein Token in Ihrer lokalen Filiale und aktualisieren Sie die Vorschau. Erwartet: Das Dashboard steuert die Aktualisierung, während die Homepage ihr ausgewähltes Marketingthema beibehält.

Marketing-Branding und Produktthema liegen in getrennten Dateien. Bearbeite apps/web/app/app-theme.css für Dashboard-, Auth-, Einstellungs-, Abrechnungs-, Chat- und Organisations-Chrome. Ergänze Farbpaletten in apps/web/src/theme/catalog.ts. Erweitere Dichte-, Radius-, Schrift- und Layout-Achsen in apps/web/src/theme/presets.ts sowie durch passende html[data-*]-Regeln in app-theme.css. Wähle die Marketing-Identität in apps/web/src/theme/marketing-theme.ts über MARKETING_THEME_MODE (locked | inherit | eine Paletten-ID), statt apps/web/app/theme.css zu bearbeiten: Die Sperre über .marketing-theme:not(.app-theme):not([data-theme]):not([data-marketing-theme="inherit"]) lässt die Obsidian-Marke von supastack auf der Startseite standardmäßig bestehen.

Zur Laufzeit speichert Einstellungen → Darstellung → ThemePicker Farbe, Dichte, Radius, Schriftart und Layout in Browser-Cookie + localStorage, sodass theme-boot.ts alle Achsen vor dem ersten Paint wiederherstellt, und synchronisiert das vollständige Darstellungsbündel des angemeldeten Benutzers über Browser hinweg über user_appearance (GET/PUT /api/account/appearance). Dieselbe Seite bindet die Kit-UI-Galerie ein, sodass Pakete und Presets Buttons, Eingabefelder, Karten, Badges und Dialoge live aktualisieren. Designdetails und Copy-Paste-Beispiele finden Sie in docs/design/kit-product-theme.md und docs/design/kit-ui-gallery.md.

/* Edit product chrome here — not theme.css */
.app-theme {
  --radius-card: 14px;
  background: var(--page);
  color: var(--text);
}
.app-theme .button-primary {
  background: var(--accent);
  color: var(--accent-ink);
}

/* catalog.ts — append a ThemeDefinition with every THEME_TOKEN_NAMES entry */
{
  id: "coral",
  name: "Coral",
  colorScheme: "light",
  tokens: { "--page": "#fff7f4", "--accent": "#e06b4f" /* …full token set… */ }
}

Befehle zum Kopieren

Befolgen Sie die Kommentare, um zu sehen, in welchem Ordner ein Befehl ausgeführt wird. Wenn zwei Terminals gekennzeichnet sind, öffnen Sie zwei Terminalfenster und lassen Sie den ersten Befehl laufen, während Sie den zweiten verwenden.

corepack pnpm --filter @supastack/web dev

# In a second terminal, after changing a theme token:
corepack pnpm test -- apps/web/src/theme/contrast.test.ts

Implementierungsablauf

Verwende in App-Komponenten bevorzugt var(--page|--section|--raised|--text|--muted|--border|--accent|…) (in app-theme.css, den Alias-Variablen in globals.css und den Routen von WorkspaceShell). Führe keine türkisfarbenen oder blasshexadezimalen Oberflächen wieder ein und hinterlege keine Obsidian-Hexwerte direkt in der Produktoberfläche.

Halte beim Hinzufügen einer Palette contrast.test.ts fehlerfrei. Wenn du eine Voreinstellungs-ID ergänzt, aktualisiere sowohl presets.ts als auch die html[data-density|data-radius|data-font|data-layout]-Zuordnungen in app-theme.css, damit ThemePicker und FOUC-Bootstrap übereinstimmen.

Bewahre die gemeinsame Geometrie der vier Kacheln in marketing/brand-geometry.ts für Marketing-Oberflächen. Logos in der Kopfzeile bleiben transparent; Favicon und App-Symbole behalten den abgerundeten schwarzen Hintergrund. Reine Marketing-Seiten bleiben im Obsidian-Look, solange MARKETING_THEME_MODE auf "locked" steht (der Standard des Kits); Produkte können eine andere Palette festlegen oder die Auswahl der Besucher übernehmen.

Überprüfung und Fehlerbehebung

Ändert sich auch die Marketing-Homepage, prüfen Sie, ob Sie app-theme.css bearbeitet haben, und sehen Sie sich apps/web/src/theme/marketing-theme.ts an. Wird Text schwer lesbar, stellen Sie den vorherigen Wert wieder her und führen Sie im Stammverzeichnis corepack pnpm test -- apps/web/src/theme/contrast.test.ts aus, bevor Sie es erneut versuchen.

Prüfe nach Änderungen an Theme-Tokens oder Farbpaletten im ThemePicker unter /settings/appearance, ob die UI-Galerie des Kits sowie /dashboard, /auth, /billing, /chat und Organisations-Oberflächen aktualisiert werden. Bestätige, dass / die Obsidian-Markensperre beibehält (sofern MARKETING_THEME_MODE nichts anderes festlegt). Führe die Theme-Vertragstests aus (catalog, presets, contrast, theme-ownership, kit-ui-gallery) und, sofern verfügbar, die Playwright-Tests für das Anwendungsthema. Prüfe Tastaturfokus, Kontrast, 320 px und reduzierte Bewegung.