update

templates/Format/Baustein.md

@@ -1,100 +1,109 @@
 ```
-BAUSTEIN-CARD-STIL (HTML+CSS, in Browser anzeigbar)
+BAUSTEIN CARD STYLE (HTML+CSS, viewable in a browser)
 
-ZWECK
-- Einzelner Baustein als kompakte Card-Darstellung
-- Schnelles Nachschlagen einzelner Konzepte
-- Card ist Teil einer größeren Baustein-Sammlung
-- Nicht zum Lernen, sondern zum Wiedererkennen
-- Pro Card genau 1 Baustein
+PURPOSE
+- Single building block ("Baustein") as a compact card
+- Quick lookup of individual concepts
+- The card is part of a larger collection of building blocks
+- Not for learning, but for recognition
+- Exactly 1 building block per card
 
 FORMAT
-- HTML mit eingebettetem CSS
-- Im Browser anzeigbar (kein PDF-Output)
-- Card auf hellgrauem Hintergrund zentriert
+- HTML with embedded CSS
+- Viewable in a browser (no PDF output)
+- Card centered on a light gray background
 - Max-width 1000px, padding 28px 36px
-- Border-radius 12px, dezenter Schatten
-- Page-Hintergrund #f0f0f5
+- Border-radius 12px, subtle shadow
+- Page background #f0f0f5
 
-STRUKTUR — STRIKT NUR DIESE 4 ELEMENTE
-1. Titel (h1, fett, ohne Label, ohne Logo)
-2. Beschreibung (ein knapper Satz)
-3. Zweck (kursiv, grau, ein knapper Satz)
-4. Code-Beispiel (das eine relevanteste, mit Mini-Label oben)
+STRUCTURE — STRICTLY ONLY THESE 4 ELEMENTS
+1. Title (h1, bold, no label, no logo)
+2. Description (one concise sentence)
+3. Purpose (italic, gray, one concise sentence)
+4. Code example (the single most relevant one, with a mini label on top)
 
-KEIN Logo, KEIN "Baustein"-Label, KEIN Sprach-Tag, KEINE Sektion-Überschriften ("Beschreibung", "Zweck", "Relevante Beispiele"), KEINE Info-Blöcke, KEINE Warn/Tip/Note-Boxen, KEINE Meta-Informationen, KEINE Trennlinien zwischen Sektionen.
+NO logo, NO "Baustein" label, NO language tag, NO section headings
+("Beschreibung", "Zweck", "Relevante Beispiele"), NO info blocks,
+NO warn/tip/note boxes, NO meta information, NO divider lines between
+sections.
 
-TYPOGRAFIE
+TYPOGRAPHY
 - Body: -apple-system, "Segoe UI", sans-serif, 14px, line-height 1.5
-- Titel h1: 28px, font-weight 800, letter-spacing -0.5px, line-height 1.1
-- Beschreibung: 14px, line-height 1.55
-- Zweck: 14px, italic, color #5a6470
+- Title h1: 28px, font-weight 800, letter-spacing -0.5px, line-height 1.1
+- Description: 14px, line-height 1.55
+- Purpose: 14px, italic, color #5a6470
 - Code: "SF Mono", Consolas, monospace, 12px, line-height 1.5
-- Code-Label: 10px, letter-spacing 1px
+- Code label: 10px, letter-spacing 1px
 
-FARBEN
-- Card-Hintergrund: #ffffff
-- Page-Hintergrund: #f0f0f5
+COLORS
+- Card background: #ffffff
+- Page background: #f0f0f5
 - Text: #1a1a1a
-- Muted (Zweck): #5a6470
-- Code-Hintergrund: #1e2a3a
-- Code-Text: #e6e6e6
-- Syntax-Highlighting:
+- Muted (purpose): #5a6470
+- Code background: #1e2a3a
+- Code text: #e6e6e6
+- Syntax highlighting:
   - Keywords (.k): #ff79c6 (pink)
-  - Variablen (.v): #ffb86c (orange)
-  - Strings (.s): #f1c40f (gelb)
-  - Funktionen (.f): #50fa7b (grün)
-  - Typen (.t): #8be9fd (cyan)
-  - Kommentare (.c): #6b8aae italic
-- Label-Farbe in Code: #8be9fd (cyan)
+  - Variables (.v): #ffb86c (orange)
+  - Strings (.s): #f1c40f (yellow)
+  - Functions (.f): #50fa7b (green)
+  - Types (.t): #8be9fd (cyan)
+  - Comments (.c): #6b8aae italic
+- Label color in code: #8be9fd (cyan)
 
-INHALTLICHE PRINZIPIEN
-- Titel: GELÄUFIGSTER Kurzbegriff, max 1-2 Wörter, kein Präfix, keine Variante
-  - Gut: "Header", "Variable", "Klasse", "for-Schleife"
-  - Schlecht: "Überschriften h1–h6", "Variablen-Deklaration mit Typ"
-- Beschreibung: WAS macht es mechanisch? 1 Satz, max 5 Wörter, abstrakt/technisch
-  - Gut: "Definiert eine Überschrift.", "Wiederholt einen Code-Block."
-  - Schlecht: "Sechs Ebenen von der wichtigsten bis zur untergeordneten Überschrift."
-- Zweck: WANN brauche ich das? 1 Satz, max 5 Wörter, situativ/Problem-Trigger
-  - Gut: "Strukturiert die Seiteninhalte.", "Liste oder Bereich durchgehen."
-  - Schlecht: "Gliedert Inhalt in Hierarchie für Leser, SEO und Screenreader-Navigation."
-- WICHTIG: Beschreibung und Zweck dürfen sich NICHT inhaltlich überschneiden
-  - Schlecht (tautologisch): Beschreibung "Wiederholt Code." / Zweck "Etwas mehrfach tun."
-  - Gut (distinkt): Beschreibung "Wiederholt einen Code-Block." / Zweck "Liste oder Bereich durchgehen."
-- Beide Sätze: jedes überflüssige Wort raus, keine Aufzählungen, keine Komma-Listen
-- Genau EIN Code-Beispiel: das relevanteste / häufigste / typischste
-- Beispiel zeigt den Standard-Use-Case, nicht Edge-Cases
-- Label über Beispiel: max 2-3 Wörter, einfach, beschreibend
-  - Gut: "Alle Header", "Zuweisung", "Grund-Regel"
-  - Schlecht: "Alle Ebenen h1–h6", "Variable mit Typ-Hint deklarieren"
+CONTENT PRINCIPLES
+- Title: the MOST COMMON short term, max 1-2 words, no prefix, no variant
+  - Good: "Header", "Variable", "Klasse", "for-Schleife"
+  - Bad: "Überschriften h1–h6", "Variablen-Deklaration mit Typ"
+- Description: WHAT does it do mechanically? 1 sentence, max 5 words,
+  abstract/technical
+  - Good: "Definiert eine Überschrift.", "Wiederholt einen Code-Block."
+  - Bad: "Sechs Ebenen von der wichtigsten bis zur untergeordneten Überschrift."
+- Purpose: WHEN do I need this? 1 sentence, max 5 words,
+  situational/problem trigger
+  - Good: "Strukturiert die Seiteninhalte.", "Liste oder Bereich durchgehen."
+  - Bad: "Gliedert Inhalt in Hierarchie für Leser, SEO und Screenreader-Navigation."
+- IMPORTANT: description and purpose must NOT overlap in content
+  - Bad (tautological): description "Wiederholt Code." / purpose "Etwas mehrfach tun."
+  - Good (distinct): description "Wiederholt einen Code-Block." / purpose "Liste oder Bereich durchgehen."
+- Both sentences: cut every superfluous word, no enumerations, no comma lists
+- Exactly ONE code example: the most relevant / most common / most typical
+- The example shows the standard use case, not edge cases
+- Label above the example: max 2-3 words, simple, descriptive
+  - Good: "Alle Header", "Zuweisung", "Grund-Regel"
+  - Bad: "Alle Ebenen h1–h6", "Variable mit Typ-Hint deklarieren"
 
-LAYOUT-DETAILS
-- Header und Body keine separaten Sektionen, alles in einer Card
-- Titel zuerst, darunter direkt Beschreibung, darunter Zweck (mit margin-bottom)
-- Margin-bottom Titel: 14px
-- Margin-bottom Beschreibung: 6px (eng zum Zweck)
-- Margin-bottom Zweck: 22px (Abstand zu Code)
-- Code-Block padding: 14px 16px, border-radius 8px
+LAYOUT DETAILS
+- Header and body are not separate sections, everything in one card
+- Title first, directly below it the description, below that the purpose
+  (with margin-bottom)
+- Margin-bottom title: 14px
+- Margin-bottom description: 6px (close to the purpose)
+- Margin-bottom purpose: 22px (distance to the code)
+- Code block padding: 14px 16px, border-radius 8px
 
-CODE-BEISPIEL
-- GENAU EIN Beispiel pro Card
-- Das relevanteste, typischste, häufigste — nicht Edge-Cases
-- Sehr kurz: ideal 3-6 Zeilen, max 8 Zeilen
-- Mit kurzem Label oben (2-4 Wörter)
-- Syntax-Highlighting durch span-Klassen (.k, .v, .s, etc.)
+CODE EXAMPLE
+- EXACTLY ONE example per card
+- The most relevant, most typical, most common one — not edge cases
+- Very short: ideally 3-6 lines, max 8 lines
+- With a short label on top (2-4 words)
+- Syntax highlighting via span classes (.k, .v, .s, etc.)
 
-HTML-ENTITIES IM CODE (PFLICHT bei HTML/XML/JSX/Vue/JSX-ähnlichem Code)
-- Wenn das Code-Beispiel SELBST HTML, XML, JSX oder ähnliche Tag-Syntax zeigt, MÜSSEN spitze Klammern als HTML-Entities geschrieben werden:
+HTML ENTITIES IN CODE (MANDATORY for HTML/XML/JSX/Vue/JSX-like code)
+- If the code example ITSELF shows HTML, XML, JSX, or similar tag syntax,
+  angle brackets MUST be written as HTML entities:
   - `<` → `&lt;`
   - `>` → `&gt;`
   - `&` → `&amp;`
-- Grund: der Code wird via v-html im Browser gerendert. Rohe `<h1>` werden sonst als echtes DOM-Element interpretiert und verschwinden.
-- Gut: `<span class="t">&lt;h1&gt;</span>Text<span class="t">&lt;/h1&gt;</span>`
-- Schlecht: `<span class="t"><h1></span>Text<span class="t"></h1></span>`
-- Schlecht: `<h1>Text</h1>` (komplett ohne Spans und ohne Entities)
-- Diese Regel gilt NUR für die Inhalte des Code-Beispiels, NICHT für die `<span class="...">`-Wrapper selbst
+- Reason: the code is rendered via v-html in the browser. Raw `<h1>` would
+  otherwise be interpreted as a real DOM element and disappear.
+- Good: `<span class="t">&lt;h1&gt;</span>Text<span class="t">&lt;/h1&gt;</span>`
+- Bad: `<span class="t"><h1></span>Text<span class="t"></h1></span>`
+- Bad: `<h1>Text</h1>` (entirely without spans and without entities)
+- This rule applies ONLY to the contents of the code example, NOT to the
+  `<span class="...">` wrappers themselves
 
-KONKRETES BEISPIEL — Baustein "Header" (HTML)
+CONCRETE EXAMPLE — building block "Header" (HTML)
 ```json
 {
   "title": "Header",
@@ -109,35 +118,35 @@ KONKRETES BEISPIEL — Baustein "Header" (HTML)
 }
 ```
 
-VERMEIDEN
-- Lange Erklärungstexte
-- Mehrere Sätze für Beschreibung oder Zweck
-- Performance-Tipps, Trade-Offs, Edge Cases
-- Verwandte Bausteine, Varianten, Anti-Patterns
-- Tabellen, Listen, Aufzählungen
-- Icons, Emojis, Symbole
-- Komplexe Code-Beispiele (über 8 Zeilen)
-- Mehrere Beispiele (Varianten, Alternativen)
+AVOID
+- Long explanatory texts
+- Multiple sentences for description or purpose
+- Performance tips, trade-offs, edge cases
+- Related building blocks, variants, anti-patterns
+- Tables, lists, enumerations
+- Icons, emojis, symbols
+- Complex code examples (over 8 lines)
+- Multiple examples (variants, alternatives)
 
-THEMENSPEZIFISCHE ANPASSUNGEN
-- Bei anderen Sprachen: Syntax-Highlighting-Klassen anpassen
-- Titel-Größe und Spacing bleiben gleich
-- Card-Layout bleibt gleich
-- Inhalte (Beschreibung, Zweck, Beispiel) sprachspezifisch
+TOPIC-SPECIFIC ADJUSTMENTS
+- For other languages: adapt syntax highlighting classes
+- Title size and spacing stay the same
+- Card layout stays the same
+- Content (description, purpose, example) is language-specific
 
-GENERIERUNG MIT FEEDBACK-LOOP
-1. HTML schreiben
-2. In Browser anzeigen (Playwright-Screenshot oder direkt)
-3. Prüfen:
-   - Wirklich nur 4 Elemente (Titel, Beschreibung, Zweck, Beispiel)?
-   - Beschreibung und Zweck je max 5 Wörter?
-   - Titel max 1-2 Wörter, geläufiger Kurzbegriff?
-   - Label max 2-3 Wörter, simpel?
-   - Code-Beispiel unter 8 Zeilen?
-   - Label über Code-Block kurz und prägnant?
-   - Card kompakt, kein leerer Raum?
-   - Ist das gewählte Beispiel wirklich das typischste?
-   - Bei HTML/XML/JSX-Code: alle `<` und `>` als `&lt;` und `&gt;` geschrieben?
-4. Wenn etwas zu viel: weglassen, nicht hinzufügen
-5. Bei jeder Iteration prüfen: lässt sich noch was weglassen?
-```
+GENERATION WITH FEEDBACK LOOP
+1. Write the HTML
+2. View in a browser (Playwright screenshot or directly)
+3. Check:
+   - Really only 4 elements (title, description, purpose, example)?
+   - Description and purpose each max 5 words?
+   - Title max 1-2 words, common short term?
+   - Label max 2-3 words, simple?
+   - Code example under 8 lines?
+   - Label above the code block short and to the point?
+   - Card compact, no empty space?
+   - Is the chosen example really the most typical one?
+   - For HTML/XML/JSX code: all `<` and `>` written as `&lt;` and `&gt;`?
+4. If something is too much: remove it, don't add
+5. On every iteration check: can anything else be removed?
+```