agid-llm-ui — un design system LLM-first per la PA italiana

LLM-first: un esperimento per aiutare gli assistenti AI (Claude, Cursor, Copilot…) a generare interfacce della PA più vicine alle linee guida di design AgID, cercando di tenere conto dell'accessibilità. I componenti e i materiali per gli LLM sono generati da un'unica fonte machine-readable.

LLM-first — an experiment to help AI assistants generate Italian-PA UIs closer to the AgID design guidelines. Components and LLM-facing materials are generated from a single machine-readable spec.

<!-- Dopo il primo push, abilita anche il badge CI: -->

🔗 Galleria + demo (GitHub Pages): https://andreaderuvo.github.io/agid-llm-ui/ · home di un Comune generata col design system

---

Da dove nasce

Il punto di partenza sono alcune caratteristiche di Bootstrap Italia (il design system ufficiale della PA), osservate senza pretese:

• il design e l'accessibilità sono ottimi, ma il markup è verboso e molte regole stanno nella documentazione, non nei componenti;
• i vari kit di framework (React, Angular, web components) sono mantenuti a mano, senza un'unica fonte machine-readable, quindi tendono a rincorrere;
• gli assistenti AI non conoscono Bootstrap Italia e spesso generano markup generico e non conforme.

Questo progetto è un esperimento per provare un approccio diverso: descrivere i componenti in una spec machine-readable e generare da lì gli artefatti — inclusi quelli che aiutano un LLM a produrre UI più conformi. Non pretende di essere completo né una soluzione definitiva: è un punto di partenza aperto ai contributi.

Come funziona, in breve: da sota/spec/ un piccolo codegen produce i Web Components (con l'accessibilità e il comportamento — focus, tastiera, stato — gestiti da macchine a stati Zag.js), i wrapper tipizzati, il CSS dai token, la documentazione, i contratti di validazione, la galleria e i dati per il server MCP. Cambiando la spec, gli artefatti si riallineano.

Note più estese: VISION.md.

⚠️ Progetto community, non ufficiale. Non affiliato né approvato da AgID o Designers Italia. Costruito sopra Bootstrap Italia (licenza BSD-3-Clause) nel rispetto della relativa attribuzione. "AgID" è usato solo in senso descrittivo; il prefisso it- è provvisorio.

🤖 Realizzato in gran parte in vibe coding, insieme a un assistente AI — coerente con lo spirito LLM-first del progetto. Da leggere e verificare con spirito critico, non come codice "pronto per la produzione".

Perché è più integrabile con gli LLM dei kit AgID originali

I kit ufficiali (Bootstrap Italia, design-react-kit…) sono pensati per sviluppatori umani. Rispetto a quelli, qui l'LLM parte avvantaggiato per ragioni concrete:

1. La conoscenza arriva all'LLM in forma machine-readable. MCP, llms.txt e i contratti mettono componenti e regole nel contesto del modello. I kit originali hanno solo documentazione per umani: l'LLM deve "ricordarsela" e spesso sbaglia.
2. Molto meno boilerplate. <it-dialog> è un tag; l'equivalente in Bootstrap Italia sono ~20 righe di div annidati con classi. Meno token da generare = meno errori.
3. Accessibilità incapsulata (corretta per costruzione). L'LLM non può "dimenticare" gli ARIA/focus/tastiera: li fornisce il componente (macchine Zag). Col markup grezzo l'a11y è convenzione, e i modelli la perdono.
4. Un solo tag, tutti i framework. <it-…> funziona in React/Vue/Angular/HTML: l'LLM non deve scegliere fra react-kit, angular-kit o vanilla.
5. Loop di verifica. validate_snippet fa autocorreggere l'LLM contro il design system — non esiste nei kit originali.

In una riga: i kit originali si possono usare con un LLM, ma glielo devi spiegare ogni volta; qui la spiegazione è integrata e verificabile.

Per chi sviluppa — cosa devi fare, in pratica

Scegli lo scenario che ti riguarda.

A) Voglio che l'AI mi generi UI conformi (Cursor, Claude, VS Code…)

1. Builda una volta:

   git clone https://github.com/andreaderuvo/agid-llm-ui.git
   cd agid-llm-ui && npm install && npm run build
   

2. Collega il server MCP al tuo editor → vedi Usare il server MCP.
3. Chiedi in italiano, es. «pagina di un servizio comunale conforme ad AgID con un form e una tabella». L'assistente usa i tool e genera markup conforme, preferendo i tag <it-…>.

B) Voglio solo i componenti nel mio sito/app (anche senza AI)

I componenti sono Web Components: HTML puro, funzionano in React, Vue, Angular o HTML.

npm install && npm run build && node sota/codegen.mjs
# poi prendi da sota/dist/ : it-tokens.css, it-components.js, it-behavioral.bundle.js

