Stili e classi

Non esiste una safelist. Tailwind fa `@source` direttamente sui file dello Studio — `db.viewmodes.json` e `db.styles.json` — e genera esattamente le classi che i viewMode e gli stili usano davvero.

Due conseguenze. In produzione il CSS è minimale per costruzione: nessuno deve ricordarsi di potarlo. E le varianti arbitrarie (`[&_p]:m-0`, `hover:text-primary`) funzionano senza doverle enumerare, perché Tailwind le vede scritte nel file.

È anche il motivo per cui gli store sono file e non righe di database, ed è la dipendenza più importante da non rompere: spostare la forma in database significherebbe reintrodurre la safelist il giorno stesso.

Il campo `className` di un viewMode o di un’istanza è una stringa di classi Tailwind. Non è validato contro un elenco, e non perché ci si fidi: le classi vivono negli store, che sono la stessa sorgente da cui Tailwind le genera. Se le scrivi lì, esistono.

Sull’ISTANZA di un blocco il `className` si somma a quello del viewMode. Serve per lo scostamento locale — una spaziatura, un colore su questa sezione e non sulle altre. Quando lo stesso scostamento compare tre volte, non è più uno scostamento: è uno stile, e va nella style guide.

• styling/resolveStyles.ts — la composizione libera passa verbatim: nessuna safelist contro cui validare
• styling/resolveViewModeStyles.ts — gli stili dichiarati dal viewMode e dai suoi slot

Gli aspetti RICORRENTI — ombra, raggio, superficie, bordo, tipografia — non si scrivono come classi nel `className` di ogni viewMode. Si definiscono una volta come stili nominati in `db.styles.json` e si richiamano per nome dal viewMode o dallo slot.

Il guadagno è la propagazione: modifichi lo stile in un punto e cambiano tutti i viewMode che lo includono. Lo stile diventa la fonte di verità dell’aspetto, invece della classe copiata in trenta posti — che è la forma in cui l’aspetto si perde nel tempo.

Ogni stile ha una categoria: Tipografia, Elevazione, Contorno, Superfici, o Generico per i compositi. Essendo il motore su elementi determinati, sapere quali TIPI di aspetto esistono è informazione, non burocrazia. I colori restano nella palette, i font nei settings, le variabili dei componenti nel loro tab: nessun doppione.

Uno stile può portare CSS grezzo: genera una regola `.us-<nome>`, usa `var(--color-*)` per seguire la palette, ed è la strada giusta per ombre, superfici e gradienti — cose che in Tailwind si scriverebbero male.

Oppure può portare classi Tailwind (`shadow-sm`, `rounded-md`), e allora si ragiona nel vocabolario della propria style guide. Queste le genera Tailwind, che scansiona `db.styles.json`. Il CSS grezzo non passa da Tailwind: è una regola emessa a runtime.

Il token `us-<nome>` funziona in qualunque `className`: viene espanso nelle classi dello stile che nomina. Un token che nomina uno stile `css`, o uno che non esiste, viene lasciato com’è — nel primo caso è già una classe valida, nel secondo è innocuo.

• styling/resolveClassName.ts — espande i token `us-<nome>` nelle classi dello stile riferito

Un tema è una palette più dei font. Le variabili del tema attivo vengono emesse come CSS var nel layout, quindi cambiare tema ri-stila tutto senza toccare né il contenuto né i viewMode.

La differenziazione STRUTTURALE — raggi, bordi, ombre, spaziature, tipografia — non sta nel tema: sta nei `themeStyles` dei viewMode, indicizzati per nome di tema. È la distinzione che tiene i temi leggeri: tredici temi in catalogo non sono tredici copie della style guide.

• src/theme/index.ts — le variabili complete di un tema: base ⊕ palette ⊕ font ⊕ `vars`
• src/utils/generateCssVars.ts — le variabili emesse come CSS var dal layout
• src/utils/hexToRgb.ts — la conversione che serve alle var colore con opacità