Design by Story

Was macht Design by Story?

Erstelle einen HTML-Einzeldatei-Prototyp eines Produkts, der auf mehreren Geräten betrachtet werden kann und nach User Story unterteilt ist – genauso wie nach Gerät.

Die obere Leiste enthält zwei Switcher:

• Gerät: z. B. Website · Android · iPhone. Gleiches Produkt, anderer Rahmen.
• Story: „Alle Stories“ plus ein Eintrag pro User Story. Die Auswahl einer Story setzt die gemeinsamen Daten auf deren Startdaten zurück, bringt jedes Gerät zum Startbildschirm der Story und öffnet ein Panel mit der Story, Priorität, Status, Akzeptanzkriterien, Walkthrough und Notizen.

Beide Auswahlen sind in der URL-Hash gespeichert (#story=S2&device=iphone), sodass ein Link zu einer Story auf einem Gerät direkt in ein Review oder Ticket eingefügt werden kann.

Arbeitsablauf

1. Eingaben sammeln (nur nach dem fragen, was fehlt, in einer Nachricht):

   • Was das Produkt ist und wer es nutzt.
   • Welche Geräte angezeigt werden sollen. Standard: Website + Android + iPhone. Tablet für Feld-/Kiosk-Nutzung.
   • Die User Stories in beliebiger Form (Liste, Backlog-Export, Feature-Dokumente).
   • AC-Format: Given/When/Then oder einfache Regeln? Standardmäßig Given/When/Then.
   • Priorität (MoSCoW) und Status, falls vorhanden. Andernfalls Standardwerte should / draft.
   • Das primäre Datenmodell (Hauptdatensatz + Schlüsselfelder) oder aus den Stories ableiten.

   Normalisiere jede Story gemäß dem Story-Format. Wenn der Benutzer keine Stories hat, erstelle 3–6 aus der Produktbeschreibung und bestätige sie, bevor der Bau beginnt.

2. Überprüfe die Stories anhand der Qualitätscheckliste. Zeige Probleme in einer kurzen Liste an. Schreibe die Formulierungen des Benutzers nicht stillschweigend um.

3. Plane Bildschirme pro Story. Liste für jede Story die Bildschirme auf, die sie auf jedem Gerät berührt, sowie die benötigten Startdaten. Eine Story überspringt ein Gerät nur, wenn das Produkt wirklich so funktioniert (z. B. Admin nur auf der Website). Ihre devices-Liste gibt dies an, und der Switcher deaktiviert die anderen Geräte, während sie ausgewählt ist.

4. Kopiere assets/shell.html in den vom Benutzer gewählten Pfad (standardmäßig docs/reference/prototype.html) und fülle es aus. Lese references/prototype-spec.md für die visuellen Regeln (Rahmen, Token, Schrift, Karten, Pillen, Toasts, Drawer, Icons, Kopier-Ton).

5. Baue Bildschirme, nicht Stories. Bildschirme werden geteilt; Stories sind Einstiegspunkte und Startdaten für diese Bildschirme. Dupliziere niemals einen Bildschirm pro Story. Wenn eine Story eine Variante benötigt, steuere sie über die Startdaten.

6. Überprüfe im Browser. Verwende ein Browser-Tool, falls vorhanden. Andernfalls verwende headless Chrome: --dump-dom "file://…/prototype.html#story=S2&device=iphone" um zu prüfen, was gerendert wurde, --screenshot um es anzusehen, und --enable-logging=stderr um Konsolenfehler zu erfassen. Prüfe:

   • dass jede Story auf jedem gelisteten Gerät auf dem richtigen Bildschirm startet;
   • dass jedes Akzeptanzkriterium demonstriert werden kann und der Walkthrough durchklickbar ist;
   • dass das Wechseln des Geräts mitten in einer Story den Zustand beibehält;
   • dass keine Steuerelemente einer Story unter einer anderen Story erscheinen und „Alle Stories“ alle Steuerelemente aller Stories zusammen funktionieren;
   • dass die Konsole sauber ist.

7. Halte es synchron. Wenn später eine Story hinzugefügt oder geändert wird, aktualisiere in derselben Bearbeitung ihren #story-text-Eintrag, ihren BEHAVIOUR-Eintrag und jedes Gerät, in dem sie gelistet ist.

Story-Format

Eine Story lebt an zwei Stellen im Shell, beide durch ihre ID referenziert:

• ihr Text im #story-text-JSON-Block (schreibgeschützt im Story-Panel angezeigt);
• ihr Verhalten in BEHAVIOUR, das nur Code ist.

<script type="application/json" id="story-text">
{
  "S1": {
    "title": "Suche speichern",
    "story": "Als Besucher kann ich eine Suche speichern, um über neue Treffer informiert zu werden, ohne erneut suchen zu müssen.",
    "priority": "must",
    "status": "draft",
    "ac": [
      { "id": "S1-AC1", "text": "Angenommen, ich habe nach \"Eichentisch\" gesucht. Wenn ich „Suche speichern“ antippe, dann erscheint sie unter „Gespeichert“." },
      { "id": "S1-AC2", "text": "Angenommen, diese Suche ist bereits gespeichert. Wenn ich sie erneut speichere, dann wird sie in „Gespeichert“ weiterhin nur einmal angezeigt." }
    ],
    "acNext": 2,
    "walkthrough": ["Nach \"Eichentisch\" suchen", "„Suche speichern“ antippen", "„Gespeichert“ öffnen"],
    "outOfScope": ["E-Mail-Benachrichtigungen"],
    "assumptions": ["Besucher müssen angemeldet sein, um zu speichern"],
    "questions": ["Gibt es ein Limit für gespeicherte Suchen?"]
  }
}
</script>

const BEHAVIOUR = {
  S1: {
    devices: ['web', 'android', 'iphone'],         // welche Rahmen diese Story betrifft
    start: { web: 'search', android: 'search', iphone: 'search' }, // Bildschirm pro Gerät
    features: ['save-search'],                      // was diese Story einschaltet
    seed: () => ({ user: SIGNED_IN, saved: [] }),  // frische Daten für diese Story
  },
};

Feld	Regeln
story	Als <Persona> kann ich <Aktion>, damit <Nutzen>. Der Nutzen ist das, was der Benutzer gewinnt, keine Wiederholung der Aktion.
priority	must · should · could · won't (MoSCoW).
status	draft · in review · agreed.
ac	Objekte { id, text }. IDs sind <Story>-AC<n>, werden nie umnummeriert, nie wiederverwendet. Siehe unten.
acNext	Die höchste jemals für diese Story vergebene AC-Nummer. Eine neue AC erhält acNext + 1, und acNext wird entsprechend aktualisiert. Aktualisiere es jedes Mal, wenn du eine AC hinzufügst.
walkthrough	Das Demo-Skript, das ein Prüfer durchklickt. Nicht Akzeptanzkriterien; halte es kurz.
outOfScope, assumptions, questions	Einfache Listen. Leer lassen, anstatt Füllmaterial zu erfinden. Notiere alles, bei dem der Benutzer unsicher ist, als Frage.

seed() gibt bei jedem Aufruf ein frisches Objekt zurück, sodass eine erneute Auswahl einer Story sie immer sauber neu startet. „Alle Stories“ verwendet DEFAULT_SEED und den jeweiligen Startbildschirm jedes Geräts.

Akzeptanzkriterien

• Ein testbares Verhalten pro AC, im vom Benutzer gewählten Format. Given/When/Then ist eine Zeile: Given <Kontext>, when <Aktion>, then <beobachtbares Ergebnis>.
• Exakter Wortlaut: Wenn es in einer AC um eine Nachricht geht, zitiere die Nachricht (then I see "Nothing open right now."), niemals „eine freundliche Nachricht“.
• Ergebnisse, nicht Styling: „Es wird als „Erledigt“ angezeigt“ statt „Ein grünes Pill-Element erscheint“. Ein visuelles Detail ist nur dann eine AC, wenn es die Anforderung ist.
• Auf einem Gerät testbar. Schreibe keine ACs über andere Geräte („erscheint auf jedem Gerät“, „nur Web“, „Handys können es nicht ändern“). Welche Geräte eine Story abdeckt, gehört in devices, und die Synchronisation zwischen Geräten ist Sache des Backends.
• IDs sind permanent. S1-AC3 behält seine ID, wenn es bearbeitet, verschoben oder in eine Unter-Story aufgeteilt wird, damit es in Tests und Tickets nachverfolgt werden kann. Neue ACs erhalten acNext + 1. Gelöschte IDs werden nie wieder vergeben, und nichts wird umnummeriert.

Qualitätscheckliste

Überprüfe jede Story vor dem Bau und jedes Mal, wenn sie sich ändert:

• Ist die Persona eine echte Benutzerrolle, und ist der Nutzen etwas, das diese Rolle sagen würde?
• Liefert sie eigenständig Wert (unabhängig) und ist sie klein genug, um in unter einer Minute demonstriert zu werden? Wenn nicht, teile sie auf.
• Hat jede AC eine ID, ein einzelnes Verhalten und ein beobachtbares Ergebnis?
• Werden leere, Fehler- und Grenzfälle abgedeckt oder unter questions aufgeführt?
• Sind Abhängigkeiten zu anderen Stories sichtbar? (Ein gemeinsamer Feature-Key, plus eine Erwähnung in assumptions, z. B. „Baut auf S2 auf“.)

Story-Funktionalität ist deaktiviert, bis die Story ausgewählt ist

Jede Interaktion, die eine Story einführt, erhält einen Feature-Key, der in der features-Liste dieser Story aufgeführt ist. can('save-search') ist nur true, solange eine Story ausgewählt ist, die diesen Key listet.

• Rendern: Umgebe die Steuerelemente der Story mit can(...), sodass sie andernfalls nicht existieren (kein Button, kein Formular, kein Menüpunkt). Zeige sie nicht deaktiviert an. Prüfer sollten nur das sehen, was die ausgewählte Story hinzufügt.
• Handler: Beginne jeden Story-Handler mit if (!can('save-search')) return;, damit nichts außerhalb der Story ausgelöst wird, selbst von einem veralteten DOM oder der Konsole aus.
• „Alle Stories“ aktiviert alle Features aller Stories gleichzeitig: das gesamte Produkt, wie es ist, auf DEFAULT_SEED. Prüfe, dass sich Stories dort nicht überschneiden (z. B. zwei Steuerelemente an derselben Stelle).
• Eine Story, die von der Interaktion einer anderen Story abhängt, listet beide Keys (z. B. listet „Nach Status filtern“ ['filter', 'complete'], sodass das Abhaken einer Aufgabe das Verlassen der gefilterten Liste zeigen kann).
• Daten, die eine Story nur anzeigt (z. B. die Initialen eines Bearbeiters), werden nicht durch can() geschützt; nur die Möglichkeit, sie zu ändern, ist geschützt.

Stories ändern

Der Prototyp zeigt nur Stories an; er bearbeitet oder speichert sie nie. Alle Story-Änderungen erfolgen über Claude, im Chat:

• Neue Story: Entwurf der Story, der ACs und Fragen, Durchlauf der Qualitätscheckliste mit dem Benutzer, dann schreibe den #story-text-Eintrag und den BEHAVIOUR-Eintrag und baue die Bildschirme in einem Schritt. Eine Story existiert niemals nur als Text. Wenn sie das täte, würde sie vom Shell im Switcher ausgelassen und ein Fehler in der Konsole protokolliert.
• Geänderte Story (Formulierung, ACs, Priorität, Status, Notizen): Bearbeite #story-text. Wenn die Änderung das Verhalten der Story ändert (eine neue AC, ein anderer Walkthrough), aktualisiere die Bildschirme und den BEHAVIOUR-Eintrag im selben Schritt.
• Review-Feedback: Wenn der Benutzer Kommentare von Prüfern weitergibt, wandle jeden in eine der obigen Änderungen um oder in einen Eintrag unter questions, falls die Frage noch offen ist.
• Sage immer, was du gebaut oder geändert hast, nach Story und AC-ID.

Wenn der Benutzer Stories in einem Tracker (Jira oder ähnlich) pflegt, ist der Tracker die master-Kopie. Spiegele hier seine Formulierung wider, anstatt Stories nur im Prototyp zu bearbeiten.

Teilen einer Story

Wenn der Benutzer darum bittet, eine Story zu teilen, oder eine Story mehr als etwa 5 ACs, mehr als einen Haupt-Feature-Key oder ACs hat, die separat ausgeliefert werden könnten, teile sie auf.

1. Wähle ein Teilungsmuster und gib an, welches du verwendet hast:

   • Arbeitsschritte (erstellen → prüfen → veröffentlichen)
   • Operationen (hinzufügen / bearbeiten / löschen)
   • zuerst den Happy Path, dann Randfälle (leer, doppelt, Limit erreicht)
   • nach Gerät oder Rolle (Handy-Aufnahme vs. Website-Verwaltung)
   • nach Datenvariation (ein Element → viele, eine Währung → mehrere)
   • zuerst einfach, dann Erweiterungen (einfache Sortierung → gespeicherte Sortiereinstellungen)

   Jedes Kind muss dennoch ein vollständiges Als … kann ich …, damit … mit eigenem Wert sein.

2. Nummeriere die Kinder vom Elternteil aus: S3 → S3.1, S3.2, … Entferne das Elternteil sowohl aus #story-text als auch aus BEHAVIOUR und setze die Kinder an seine Stelle. Der readHash des Shells leitet einen alten #story=S3-Link an S3.1 weiter, sodass geteilte Links weiterhin funktionieren.

3. Teile auf, nicht duplizieren:

   • Akzeptanzkriterien. Jede elterliche AC wandert mit ihrer ursprünglichen ID zu genau einem Kind (S3-AC2 bleibt S3-AC2 innerhalb von S3.1). Wenn eine AC zwei Kinder betrifft, schreibe sie in zwei neue ACs um (S3.1-AC1, S3.2-AC1) und notiere, welche Eltern-ID sie ersetzen.
   • Feature-Keys. Teile einen Key, wenn seine Interaktion aufgeteilt wird (filter → filter-status, filter-counts). Ein Kind kann auch den Key eines Geschwisterkindes aufführen, wenn es darauf aufbaut, wie in der Abhängigkeitsregel oben.
   • Geräte. Jedes Kind listet nur die Geräte auf, die es wirklich berührt.
   • Startdaten. Das seed() eines späteren Kindes beginnt in dem Zustand, den die früheren Kinder hinterlassen würden (z. B. seedet S3.2 bereits einige gespeicherte Elemente), sodass jedes Kind unabhängig geprüft werden kann.
   • Notizen. Gib jedem Kind die Out-of-Scope-Items, Annahmen und Fragen, die darauf zutreffen. Kinder erben die Priorität des Elternteils, es sei denn, der Benutzer sagt etwas anderes.

4. Aktualisiere die Bildschirme: Sperre jedes Steuerelement erneut, das zu einem anderen Key gewandert ist. Überprüfe dann jedes Kind auf jedem gelisteten Gerät und prüfe, ob die ID des Elternteils weiterleitet.

5. Melde die Teilung als kurze Tabelle (Kind-ID, Story, Priorität, Geräte, AC-IDs), damit der Benutzer prüfen kann, ob jede elterliche AC irgendwo gelandet ist. Spiegele die Teilung in ihrem Backlog oder ihren Feature-Dokumenten wider, wenn sie Stories dort pflegen.

Regeln

• Eine HTML-Datei, Inline-CSS/JS, kein Build-Schritt, kein Framework, kein Backend. Direkt von der Festplatte öffnen.
• Alle Daten in einem gemeinsamen In-Memory-state; jedes Gerät liest und schreibt darauf.
• Render-Funktionen nehmen die Geräte-ID und zeichnen neu aus state (siehe Shell).
• Verwende erfundene, neutrale Beispieldaten. Kopiere niemals Namen, Marken oder Inhalte aus anderen Projekten in den Prototyp.
• Mobile Rahmen rendern dasselbe App-Markup; Unterschiede zwischen Android und iPhone sind Chrome-UI (Statusleiste, Notch/Kerbe, Gestenleiste), nicht separate Apps, es sei denn, der Benutzer wünscht plattformspezifische UI.