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.

È qui che entra in gioco DESIGN.md, il nuovo formato open source pubblicato da Google Labs Code per descrivere una visual identity in modo leggibile sia dagli esseri umani sia dagli agenti di coding. L’idea è semplice ma molto potente: creare un file testuale, versionabile e validabile che contenga design token, razionale visivo, regole sui componenti e indicazioni pratiche su cosa fare e cosa evitare.

In altre parole, DESIGN.md prova a diventare per il design quello che altri file di configurazione sono già diventati per sviluppo, linting, formattazione e automazione: una fonte di verità chiara, portabile e adatta ai workflow moderni con AI.

Cos’è DESIGN.md e perché è importante

DESIGN.md è un formato pensato per descrivere l’identità visiva di un prodotto agli agenti di codice. La definizione ufficiale del repository google-labs-code/design.md parla di una specifica per dare agli agenti una comprensione persistente e strutturata di un design system.

Il punto chiave è la parola persistente. Un agente AI può ricevere istruzioni nel prompt, ma quelle istruzioni spesso sono temporanee, incomplete o ambigue. Un file DESIGN.md, invece, può stare nel repository accanto al codice, essere revisionato in pull request, validato con una CLI e riutilizzato da strumenti diversi.

Il formato unisce due livelli:

• una parte machine-readable in YAML front matter, dove vengono definiti token come colori, tipografia, spacing, radius e componenti;
• una parte human-readable in Markdown, dove si spiega il perché delle scelte e come applicarle in situazioni reali.

Questa combinazione è interessante perché i soli token non bastano. Sapere che il colore primario è #1A1C1E dice poco sul tono dell’interfaccia. Sapere anche che quel colore rappresenta “deep ink”, autorevolezza e leggibilità editoriale aiuta l’agente a usarlo con più coerenza.

Il problema che DESIGN.md prova a risolvere

Molti team hanno già un design system, ma spesso è distribuito in troppi luoghi: Figma, Storybook, documentazione interna, file CSS, Tailwind config, component library, issue di progetto e memoria informale del team. Quando entra in scena un agente AI, questa frammentazione diventa un problema tecnico.

Un agente può generare una pagina funzionante, ma senza un contesto stabile rischia di:

• inventare colori non presenti nel brand;
• usare font o pesi tipografici incoerenti;
• creare bottoni con radius e padding casuali;
• mescolare stili editoriali, SaaS, dashboard e landing page;
• ignorare contrasto e accessibilità;
• produrre componenti apparentemente belli ma scollegati dal sistema reale.

DESIGN.md riduce questo rischio perché trasforma le linee guida di design in un contratto leggibile dal codice e dagli agenti. Non sostituisce Figma o una libreria componenti, ma aggiunge un livello di istruzioni condivise che può viaggiare con il repository.

Come è fatto un file DESIGN.md

La struttura ufficiale prevede un file Markdown con front matter YAML opzionale. Il front matter contiene i token normativi; il corpo Markdown contiene spiegazioni, razionale e linee guida.

Ecco un esempio semplificato:

---
version: alpha
name: Editorial Tech
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  headline-lg:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
  lg: 32px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#ffffff"
    rounded: "{rounded.sm}"
    padding: 12px
---

## Overview

Interfaccia editoriale, tecnica e autorevole. Il prodotto deve comunicare
precisione, leggibilità e affidabilità, evitando decorazioni inutili.

## Colors

Il colore primario è usato per testi e titoli. Il terziario è riservato
alle azioni principali e agli stati di enfasi.

Questo esempio mostra il principio operativo: i valori precisi sono nei token, mentre il Markdown spiega come interpretarli. Un agente può quindi rispettare sia la misura esatta sia l’intenzione progettuale.

I token supportati: colori, tipografia, spacing e componenti

La specifica ufficiale descrive un insieme di gruppi token pensati per coprire gli aspetti fondamentali di una UI.

I gruppi principali sono:

• colors, per palette e ruoli cromatici;
• typography, per font, dimensioni, pesi, line-height e letter-spacing;
• rounded, per la scala dei bordi arrotondati;
• spacing, per distanze, margini e ritmo visivo;
• components, per collegare i token a elementi come bottoni, chip, input e stati.

Un dettaglio tecnico importante è il supporto ai riferimenti tra token con sintassi {path.to.token}. Per esempio, un bottone può usare backgroundColor: "{colors.tertiary}", evitando duplicazione e riducendo il rischio di divergenze.

Questa scelta rende DESIGN.md più simile a un piccolo linguaggio di configurazione che a una semplice pagina di documentazione. È leggibile, ma anche analizzabile da un linter.

Le sezioni Markdown consigliate

Il corpo del file non è libero in modo caotico. La specifica suggerisce un ordine canonico delle sezioni, tutte basate su heading ##:

