Progettare un tema WordPress completo con DESIGN.md, Google Stitch e prompt AI

Oggi la progettazione di un tema WordPress parte da un'osservazione fondamentale: l'AI non elimina il lavoro difficile, lo sposta prima della scrittura del codice. Un developer può far implementare una SaaS completa da un agente, ma solo se prima ha definito architettura, vincoli, confini e criteri di completamento. Lo stesso principio vale quando vogliamo creare un tema WordPress con DESIGN.md: il risultato dipende meno dal prompt generico e molto di più dalla qualità della specifica.

Per chi lavora su siti WordPress, questo cambia il metodo. Invece di chiedere all'AI "crea un tema moderno", conviene progettare un sistema leggibile da persone e agenti: brief, pagine, componenti, token, accessibilità, template, pattern e test. È lo stesso cambio di mentalità che ho già approfondito parlando di web design WordPress con Novamira.ai e di temi WordPress generati dall'intelligenza artificiale: l'AI funziona meglio quando ha un perimetro tecnico preciso.

In questa guida vediamo un flusso completo: prima si scrive la specifica, poi si usa Google Stitch per esplorare l'interfaccia, quindi si traduce il design in DESIGN.md, si implementa un block theme WordPress con theme.json, template e pattern, e infine si controlla tutto con prompt mirati, WP-CLI e test manuali. Se vuoi ripassare le basi tradizionali, puoi affiancare questa guida a come creare un tema WordPress da zero.

La tesi è semplice: il tema non deve emergere dal codice per tentativi. Deve derivare da una specifica. Il codice è una conseguenza, non il punto di partenza.

Perché partire da una specifica prima del codice

Per progettare in modo efficace un tema WordPress con standard attuali bisogna insistere su un punto: chi usa bene gli agenti AI non salta la parte difficile, salta solo la parte più meccanica dell'implementazione. Nel caso di un tema WordPress, la parte difficile non è creare una cartella in wp-content/themes. È decidere cosa il tema deve fare, cosa non deve toccare, come deve comportarsi nel Site Editor, quali blocchi deve supportare e quali vincoli non possono essere violati.

Una specifica utile deve rispondere almeno a queste domande:

• Quale problema risolve il tema e per quale pubblico?
• Quali pagine e template sono indispensabili al primo rilascio?
• Quali componenti devono essere riutilizzabili come pattern Gutenberg?
• Quali token regolano colori, font, spaziature, raggi, ombre e layout?
• Quali file l'agente AI può modificare e quali deve lasciare intatti?
• Quali criteri definiscono "finito": responsive, accessibilità, performance, SEO, compatibilità editor?

Questa è la differenza tra vibe coding casuale e sviluppo assistito serio: non chiedi all'AI di indovinare, le dai un contratto operativo.

Architettura del workflow

Il flusso consigliato è diviso in sette fasi. Ogni fase produce un output che diventa input per la successiva.

Step 1: scrivere il brief tecnico del tema

Prima di aprire Stitch o un editor, crea un file SPEC.md. Questo file descrive il risultato atteso in modo verificabile.

# SPEC.md - Tema WordPress per studio professionale

## Obiettivo
Creare un block theme WordPress per uno studio di consulenza B2B.
Il tema deve comunicare autorevolezza, chiarezza, velocità e affidabilità.

## Pagine prioritarie
- Homepage
- Servizi
- Caso studio
- Blog
- Contatti
- 404

## Vincoli
- Nessun page builder esterno.
- Compatibile con Site Editor e Gutenberg.
- Tutte le sezioni riutilizzabili devono diventare pattern.
- Nessun H1 duplicato nei template.
- Palette e tipografia governate da theme.json.
- CSS custom ridotto al minimo.

## Criteri di completamento
- Mobile, tablet e desktop senza overflow.
- Contrasto WCAG AA sulle CTA principali.
- Template principali presenti in /templates.
- Header e footer presenti in /parts.
- Pattern registrati in /patterns.
- Score PageSpeed da verificare prima del rilascio.

