awesome-design-md: design system in Markdown per agenti AI

Cos'è awesome-design-md

VoltAgent ha pubblicato awesome-design-md, un repository open source (MIT) che raccoglie file DESIGN.md estratti dai siti di aziende come Stripe, Vercel, Airbnb, Linear, Notion e altre 40+. Ogni file contiene token di design — colori, tipografia, spaziatura, componenti — in formato Markdown. L'agente AI li legge e genera interfacce visivamente coerenti con il brand originale senza bisogno di Figma, JSON o configurazioni particolari.

Il concetto di DESIGN.md nasce da Google Stitch, uno strumento per la generazione di UI tramite AI. L'idea è semplice: il Markdown è il formato che i modelli di linguaggio leggono meglio. Un file di testo strutturato batte qualsiasi schema proprietario in termini di portabilità e comprensione da parte di un LLM.

Il progetto ha già superato le 13.500 stelle su GitHub, con 1.700 fork e 63 watcher. Scritto interamente in HTML (per le preview), pesa pochi KB per file.

Come funziona in pratica

Ogni sito nella raccolta include tre file:

• DESIGN.md — il documento principale con palette colori, scale tipografiche, spaziatura, raggi dei bordi, ombre e componenti UI
• preview.html — anteprima visiva del design system in modalità chiara
• preview-dark.html — anteprima in modalità scura

Il flusso di utilizzo è diretto. Si copia il DESIGN.md del sito desiderato nella root del proprio progetto e si chiede all'agente AI di costruire l'interfaccia seguendo quelle specifiche. Funziona con qualsiasi agente che legga il contesto del progetto: Claude Code, Cursor, Gemini CLI, Copilot.

La raccolta è organizzata in categorie:

• AI & ML — Claude, Mistral AI, Ollama, Replicate, ElevenLabs, xAI
• Developer Tools — Cursor, Vercel, Supabase, Linear, Sentry, Warp, Raycast
• Infrastructure — Stripe, ClickHouse, MongoDB, HashiCorp
• Design & Productivity — Figma, Notion, Framer, Miro, Webflow
• Fintech — Coinbase, Revolut, Kraken, Wise
• Enterprise — Apple, BMW, SpaceX, Spotify, Uber, NVIDIA

Ogni DESIGN.md segue il formato definito dalla documentazione di Google Stitch, con sezioni estese per coprire anche componenti specifici del sito.

Perché è utile e dove ha limiti

Il vantaggio principale è la velocità di prototipazione. Invece di partire da zero o fotografare un sito e sperare che l'AI lo replichi, si fornisce un documento strutturato con token esatti. I valori CSS sono quelli reali, estratti dai siti pubblici.

Per gli agenti AI questo è un contesto molto più efficace di uno screenshot. Un'immagine è ambigua — il Markdown no. Specifiche come border-radius: 12px, font-weight: 500, color: #635BFF non lasciano margine di interpretazione.

I limiti sono evidenti. I design system estratti sono istantanee statiche di siti che evolvono continuamente. Stripe potrebbe cambiare la sua palette domani e il DESIGN.md nel repository resterebbe obsoleto. Inoltre, catturare token CSS non significa catturare l'intera esperienza utente — animazioni, micro-interazioni e logica di layout responsivo non sempre emergono da un file Markdown.

C'è anche una questione di proprietà intellettuale. Il repository dichiara esplicitamente di non rivendicare alcuna identità visiva altrui, e i token sono valori CSS visibili pubblicamente. Ma usare il design system di Stripe per costruire un prodotto che sembra Stripe solleva interrogativi legittimi.

Contribuire è semplice: basta aprire una issue su GitHub con il template dedicato per richiedere la generazione di un nuovo DESIGN.md.

FAQ

Serve Google Stitch per usare i file DESIGN.md? No. Qualsiasi agente AI che legga file Markdown dal contesto del progetto può usarli — Claude Code, Cursor, Copilot, Gemini CLI.

I design token sono aggiornati? Sono estratti una tantum dai siti pubblici. Possono diventare obsoleti se il sito aggiorna il proprio design system.

Posso contribuire con il DESIGN.md di un sito non ancora presente? Sì, il repository accetta contributi. Va aperta prima una issue per discutere la proposta con i maintainer.