Design-Canvas
Du entwirfst Bildschirme als echte HTML-Dateien innerhalb des Projekts und zeigst sie im lokalen Design-Viewer an. Der Benutzer sieht jeden Bildschirm nebeneinander, wechselt Gerätegröße und Licht/Dunkel-Theme, exportiert PNG und kommentiert einen Bildschirm; Kommentare kommen als Chat-Nachrichten mit einem exakten Präfix zu dir zurück.
Dateien (der Vertrag)
design/
tokens.json die einzige Quelle der Wahrheit für jedes Design-Token
(beide Themes); der einzige Ort, an dem Markenwerte leben
design-system.css GENERIERT aus tokens.json: Design-Tokens für
[data-theme="light"] und [data-theme="dark"] (niemals bearbeiten)
utilities.css GENERIERT aus tokens.json: das geschlossene Utilities-
Vokabular (niemals bearbeiten)
design-system.md Markenentscheidungen in Worten (kurz)
validate.mjs der Validator (einmal pro Projekt kopiert – siehe Einrichtung)
serve.mjs winziger statischer Server für den Viewer (einmal pro Projekt kopiert)
viewer.html der Viewer (einmal pro Projekt kopiert)
mock.js Mock-Laufzeitumgebung für interaktive Bildschirme (einmal pro Projekt kopiert)
mock.css statische Styles für die Mock-Laufzeit-Klassen (einmal pro Projekt kopiert)
– Toast-, Overlay-, Enter-Transition-Status;
Bildschirme verlinken es als `../mock.css`; mock.js schaltet
nur diese Klassen um und injiziert niemals CSS
scripts/ einmal pro Projekt kopiert (siehe Einrichtung)
gen-tokens.mjs regeneriert design-system.css + utilities.css aus
tokens.json
sync-components.mjs materialisiert jede Komponenten-Markierungsregion aus ihrem
Partial neu (einmal pro Projekt kopiert)
marker-parser.mjs der gemeinsam genutzte Marker-Grammatik-Parser, den sync bei
Laufzeit importiert (einmal pro Projekt kopiert)
components/ Komponenten-Registry + Partial-Saat (einmal pro Projekt kopiert):
components.json + ein Partial pro Komponente
vendor/html-to-image.js PNG-Export-Bibliothek (einmal pro Projekt kopiert)
index.json {"canvases": ["login", ...]} damit der Viewer sie auflisten kann
<canvas>/ ein Ordner pro Canvas, Kebab-Case (login, dashboard)
canvas.json
data.json optionale fiktive Daten; optionales "scenarios"-Objekt
mit benannten Top-Level-Überschreibungen (leer, kritisch…)
01-<screen>.html ein vollständiges HTML-Dokument pro Bildschirm
assets/ optionale lokale Bilder/Skripte
canvas.json (Bildschirme erscheinen in dieser Reihenfolge):
{
"title": "Login do app",
"screens": [
{ "id": "login", "name": "Login", "file": "01-login.html", "device": "mobile" },
{ "id": "cadastro", "name": "Cadastro", "file": "02-cadastro.html", "device": "mobile" }
]
}
device:mobile= 390×844,tablet= 834×1112,desktop= 1440×900; optionalwidth/height(Integer 100–10000) überschreiben es.group(optional): Bezeichnung, die die Bildschirme in titelierte Blöcke im View- Strip gruppiert – komplexe Projekte bleiben lesbar (z.B."group": "Checkout").transition(optional):fade,slide-leftodernone(Standard). Es ist die Eingangsanimation des Bildschirms nachMock.go– siehe Arbeitsablauf Schritt 3 für die Regel gleiches Canvas/übergreifendes Canvas.ideindeutig und nicht leer;namenicht leer;titleoptional.fileist relativ zum Canvas-Ordner: niemals.., führendes/,\oder ein Schema (http:,file:…).
Einmalige Einrichtung pro Projekt
Wenn design/ noch nicht existiert, erstelle es und kopiere aus dem Ordner dieser Fähigkeit (dem Ordner, der diese SKILL.md enthält):
scripts/validate.mjs→design/validate.mjsassets/viewer.html→design/viewer.htmlassets/serve.mjs→design/serve.mjsassets/mock.js→design/mock.jsassets/mock.css→design/mock.css(Styles für die Mock-Laufzeit-Klassen; Bildschirme verlinken../mock.css)assets/docs.html→design/docs.html(Nutzungsanleitung, verlinkt über die 📘 Docs-Schaltfläche des Viewers)assets/vendor/html-to-image.js→design/vendor/html-to-image.jsscripts/gen-tokens.mjs→design/scripts/gen-tokens.mjsassets/components/→design/components/(Registry + Partial-Saat)scripts/sync-components.mjs→design/scripts/sync-components.mjsscripts/marker-parser.mjs→design/scripts/marker-parser.mjs(der gemeinsam genutzte Parser-Modul-Sync-Import, der zur Laufzeit benötigt wird)scripts/export-tokens.mjs→design/scripts/export-tokens.mjs(der W3C/DTCG-Austausch- Export: tokens.json → tokens.w3c.json; abgeleitetes Artefakt, niemals von Hand bearbeitet)
Regel für diese Kopierliste: nur Dateien, die bereits existieren, kommen hinein ("só entra no copy list arquivo que já existe"). Dateien, die noch kommen, treten erst bei ihrer Contract-Welle bei: export-tokens.mjs trat bei Contract-Welle 6 (todo 30) bei und ist oben aufgeführt – die Regel ist erfüllt (die Datei existiert seit todo 26). (mock.css trat bei Welle 3 bei und ist oben aufgeführt.)
Wann immer tokens.json geändert wird, generiere die beiden generierten Dateien aus dem Projektstammverzeichnis neu:
node design/scripts/gen-tokens.mjs
Erstelle design/index.json ({"canvases": []}) und füge jeden neuen Canvas-Namen hinzu, wenn du Canvases erstellst. Ein vollständiges, gültiges Beispiel befindet sich im assets/example/ dieser Fähigkeit – ein funktionierendes Aktien-App-System über zwei Canvases hinweg:
login/ (Login, Registrierung und ein Bestätigungsmodal zum Löschen des Kontos, das als Overlay über einen einfachen Link geöffnet wird) und dashboard/ (interaktive Übersicht mit einer langen Artikelliste, einer canvas-internen "Liste aktualisieren"-Auffrischung, die die fade-Transition und das Wiederherstellen der Scroll-Position demonstriert), wobei Login und Registrierung canvas-übergreifend zur Übersicht navigieren, die ihre fiktiven Artikel liest, benannte Szenarien unterstützt und zurück zum Login-Canvas ausloggt. Lies es, bevor du ein neues Designsystem oder Canvas beginnst, und passe es an. Die Beispiel example/components/ ist eine byteidentische Kopie von assets/components/ ("example/components/ ist byteidentische Kopie von assets/components/ (einzige Quelle)"): bearbeite Partial nur in assets/components/, niemals in der Beispielkopie.
Arbeitsablauf
- Zuerst das Designsystem. Lies
design/design-system.cssunddesign/design-system.md. Wenn sie nicht existieren, frage den Benutzer nach der Marke (Primärfarbe, Schriftartgefühl, Ton; biete eine neutrale Palette als eine Option an), erstelle dann beide. Spätere Canvases verwenden sie wieder. Ändere die Tokens nur, nachdem du gefragt hast. - Frage nur nach dem, was fehlt. Wenn die Anfrage vage ist (welche Bildschirme, welche Plattform, welche Daten), frage einmal; wenn sie klar ist, beginne.
- Erstelle den Canvas. Lies zuerst
assets/craft.mdaus dem Ordner dieser Fähigkeit (es vereint die verwandten Craft-Fähigkeiten – taste, emil-design-eng, impeccable – zu Regeln für Canvas-Bildschirme) und wende es auf jeden Bildschirm an. Erstelle danncanvas.jsonund die Bildschirme. Regeln für jeden Bildschirm:- Styling-Richtlinie: Das Utilities-Vokabular ist das Vokabular. Alles, was auf Tokens
basiert (Farben, Typografie, Abstände, Radius), wird durch die generierten Utilities
realisiert: verlinke
<link rel="stylesheet" href="../design-system.css">und<link rel="stylesheet" href="../utilities.css">, verwende dann Klassen wiebg-accent,p-2,text-heading,rounded-md. Interaktive Bildschirme verlinken auch<link rel="stylesheet" href="../mock.css">(die Mock-Laufzeit-Klassen: Toast, Overlay, Enter-Transitionen). Semantische Klassen tragen nur Struktur und Layout.var(--…)bleibt erlaubt, wo kein Utility passt, und ein Inline-<style>-Block ist erlaubt, darf aber NULL wörtliche Farben enthalten. Der Verbots-Durchlauf scannt wörtliche Farben in<style>,style=""und den WERT-Positionen von SVGfill=/stroke=; er verbietet auchhttp(s)://irgendwo in Bildschirmen, Tailwind-Palettenklassen wiebg-zinc-900und beliebige Werte wietext-[13px]. - Arbeite in beiden Themes durch die Tokens; das Theme kommt als
data-themeauf<html>(lightstandardmäßig – füge das Attribut hinzu). - Kein CDN oder Remote-URL jeglicher Art (der Canvas ist offline und in einer Sandbox):
Inline-SVG-Symbole, Systemschriftarten oder Schriftartdateien unter
design/, lokale Bilder. - Echter Text in der Sprache des Benutzers (standardmäßig brasilianisches Portugiesisch) und plausible Beispieldaten – kein Lorem Ipsum.
- Leere, Lade- und Fehlerzustände abdecken, wenn sie relevant sind, als zusätzliche Bildschirme.
- Grundlegende Barrierefreiheit: Labels auf Eingaben, sichtbarer Fokus, ausreichender Kontrast, Touch-Ziele ≥ 44px auf Mobilgeräten.
- Das Layout muss bei der Bildschirmbreite des Geräts halten.
- Komponenten sind Instanzen von Partial, niemals lose Komponenten-Markups
("Instanz verwendet Partial, niemals loses Komponenten-Markup"). Umfasse jede Instanz
mit dem Marker-Paar
<!-- component:id size=md tone=primary state=default -->…<!-- /component:id -->mit den DREI erforderlichen Argumentensize=,tone=,state=(Werte müssen in den Registry-Enums vondesign/components/components.jsonsein) und fülle ihre Slots als gepaarte Marker<!-- slot:name -->…<!-- /slot:name -->. Vorrang: Marker-Argumente sind die Quelle der Wahrheit (Marker-Args gewinnen). Der Sync gibtdata-size/data-tone/data-stateund die Varianten-Klassen aus dem Marker bei jedem Lauf neu aus; Slot-Inhalte und benutzerdefinierte zusätzlichedata-*-Attribute auf der Wurzel bleiben erhalten. - Es als Systemvorschau, nicht als Poster gestalten. Wenn die Anfrage ein
funktionierendes Produkt impliziert, verbinde die Bildschirme mit der Mock-Laufzeit
(
<script src="../mock.js"></script>, durch Einrichtung kopiert): Formulare validieren und senden, Schaltflächen geben Feedback, Bildschirme navigieren mitMock.go('03-dashboard.html'), fiktive Daten leben imdata.jsondes Canvas (await Mock.data('items')), Fluss-Status (eingeloggter Benutzer, erstellte Elemente) lebt inMock.state(Sitzung, pro Canvas namensbereichbezogen) und simulierte Aktionen bestätigen mitMock.toast('…'). Jeder Bildschirm muss trotzdem als statische Komposition rendern, wenn JS fehlschlägt. Der Viewer zeigt eine ↺ Anfang-Schaltfläche auf Karten, die navigiert haben, und "⟲ Fluss zurücksetzen", um den gesamten Fluss neu zu starten. Decke die Zustände ab, die wichtig sind, als benanntescenariosindata.json(Top-Level-Überschreibungen, z.B."vazio": {"items": []}) – der Viewer erhält einen Selektor dafür, die Auswahl überlebt die Navigation, und jedes Szenario muss gut funktionieren (leere Liste, alle Elemente unter Minimum, API-Fehler). Ein System kann sich über mehrere Canvases erstrecken (einer pro Fluss): navigiere zwischen ihnen mitMock.go('../<canvas>/<screen>.html')– der Fluss-Status wird projektweit geteilt, sodass der Login-Canvas den Benutzer setzt und der Dashboard-Canvas ihn liest. Der Canvas-Selektor des Viewers springt zwischen Canvases (jeder Canvas behält sein eigenes Szenario, Theme und Gerät). Modale und Bestätigungsdialoge sind auch vollständige Canvas-Bildschirme (eine Quelle der Wahrheit): der Auslöser ist ein einfacher Bildschirmlink,<a href="03-modal.html">, den die Mock-Laufzeit inMock.overlay('03-modal.html')umwandelt – ohne JS navigiert der unbearbeitete href zum Modal-Bildschirm selbst (der JS-aus-Fallback). Beständige Navigation (Sidebar, Top-Menü, Tabs) muss Bildschirme wirklich wechseln: setzedata-go="02-cadastro.html"auf jedes Element (behalte einen echtenhref="02-cadastro.html"auf demselben Link als JS-aus-Fallback – die Laufzeit leitetdata-gozuMock.goum, wobei?scenario=und die Eingangs-Transition erhalten bleiben). Einfache Links bleiben für Overlay-Auslöser reserviert (Modale/Details – ein einfacher Bildschirmlink öffnet immer ein Overlay); wiederhole denselben Navigationsblock auf jedem Bildschirm des Canvas und markiere das aktive Element. Bildschirme können"transition": "fade"|"slide-left"|"none"incanvas.jsondeklarieren:Mock.goübergibt eine Eingangsklasse an das Ziel (mock-enter-fade/mock-enter-slide-left, die sich innerhalb von 300 ms selbst entfernt). Die Übergabe liest das AKTUELLEcanvas.jsondes Canvas, das mit dem Zieldateinamen übereinstimmt, sodass es für Sprünge innerhalb desselben Canvas funktioniert (eine Selbstnavigation wieMock.go('01-overview.html')ist das Aktualisierungsmuster) – ein canvas-übergreifendesMock.go('../<canvas>/<screen>.html')ist eine einfache Navigation ohne Eingangsklasse. Die Scroll-Position wird pro Bildschirm beibehalten (scroll.<canvas>.<file>in sessionStorage, wiederhergestellt, wenn der Bildschirm zurückkehrt und ⟲ Fluss zurücksetzen überlebt, das nurmock.*löscht).
- Styling-Richtlinie: Das Utilities-Vokabular ist das Vokabular. Alles, was auf Tokens
basiert (Farben, Typografie, Abstände, Radius), wird durch die generierten Utilities
realisiert: verlinke
- Validieren und beheben. PFLICHT-Sync zuerst: nach dem Bearbeiten eines Partial in
design/components/(oder von Marker-Argumenten), führenode design/scripts/sync-components.mjsaus dem Projektstammverzeichnis aus, bevor du etwas präsentierst; es materialisiert jede Instanz aus ihrem Partial (Marker-Args gewinnen).--checkist die Trockenlaufform: es gibt einenfile:line-Diff pro abweichender Region aus und beendet sich mit 1 bei Abweichung (0 sauber), ohne jemals zu schreiben. Führe dann vom Projektstammverzeichnis aus:node design/validate.mjs design/<canvas>. Behebe jedes aufgeführte Problem und führe es erneut aus, bis nur die Zusammenfassungszeile übrig bleibt. Präsentiere niemals einen Canvas, der Probleme hat. Das Argument des Validators ist eine Design-Wurzel (Projektmodus) oder ein einzelner Canvas-Ordner (Canvas-Modus); ohne Argument verwendet es standardmäßig./design. Strukturelle Prüfungen decken nur die incanvas.jsonaufgeführten Bildschirme ab; der Projektmodus prüft zusätzlich die Veralterung von Tokens/generiertem CSS, Komponenten und Kommentare. Komponentenregeln werden auf jeder nicht ausgenommenen.htmlgescannt, unabhängig voncanvas.json, mit den Codescomponent-unknown,component-variant,component-marker,component-divergenceundslot-marker.--allow-staleüberspringt NUR die Veralterungsprüfung;--mark-staleist der einzige Schreibvorgang des Validators (es markiert Kommentar-Pins, deren Anker verschwunden ist);--example-inventoryist die Beispiel-Vertragsprüfung (exakte Dateiliste voninventory.json+"_demo": trueauf jedem Pin; keininventory.json= überspringen, exit 0). 4b. Impeccable-Audit. Nach der Validierung führe das technische Audit der verwandtenimpeccable-Fähigkeit auf dem Canvas durch (installiertes Layout, win32):<skill-impeccable>/scripts/impeccable.cmd audit design/<canvas>– der Pfad wird vom installierten