Il prompt iniziale per l'agente AI non deve chiedere codice. Deve chiedere di verificare la specifica.

Agisci come senior WordPress theme architect.

Leggi questa specifica per un block theme WordPress.
Non generare codice.

Task:
1. Trova requisiti ambigui.
2. Elenca decisioni mancanti.
3. Proponi una struttura file coerente con un block theme moderno.
4. Indica quali parti devono diventare template e quali pattern.
5. Restituisci solo una checklist tecnica approvabile.

SPEC:
[incolla qui SPEC.md]

Step 2: progettare le prime schermate con Google Stitch

Google descrive Stitch come un canvas AI-native per creare, iterare e collaborare su UI ad alta fedeltà usando linguaggio naturale. Nel workflow WordPress non va usato come scorciatoia per copiare HTML a caso, ma come strumento di esplorazione: produce direzioni visive, layout e varianti che poi vanno convertite in un sistema WordPress mantenibile.

Un prompt efficace per Stitch deve contenere obiettivo, pubblico, tono, struttura e vincoli. Ecco un esempio pronto.

Design a responsive WordPress block theme homepage for a B2B consulting studio.

Business goal:
Generate qualified leads for consulting calls.

Audience:
Small business owners and marketing managers who need a reliable WordPress partner.

Visual direction:
Clean, editorial, professional, calm. Avoid generic SaaS gradients and oversized decorative blobs.

Page structure:
1. Header with logo, navigation and primary CTA.
2. Hero with clear value proposition and one CTA.
3. Trust strip with service areas.
4. Services grid with 3 cards.
5. Case study preview.
6. Process section with 4 steps.
7. FAQ.
8. Final CTA.
9. Footer with contacts and legal links.

Constraints:
- Design must translate cleanly into WordPress Gutenberg blocks.
- Use reusable sections that can become block patterns.
- Keep text readable on mobile.
- Use accessible contrast for buttons and links.

Dopo aver ottenuto una variante convincente, non fermarti allo screenshot. Chiedi a Stitch o all'agente di estrarre le decisioni di design: palette, font, scala tipografica, spacing, componenti e stati. Queste informazioni diventano il materiale per DESIGN.md.

Step 3: trasformare il design in DESIGN.md

DESIGN.md è utile perché rende esplicito il design system in un formato testuale leggibile dagli agenti. Il repository ufficiale di Google Labs include anche comandi CLI per validare, confrontare ed esportare token. La documentazione WordPress, invece, indica theme.json come il file fondamentale per impostazioni e stili globali di un block theme. Il ponte naturale è questo: DESIGN.md governa il linguaggio visivo, theme.json lo applica in WordPress.

Un esempio essenziale di DESIGN.md per il tema potrebbe essere:

# DESIGN.md

## Brand
Name: Studio Atlas
Personality: clear, practical, reliable, technical.
Audience: business owners, marketing managers, WordPress site owners.

## Color Tokens
- primary: #1E3A5F
- primary-hover: #15304F
- accent: #D97706
- background: #F7F8FA
- surface: #FFFFFF
- text: #17202A
- muted: #5F6B7A
- border: #D9DEE7

## Typography
- heading-font: Inter Tight, system-ui, sans-serif
- body-font: Inter, system-ui, sans-serif
- h1: 56px / 1.08 / 700
- h2: 40px / 1.15 / 700
- h3: 26px / 1.25 / 650
- body: 18px / 1.7 / 400
- small: 14px / 1.5 / 400

## Spacing
- xs: 8px
- sm: 16px
- md: 24px
- lg: 40px
- xl: 64px
- section: 96px

## Components
Button primary:
- background: primary
- text: #FFFFFF
- radius: 6px
- padding: 14px 22px
- hover: primary-hover
- focus: 2px solid accent

Card:
- background: surface
- border: 1px solid border
- radius: 8px
- padding: 24px
- no decorative shadow unless needed for hierarchy

## WordPress Rules
- Prefer core blocks and patterns.
- Avoid hard-coded inline styles in templates.
- Put global decisions in theme.json.
- Use CSS only for behavior not expressible through theme.json.

