Cos'è DESIGN.md? Il file di design letto dagli agenti di coding IA (con esempi di app mobile gratuiti)

DESIGN.md è un file Markdown che descrive l'identità visiva di un prodotto per gli agenti di coding IA. Il formato di Google Labs unisce token di design YAML opzionali a indicazioni scritte su come utilizzarli. Offre all'agente regole concrete su colori, tipografia, spaziatura e componenti da leggere prima di generare un'interfaccia.

Per chi sviluppa app mobile, l'aspetto più utile è poter trasferire queste scelte nelle schermate successive. Inizia con un file dalla nostra libreria gratuita di DESIGN.md per mobile, analizza le schermate corrispondenti e adatta le regole alla tua app.

Chi ha creato DESIGN.md?

Google Labs pubblica il formato DESIGN.md utilizzato da Stitch. Google ha introdotto l'importazione e l'esportazione di DESIGN.md nel suo annuncio su Stitch di marzo 2026, per poi rendere open source la bozza delle specifiche ad aprile. Il repository ufficiale indica ancora il formato come alpha, quindi è bene verificare le specifiche attuali quando si sviluppa un'integrazione.

Un file chiamato DESIGN.md può anche essere un normale documento di progetto. Quando ne condividi uno, specifica quale formato utilizza e mantieni il testo grezzo accessibile per la consultazione.

Cosa contiene un file DESIGN.md?

Le specifiche di Google Labs descrivono un corpo in Markdown con frontmatter YAML opzionale. I gruppi di token coprono colori, tipografia, angoli arrotondati, spaziatura e componenti. Il corpo del testo spiega decisioni come la collocazione di un colore di accento o la differenza visiva tra pulsanti e schede. Valori precisi e indicazioni scritte svolgono ruoli diversi.

Le specifiche accettano stringhe di colore CSS, inclusi i valori esadecimali. Racchiudi i colori hex tra virgolette in YAML: un cancelletto senza virgolette avvia un commento. Un riferimento come {colors.primary} punta a un altro token nel file. La libreria di Sleek mostra campioni esadecimali accanto al testo originale, permettendoti di verificare la palette prima di scaricarla.

Come si presenta un esempio essenziale di DESIGN.md?

Un file DESIGN.md iniziale può descrivere un piccolo sistema visivo: una palette, uno stile per il testo, un valore di spaziatura e un pulsante. L'esempio seguente è stato preparato per questa guida. Salvalo come DESIGN.md, poi aggiungi regole in base alle esigenze della tua app mobile. Si tratta di un punto di partenza, non di una libreria di componenti definitiva.

---
version: alpha
name: Quiet Blue Mobile
colors:
  primary: "#2459C4"
  on-primary: "#FFFFFF"
  surface: "#FAF8F3"
  on-surface: "#20242B"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
rounded:
  md: 12px
spacing:
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
    padding: "{spacing.md}"
---
## Overview
A quiet mobile interface with cream surfaces and blue actions.

## Colors
Use primary for actions. Keep reading surfaces cream.

## Typography
Use body-md for reading text. Keep labels short.

## Layout
Use spacing.md for screen gutters and related content groups.

## Shapes
Use rounded.md on cards and buttons.

## Components
Primary buttons use button-primary. Keep one main action per view.

## Do's and Don'ts
Keep text readable at larger system font sizes.
Do not use color as the only signal for an error.

Verifica le tue aggiunte con il comando di lint del repository. I suoi report ti aiutano a individuare riferimenti interrotti e problemi di contrasto tra le coppie di colori. È comunque necessario controllare la schermata generata: un file di testo non può mostrarti un'etichetta tagliata, un controllo poco chiaro o una tastiera che copre un modulo.

npx @google/design.md lint DESIGN.md

Come si usa DESIGN.md con Claude Code?

Tieni DESIGN.md nel progetto e chiedi a Claude Code di leggerlo per le attività sull'interfaccia. La documentazione sulla memoria di Anthropic spiega che le importazioni di CLAUDE.md vengono caricate all'avvio della sessione. Usa un semplice riferimento al percorso per la lettura su richiesta, oppure una regola in .claude/rules/ con pattern paths che corrispondano ai file dell'interfaccia.

Per esempio, aggiungi questa istruzione a CLAUDE.md senza un'importazione con @:

For UI tasks, read DESIGN.md before creating or changing app screens.

Successivamente, richiedi una schermata specifica e i relativi stati: ad esempio, un elenco di attività con uno stato vuoto e uno stato di errore di sincronizzazione. Controlla se l'interfaccia generata rispetta i valori del file e aggiorna il file ogni volta che modifichi intenzionalmente il design. La nostra guida al design con Claude approfondisce l'intero flusso di lavoro.

Come si usa DESIGN.md con Cursor o Stitch?

In Cursor, allega esplicitamente DESIGN.md alla richiesta oppure fa' riferimento al file all'interno di una regola di progetto. In Stitch, utilizza il flusso di importazione ed esportazione di DESIGN.md per trasferire le regole di design da un progetto all'altro. La differenza è importante: un agente di coding ha bisogno del file nel suo contesto, mentre Stitch offre un flusso di lavoro integrato attorno a questo formato.

Per Cursor, la documentazione sulle regole illustra le regole di progetto e i riferimenti ai file. Una regola può istruire l'agente a consultare DESIGN.md per le modifiche all'interfaccia. Definisci con attenzione quando applicare la regola, così da evitare di includere un lungo documento di design nelle attività di backend non correlate.

Per quanto riguarda Stitch, l'annuncio di Google su DESIGN.md conferma la possibilità di importare ed esportare regole di design tra i vari progetti. Dopo l'importazione, confronta la schermata generata con il file sorgente e modifica le regole dove necessario.

In che modo Sleek utilizza DESIGN.md per gli stili delle app mobile?

Sleek associa un file di design a ciascun progetto in evidenza riutilizzabile. Quando selezioni Usa questo stile e descrivi la tua app, Sleek invia quel file insieme al tuo brief al processo di generazione. Il file definisce l'estetica; il brief determina lo scopo e i contenuti dell'app. Puoi analizzare sia le schermate sia il file prima di procedere.

La galleria dei riferimenti e la libreria di DESIGN.md utilizzano gli stessi progetti in evidenza. Sleek usa la struttura di Google Labs e aggiunge proprietà dei componenti come bordi e ombre, che il linter segnala come avvisi. Aggiunge anche indicazioni per iconografia, illustrazioni, gerarchia visiva e dettagli distintivi. Il file di stile raccoglie le scelte visive per generare una nuova app.

Apri uno stile nella libreria per copiarne o scaricarne il file DESIGN.md, oppure scegli Use this style in Sleek per inserire la tua idea di app. Se desideri gestire Sleek direttamente dal tuo ambiente di sviluppo, la guida alla configurazione dell'agente ne illustra l'integrazione separata.

FAQ su DESIGN.md