Nella tua pagina:

<link rel="stylesheet" href="it-tokens.css">
<script defer src="it-components.js"></script>
<script defer src="it-behavioral.bundle.js"></script>

<it-button variant="success">Invia</it-button>
<it-dialog trigger="Apri" title="Conferma">Vuoi procedere?</it-dialog>
<it-datatable page-size="10" searchable> …una &lt;table&gt; nativa… </it-datatable>

ℹ️ Pubblicazione su npm/CDN: prevista, non ancora fatta. Per ora si builda in locale e si prendono i file da sota/dist/.

C) Uso OpenAI o un altro strumento

• Se parla MCP (OpenAI Agents SDK / Responses API, VS Code Copilot…): fai come in A.
• Altrimenti: usa i componenti come in B e passa sota/dist/llms.txt come contesto all'LLM.

Non sai da dove partire? Apri la galleria sota/dist/index.html: per ogni componente trovi anteprima dal vivo, props e codice da copiare.

Cosa contiene

• 49 componenti verificati (render + accessibilità), ~20 interattivi su Zag (dialog, menu, select, combobox, datepicker, tabs, toast, steps, slider, datatable…) + presentazionali (card, table, header, footer, breadcrumb…).
• Server MCP con 9 tool — serve sia il markup Bootstrap Italia grezzo (v1) sia i Web Components AI-first (v2):

Tool	A cosa serve
list_components / search_component / get_component_code	Componenti Bootstrap Italia (markup + a11y)
list_recipes / get_page_recipe	Ricette di pagina dei modelli PA
get_accessibility_rules	Regole WCAG 2.1 AA / AgID
list_webcomponents / get_webcomponent	Componenti AI-first universali (consigliati)
validate_snippet	Valida uno snippet e suggerisce i tag conformi (loop di autocorrezione)

Architettura: una fonte → tutti gli artefatti

sota/spec/  (design token DTCG + manifest dei componenti = fonte unica)
   │  node sota/codegen.mjs
   ├─ Web Components (a11y incapsulata, Zag dentro)
   ├─ wrapper React tipizzati
   ├─ CSS dai token
   ├─ llms.txt            (doc per LLM)
   ├─ contracts.json      (validazione → MCP)
   ├─ galleria (GitHub Pages)
   └─ dati per il server MCP

Dettagli: VISION.md.

Installazione

git clone https://github.com/andreaderuvo/agid-llm-ui.git
cd agid-llm-ui
npm install
npm run build            # compila il server MCP
node sota/codegen.mjs    # genera componenti, galleria, llms.txt, contratti

Usare il server MCP

MCP è uno standard aperto: questo server funziona con qualsiasi client compatibile — Claude (Desktop/Code), Cursor, VS Code (GitHub Copilot agent), Windsurf, Cline, Zed, JetBrains AI… Non è legato a un solo editor.

Provalo con l'Inspector:

npm run inspect

Claude Code:

claude mcp add agid-llm-ui -- node /percorso/assoluto/agid-llm-ui/dist/index.js

Cursor / Claude Desktop / altri client — aggiungi al file di configurazione MCP:

{
  "mcpServers": {
    "agid-llm-ui": {
      "command": "node",
      "args": ["/percorso/assoluto/agid-llm-ui/dist/index.js"]
    }
  }
}

Poi, nell'editor: «Crea una pagina di un servizio comunale conforme ad AgID» → l'assistente usa i tool e genera markup conforme, preferendo i Web Components.

Galleria in locale: apri sota/dist/index.html (o servila con un web server statico).

Contribuire

Aggiungere un componente presentazionale = un file spec (sota/spec/components/*.json). Uno interattivo = una macchina Zag + un piccolo Web Component. Vedi CONTRIBUTING.md.

Roadmap

• [x] Catalogo Bootstrap Italia (~50 componenti)
• [x] validate_snippet (loop di conformità)
• [x] llms.txt generato dalla spec
• [x] Galleria + demo (mini-sito comunale) su GitHub Pages
• [x] Selettore lingua IT/EN (i18n) e color theming live
• [x] Demo PWA (installabile / offline)
• [ ] Componenti mancanti: input-ora, transfer, cookiebar, video-player
• [ ] Rules pack (.cursor/rules, AGENTS.md) + registry.json (shadcn)
• [ ] Adapter Vue / Angular / Svelte generati dalla spec
• [ ] render_check (screenshot headless → verifica visiva) nel loop MCP
• [ ] Submission al catalogo Developers Italia

Riferimenti

Bootstrap Italia · Designers Italia · Zag.js · Model Context Protocol

Licenza

EUPL-1.2 — la licenza raccomandata per il software della PA europea.