1. Overview;
2. Colors;
3. Typography;
4. Layout;
5. Elevation & Depth;
6. Shapes;
7. Components;
8. Do’s and Don’ts.

Questo ordine serve a dare prevedibilità agli strumenti. Un agente sa dove cercare la personalità visiva, dove trovare le regole tipografiche, dove leggere i vincoli di layout e dove individuare errori da evitare.

La scelta è pragmatica: DESIGN.md non vuole essere un trattato di brand identity, ma un formato operativo. Deve essere abbastanza espressivo per guidare un’interfaccia reale, ma abbastanza strutturato per essere letto e validato da una CLI.

Esempio pratico: usare DESIGN.md in un progetto frontend

Immagina un team che sta costruendo una dashboard SaaS. Nel repository sono presenti componenti React, Tailwind, test e documentazione. Senza DESIGN.md, un agente AI chiamato a creare una nuova pagina “Billing” potrebbe copiare pattern visti in altre parti del codice, ma potrebbe anche introdurre nuove sfumature, radius non standard o gerarchie tipografiche incoerenti.

Con DESIGN.md, il workflow diventa più controllabile:

1. il team definisce colori, tipografia, spacing e componenti principali;
2. il file viene salvato nel repository;
3. l’agente legge DESIGN.md prima di generare UI;
4. la CLI valida token, riferimenti e contrasto;
5. eventuali modifiche al design system vengono confrontate con diff.

Il risultato non è una garanzia assoluta di qualità, ma riduce drasticamente l’improvvisazione. In un contesto con più agenti o più sviluppatori, questo è un vantaggio concreto.

Comandi CLI: lint, diff, export e spec

Google distribuisce anche una CLI installabile come pacchetto npm @google/design.md. Dal README ufficiale emerge un set di comandi pensato per validare, confrontare ed esportare il formato.

Il comando più immediato è il lint:

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

Il linter restituisce JSON strutturato con finding, severità, percorso e messaggio. Questo è utile perché un agente può leggere l’output e correggere il file in modo mirato.

Per confrontare due versioni:

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

Questo aiuta a capire se sono stati aggiunti, rimossi o modificati token. In una pull request, può diventare un controllo utile per evitare regressioni nel design system.

Per esportare i token:

npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

Gli export sono importanti perché collegano DESIGN.md agli strumenti già usati dai team: Tailwind, CSS custom properties e formati compatibili con il mondo dei design token.

Un riferimento pratico da aggiungere al workflow è Stitch di Google, che consente di lavorare su interfacce e prototipi con un percorso orientato anche all’esportazione nel formato DESIGN.md. Questo rende il file ancora più interessante: non è solo una specifica da scrivere manualmente, ma può diventare un formato di passaggio tra progettazione visuale, generazione assistita e codice.

Le regole di linting più utili

La documentazione cita diverse regole di linting, tra cui riferimenti rotti, contrasto, assenza di colore primario, token orfani, sezioni mancanti, tipografia mancante e ordine delle sezioni.

Queste verifiche rendono DESIGN.md più serio di una semplice convenzione testuale. Un file può essere scritto male, ma la CLI permette di intercettare almeno una parte degli errori prima che arrivino nel codice generato.

Perché DESIGN.md interessa a chi lavora con AI coding agent

Il valore più evidente è per chi usa agenti AI nel frontend. Strumenti di coding assistito possono già generare componenti, landing page e layout, ma spesso hanno bisogno di contesto. DESIGN.md offre quel contesto in una forma leggera.

Un agente può leggere frasi come:

• “usa il colore primario solo per l’azione più importante”;
• “evita ombre pesanti, usa gerarchie tonali”;
• “mantieni radius da 4px per un aspetto tecnico”;
• “non usare più di due pesi tipografici nella stessa schermata”.

Queste indicazioni sono diverse dai token numerici. Sono regole di comportamento progettuale. Per un essere umano sono normali linee guida; per un agente diventano vincoli espliciti da seguire.

Differenze rispetto a tokens.json, Figma variables e Tailwind config

DESIGN.md non nasce per sostituire tutto. Un file tokens.json resta più adatto allo scambio formale di token tra strumenti. Figma variables restano fondamentali nel lavoro dei designer. Tailwind config resta centrale quando si implementa una UI con utility class.

La differenza è che DESIGN.md mette nello stesso posto token e razionale. Questo lo rende particolarmente adatto agli agenti, perché gli agenti non hanno bisogno solo di valori: hanno bisogno di contesto.

Per esempio, un token può dire che tertiary vale #B8422E; il testo può spiegare che quel colore è “Boston Clay” e che deve essere usato solo per interazioni primarie. Questa seconda informazione può fare la differenza tra una UI coerente e una UI tecnicamente corretta ma visivamente confusa.

Limiti attuali del formato

