Badge SDC — 5 SOLCOM-Varianten

Problem Statement

Die byte_theme:badge-Komponente existiert mit drei Varianten (primary, secondary, pill), die keine Entsprechung im SOLCOM Figma Design System haben. Redakteure und Site-Builder können im Canvas-Editor keine Badges einfügen, die dem Corporate Design entsprechen — die verfügbaren Stile sind entweder Tailwind-Defaults (primary, secondary) oder eine nicht-dokumentierte Kapselvariante (pill). Das Figma-Design-System definiert fünf konkrete Badge-Varianten mit exakten Tokenwerten, Radien und Padding-Regeln, die bisher nicht im Code abgebildet sind. Solange diese Lücke besteht, ist der Badge-SDC-Eintrag in docs/design/MAPPING.html als partial markiert.

Solution

Das style-Prop in badge.component.yml wird auf exakt 5 Figma-autoritative Werte eingeschränkt: lime, dark, disabled, lined, matching. Das CVA-Objekt in badge.twig erhält für jeden der fünf Werte ein dediziertes Klassen-Array mit var(--brand-*)-Tokens statt Hex-Literalen. Legacy-Werte werden im Twig via |default('lime')-Fallback abgefangen — keine bestehenden Canvas-Blöcke brechen. Die matching-Variante bekommt zwei neue optionale Props (abbreviation und percentage), die ihre spezifische Substruktur (Lime-Kreis + Kürzel + Prozentwert) steuern. Abschließend wird der Badge-Eintrag in docs/design/MAPPING.html auf Status matched gesetzt.

User Stories

1. Als Site-Builder möchte ich im Canvas-Editor eine Badge-Komponente mit dem Stil lime (weißer Hintergrund, Dark-Blue-Text, 10px-Radius) auswählen können, damit Badges auf dunklen Sektionshintergründen des SOLCOM Corporate Designs korrekt erscheinen.
2. Als Site-Builder möchte ich im Canvas-Editor eine Badge-Komponente mit dem Stil dark (Lime-Hintergrund, Dark-Blue-Text, 10px-Radius) auswählen können, damit Badges auf hellen oder neutralen Hintergründen die SOLCOM-Brand-Farbe tragen.
3. Als Site-Builder möchte ich im Canvas-Editor eine Badge-Komponente mit dem Stil disabled (Grau-Hintergrund, Hellgrau-Text, 10px-Radius) auswählen können, damit inaktive oder nicht verfügbare Zustände visuell korrekt dargestellt werden.
4. Als Site-Builder möchte ich im Canvas-Editor eine Badge-Komponente mit dem Stil lined (transparenter Hintergrund, Lime-Border, weißer Text, 20px-Radius) auswählen können, damit Pill-förmige Outline-Badges auf dunklen Hintergründen verfügbar sind.
5. Als Site-Builder möchte ich im Canvas-Editor eine Badge-Komponente mit dem Stil matching auswählen können und dabei ein Kürzel sowie einen Prozentwert eingeben können, damit „Matching"-Anzeigen (z. B. Bewerber-Passung) mit Lime-Kreis, Kürzel-Text und Prozent-Wert korrekt dargestellt werden.
6. Als Site-Builder möchte ich, dass bestehende Canvas-Blöcke, die noch den alten Stil pill oder secondary tragen, weiterhin gerendert werden, damit keine existierenden Seiten visuell brechen, wenn die neuen Stile eingeführt werden.
7. Als Entwickler möchte ich, dass alle Badge-Farben ausschließlich über var(--brand-*)-Tokens aus theme.brand.css gesetzt werden, damit zukünftige Branding-Anpassungen ausschließlich an der Token-Quelle vorgenommen werden müssen.
8. Als Figma-Designer möchte ich, dass der Badge-Eintrag im MAPPING.html den Status matched trägt, damit ich den Parität-Status des Design Systems auf einen Blick ablesen kann.
9. Als Entwickler möchte ich, dass die Textgröße in allen Badge-Varianten 15px beträgt (statt des bisherigen text-sm = 14px), damit das Rendering mit der Figma-Spec übereinstimmt.
10. Als Site-Builder möchte ich, dass der Canvas-Editor automatisch die aktualisierten Style-Optionen (lime, dark, disabled, lined, matching) im Dropdown anzeigt, sobald das Schema geändert ist, ohne manuellen Config-Import oder Update-Hook.

