Temi di prodotto

Installazione e configurazione

Prima di qualsiasi passaggio, leggere Prima di iniziare e Nozioni di base sui terminali. Queste istruzioni presuppongono che tu abbia aperto l'intero supastack monorepo in VS Code; la sua radice package.json contrassegna la radice del repository. Nei comandi pnpm, un pacchetto dell'area di lavoro è un'app o una cartella di codice condiviso; nel prodotto, uno spazio di lavoro è il contenitore dei dati di un team e il limite di sicurezza. corepack pnpm --filter ... seleziona un pacchetto dal monorepo mentre i comandi vengono eseguiti dalla sua radice. Se hai aperto solo una cartella mobile o desktop sincronizzata, non contiene il backend Web, la configurazione di Docker o gli script root: esegui il backend da questo monorepo o da un server ospitato raggiungibile e utilizza gli script della cartella della piattaforma. Una variabile di ambiente è un'impostazione denominata memorizzata in un file .env locale o nel dashboard dell'hosting; riavvia l'app pertinente dopo averla modificata e mantieni i segreti del server fuori dai valori NEXT_PUBLIC_ e EXPO_PUBLIC_.

1. In VS Code apri apps/web/app/app-theme.css per le schermate dei prodotti a cui hai effettuato l'accesso e apps/web/src/theme/catalog.ts per aggiungere un pacchetto colori. Non modificare apps/web/app/theme.css per i colori del prodotto; controlla il marchio di marketing.

2. Dal root del repository esegui corepack pnpm --filter @supastack/web dev, quindi visita http://localhost:3000/settings/appearance.

3. Modifica un token nella tua filiale locale e aggiorna l'anteprima. Previsto: il dashboard controlla l'aggiornamento mentre la home page mantiene il tema di marketing selezionato.

Il brand marketing e il tema di prodotto sono file separati. Modifica apps/web/app/app-theme.css per il chrome di dashboard, auth, settings, billing, chat e org. Aggiungi pacchetti colore in apps/web/src/theme/catalog.ts. Estendi gli assi densità, raggio, font e layout in apps/web/src/theme/presets.ts più le regole html[data-*] corrispondenti in app-theme.css. Scegli l'identità di marketing in apps/web/src/theme/marketing-theme.ts (MARKETING_THEME_MODE: locked | inherit | un id di pack) invece di modificare apps/web/app/theme.css — il suo blocco tramite .marketing-theme:not(.app-theme):not([data-theme]):not([data-marketing-theme="inherit"]) mantiene di default il brand Obsidian della homepage di supastack.

A runtime, Impostazioni → Aspetto → ThemePicker salva colore, densità, raggio, font e layout nei cookie del browser + localStorage così che theme-boot.ts ripristini tutti gli assi prima del primo rendering, e sincronizza il pacchetto completo di aspetto dell’utente autenticato tra browser tramite user_appearance (GET/PUT /api/account/appearance). La stessa pagina monta la galleria UI del kit in modo che pacchetti e preset aggiornino dal vivo pulsanti, input, schede, badge e finestre di dialogo. I dettagli di design e gli esempi copia-incolla si trovano in docs/design/kit-product-theme.md e 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… */ }
}

Comandi da copiare

Segui i commenti per vedere in quale cartella viene eseguito un comando. Se due terminali sono etichettati, apri due finestre di terminale e mantieni il primo comando in esecuzione mentre usi il secondo.

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

Flusso di implementazione

Preferisci var(--page|--section|--raised|--text|--muted|--border|--accent|…) nei consumatori dell'app (app-theme.css, alias di globals.css, route WorkspaceShell). Non reintrodurre shell teal/pallidi e non hardcodare l'hex Obsidian nella UI di prodotto.

Quando aggiungi un pack, mantieni contrast.test.ts verde. Quando aggiungi un id di preset, aggiorna presets.ts e i remap html[data-density|data-radius|data-font|data-layout] in app-theme.css così ThemePicker e il boot anti-FOUC restano allineati.

Preserva la geometria condivisa del brand a quattro tessere in marketing/brand-geometry.ts per le superfici di marketing. I marchi dell'header restano trasparenti; gli asset favicon e icona app mantengono lo sfondo nero arrotondato. Le pagine puramente marketing restano Obsidian finché MARKETING_THEME_MODE è "locked" (il default del kit); i prodotti possono fissare un altro pack o ereditare la scelta del visitatore.

Verifica e risoluzione dei problemi

Se un cambiamento di colore influisce sulla home page di marketing, controlla di aver modificato app-theme.css e rivedi apps/web/src/theme/marketing-theme.ts. Se il testo diventa difficile da leggere, ripristina il valore precedente ed esegui corepack pnpm test -- apps/web/src/theme/contrast.test.ts dalla radice prima di riprovare.

Dopo aver modificato token o pack del tema del kit, verifica che ThemePicker su /settings/appearance aggiorni la galleria UI del kit oltre a /dashboard, /auth, /billing, /chat e le shell org. Conferma che / resta sul blocco marketing Obsidian (a meno che MARKETING_THEME_MODE non dica diversamente). Esegui i contratti unitari del tema (catalog, presets, contrast, theme-ownership, kit-ui-gallery) e il Playwright application-theme quando disponibile. Controlla focus da tastiera, contrasto, 320 px e movimento ridotto.