mikeozornin/skills

HTML-Prototyp erstellen

Jeden Prototyp in assets/template.html (im Verzeichnis dieses Skills) erstellen: eine einzige, in sich geschlossene HTML-Datei. Die Vorlage enthält bereits die gesamte Hülle: Kopfzeile, Browserrahmen, Zustandswechsler, Notizenbereich, Bildschirmkarte, Prüferkommentare, Koobiq-Tokens mit k-*-Komponenten und die Laufzeit. Die Shell-Oberfläche ist in Englisch oder Russisch, je nach Sprache des Betriebssystems/Browsers; der eigene Text des Prototyps ist das, was Sie schreiben. Sie schreiben nur den PROTOTYPE-Block (JS) und den Abschnitt 5. PROTOTYPE STYLES (CSS). Die Vorlage nicht beschädigen: Die Shell nie neu erstellen, umgestalten oder beschreiben.

Design vor Code

Ein Prototyp ist ein Werkzeug für eine Entscheidung, keine Galerie von Bildschirmen. Arbeiten Sie diese Schritte durch, bevor Sie prototype.js schreiben.

1. Kontext sammeln. Wer der Benutzer ist (Rolle, Fachkenntnisse), welche Aufgabe er erledigt, was sie auslöst und wie „erledigt“ für ihn aussieht. Wenn das Produkt existiert (Repository, Screenshots, Figma, Dokumentation, ein früherer Prototyp), übernehmen Sie dessen Navigation, Begriffe, Entitäten und Daten von dort und entwerfen nur die Änderung. Erfinden Sie kein Produkt um die Funktion herum.

2. Die Frage benennen. Ein Satz oder nur mehrere für einen großen Prototyp: Was die Prüfer entscheiden müssen oder was in der UI am zweifelhaftesten ist (werden Benutzer X finden, Y verstehen, hält Z mit echten Daten). Notieren Sie für jede Frage, was ein Prüfer sehen muss, um sie zu beantworten, und welcher Zustand oder welche Daten das Design zerstören könnten. Wenn die Anfrage keine Frage nennt, nehmen Sie die riskanteste Entscheidung als eine und legen Sie sie dem Autor in Schritt 4 vor.

3. Das Szenario schreiben in den Worten des Benutzers, vom Auslöser bis zum Ergebnis: „Analyst sieht einen Spike → öffnet die Regel → senkt den Schwellenwert → sieht, wie viele Vorfälle es geben wird“. Fügen Sie dann nur die Verzweigungen hinzu, die die Frage benötigt: Abbrechen, Validierungsfehler, leer oder erste Nutzung sowie die schwierigen Fälle, bei denen zuvor nicht gesehene Anforderungen auftauchen: keine Berechtigung, ein Konflikt mit einem anderen Objekt, eine Grenze, viele Daten, eine Aktion, die der aktuelle Zustand des Objekts verbietet. Schritte werden zu STEPS, Verzweigungen zu Zuständen und übergreifende Bedingungen (Rolle, Feature-Flag, Datenvolumen) zu SWITCHES.

4. Mit dem Autor abstimmen, bevor Sie bauen. Senden Sie in einer kurzen Nachricht:

   • die Frage;
   • das Szenario mit den Verzweigungen und Randfällen, die Sie zeigen möchten;
   • alles, was Sie angenommen statt aus der Anfrage oder dem Produkt übernommen haben, als nummerierte Liste mit einer Aussage pro Punkt, damit der Autor nach Nummer antworten kann: „2 – nein, eine Managerfreigabe ist erforderlich“.

   Warten Sie auf die Antwort. Überspringen Sie diesen Schritt bei kleinen Änderungen an einem vorhandenen Prototyp. Wenn der Autor gebeten hat, nicht zu fragen, bauen Sie auf Ihren Annahmen auf und listen Sie diese in der Antwort auf.