Prima di usare questo file come contesto per un agente, validalo. La CLI ufficiale consente il controllo strutturale.

# comando lint
npx @google/design.md lint DESIGN.md

Quando fai evolvere il design, confronta due versioni per evitare regressioni nei token.

# confronto due versioni
npx @google/design.md diff DESIGN.md DESIGN-v2.md

Step 4: creare lo scheletro del block theme

Un tema a blocchi moderno parte da pochi file ordinati. La documentazione ufficiale WordPress ricorda che i block theme usano blocchi per tutte le parti del sito, inclusi header, contenuto e footer. Per questo conviene progettare la struttura in modo compatibile con Site Editor.

studio-atlas/
├── style.css
├── functions.php
├── theme.json
├── screenshot.png
├── templates/
│   ├── index.html
│   ├── front-page.html
│   ├── single.html
│   ├── page.html
│   ├── archive.html
│   └── 404.html
├── parts/
│   ├── header.html
│   └── footer.html
├── patterns/
│   ├── hero-consulenza.php
│   ├── servizi-grid.php
│   ├── processo.php
│   ├── faq.php
│   └── cta-finale.php
└── assets/
    ├── css/
    └── js/

Il file style.css contiene l'intestazione riconosciuta da WordPress.

/*
Theme Name: Studio Atlas
Theme URI: https://example.com/studio-atlas
Author: Emilio Petrozzi
Description: Block theme WordPress progettato con DESIGN.md, Google Stitch e specifiche AI.
Version: 1.0.0
Requires at least: 6.5
Tested up to: 6.9
Requires PHP: 8.0
Text Domain: studio-atlas
*/

Il prompt per generare lo scheletro deve limitare il raggio d'azione dell'agente.

Agisci come sviluppatore senior WordPress specializzato in block theme.

Contesto:
- SPEC.md definisce requisiti e pagine.
- DESIGN.md definisce token e componenti.

Task:
Crea lo scheletro del tema "studio-atlas".

Vincoli:
- Non creare plugin.
- Non usare page builder.
- Non inserire CSS inline nei template.
- Usa theme.json per colori, font, spacing e layout.
- Crea solo file necessari al primo rilascio.

Output:
1. Alberatura file.
2. Contenuto di style.css.
3. Contenuto minimo di functions.php.
4. Contenuto iniziale di theme.json.
5. Note sui file da completare dopo approvazione.

Step 5: tradurre DESIGN.md in theme.json

theme.json è il punto in cui il design system diventa editoriale: palette, tipografia, spaziature e layout appaiono sia nel frontend sia nell'editor. WordPress lo definisce una lingua comune tra tema, plugin, utenti e interfaccia di editing.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "appearanceTools": true,
    "layout": {
      "contentSize": "760px",
      "wideSize": "1180px"
    },
    "color": {
      "palette": [
        { "slug": "primary", "name": "Primary", "color": "#1E3A5F" },
        { "slug": "accent", "name": "Accent", "color": "#D97706" },
        { "slug": "background", "name": "Background", "color": "#F7F8FA" },
        { "slug": "surface", "name": "Surface", "color": "#FFFFFF" },
        { "slug": "text", "name": "Text", "color": "#17202A" },
        { "slug": "muted", "name": "Muted", "color": "#5F6B7A" }
      ]
    },
    "typography": {
      "fontFamilies": [
        {
          "slug": "inter",
          "name": "Inter",
          "fontFamily": "Inter, system-ui, sans-serif"
        },
        {
          "slug": "inter-tight",
          "name": "Inter Tight",
          "fontFamily": "\"Inter Tight\", Inter, system-ui, sans-serif"
        }
      ],
      "fontSizes": [
        { "slug": "small", "name": "Small", "size": "14px" },
        { "slug": "base", "name": "Base", "size": "18px" },
        { "slug": "h2", "name": "Heading 2", "size": "40px" },
        { "slug": "hero", "name": "Hero", "size": "56px" }
      ]
    },
    "spacing": {
      "spacingScale": {
        "steps": 0
      },
      "spacingSizes": [
        { "slug": "sm", "name": "Small", "size": "16px" },
        { "slug": "md", "name": "Medium", "size": "24px" },
        { "slug": "lg", "name": "Large", "size": "40px" },
        { "slug": "xl", "name": "Extra Large", "size": "64px" }
      ]
    }
  },
  "styles": {
    "color": {
      "background": "var:preset|color|background",
      "text": "var:preset|color|text"
    },
    "typography": {
      "fontFamily": "var:preset|font-family|inter",
      "fontSize": "var:preset|font-size|base",
      "lineHeight": "1.7"
    },
    "elements": {
      "heading": {
        "typography": {
          "fontFamily": "var:preset|font-family|inter-tight",
          "lineHeight": "1.15"
        }
      },
      "button": {
        "border": {
          "radius": "6px"
        },
        "color": {
          "background": "var:preset|color|primary",
          "text": "var:preset|color|surface"
        }
      }
    }
  }
}