Implementation Decisions

Schema-Änderungen (badge.component.yml)

• Der style-Enum wird auf exakt 5 Werte eingeschränkt: lime, dark, disabled, lined, matching. Die Werte primary, secondary und pill werden aus dem Enum entfernt.
• Zwei neue optionale Props werden hinzugefügt: abbreviation (type: string | null) und percentage (type: string | null). Beide haben nur visuellen Effekt bei style=matching.
• Die bestehenden Props icon und icon_first bleiben im Schema erhalten (Backward-Compat für Canvas-Blöcke, die diese Props gesetzt haben), werden aber in den 5 neuen Varianten-Implementierungen nicht gerendert.
• Der label-Prop bleibt unverändert optional (type: string | null). Bei style=matching wird er nicht gerendert — stattdessen steuern abbreviation und percentage den Inhalt.

Twig-Implementierung (badge.twig)

• Deprecation-Strategie — Twig-Fallback (Option C): Alle Legacy-Werte (pill, primary, secondary, unbekannte Strings) werden via style|default('lime') auf lime abgebildet. Kein Update-Hook, kein DB-Migration-Script. Bestehende Canvas-Blöcke rendern unverändert als lime.
• Das CVA-Objekt erhält 5 neue style-Varianten. Alle Farben werden ausschließlich über var(--brand-*)-Tokens gesetzt — keine Hex-Literale in Tailwind-Klassen.
• Figma-konforme Klassen je Variante:
  • lime: bg-white text-[var(--brand-dark-blue)] rounded-[10px] px-[4px]
  • dark: bg-[var(--brand-lime)] text-[var(--brand-dark-blue)] rounded-[10px] px-[4px]
  • disabled: bg-[var(--brand-gray)] text-[var(--brand-light-gray)] rounded-[10px] px-[4px]
  • lined: bg-transparent border border-[var(--brand-lime)] text-white rounded-[20px] px-[8px] py-[4px]
  • matching: bg-transparent border border-[var(--brand-lime)] text-white rounded-[20px] px-[8px] py-[4px]
• Textgröße: Bisheriges text-sm (14px) wird auf text-[15px] korrigiert — Figma-Spec bestätigt 15px.
• Matching-Substruktur: Bei style=matching rendert das Twig drei feste Elemente: einen 8×8px Lime-Kreis (w-2 h-2 rounded-full bg-[var(--brand-lime)], dekorativ), den abbreviation-Text (font-sans font-medium text-[15px] text-white) und den percentage-Text (font-sans font-bold text-[19px] text-[var(--brand-lime)]). Gap: gap-[4px].
• Icon-Rendering entfällt in allen 5 neuen Varianten — die Figma-Spec zeigt in keiner Variante ein Icon-Element.

Canvas-Integration

• Die Canvas-Config canvas.component.sdc.byte_theme.badge.yml verwendet allowed_values_function: canvas_load_allowed_values_for_component_prop für den style-Prop. Diese Funktion liest die Werte direkt aus dem SDC-Schema — nach dem Schema-Update spiegelt der Canvas-Editor automatisch die 5 neuen Werte ohne Config-Deploy.
• Der default_value für style in der Canvas-Config bleibt bei primary — dieser wird beim Rendern durch den Twig-Fallback auf lime gemappt, bis ein Redakteur bewusst einen neuen Wert wählt.
• Keine neuen Canvas-Config-Versionen werden angelegt — die bestehenden Versionen bleiben unverändert, da der Twig-Fallback Rückwärtskompatibilität sichert.