5. Die Tiefe festlegen jeder Schritt × Zustand Zelle:

   • voll = auf dem Pfad der Frage: klickbar, jeder Zustand, Stressdaten;
   • plausibel = Kontext: statisch, aber realistisch;
   • aus = in der Antwort als nicht abgedeckt genannt.

   Verwenden Sie nur die Zustände, die die Frage benötigt: ideal, leer oder erste Nutzung, teilweise, Fehler, keine Berechtigung, maximal etwa 6 pro Schritt. Fügen Sie Ladezustände nur hinzu, wenn sie etwas Bestimmtes zeigen (einen langen Vorgang, Fortschritt, Teilergebnisse). Ein fehlgeschlagener Ladevorgang ist selten einen Zustand wert, aber „in diesem Objektzustand nicht erlaubt“ ist es normalerweise. Täuschen Sie niemals ein Ergebnis vor, das nicht entworfen wurde.

6. Jeden Bildschirm zuerst in Worten entwerfen: seinen Zweck in einem Satz, die eine primäre Aktion und was der Benutzer sehen muss, um hier zu entscheiden, geordnet nach Wichtigkeit. Bauen Sie es dann aus Standard-Koobiq-Mustern (Tabelle, Formular, Seitenbereich, Modal, leerer Zustand). Setzen Sie Neuartigkeit nur dort ein, wo die Frage ist; alles andere sieht aus wie die üblichen Bildschirme des Produkts.

   • Jede Aktion hat ein sichtbares Ergebnis: was passiert ist und wo sich das Objekt jetzt befindet.
   • Eine destruktive Aktion benennt das Objekt und die Konsequenz. Schaltflächen sagen normalerweise das Verb.
   • Ein Fehler sagt, wie man ihn behebt, und behält die Eingabe bei.
   • Ein Name pro Sache über Bildschirme, Breadcrumbs, Toasts und die URL hinweg. UI-Text ist in der Sprache des Benutzers und folgt ux-write, falls installiert.

7. Die Daten vor den Ansichten schreiben. Verwenden Sie realistische Domaindaten, die das Layout belasten: einen langen Namen, eine 0/1/viele-Anzahl, einen seltenen Status. Verwenden Sie feste Daten und Werte (kein Date.now()/Math.random()) und kein Lorem Ipsum.

Varianten, nur wenn die Frage „welche Lösung“ ist. Bauen Sie 2–3 (max. 5) in VARIANTS anstatt für Prüfer zu wählen.

• Sie unterscheiden sich in der Struktur (Layout, Hierarchie, primäre Aktion), nicht in Farbe oder Text. Wenn zwei Entwürfe ähnlich aussehen, überarbeiten Sie einen mit einem expliziten Verbot („kein Kartenraster“).
• Varianten können Daten teilen, niemals das Layout.
• Geben Sie jeder einen title und eine einzeilige Idee im text.
• Das beste Feedback ist „Kopfzeile von B, Liste von C“.

Erledigt wenn

Überprüfen Sie den Prototyp anhand jedes Punktes, bevor Sie antworten:

• Jeder gezeigte Pfad läuft von Anfang bis Ende. Er beginnt dort, wo der Benutzer auf den Auslöser trifft, nicht bei einem Login oder einem Dashboard. Jeder gezeigte Zweig endet, zurück auf dem Pfad oder bei einem Ergebnis. Eine Übergabe an ein anderes Produkt oder System ist ein Stub mit einem sichtbaren Ergebnis (ein Toast oder ein Zustand wie „Aufgabe in Jira erstellt“), niemals eine Kopie der anderen UI. Ein sekundäres Steuerelement darf nichts tun (ein Menüpunkt kann einfach close), solange kein Szenario damit beginnt.
• Was diskutabel ist, ist markiert. Jedes geänderte oder diskutable Element hat eine Notiz. Wenn die Frage ist, welche Lösung genommen werden soll, gibt es 2–3 Varianten, die sich in der Struktur unterscheiden.
• Nichts Überflüssiges. Jeder Zustand, jeder Schalter und jede Notiz hilft entweder, die Frage zu beantworten, oder testet eine Annahme über eine Anforderung. Entfernen Sie den Rest.

Bauen

