Atlassian veröffentlicht DESIGN.md – Erkenntnisse aus Praxistests mit portablem Design-Kontext

• Ein portables Markdown-Format, um das Problem von „Slop“ zu lösen, bei dem KI-generierte UIs ohne Markenidentität generisch wirken: Die Kernelemente eines Designsystems werden in einer Datei gebündelt und in Prompts eingebunden
• DESIGN.md besteht aus zwei Teilen: maschinenlesbaren Design Tokens und einer für Menschen und Agenten lesbaren Design-Begründung (Rationale). Es enthält nicht die vollständige technische Spezifikation des Systems, sondern dessen Absicht (Intent)
• Beim Einsatz in einer Demo zur Dashboard-Erstellung mit Figma Make auf der Team-'26-Keynote wurden Farben, Abstände, Formen und Typografie am Atlassian-System ausgerichtet; gute Leistung bei One-Shot-Prototypen
• In Produktions-Codebases verbrauchte es jedoch rund 92 % mehr Tokens als der eigene MCP-Server und Skills, verlängerte die Generierungszeit und zeigte etwa 2,7-mal stärkere Schwankungen beim Token-Verbrauch zwischen Läufen
• Seine besonderen Stärken – Portabilität und Kompaktheit – sind wertvoll für Cross-Plattform-Portierung, Customer Theming und Prototyping in neuen Umgebungen; es positioniert sich als Ergänzung, nicht als Ersatz für umfangreiche Designsystem-Tools

---

Hintergrund – das „Slop“-Problem von KI-UIs

• Wenn KI UIs generiert, ähneln sich die Ergebnisse oft: Gradient-Buttons, Überschriften in Großbuchstaben, generische Kartenlayouts, unnötige Hover-Animationen. Die Funktionalität ist vorhanden, aber die visuelle Identität fehlt
• Die Design-Community bezeichnet solche Ergebnisse als „Slop“: funktionale Ausgaben ohne bewusste Designentscheidungen
• Ursache ist fehlender Kontext zu Marke, Komponenten und Patterns. Die KI erzeugt Standardausgaben auf Basis von Durchschnittswerten aus den Trainingsdaten → „Generic in, generic out“
• Das Atlassian-Designsystem-Team baut für das KI-Zeitalter eine Context Engine auf und stellt Agenten über den ADS MCP Server sowie detaillierte AI Skills umfangreichen Designkontext bereit
  • Dadurch wurden geringere KI-Token-Kosten sowie bessere Genauigkeit und Qualität der Ergebnisse bestätigt, die Tausende Produktentwickler erzeugen

Überblick über DESIGN.md

• Ein von Google für das eigene Designtool Stitch entworfenes Open-Source-Markdown-Format, ein portabler Snapshot der Marke und UI-Patterns eines Teams
• Das Funktionsprinzip ist einfach: Wird die Datei in einen Prompt eingebunden, beginnen generierte Ergebnisse wie das eigene Produkt auszusehen

• Was es ist (What it is)

  • Eine portable Markdown-Datei, die nur die Kernelemente eines Designsystems beschreibt
  • Der erste Teil listet maschinenlesbare Design Tokens auf
  • Der zweite Teil beschreibt für Menschen und Agenten lesbar die Design-Begründung zu Farben, Abständen, Layout, Elevation, Komponenten usw.

