Document

Quando usarlo

Esegui /impeccable document una volta che hai abbastanza sistema visivo da documentare: colori, tipografia, almeno un pulsante e una card. Il comando analizza il tuo codebase, estrae i token e i pattern dei componenti che trova, e scrive un DESIGN.md alla root del progetto che segue il formato Google Stitch DESIGN.md, sei sezioni in un ordine fisso, interoperabile con ogni altro tool compatibile con DESIGN.md.

Ricorri a document quando:

• Hai appena eseguito /impeccable teach e PRODUCT.md ora esiste. Document è il file visivo corrispondente.
• Un comando ti ha spinto verso di esso. Live, craft e polish leggono tutti DESIGN.md. Se manca, la skill suggerisce di eseguire document prima.
• Il design ha derivato da un DESIGN.md più vecchio e il file non descrive più il sistema live.
• Prima di un grande redesign, per catturare lo stato attuale come riferimento per la prossima direzione.

Per progetti senza ancora codice (esecuzione teach fresca, nulla di costruito), c’è una modalità seed: /impeccable document --seed fa cinque rapide domande strategiche (strategia colore, direzione tipo, energia del movimento, riferimenti, anti-riferimenti) e scrive uno scaffold. Esegui di nuovo in modalità scan una volta che c’è codice.

Come funziona

Il passaggio di scansione trova gli asset di design in ordine di priorità: CSS custom properties, configurazione Tailwind, temi CSS-in-JS, file di design token, sorgente dei componenti, il foglio di stile globale e infine gli stili calcolati dall’output renderizzato live se un browser è disponibile. Estrae automaticamente tutto ciò che può, poi fa una domanda raggruppata per le parti che richiedono input creativo: la Stella Polare Creativa (una singola metafora nominata per l’intero sistema, come “Il Santuario Editoriale”), nomi di colore descrittivi, la filosofia di elevazione e il carattere dei componenti.

L’output è un DESIGN.md con esattamente sei sezioni: Panoramica, Colori, Tipografia, Elevazione, Componenti, Da fare e Non fare. Le intestazioni sono fisse carattere per carattere così il file è analizzabile da altri strumenti. Insieme ad esso, DESIGN.json viene scritto come sidecar leggibile dalla macchina. Quel sidecar è ciò che il pannello design della live mode usa per renderizzare i tile di pulsante, input, nav e card di questo progetto anziché un’approssimazione generica.

Ogni altro comando legge DESIGN.md all’invocazione. Varianti, polish, audit e nuove funzionalità ereditano il sistema visivo senza che venga detto.

Provalo

/impeccable document

Su un progetto con token già definiti, questo richiede circa due minuti: la scansione trova la tua palette e lo stack tipografico, scegli una Stella Polare tra 2 o 3 opzioni, confermi i nomi descrittivi dei colori (“Deep Muted Teal-Navy”, non “blue-800”) e il file atterra alla root del progetto.

Su un progetto nuovo:

/impeccable document --seed

Cinque domande, circa cinque minuti. Il file è uno scaffold, marcato con un commento <!-- SEED --> così è onesto su cosa è. Esegui di nuovo senza il flag una volta che hai implementato i token.

Insidie

• Eseguirlo troppo presto. Su un progetto senza token implementati, la modalità seed è quella giusta. Non fabbricare una specifica completa che il codice non può supportare. Un DESIGN.md falso è peggio di nessun DESIGN.md.
• Trattare DESIGN.md come documentazione solo per umani. È principalmente per l’IA. Ogni altro comando lo legge. La rigidità del formato (“mai”, “sempre”, Regole Nominate) è intenzionale.
• Aggiungere una sezione di primo livello Layout / Movimento / Responsive. La specifica ha sei sezioni, in un ordine fisso, con nomi fissi. Ripiega il contenuto di layout o movimento in Panoramica (regole a livello di filosofia) o Componenti (comportamento per componente).
• Sovrascrivere un DESIGN.md esistente senza avviso. Document conferma sempre prima. Se vuoi ricominciare da zero, rinomina il file esistente o dì esplicitamente alla skill di sovrascrivere.