1. Die bearbeitbaren Teile holen. Mit SKILL_DIR = Verzeichnis dieses Skills, A=$SKILL_DIR/scripts/assemble.mjs (mit node ausführen, keine Abhängigkeiten), Arbeitsverzeichnis z.B. /tmp/proto-<name>/:

   • neuer Prototyp: node $A --split $SKILL_DIR/assets/template.html /tmp/proto-<name>;
   • Änderung eines vorhandenen: node $A --split <file>.html /tmp/proto-<name>. Das Zusammenbauen aktualisiert auch seine Shell.

   Dies ergibt prototype.js (demo PROTOTYPE-Block) und prototype.css (Abschnitt 5).

2. prototype.js umschreiben, alle Demo-Inhalte ersetzen: PROTO, STEPS, SWITCHES, S, NOTES, LINKS (normalerweise []), Daten, VIEWS, ACTIONS. Benutzerdefiniertes CSS geht in prototype.css. Arbeiten Sie in Durchgängen:

   1. den Hauptpfad, klickbar von Anfang bis Ende, im idealen Zustand;
   2. die anderen Zustände und Zweige;
   3. Notizen;
   4. Verifizieren und Erledigt wenn.

   Polieren Sie keinen Bildschirm, bevor der Pfad dadurch funktioniert.

3. Zusammenbauen: node $A <target>.html /tmp/proto-<name>/prototype.js /tmp/proto-<name>/prototype.css. Es prüft die Syntax und die erforderlichen Deklarationen. Liefern Sie nur das HTML aus.

4. Ansichten: eine VIEWS[step](S) pro Schritt, die einen HTML-String zurückgibt und auf S.state / S.sw verzweigt. Bauen Sie aus k-*-Klassen; siehe references/koobiq-cheatsheet.md.

   • Jeder Zustand rendert vollständig, wenn er direkt geöffnet wird. Ein direkter Öffner (Popover, Hash-Link, Kartenminiatur, Notiz, ←/→, protoCheck) beginnt mit dem initialen S plus dem seed des Zustands, z.B. { id: 'confirm', title: 'Bestätigung', seed: { name: 'Brute-Force: RDP' } }. Ein goto() im Ablauf behält, was der Benutzer eingegeben hat. VIEWS lesen nur S und konstante Daten.
   • Overlays. Ein Modal oder Seitenbereich wird über dem Bildschirm gezeichnet, den es abdeckt, innerhalb derselben Ansicht. Ein einmaliges Overlay (eine Bestätigung) ist ein Zustand dieses Schritts (form/confirm). Ein Overlay mit eigenem Unterablauf (Formular → Fehler → Bestätigen) kann ein eigener Schritt sein, der den darunter liegenden Bildschirm zeichnet. Für ein Modal über einem Bereich rendern Sie das Modal nach dem Bereich: das letzte .k-overlay ist das oberste, und nur seine Markierungen werden angezeigt.
   • Scrollen. Ein Bildschirm, der höher als der Browserrahmen ist, scrollt darin, wie eine Seite. Ein neuer Schritt beginnt oben; ein neuer Zustand oder eine neue Variante im selben Schritt behält den Scroll, damit Prüfer sie an derselben Stelle vergleichen können. Eine App-Shell (.app-body + .app-content) scrollt innerhalb von .app-content, wie zuvor.
   • Verdrahten Sie Klicks mit data-act → ACTIONS. Wechseln Sie Bildschirme nur über goto(step, state) / data-goto, damit die Zustandsschaltfläche, die URL-Leiste und der Hash synchron bleiben.

5. Notizen (3–7) gehen nur auf die Elemente, um die es bei der Frage geht: geänderte oder diskutable.

   • Setzen Sie class="changed" data-anchor="note-N" auf das Element und ${marker(N)} darin. Wickeln Sie leere oder deaktivierte Elemente in <span class="k-anchor changed" data-anchor="note-N">.
   • Der Notiz-text sagt, was sich geändert hat und warum, in 1–2 Sätzen. Für eine Hypothese enden Sie mit „Prüfen: …“.
   • try sagt, worauf geklickt werden soll, um es zu sehen.

