Documentazione per sviluppatori dei Layout

I Layout definiscono il frame di pagina condiviso utilizzato dalle pagine di FaceFlow.

Per gli utenti tecnici, un Layout è il contratto del shell della pagina. Determina dove risiedono le regioni condivise, dove viene iniettato il contenuto della pagina e come una famiglia di pagine mantiene un frame coerente senza duplicare la struttura pagina per pagina.

Responsabilità principali

Un Layout dovrebbe controllare:

la struttura complessiva del documento
il posizionamento di header, footer e regioni condivise
il punto di inserimento principale del contenuto
i wrapper strutturali e l'inquadramento della famiglia di pagine
stili o comportamenti opzionali a livello di layout

Un Layout non dovrebbe avere la responsabilità dei contenuti di marketing specifici per una pagina.

Scheletro del Layout

La maggior parte dei Layout può essere compresa attraverso un semplice schema:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{{ page.title }}</title>
</head>
<body>
  {header}
  {siteComponents}
  <main>
    {content}
  </main>
  {footer}
</body>
</html>

Il requisito chiave è un punto di inserimento {content} affidabile. Senza quello, le Pagine non hanno un punto prevedibile dove renderizzare.

Esempio di contratto della shell

Un Layout può anche esporre regioni condivise aggiuntive mantenendo però chiari i confini di proprietà:

<body class="resource-layout">
  {header}
  <div class="resource-shell">
    <aside class="resource-sidebar">
      {siteComponents}
    </aside>
    <main class="resource-main">
      {content}
    </main>
  </div>
  {footer}
</body>

La regola importante è che la shell rimanga strutturale. La Pagina mantiene comunque la proprietà della sequenza renderizzata in {content}.

Relazione con Pagine e Componenti

Mantieni chiaro il modello di proprietà:

Layout possiede la shell
Pagina possiede la composizione dell'esperienza
Componente possiede le sezioni di contenuto riutilizzabili all'interno dell'esperienza

Quando i Layout rimangono strutturali, le famiglie di pagine restano facili da far evolvere.

Regioni condivise

I Layout sono il posto giusto per regioni condivise come:

navigazione persistente
inquadratura footer standard
sidebar della documentazione
corsie di supporto usate in una famiglia di pagine

Esempio:

<body class="docs-layout">
  {header}
  <div class="docs-shell">
    <aside class="docs-sidebar">
      {siteComponents}
    </aside>
    <main class="docs-content">
      {content}
    </main>
  </div>
  {footer}
</body>

Questo è riuso strutturale. Un banner promozionale una tantum non appartiene qui.

Famiglie di Layout

Famiglie comuni di layout includono:

shell principale del sito marketing
shell di landing per campagne
shell di risorsa o documentazione
shell per portali o knowledge-base

Ogni famiglia dovrebbe rappresentare uno schema strutturale duraturo, non una variazione temporanea di contenuto.

Stilizzazione a livello di Layout

I Layout possono definire decisioni di stile condivise che appartengono alla shell:

<body class="min-h-screen bg-slate-950 text-white">
  {header}
  <main class="mx-auto max-w-7xl px-6 py-16">
    {content}
  </main>
  {footer}
</body>

Questo è appropriato quando lo stile appartiene al frame della pagina. Gli stili specifici di sezione appartengono ancora ai Componenti.

Impatto delle modifiche

Le modifiche al Layout hanno un impatto elevato perché un singolo Layout spesso influisce su molte Pagine.

Prima di modificare un Layout, esamina:

quale famiglia di pagine dipende da esso
se le regioni condivise cambiano significato
se cambiano larghezza del contenuto, spaziatura o assunti di navigazione
se i Componenti esistenti si adattano ancora correttamente alla shell

Schema di revisione del Layout

Quando viene proposta una modifica al Layout, controlla l'impatto in questo ordine:

shell semantics
-> shared regions
-> content width and spacing
-> component fit
-> dependent page-family behavior

Questo aiuta i team a evitare di approvare una modifica alla shell apparentemente piccola che rompe silenziosamente diverse Pagine dipendenti.

Checklist di revisione tecnica

il Layout espone un chiaro punto di inserimento del contenuto?
possiede solo preoccupazioni a livello di shell?
può essere riutilizzato da più Pagine senza eccezioni una tantum?
le regioni condivise sono veramente condivise?
cambiare questo Layout influenzerebbe molte Pagine in modo comprensibile?

Anti-pattern

Evita:

incorporare direttamente nel Layout testi specifici per una pagina
creare Layout quasi duplicati per piccole variazioni
spostare la logica delle sezioni nella shell
usare il Layout come discarica per tutto il contenuto condiviso
cambiare la semantica della shell senza verificare le Pagine dipendenti

Esempio di regola decisionale

Usa un Layout quando la modifica interessa il frame attorno a molte Pagine:

new docs sidebar across the whole docs section -> Layout
new CTA block inside one page section -> Component
new page-specific proof content -> Page composition

FaceFlow — Layout System