Architecture Decision Record · 0025

MAPPING.html: Figma-Status als zweite Dimension

TL;DR — docs/design/MAPPING.html bekommt zwei neue orthogonale Spalten: Figma-Status (ready-for-dev / wip / archived / -) und Jira Sub-Task (P2503-<n> oder leer). Die bestehende Status-Spalte (Implementierungs-Parity) bleibt unverändert. Tupel-Status-Werte wie gap-ready-for-dev werden verworfen.

Kontext

Das laufende Feature figma-ready-for-dev-to-jira (Plan 2026-05-11-002) braucht eine Möglichkeit, in docs/design/MAPPING.html festzuhalten:

  1. Figma-Readiness: Hat der Designer den Frame in Figma auf „Ready for Dev" gesetzt? (Figma-seitige Information, unabhängig vom Implementierungsfortschritt im Code.)
  2. Jira-Verknüpfung: Existiert bereits ein Jira-Sub-Task unter P2503-83 für diesen Frame? (Dient als Idempotenz-Anker — verhindert Duplicate-Sub-Tasks beim wiederholten Skill-Run.)

Beide Informationen sind orthogonal zur bestehenden Status-Spalte (matched / partial / gap / obsolete), die den Implementierungs-Parity-Stand abbildet. Ein Frame kann gleichzeitig gap sein (noch kein SDC) und ready-for-dev (der Designer hat ihn freigegeben) — das ist ein zulässiger, informativer Zustand, kein Widerspruch.

Bislang hat die MAPPING-Tabelle sechs Spalten: Figma-Frame / Figma-Node-ID / SDC / Komposition / Status / Last verified / Notes. Die Erweiterungsentscheidung ist nicht aus dem Code allein erschließbar und betrifft das Schema der zentralen Source-of-Truth für Design-Parity im Projekt. Ein ADR ist daher angemessen (Kriterium: hard-to-reverse + surprising-without-context + real-trade-off).

→ Weil die Entscheidung ≥ 2 Optionen mit echtem Trade-off hat, wurde vor dem ADR-Schreiben der customer-lens-reviewer-Agent konsultiert. Das Konsultations-Log steht im nächsten Abschnitt.

Reviewer-Konsultation