6. Bildschirmkarte baut sich selbst aus den Zuständen und Übergängen. Übergänge stammen aus dem Markup jedes Zustands: data-goto und literale goto() / openState()-Aufrufe in den ACTIONS, die seine aktivierten Steuerelemente, Menüpunkte und das oberste Overlay aufrufen (deaktivierte Steuerelemente geben keinen Pfeil). Ein im selben Aktionsberechneter Zustand funktioniert, wenn seine möglichen IDs dort als Zeichenfolgen erscheinen: goto('list', S.q ? 'empty' : 'data'). Ein Übergang hinter einer Hilfsfunktion, einem Timer oder einem Ereignis, auf das der Benutzer nicht klickt, geht zu LINKS: { from: 'report/building', to: 'report/ready', label: 'Bericht bereit' }.

7. Verifizieren (siehe Verifizierung). Korrigieren und neu zusammenbauen, bis protoCheck() sauber ist, dann den Prototyp gegen „Erledigt wenn“ prüfen.

8. Antworten mit dem Dateipfad, der Schritt × Zustand Tabelle, was bewusst nicht abgedeckt ist und allen nach der Vereinbarung getroffenen Annahmen. Die Shell nicht beschreiben.

Prüferkommentare

Der Benutzer kann das Markdown aus „Alle kopieren“ einfügen. Es nennt die Datei in der Zeile Datei:. Jedes ## ist ein Bildschirm mit seinem Hash (#step/state?switches); bei Varianten beginnt es mit Variante B · Karten → und der Hash hat variant=<id>. Die Shell schreibt es in der UI-Sprache des Prüfers, daher kann es Russisch sein: Файл:, Вариант B. Jedes ### ist ein Element mit seinem Selektor innerhalb von #view, seinen data-*-Attributen und der verknüpften Notiznummer, gefolgt vom Kommentar als Zitat.

Um es anzuwenden, finden Sie das Element in VIEWS[step] / ACTIONS dieser Datei (dieser Variante), bearbeiten Sie es dann über --split und bauen Sie es in dieselbe Datei wieder zusammen: Kommentare leben im localStorage des Browsers unter dem Dateipfad.

Shell-Regeln

• Kopfzeile = nur kurzer Titel. Kein Untertitel, keine Bildunterschrift, Legende oder „Prototyp des Ablaufs …“ Text irgendwo über dem Rahmen.
• Ein Zustandssteuerelement: das Popover „Schritt · Zustand“. Keine Vor-/Zurück-Schritte, bildschirmspezifische segmentierte Steuerelemente, Tabs über dem Rahmen oder benutzerdefinierte Hotkeys (←/→, Esc und die Variantenauswahl mit 1–9 sind integriert).
• Notizen leben nur in aside#notes, außerhalb von .browser. Innerhalb von .app gibt es nur nummerierte Markierungen. Setzen Sie Notiztext nie in ::after-Tooltips, Overlays oder eine „Prüfmodus“-Spalte innerhalb der App.
• RUNTIME nicht bearbeiten, und das Deck, die Bühne, den Browser, Notizen, Kommentare oder die Bildschirmkarte nicht verschieben oder umgestalten. Verhalten geht in ACTIONS.
• Koobiq als Standard: k-*-Klassen und --kbq-*-Tokens. Keine Hex-/RGB-Farben, keine erfundene Palette (--bg, lila Akzente) und keine Nur-Hell-Stil, weil der Theme-Umschalter funktionieren muss. Für ein anderes Designsystem die Shell behalten und nur die App umgestalten.
• Eine Datei, kein externes JS.

PROTOTYPE API