Prompt consigliato per questa conversione:

Agisci come WordPress block theme engineer.

Input:
- DESIGN.md con token colore, tipografia, spacing e componenti.
- SPEC.md con vincoli del tema.

Task:
Genera un theme.json compatibile con WordPress 6.5+.

Regole:
- Usa version 2 e $schema ufficiale.
- Inserisci palette, fontFamilies, fontSizes, spacingSizes e layout.
- Evita valori duplicati non necessari.
- Non generare template.
- Non usare commenti nel JSON.

Output:
Solo JSON valido.

Step 6: creare template e parti riutilizzabili

I template HTML di un block theme sono markup Gutenberg. L'obiettivo non è replicare pixel per pixel l'output di Stitch, ma ricostruire le sezioni usando blocchi core, classi coerenti e pattern.

Esempio di parts/header.html:

<!-- wp:group {"align":"full","style":{"spacing":{"padding":{"top":"16px","bottom":"16px"}}},"layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull" style="padding-top:16px;padding-bottom:16px">
  <!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between","flexWrap":"wrap"}} -->
  <div class="wp-block-group">
    <!-- wp:site-title {"level":0} /-->
    <!-- wp:navigation {"layout":{"type":"flex","justifyContent":"right"}} /-->
    <!-- wp:buttons -->
    <div class="wp-block-buttons">
      <!-- wp:button -->
      <div class="wp-block-button"><a class="wp-block-button__link wp-element-button">Prenota una consulenza</a></div>
      <!-- /wp:button -->
    </div>
    <!-- /wp:buttons -->
  </div>
  <!-- /wp:group -->
</div>
<!-- /wp:group -->

Prompt per generare template senza perdere controllo:

Agisci come Gutenberg block theme developer.

Task:
Crea i template HTML per:
- front-page.html
- single.html
- archive.html
- 404.html
- parts/header.html
- parts/footer.html

Vincoli:
- Usa solo markup di blocchi core WordPress.
- Non creare un H1 nel contenuto se il template già usa post-title.
- Usa template parts per header e footer.
- Le sezioni complesse devono richiamare pattern, non duplicare markup.
- Non usare CSS inline salvo padding/spaziature supportate dai blocchi.

Output:
Un file alla volta, con percorso e contenuto completo.

Step 7: convertire le sezioni in pattern Gutenberg

I pattern sono il punto in cui un tema diventa davvero usabile. Un cliente o editor può inserire una hero, una CTA o una FAQ senza chiedere modifiche al codice. Un pattern PHP minimo contiene intestazione e markup blocchi.

<?php
/**
 * Title: Hero consulenza
 * Slug: studio-atlas/hero-consulenza
 * Categories: featured
 */
?>

<!-- wp:group {"align":"full","style":{"spacing":{"padding":{"top":"96px","bottom":"80px"}}},"backgroundColor":"background","layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull has-background-background-color has-background" style="padding-top:96px;padding-bottom:80px">
  <!-- wp:heading {"level":1,"fontSize":"hero"} -->
  <h1 class="wp-block-heading has-hero-font-size">Un sito WordPress più chiaro, veloce e facile da gestire</h1>
  <!-- /wp:heading -->

  <!-- wp:paragraph {"fontSize":"base"} -->
  <p class="has-base-font-size">Progettiamo temi WordPress su misura con design system, Gutenberg e workflow AI controllati.</p>
  <!-- /wp:paragraph -->

  <!-- wp:buttons -->
  <div class="wp-block-buttons">
    <!-- wp:button -->
    <div class="wp-block-button"><a class="wp-block-button__link wp-element-button">Richiedi una consulenza</a></div>
    <!-- /wp:button -->
  </div>
  <!-- /wp:buttons -->
</div>
<!-- /wp:group -->

Per pattern più complessi, come pricing o FAQ, chiedi prima all'agente una lista di campi modificabili. Poi genera il markup. Questo riduce il rischio di sezioni belle ma scomode da gestire.

Step 8: aggiungere funzioni WordPress minime

Un block theme pulito deve avere un functions.php essenziale. Evita di trasformarlo in un plugin mascherato: registra asset, supporti e piccole ottimizzazioni legate al tema. Per logiche avanzate, meglio creare un plugin dedicato. Puoi approfondire la logica degli hook nella guida su azioni e filter WordPress.

<?php
/**
 * Studio Atlas theme setup.
 */

add_action('after_setup_theme', function () {
    add_theme_support('wp-block-styles');
    add_theme_support('editor-styles');
    add_editor_style('assets/css/editor.css');
});

add_action('wp_enqueue_scripts', function () {
    wp_enqueue_style(
        'studio-atlas-style',
        get_stylesheet_uri(),
        array(),
        wp_get_theme()->get('Version')
    );
});

add_filter('should_load_separate_core_block_assets', '__return_true');

Se servono interazioni più evolute, valuta la Interactivity API, disponibile in WordPress Core dalla versione 6.5 tramite il pacchetto @wordpress/interactivity. Non usarla per tutto: è utile quando l'interazione appartiene a blocchi e componenti, non per animazioni decorative superflue.

Prompt ottimizzati per implementare il tema passo passo

La regola operativa è: un prompt, un risultato verificabile. Non chiedere all'agente di "fare tutto il tema" in una volta sola. Spezza il lavoro.

Prompt 1: revisione architetturale

Agisci come reviewer senior WordPress.

Analizza SPEC.md e DESIGN.md.
Non scrivere codice.

Dimmi:
1. Quali requisiti sono incompleti.
2. Quali rischi tecnici vedi.
3. Quali template e pattern sono davvero necessari.
4. Quali decisioni devono finire in theme.json.
5. Quali controlli fare prima del rilascio.

Prompt 2: implementazione controllata

Agisci come implementatore WordPress.

Task:
Implementa solo theme.json e style.css.

Input:
- SPEC.md
- DESIGN.md

Vincoli:
- Non modificare template.
- Non creare pattern.
- Non aggiungere dipendenze.
- Mantieni JSON valido.
- Usa token coerenti con DESIGN.md.

Dopo l'implementazione:
1. Spiega le scelte.
2. Elenca cosa resta da fare.
3. Suggerisci un comando di verifica.

Prompt 3: generazione pattern

Agisci come Gutenberg pattern designer.

Task:
Crea il pattern "servizi-grid.php".

Requisiti:
- 3 card servizio.
- Ogni card ha titolo, testo breve e link.
- Usa colori e font di theme.json.
- Markup compatibile con blocchi core.
- Nessun CSS custom nel pattern.

Output:
Solo contenuto completo del file PHP.

Prompt 4: QA finale

Agisci come QA engineer WordPress.

Analizza il tema appena creato.

Controlla:
- Struttura file.
- Validità theme.json.
- Presenza template principali.
- Presenza header e footer.
- Pattern registrati.
- Possibili H1 duplicati.
- Accessibilità base.
- Responsive risk.
- SEO tecnica.

Output:
Tabella con problema, severità, file coinvolto e correzione consigliata.

Verifiche tecniche prima della pubblicazione

Quando il tema è pronto, installalo prima in locale o staging. Se hai WP-CLI disponibile, puoi automatizzare alcune verifiche.

# verifica temi installati
wp theme list

Attiva il tema solo in ambiente di test.

# attivazione in staging
wp theme activate studio-atlas

Controlla che WordPress non segnali errori PHP dopo l'attivazione.

# controllo errori recenti
wp eval 'echo "Tema attivo: " . wp_get_theme()->get("Name");'

La checklist finale deve includere:

• Homepage leggibile su mobile senza overflow orizzontale.
• Menu e CTA accessibili da tastiera.
• Un solo H1 per pagina.
• Contrasto sufficiente per testo, link e pulsanti.
• Template per singolo articolo, pagina, archivio e 404.
• Pattern modificabili nel Site Editor.
• Nessun contenuto essenziale hard-coded se deve essere gestito dal cliente.
• Font caricati in modo efficiente.
• Performance controllata con PageSpeed Insights.

Errori comuni da evitare

Il primo errore è usare Stitch come se producesse direttamente un tema WordPress finito. Può aiutare molto nella direzione UI, ma il tema deve rispettare gerarchie WordPress, Gutenberg, template parts e manutenzione futura.

Il secondo errore è mettere tutto in CSS. Se palette, font e spacing finiscono solo in style.css, l'editor non riflette davvero il design system. Il cliente vedrà opzioni incoerenti e tenderà a rompere il layout.

Il terzo errore è chiedere all'AI output troppo ampi. Prompt enormi come "crea tutto il tema" generano codice plausibile ma difficile da verificare. Meglio far lavorare l'agente su una porzione alla volta, con file e confini chiari.

Il quarto errore è non documentare le decisioni. Se il tema evolve, aggiorna SPEC.md e DESIGN.md. Altrimenti l'agente continuerà a lavorare su istruzioni vecchie e produrrà incoerenze.

Risorse utili

• Google Stitch: canvas AI per esplorare interfacce e prototipi.
• Blog Google su Stitch e vibe design: panoramica ufficiale dell'evoluzione di Stitch.
• Google Labs DESIGN.md: specifica, CLI, lint, diff ed export token.
• Documentazione WordPress su theme.json: base tecnica per stili globali e impostazioni.
• Documentazione WordPress sui block theme: introduzione al modello Site Editor.
• Interactivity API: standard WordPress per blocchi interattivi moderni.

FAQ

Posso creare un tema WordPress completo solo con Stitch?

No, non in modo professionale. Stitch è utile per ideazione, layout e direzione visiva. Un tema WordPress completo richiede struttura del tema, theme.json, template, pattern, compatibilità Gutenberg, test e controlli tecnici.

DESIGN.md sostituisce theme.json?

No. DESIGN.md documenta il design system in forma leggibile dagli agenti AI. theme.json applica quelle decisioni dentro WordPress, rendendole disponibili al frontend e all'editor.

Meglio un tema classico o un block theme?

Per un nuovo progetto orientato a Gutenberg e Site Editor, un block theme è spesso la scelta più coerente. Un tema classico resta valido quando il progetto ha vincoli legacy, template PHP complessi o dipendenze già consolidate.

Gli agenti AI possono implementare direttamente il tema?

Sì, ma solo se ricevono specifiche, confini e criteri di verifica. Il punto del documento allegato è proprio questo: l'AI produce risultati migliori quando il lavoro di progettazione è esplicito, scritto e verificabile.

Conclusione

Creare un tema WordPress completo con AI non significa delegare il pensiero al modello. Significa spostare il valore sulla progettazione: descrivere bene il sistema, definire vincoli, produrre un design system e far implementare porzioni controllate. Google Stitch aiuta a esplorare l'interfaccia, DESIGN.md conserva la coerenza visiva, theme.json porta quella coerenza dentro WordPress.

La domanda utile, prima di generare codice, è questa: se un altro sviluppatore o un agente AI dovesse costruire il tema senza parlarti, avrebbe abbastanza informazioni per farlo correttamente? Se la risposta è no, non manca un prompt migliore. Manca una specifica migliore.