DESIGN.md è indicato come formato in stato alpha. Questo significa che lo schema, la CLI e le convenzioni potrebbero cambiare. È quindi intelligente adottarlo con aspettative realistiche.

I limiti più evidenti sono:

• la specifica è ancora giovane;
• la sezione componenti è flessibile e in evoluzione;
• non sostituisce test visivi, review di design o accessibilità manuale;
• richiede disciplina nella manutenzione;
• può diventare obsoleto se non viene aggiornato insieme al prodotto.

Detto questo, il formato è già utile per sperimentare un workflow più ordinato tra design system e AI coding.

Come introdurre DESIGN.md in un team

Il modo migliore non è provare a documentare tutto subito. Conviene partire da un file piccolo ma accurato.

Un percorso pratico può essere:

1. definire nome, descrizione e personalità del prodotto;
2. inserire palette primaria, secondaria, accento e neutral;
3. aggiungere 4-6 livelli tipografici realmente usati;
4. documentare spacing e radius principali;
5. descrivere 3 componenti critici: bottone primario, card e input;
6. scrivere 5 regole “do” e 5 regole “don’t”;
7. eseguire il lint e correggere gli errori;
8. usare il file in una singola feature generata con agenti AI;
9. confrontare output generato prima e dopo DESIGN.md.

Questo approccio evita il classico errore dei design system: puntare alla perfezione iniziale e non arrivare mai all’adozione reale.

SEO tecnico e opportunità per sviluppatori WordPress

Anche se DESIGN.md nasce per agenti di codice e design system, il tema è rilevante anche per chi lavora con WordPress, temi custom e page builder avanzati. Un file di questo tipo potrebbe aiutare a mantenere coerenza visiva quando si generano componenti, blocchi Gutenberg, pattern di tema o layout con strumenti AI.

Per esempio, un team WordPress potrebbe creare un DESIGN.md per descrivere:

• palette del brand;
• gerarchia tipografica del tema;
• spaziature dei blocchi editoriali;
• stile di card, bottoni e call to action;
• regole per landing page e template WooCommerce;
• vincoli di accessibilità e contrasto.

In futuro, agenti AI capaci di leggere DESIGN.md potrebbero generare pattern Gutenberg più coerenti, componenti React per block editor o CSS custom properties allineate alla brand identity. È un ponte naturale tra content management, frontend engineering e automazione.

Per approfondire il tema nel contesto WordPress, sono collegati due percorsi utili: una guida su AI per migliorare SEO, UX e design su WordPress e un approfondimento sui tool essenziali per il web design WordPress. Entrambi aiutano a collegare DESIGN.md a casi d’uso concreti: coerenza visiva, automazione dei layout, qualità UX e produzione di interfacce più controllabili.

FAQ

DESIGN.md è un file di configurazione ufficiale di Google?

È un progetto open source pubblicato nel repository Google Labs Code. La specifica è in fase alpha e propone un formato per descrivere visual identity e design system agli agenti di coding.

DESIGN.md sostituisce Figma?

No. Figma resta uno strumento visuale per progettare, discutere e prototipare. DESIGN.md aggiunge un formato testuale, versionabile e leggibile dagli agenti, utile dentro i repository di codice.

Qual è la differenza tra DESIGN.md e design tokens?

I design token definiscono valori come colori, font, spacing e radius. DESIGN.md può contenere quei token, ma aggiunge anche spiegazioni in Markdown, cioè il razionale che aiuta gli agenti a capire come applicarli.

Si può usare DESIGN.md con Tailwind?

Sì. La CLI documenta export verso Tailwind v3 in JSON e Tailwind v4 tramite CSS @theme, oltre al formato DTCG per design token.

È pronto per la produzione?

È utilizzabile per sperimentazioni e workflow interni, ma va considerato un formato alpha. Prima di inserirlo in processi critici, conviene testarlo su un progetto pilota e monitorare l’evoluzione della specifica.

Conclusione

DESIGN.md è interessante perché affronta un problema reale: gli agenti AI possono scrivere codice, ma senza una memoria progettuale rischiano di generare interfacce incoerenti. Un file testuale, versionabile e validabile può diventare il ponte tra design system, frontend e automazione.

Il valore non sta solo nei token, ma nel contesto: colori con significato, tipografia con ruolo, componenti con stati, regole pratiche e divieti espliciti. Per chi lavora con AI coding agent, design system o sviluppo WordPress avanzato, DESIGN.md è un formato da osservare subito e da testare in un piccolo progetto reale.

Il consiglio pratico è semplice: crea un primo DESIGN.md con pochi token affidabili, aggiungi rationale chiaro, esegui il lint e usalo come contesto per un agente AI. La differenza nella coerenza dell’output diventa evidente appena il progetto supera la singola pagina dimostrativa.