Was	Wie
Titel / URL-Leiste	PROTO.title, PROTO.url(S)
Popover-Raster	STEPS[{id,title,states[{id,title,seed?}]}], SWITCHES[{id,title,options}]
Zustand	S.step, S.state, S.sw[id], S.menu (offene Menü-ID), plus eigene Felder
Navigieren	goto(step, state, patch?) innerhalb des Ablaufs (behält S); Markup data-act="goto" data-goto="form/errors". openState(step, state) = direktes Öffnen (initial S + seed)
Aktionen	data-act="name" → ACTIONS.name(el, e); rendert neu, es sei denn, es gibt false zurück
Eingebaute Aktionen	goto; close (S.menu = null); menu + data-menu="id" (umschalten); set + data-field + data-value (in S schreiben, Menü schließen). Ein Menü schließt auch bei Esc, Klick außerhalb und jeder anderen Aktion
Eingaben	data-model="field" schreibt S.field; data-live rendert bei Eingabe neu (Fokus und Caret bleiben erhalten); data-live="act" ruft zuerst ACTIONS.act auf; data-scroll="key" behält Scroll
Fokus	goto('form', 'errors', { focus: 'name' }) fokussiert [data-model="name"] einmal
Helfer	icon('search'), marker(n, '--x:100%;--y:50%'), tip(html, text, 'k-float--right'), matches(S.q, ...fields), toast(title, {kind, text}), esc(str)
Notizen	NOTES[{id, step, state, title, text(html), try}]: step/state sagen, wo der Anker lebt
Bildschirmkarte	Wird automatisch erstellt; LINKS[{from: 'step/state', to: 'step/state', label}] fügt Übergänge hinzu, die der Scan nicht sehen kann
Varianten	VARIANTS[{id, title, text, STEPS?, NOTES?, VIEWS?, ACTIONS?, LINKS?, S?, url?}]. Die globalen Deklarationen sind Variante A; eine Variante überschreibt nur, was anders ist (S wird über das globale S gemergt). Jede hat ihre eigene Bildschirmkarte, Notizen und Kommentare; SWITCHES und Zurück/Vorwärts werden geteilt. Auswahl in der Kopfzeile, Tasten 1–9

Verifizierung

Stellen Sie den Ordner im Hintergrund bereit (file:// ist oft blockiert) und öffnen Sie die gedruckte URL plus <file>.html im Browser-Tool. Nach jedem erneuten Zusammenbauen neu laden, da eine reine Hash-Änderung die Datei nicht neu lädt.

cd <dir> && node -e "const fs=require('fs'),T={'.html':'text/html; charset=utf-8','.js':'text/javascript','.css':'text/css','.svg':'image/svg+xml'};require('http').createServer((q,r)=>{const p='.'+decodeURIComponent(new URL(q.url,'http://x').pathname);fs.readFile(p,(e,d)=>{r.writeHead(e?404:200,{'Content-Type':T[require('path').extname(p)]||'application/octet-stream'});r.end(e?'Not found':d)})}).listen(0,'127.0.0.1',function(){console.log('http://127.0.0.1:'+this.address().port+'/')})"

1. protoCheck() ausführen in der Seite (Konsole oder das Browser-Tool auswerten) bei einer Fensterbreite von 1440 oder mehr. Es muss ok: true zurückgeben. Es öffnet jede Schritt × Zustand × Schalter-Kombination in beiden Themes und meldet Renderfehler, leere Bildschirme, Überlauf, defekte Markierungen oder Notizen, unbekannte data-act / data-goto / goto() / LINKS-Ziele, hartcodierte Farben und Vorlagenreste. Beheben Sie jede Warnung (identische Zustände, Schalter ohne Wirkung, nicht deterministische Daten, Notizen außerhalb von 3–7, ein nicht mit anderen verbundener Schritt) oder erklären Sie sie in der Antwort.
2. Schauen Sie es sich im Live-Server an. Klicken Sie den Pfad durch: Verbinden Sie jedes Detail und korrigieren Sie Fehler. Öffnen Sie jeden Zweig mit den Popover-Steuerelementen. Lesen Sie jede Notiz.
3. Stellen Sie schmale Fensterbereiche, Themen und Sprachwechsel bereit. Ändern Sie die Fensterbreite, das Theme (über das Tool des Browsers, document.documentElement.dataset.theme = 'dark' und zurück), und wenn die Shell eine Sprachumschaltung unterstützt, schalten Sie sie um. Ein Prototyp sieht in beiden Sprachen gleich aus, da er keine UI-Strings der Shell enthält, aber das ist ein guter Test für nichts.
4. Reparieren Sie die über protoCheck() hinausgehenden Warnungen aus Schritt 1. Alle Befunde erklären: tote Links, die niemandem wehtun, oder Randfälle, die über Skripte geprüft werden, die der Prototyp voraussetzt.