Konsultation des customer-lens-reviewer-Agents (2026-05-11) gemäß solcom-adr-workflow-Pflicht (≥ 2 Optionen). Entscheidungsfrage: Option A (Tupel-Werte in einer Spalte) vs. Option B (zwei orthogonale Spalten). Die Review wurde in zwei Etappen geführt: zuerst Lens-style Self-Review durch den S1-Implementations-Subagenten, danach validierende Konsultation des echten customer-lens-reviewer-Agents durch den Orchestrator. Beide Reviews empfehlen einstimmig Option B; die echte Konsultation hat zusätzlich den Edge-Case obsolete-Frame mit existierender Jira-Key als Kipp-Argument gegen Option A herausgearbeitet (siehe „Rejected alternatives").

Customer-Lens Review — Figma-Status-Schema in MAPPING.html

Optionen

  • Option A: Eine erweiterte Status-Spalte mit Tupel-Werten (gap-ready-for-dev, matched-wip, partial-archived usw.). Implementierungs-Status und Figma-Readiness werden in einem einzigen Wert codiert.
  • Option B: Zwei neue orthogonale Spalten: bestehende Status-Spalte bleibt unverändert, neue Spalte Figma-Status (ready-for-dev / wip / archived / -) plus neue Spalte Jira Sub-Task (P2503-Key oder leer).

Review-Matrix

Lens Option A Option B
Designer:innen (Figma-Mapping) ⚠️ Tupel-Werte erzeugen eine implizite Kreuzprodukt-Semantik, die in Figma kein Äquivalent hat. Der „ready-for-dev"-Zustand ist eine eigenständige Figma-Dimension (Dev Mode Marker), orthogonal zu Implementierungsgrad. Mischung in einem Wert verunklärt, welche Achse gerade kommuniziert wird. ✅ Klare 1:1-Entsprechung: Figma-Status spiegelt direkt den Figma-Dev-Mode-Marker. Designer können ihren Workflow-Status separat lesen, ohne ihn mit dem Implementierungsgrad zu verknüpfen.
Site-Builder:innen (SDC-UX) ❌ Tupel-Vokabular (gap-ready-for-dev, partial-archived) ist für Nicht-Entwickler nicht selbsterklärend. Die Tabelle würde zu einem Mapping von Mappings — mentaler Overhead steigt stark an. ✅ Jede Spalte hat genau eine Bedeutungsachse. Status beantwortet „Ist es gebaut?", Figma-Status beantwortet „Hat der Designer es freigegeben?", Jira Sub-Task beantwortet „Gibt es ein Ticket?". Drei einfache Fragen, drei Spalten.
Theme-Entwickler:innen (Code-Health) ⚠️ Das Status-Vokabular ist in der Skill-Doku (solcom-design-mapping/SKILL.md) als genau vier Werte festgelegt; Erweiterung auf Tupel würde die Regel „Erweiterung nur per ADR" formal einhalten, aber das Enum auf 4×4 = 16 mögliche Kombinationen aufblähen, von denen viele semantisch unsinnig sind (obsolete-ready-for-dev). Scanner- und Skill-Code müsste Tupel parsen statt zwei unabhängige Felder lesen. ✅ Scanner und Skill lesen zwei voneinander unabhängige Felder. Jede Spalte ist unabhängig nullable/leer. Kein Parsing-Overhead, keine unsinnigen Kombinationen. Migrations-Aufwand ist einmalig (leere <td>s einfügen), kein Rewrite bestehender Werte.

Rote Flaggen pro Option

Option A:

  • Variant-Wildwuchs: 4 Impl.-Status × 4 Figma-Status = 16 Tupel-Kombinationen. Mindestens 4 davon sind semantisch unsinnig (matched-archived impliziert, dass ein vollständig implementiertes SDC einen archivierten Figma-Frame referenziert — ein Zustand, der in der Praxis als obsolete geführt werden sollte, nicht als Tupel). Das Status-Vokabular verliert seine Eindeutigkeit.
  • Conditional-Props-Analogon: Im Tupel-Modell hängen die gültigen Werte der „zweiten Hälfte" implizit vom Status der „ersten Hälfte" ab — ein Constraint, den kein HTML-Schema enforcen kann.
  • Scanner-Komplexität: Der solcom-design-scanner-Agent müsste bei jedem Update sowohl Impl.-Status als auch Figma-Status lesen und neu kombinieren, statt die Felder unabhängig schreiben zu können.

Option B:

  • Tabellenbreite wächst um zwei Spalten. Bei >40 Rows kann das auf kleinen Viewports horizontales Scrollen erzwingen — kein funktionaler, aber ein visueller Nachteil.

Empfehlung: Option B — Zwei orthogonale Spalten, bestehende Status-Spalte unverändert.

Alle drei Linsen bewerten Option B besser. Der einzige Nachteil (Tabellenbreite) ist visuell, nicht funktional. Option A würde ein Status-Vokabular schaffen, das 16 Kombinationen hat, von denen viele semantisch leer sind — ein klares Zeichen für falsche Abstraktion.

Gegenargument zur Empfehlung

Das stärkste Argument für Option A: Wer nur die MAPPING-Tabelle liest (ohne Skill-Kontext), sieht bei Option B drei separate Spalten, ohne den kausalen Zusammenhang „gap + ready-for-dev → Jira-Sub-Task anlegen" sofort zu erkennen. Option A würde diesen Zusammenhang in der Spalte selbst codieren und so die Tabelle als Kommunikationsmittel dichter machen. Dieses Argument trägt jedoch nur, wenn die Tabelle primär von Menschen ohne Skill-Kontext gelesen wird — im vorliegenden Workflow ist der Hauptkonsument der Skill selbst, nicht der menschliche Leser.

Was nicht geprüft wurde

  • Performance-Impact breiterer Tabelle im Browser (vernachlässigbar bei statischem HTML).
  • Accessibility der erweiterten Tabelle (WCAG 2.1 AA für Datentabellen — kein akutes Problem, da die Tabelle keine komplexen Header-Verknüpfungen einführt).
  • Figma-API-Verfügbarkeit des readyForDev-Flags — das ist eine Slice-2-Frage, nicht eine Schema-Frage.

Entscheidung

docs/design/MAPPING.html erhält zwei neue orthogonale Spalten zwischen Status und Last verified: Figma-Status und Jira Sub-Task. Die bestehende Status-Spalte bleibt unverändert.

Das neue 8-Spalten-Schema:

<thead>
  <tr>
    <th>Figma-Frame</th>
    <th>Figma-Node-ID</th>
    <th>SDC / Komposition</th>
    <th>Status</th>          <!-- Implementierungs-Parity: matched|partial|gap|obsolete -->
    <th>Figma-Status</th>    <!-- NEU: ready-for-dev|wip|archived|- -->
    <th>Jira Sub-Task</th>   <!-- NEU: P2503-<n> | leer -->
    <th>Last verified</th>
    <th>Notes</th>
  </tr>
</thead>

Akzeptierte Werte für Figma-Status:

  • ready-for-dev — Frame in Figma als „Ready for Dev" markiert (Dev Mode Marker).
  • wip — Default für nicht-markierte Frames; Designer hat Frame noch nicht freigegeben.
  • archived — Frame aus Figma entfernt oder als deprecated markiert.
  • - — Status unbekannt (z.B. vor erstem Scanner-Update nach Migration).

Akzeptierte Werte für Jira Sub-Task:

  • P2503-<n> — Key des angelegten Sub-Tasks unter P2503-83.
  • Leer — Sub-Task noch nicht angelegt; Frame ist damit Pickup-Kandidat für den Skill figma-ready-for-dev-to-jira.

Migrations-Schritt (Slice 1): Alle bestehenden Rows in MAPPING.html erhalten zwei leere <td></td>. Bestehende Zellwerte werden nicht verändert. Die Befüllung übernimmt der solcom-design-scanner-Agent in Slice 2.

Hinweis zur Spaltenzahl: Das Plan-Dokument (2026-05-11-002-feat-figma-ready-for-dev-to-jira.html) nennt „7-Spalten-Schema" im Prosa-Text, zeigt aber in der Schema-Box Sektion 04 korrekt 8 Spalten. Die 8-Spalten-Zählung aus der Schema-Box ist kanonisch; die 7-Wording im Text ist ein Fehler im Plan-Dokument.

Rejected alternatives

  • Option A — Tupel-Status-Werte in der bestehenden Status-Spalte: Verworfen, weil das Status-Vokabular auf 16 Kombinationen (4 Impl.-Status × 4 Figma-Status) anwächst, von denen mindestens 4 semantisch unsinnig sind. Das Scanner-/Skill-Parsing wird komplexer, und die klare Achsentrennung (Implementierungsstand vs. Design-Freigabe) geht verloren. Reviewer-Empfehlung aus der Customer-Lens-Konsultation (2026-05-11) sprach sich einstimmig über alle drei Lenses gegen Option A aus. Zusätzlicher Kipp-Edge-Case (aus der validierenden Konsultation): Ein Frame im Zustand obsolete (SDC im Code deprecated) mit gleichzeitig existierender Jira-Sub-Task-Key (vor der Deprecation angelegt) braucht in Option A trotzdem eine separate Jira Sub-Task-Spalte — Option A landet damit bei 7 Spalten plus Tupel-Overhead, der einzige scheinbare Vorteil („weniger Spalten") löst sich auf.
  • Notes-Feld als Träger: Hätte keine Schema-Änderung erfordert, wäre aber weder maschinell lesbar noch idempotent. Der Skill müsste Free-Text in Notes parsen, statt ein definiertes Zellen-Feld lesen zu können.
  • Separate Tracking-Datei (z.B. docs/design/JIRA-LINKS.html): Hätte MAPPING-Drift eingeführt — zwei Dateien mit Zustand zum gleichen Frame müssten synchron gehalten werden. Die MAPPING.html ist bewusst die einzige Source-of-Truth für Frame-Level-Informationen.

Consequences

  • Skill-Doku (solcom-design-mapping/SKILL.md) muss auf 8-Spalten-Schema aktualisiert werden — Beispiel-Tabelle, Markdown-Referenz und Spalten-Regeln-Abschnitt werden in Slice 1 angepasst.
  • Bestehende MAPPING.html-Rows erhalten leere Spalten — einmaliger Migrations-Schritt, rückwärtskompatibel. Kein bestehender Wert wird verändert.
  • Scanner-Agent (solcom-design-scanner.md) muss erweitert werden (Slice 2): neuer Workflow-Schritt für Figma-Status-Ermittlung via Figma-API. Die Methode (ob mcp__claude_ai_Figma__get_metadata das readyForDev-Flag exponiert oder ein anderer Ansatz nötig ist) ist Gegenstand der Slice-2-Sondierung.
  • Skill figma-ready-for-dev-to-jira (Slice 3) kann die Jira Sub-Task-Spalte als Idempotenz-Anker nutzen: leere Zelle = Pickup-Kandidat, befüllte Zelle = bereits angelegt → kein Duplicate-POST.
  • Tabellenbreite: Die MAPPING-Tabelle wächst von 6 auf 8 Spalten. Auf kleinen Viewports kann horizontales Scrollen nötig sein. Das MAPPING-CSS hat aktuell kein overflow-x: auto — falls horizontales Scrollen stört, kann die Regel in einem separaten Schritt ergänzt werden.
  • Status-Vokabular-Erweiterungsregel (aus Skill-Doku: „Erweiterung nur per ADR") gilt analog für Figma-Status-Werte. Dieser ADR dokumentiert die initiale Wertmenge; spätere Erweiterungen brauchen einen neuen ADR.