• Was es nicht ist (What it isn't)

  • Es ist keine vollständige technische Spezifikation dazu, wie ein Designsystem in Produktion funktioniert, und enthält nicht alle Details des Systems
  • Bestehende Codebibliotheken, Linter zur Einhaltung von Coding Standards oder detaillierte Design-Spezifikationen aus Figma sind nicht enthalten
  • Die Spezifikation definiert dieses Format nicht als vollständige Systembeschreibung, sondern als Erfassung der Absicht (Intent)

Aufbau einer eigenen DESIGN.md

• Atlassian hatte sein Designsystem bereits über den MCP-Server, eine strukturierte Content-Pipeline und verschiedene Agent Skills für den KI-Konsum vorbereitet
• Die eigene DESIGN.md wurde aus derselben strukturierten Content-Pipeline generiert, die MCP und Agent Skills antreibt
• Das Format wurde in gängigen Vibe-Coding-Tools getestet; für häufige Fehler, die in bestehenden Leitfäden nicht abgedeckt waren, wurden strengere Anweisungen ergänzt

Test auf der Team '26

• Die vor einem Monat in Anaheim abgeschlossene Team-'26-Keynote-Demo diente als passender Testfall
• In einer Keynote-Demo erzeugte Figma Make mithilfe des Teamwork Graph ein maßgeschneidertes Dashboard; Ziel war es, die Designsprache in einem Durchlauf auszurichten, ohne sich auf interne MCP-Server und Tools zu stützen
• Mit DESIGN.md wandelte sich der übliche „Slop“ in ein erkennbares Atlassian-Ergebnis: erwartete Farben, Abstände, Formen und Typografie wurden verwendet, und Komponenten erhielten eine systemkonforme Elevation
• Die High-Level-Anweisungen und Spezifikationen der Datei eignen sich gut, um gemeinsame Bibliotheken wie Tailwind und Shadcn anzupassen und damit UIs von Grund auf zu erstellen

Trade-offs beim Einsatz in Produktion

• Produktions-Codebases unterscheiden sich stark von isolierten Umgebungen, die von Grund auf neu entstehen: Dort gibt es bestehende Token- und Komponentenbibliotheken sowie strenge Lint-Regeln und Type Checks
• Bei einer einfachen Aufgabe wie einem Login-Bildschirm verbrauchte DESIGN.md als alleiniger Designleitfaden rund 92 % mehr Tokens, benötigte längere Generierungszeiten und zeigte etwa 2,7-mal stärkere Schwankungen beim Token-Verbrauch zwischen Läufen
  • Zugleich wird klargestellt, dass diese Ergebnisse nicht endgültig sind und je nach Modell, Prompt, Designsystem, Umgebung und Qualität des Kontexts variieren können

• Grenze 1 – Kontext wird nicht on demand, sondern auf einmal übergeben

  • Der MCP-Server holt per Tool Call wie ads_plan nur die Anweisungen für bestimmte Komponenten on demand ab
  • Dadurch wird vermieden, bei schweren Bereichen wie Hunderten Icons oder umfangreichen semantischen Design Tokens unnötige Elemente zu laden
  • DESIGN.md lädt jedes Mal die gesamte Datei, was von Beginn an höhere Kosten und langsamere Antworten verursacht; bei wenigen Turns kann abgeschnittener Kontext die Genauigkeit verringern

• Grenze 2 – Eine kurze Datei führt zu Kontextverlust

  • Ein Designsystem ist ein komplexes Gebilde, das die gemeinsame Sprache von Tausenden Views, Figma-Dateien und Frontend-Komponenten verdichtet
  • On-Demand-MCP und Skills wurden auf etwa 2,5 MB Anweisungen destilliert; DESIGN.md muss deutlich stärker reduziert werden, weil es auf einmal geladen wird
  • Die resultierende Datei ist 80 KB groß und umfasst rund 19.800 LLM-Tokens (ohne Frontmatter rund 10.700), was im Vergleich zu Community-Beispielen eher groß ist
  • Um diese Größe zu erreichen, wurden große Teile der Nutzungsanweisungen für mehr als 50 Komponenten entfernt, grundlegende Anweisungen stark gekürzt und einige selten genutzte Design Tokens gelöscht
  • Wegen des fehlenden Kontexts wurde beobachtet, dass Agenten mit Produktionsqualität als Ziel ungenauer werden oder selbst Kontext sammeln, etwa indem sie Komponentenimplementierungen direkt lesen, um nicht spezifizierte Nutzungsanweisungen zu finden

• Grenze 3 – Die Spezifikation legt das Innere des Designsystems offen

  • DESIGN.md ist ein portabler Snapshot, der ein Designsystem in Prosa neu formuliert; Ziel ist es, Prinzipien, Spezifikationen und Anweisungen bereitzustellen, um das System von Grund auf nachzubauen
  • In etablierten Produktionsumgebungen sind diese Informationen unnötig oder verleiten Agenten dazu, Technical Debt zu erzeugen, besonders bei Komponenten
  • Statt alle Details des Button-Stylings (backgroundColor, textColor, borderColor usw.) zu lesen und zu interpretieren, ist es wünschenswert, eine bestehende Komponente zu importieren und zu verwenden
    • Beispiel: import Button from '@atlaskit/button'; und anschließend <Button appearance="primary" spacing="compact" />
  • Die Nutzung geteilter Komponenten ist entscheidend für Wartbarkeit: Wird ein Button an einer Stelle geändert, wirkt sich das auf die gesamte Codebase aus und Code Reviews sowie Wartung werden einfacher
  • DESIGN.md lässt Code-Anweisungen bewusst aus und liefert nur Spezifikationen zur Reimplementierung; in Tests führte das eher dazu, dass bestehende Systeme nicht genutzt, sondern Komponenten neu erstellt wurden
  • MCP-Server und Skills bieten auf Basis der technischen Grundlage eine bessere Abstraktionsebene: Sie erklären die Nutzung des bestehenden Systems statt dessen Reimplementierung
  • In Kombination mit Lint-Regeln, die Coding Standards ohne Token-Verbrauch erzwingen, entsteht für Agenten eine positive Feedback-Schleife

Wo DESIGN.md am nützlichsten ist

• Künstlerische Richtung auf hoher Ebene (High-level artistic direction)

  • Die einfachste DESIGN.md konzentriert sich auf die visuelle Richtung und das Gefühl eines Systems; wenn dies bisher nicht dokumentiert wurde, ist sie ein nützliches Ergebnis
  • Allerdings dupliziert das Frontmatter Inhalte, die bereits in der Codebase vorhanden sind

• Schnelles Prototyping in unvertrauten Umgebungen

  • Bei Blue-Sky-Prototyping oder Tests neuer Tools hilft es, markenkonforme UIs zu erzeugen, ohne den gesamten Tech Stack aufzusetzen oder sich mit Einschränkungen bestehender Komponenten zu befassen

• Interoperabilität mit Designtools (Interoperability)

  • Einige KI-Tools setzen UIs zusammen, indem sie vorgefertigte Komponenten anpassen, die auf eine Designsprache ausgerichtet sind; DESIGN.md liefert dafür Anweisungen auf passender Ebene

• Customer Theming für adaptive UIs (Customer theming)

  • Bei Produkten, die dynamische Interfaces wie Reports, Charts oder Dashboards erzeugen müssen, kann DESIGN.md Kunden helfen, ihre eigene Marke einfach zu beschreiben, sodass KI-Ausgaben wie ihre Kundenmarke wirken
  • Denkbar ist eine Option, bei der Admins oder Brand Teams die Datei in ihre Arbeitswerkzeuge hochladen
• Gemeinsam ist diesen Szenarien, dass es um agentengenerierte UIs in Umgebungen geht, in denen die Ausgabe des bestehenden Designsystems nicht verfügbar oder unpraktisch ist

Einstieg und Beitrag zum Standard

• Atlassian möchte den Standard nicht nur reaktiv übernehmen, sondern mitgestalten, und hat seine DESIGN.md-Datei unter atlassian.design/DESIGN.md veröffentlicht
• Die eigene Datei weicht derzeit teilweise vom Standard ab, enthält nicht standardisierte Eigenschaften für Komponenten-Rendering, und da der Standard kein Theming unterstützt, wird eine separate Dark-Mode-Variante bereitgestellt
• Feedback wurde auf GitHub geteilt, einige Vorschläge wurden bereits in die Spezifikation übernommen; die gesamte Branche wird zur Beteiligung ermutigt

Fazit

• DESIGN.md ist als Snapshot eines Designsystems ein nützliches portables Format, aber kein Ersatz für umfangreichere Designsystem-Tools
• Wenn Agenten MCP oder Skills unterstützen, liefern diese zu geringeren Kosten bessere Ergebnisse
• Bei Cross-Plattform-Portierung, Customer Theming und Blue-Sky-Prototyping bietet eine gut strukturierte DESIGN.md spürbare Verbesserungen
• Wenn Designsysteme für KI lesbar werden, profitiert das gesamte Ökosystem