Figma-Korrekturen gegenüber Jira-Ticket

Das Jira-Ticket P2503-157 enthält drei Ungenauigkeiten, die durch direkte Figma-Analyse korrigiert wurden:

• Radius lime/dark/disabled: Ticket nennt rounded-full, Figma-Spec bestätigt rounded-[10px].
• Lined-Borderfarbe: Ticket schweigt, Figma bestätigt border-[var(--brand-lime)] (nicht weiß).
• Token-Namen: Ticket nennt --color-lime, --color-dark-blue — korrekte Namen in theme.brand.css sind --brand-lime, --brand-dark-blue.

Testing Decisions

Was macht einen guten Test aus

Tests prüfen das externe Verhalten (gerenderte Klassen, HTML-Struktur) — nicht die interne CVA-Implementierung. Ein Test gibt keinen Aufschluss darüber, wie eine Klasse berechnet wird, sondern ob das finale Markup die erwarteten Token-Klassen trägt und die Substruktur der matching-Variante korrekt ist.

Zu testende Module

• badge.twig — Kernel-Render-Test (PHPUnit, Gruppe badge): Sofern ein Kernel-Test für das Badge-SDC existiert, wird er um die 5 neuen Varianten erweitert. Geprüft wird: (a) jede Variante rendert die erwarteten Tailwind-Klassen, (b) der Twig-Fallback für pill/primary/secondary produziert lime-Klassen, (c) bei style=matching sind Lime-Kreis, abbreviation- und percentage-Textelemente im Markup vorhanden.
• Manueller Browser-Smoketest: Da Tailwind-Klassen erst nach npm run build im CSS landen, ist für die visuellen Token-Werte (var(--brand-lime) etc.) ein manueller Browser-Check via DDEV nötig. Der QA-Plan im Story-Hub (docs/stories/P2503-157-badge-sdc-solcom-varianten.html#qa-plan) listet 9 click-genaue Schritte.

Prior Art

Vergleichbare Kernel-Render-Tests für SDC-Komponenten im Projekt: web/themes/custom/byte_theme/components/button/ und web/themes/custom/byte_theme/components/card/ — dort Twig-Render-Tests über ddev exec ./vendor/bin/phpunit --group <sdc>.

Out of Scope

• Hover- und Focus-States für die 5 neuen Varianten — Figma zeigt keine Hover-Varianten für Badge-Elemente.
• Link-Verhalten (url-Prop) in Kombination mit den neuen Varianten — der Prop bleibt erhalten, aber keine neue Figma-Spec dafür.
• Icon-Support in den neuen Varianten — kein Figma-Äquivalent vorhanden.
• DB-Migration oder Update-Hook für bestehende Canvas-Blöcke — der Twig-Fallback übernimmt das.
• Responsive-Breakpoint-Unterschiede für Badge-Größen — Figma spezifiziert keine Breakpoint-Varianten.
• Barrierefreiheits-Anpassungen (aria-label, Kontrastprüfung) — sind für ein separates A11y-Ticket vorgesehen.

Further Notes

• Die matching-Variante ist inhaltlich für Bewerber-Passungs-Badges konzipiert (Figma-Node 61121:32532). Zukünftige Entity-Bindings sollten abbreviation an ein Kurztext-Feld und percentage an ein Integer-Feld binden.
• Nach dem Build (npm run build) muss überprüft werden, dass Tailwind die neuen arbiträren Klassen (text-[15px], text-[19px], rounded-[10px], rounded-[20px], gap-[4px], px-[4px], px-[8px], py-[4px]) in build/main.min.css aufnimmt — sofern diese nicht durch andere Komponenten bereits referenziert sind.
• Story-Hub mit vollständigem QA-Plan: docs/stories/P2503-157-badge-sdc-solcom-varianten.html
• Design-Mapping-Eintrag (Node 61121:32532) ist nach der Implementierung auf matched zu setzen.