Stripes zwei Designsysteme und warum sie gegensätzlich sind

Die eigenen Produktflächen von Stripe – das Dashboard, die Marketing-Seite, die Dokumentation – basieren auf einem internen System, das im Laufe der Jahre unter verschiedenen Namen bekannt war und nie als öffentliches Paket veröffentlicht wurde. Es gibt kein npm install, kein Storybook, keinen Token-Export. Falls Sie danach gesucht haben: Es ist nicht verfügbar, und Rekonstruktionen durch Dritte basieren lediglich auf Schlussfolgerungen aus Screenshots.

Was Stripe veröffentlicht und gründlich dokumentiert, sind zwei Systeme für Entwickler, die eine Integration mit Stripe vornehmen. Diese werden meist separat diskutiert, da sie an unterschiedlichen Stellen der Dokumentation stehen. Zusammen gelesen bilden sie eine kleine Masterclass in Bezug auf die Grenzen von Designsystemen.

Die Trennlinie zwischen beiden ist nicht technischer Natur. Es ist eine Vertrauensgrenze. Wenn die UI auf der Oberfläche von Stripe liegt, kann Stripe nicht zulassen, dass eine schlecht gestaltete Drittanbieter-App das Dashboard fehlerhaft aussehen lässt – daher wird diese Möglichkeit entfernt. Wenn die UI von Stripe auf der eigenen Oberfläche liegt, würde ein Zahlungsformular, das das eigene Design ignoriert, wie ein Sicherheitsproblem wirken; deshalb gibt Stripe die Kontrolle ab. Gleiches Unternehmen, gleiche Designwerte, gegensätzliche Standardeinstellungen – denn die Frage ist nicht „wie soll es aussehen“, sondern „wer ist dafür verantwortlich, wie es aussieht“.

Das Stripe Apps UI-Toolkit bietet einen Satz an Komponenten – Views, Layout, Navigation, Content, Formulare, Charts – sowie ein Box-Primitiv mit einer css-Prop. Die css-Prop sieht wie ein Styling-Escape-Hatch aus, ist es aber nicht. Sie akzeptiert benannte Tokens und nichts anderes.

<Box css={{
  stack: 'y',
  gap: 'medium',
  padding: 'large',
  backgroundColor: 'surface',
  borderRadius: 'medium',
}} />

// gap: 'medium'  ✅  a token
// gap: '17px'    ❌  not in the vocabulary

Das Spacing-Vokabular besteht aus sieben Stufen und einer Null, dokumentiert mit festen Pixelwerten: xxsmall 2px, xsmall 4px, small 8px, medium 16px, large 24px, xlarge 32px, xxlarge 48px. Die Größen sind fraktional – Halbe, Drittel, Viertel, Fünftel, Sechstel, Zwölftel, plus fill – mit inhaltsbasierten min-, max- und fit-Optionen.

Der interessante Teil ist das, was über Box hinausgeht. Komponenten außer Box und Inline besitzen vordefinierte Styles, und die Dokumentation stellt explizit klar, dass einige davon überhaupt nicht überschrieben werden können – eine Komponente, die ihr Aussehen basierend auf den implementierten Callbacks ändert, lässt dies nicht zu, da das Aussehen eine Bedeutung trägt. Andere bieten ein kleines Enum an: Button hat primary, den Standardwert und destructive – das ist die vollständige Liste. Einige wenige bieten eine einzige Eigenschaft an, wie Icon, das fill akzeptiert.

Es gibt zudem einen dokumentierten Satz an Constraints für die Komponenten-Hierarchie – Regeln darüber, welche Komponenten welche enthalten dürfen. Das ist das Layout-Äquivalent derselben Idee: kein Ratschlag für eine gute Struktur, sondern eine Einschränkung, die eine schlechte Struktur scheitern lässt, anstatt sie in die Produktion zu bringen.

Fast jedes Designsystem ist ein Dokumentationsprojekt. Es besagt, man solle die Tokens verwenden, liefert dann aber eine className-Prop aus, die alles akzeptiert. Sechs Monate später enthält die Hälfte der Codebasis willkürliche Hex-Werte, weil jemand an einem Freitag in Eile war.

Stripe Apps entfernt diese Option. Es gibt keinen Weg von „in Eile“ zu #3c82f6, weil die Prop diesen Wert nicht akzeptiert. Das ist eine wesentlich stärkere Garantie als eine Linting-Regel und eine unendlich stärkere als ein Absatz in einem Wiki. Wenn Sie ein System pflegen, das Entwickler überleben muss, die die Dokumentation nicht gelesen haben – was auf alle zutrifft –, dann ist dies der richtige Weg.

Die Appearance API löst das gegenteilige Problem. Ein Zahlungsformular muss sich auf einer Website, die niemand bei Stripe jemals gesehen hat, nativ anfühlen, während Stripe aus Gründen der Conversion und Compliance das Layout kontrolliert. Stripes Antwort ist eine Leiter mit drei Sprossen, und die Dokumentation rät dazu, diese der Reihe nach zu erklimmen.

1. 1

   Ein Theme wählen

   Drei vorgefertigte Startpunkte – stripe, night, flat. Eine Zeile Code, und die meisten Integrationen, die lediglich nicht optisch kollidieren sollen, sind damit erledigt.

   Copy

   const appearance = { theme: 'night' }

2. 2

   Variablen setzen

   Ein kleiner Satz an Werten, die überall durchschlagen. Dies ist die Token-Ebene, und hier findet der Großteil der eigentlichen Anpassung statt.

   Copy

   const appearance = {
     theme: 'stripe',
     variables: {
       colorPrimary: '#0570de',
       colorBackground: '#ffffff',
       colorText: '#30313d',
       colorDanger: '#df1b41',
       fontFamily: 'Ideal Sans, system-ui, sans-serif',
       spacingUnit: '2px',
       borderRadius: '4px',
     },
   }

3. 3

   Regeln hinzufügen, nur wenn es immer noch nötig ist

   Ein Mapping von CSS-ähnlichen Selektoren auf CSS-Properties, das einzelne Komponenten und Zustände erreicht. Dies ist der Escape-Hatch, und er steht bewusst an letzter Stelle.

   Copy

   const appearance = {
     rules: {
       '.Tab': { border: '1px solid #E0E6EB' },
       '.Tab:hover': { color: 'var(--colorText)' },
       '.Tab--selected': { borderColor: '#E0E6EB' },
     },
   }

Die Reihenfolge ist das Design. Jede Sprosse ist mächtiger und wartungsintensiver als die darunterliegende, und die Dokumentation drängt einen die Leiter hinunter statt hinauf. Ein Team, das bei rules beginnt, schreibt vierzig Selektoren und muss diese für immer pflegen; ein Team, das bei theme beginnt, schreibt eine Zeile und steigt nur dann tiefer ab, wenn es absolut notwendig ist.

Unter den Variablen verdienen zwei besondere Aufmerksamkeit, da sie abgeleitete Basen statt fester Werte sind. spacingUnit wird als die Basiseinheit beschrieben, von der alle anderen Abstände abgeleitet werden – erhöht man sie, wird die gesamte Komponente großzügiger. fontSizeBase legt die Wurzelgröße fest, und die anderen Schriftgrößen-Variablen skalieren in rem davon aus.

Vergleichen Sie dies mit dem üblichen Ansatz, bei dem ein Designsystem --space-1 bis --space-12 als zwölf unabhängige, hartcodierte Werte veröffentlicht. Beides liefert eine Skala. Nur eines liefert einen Regler. Wenn ein Kunde ein kompakteres Formular benötigt, ist die abgeleitete Version eine einzige Zahl; die enumerierte Version bedeutet zwölf Änderungen und eine Einzelfallentscheidung für jede davon.

/* Enumerated: twelve values, twelve things to change */
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
/* ... */

/* Derived: one dial */
--space-unit: 4px;
--space-1: calc(var(--space-unit) * 1);
--space-2: calc(var(--space-unit) * 2);
--space-3: calc(var(--space-unit) * 3);

Die Dokumentation der Appearance API stellt fest, dass colorPrimary, colorBackground, colorText, colorSuccess, colorDanger und colorWarning keine rgba()- oder var(--myVariable)-Syntax unterstützen, während andere Variablen dies tun. Zudem wird darauf hingewiesen, dass die API nicht für einzelne Payment-Method-Elements wie CardElement gilt, die ein separates Style-Objekt verwenden.

Das sind unspektakuläre Inkonsistenzen, und es ist die richtige Entscheidung, sie zu veröffentlichen. Eine Anpassungs-API, die bei einer Teilmenge von Eingaben stillschweigend fehlschlägt, kostet einen Integrator einen Nachmittag verwirrten Debuggings; eine, die dies in einer Tabelle vermerkt, kostet ihn dreißig Sekunden. Wenn Ihr eigenes System eine Regel hat, die nur an einigen Stellen funktioniert, gehört diese Information in die Dokumentation, nicht in das Changelog.

Beide Systeme wurden für menschliche Entwickler entworfen, die Dokumentationen lesen. Die interessante Frage für 2026 ist, was sich ändert, wenn der Entwickler ein Coding-Agent ist. Die Antwort lautet: Der Ansatz von Stripe Apps wird stärker, während der Ansatz von Elements schwächer wird.

Ein Agent hat keinen Anreiz, an einem Freitag Abkürzungen zu nehmen, aber er hat auch keine Erinnerung an Ihre Konventionen zwischen den Sessions. Geben Sie ihm ein geschlossenes Vokabular, und er wird dieses Vokabular zuverlässig und für immer verwenden. Geben Sie ihm eine className-Prop und einen Absatz mit dem Hinweis „bevorzugen Sie die Tokens“, und er wird die Tokens etwa so oft verwenden wie die Trainingsdaten es tun – das heißt: manchmal.

Wir haben 299 DESIGN.md-Dateien analysiert, die für AI-Agenten veröffentlicht wurden. 86 % gaben Farben als reine Hex-Werte ohne semantische Rolle an, und 76 % enthielten keinerlei Verbote. Diese beiden Zahlen beschreiben eine Datei, die einem Modell sagt, welche Farben existieren, aber nichts darüber, was sie bedeuten oder was verboten ist – das genaue Gegenteil beider Stripe-Systeme, bei denen es fast ausschließlich um Bedeutung und Einschränkung geht.

Das ist der Ansatz von Stripe Apps, in Worte gefasst: Man kann einem Agenten keinen Typfehler übermitteln, aber man kann ihm sagen, was ein solcher wäre. Auch der Ansatz von Elements lässt sich übertragen, etwa als Hierarchie: Zuerst die Standardwerte auf Theme-Ebene, dann die Tokens, dann die spezifischen Ausnahmen. So stößt ein Modell, das den Text von oben nach unten liest, zuerst auf die allgemeine Regel und erst danach auf den Sonderfall.

Die meisten Teams, die ein Designsystem entwickeln, entscheiden sich für eine einzige Strategie und wenden diese überall an. Die Dokumentation von Stripe zeigt jedoch, dass die Strategie der Grenzziehung folgen sollte. Auf Oberflächen, für die man selbst verantwortlich ist, sollte das Vokabular geschlossen sein, um Verstöße unmöglich zu machen. Auf Oberflächen, für die jemand anderes verantwortlich ist, sollte man eine Leiter bereitstellen und den Nutzern erlauben, nur so weit aufzusteigen, wie es absolut notwendig ist.

Die meisten Produkte verfügen über beide Arten von Oberflächen. Ein internes Admin-Tool und ein einbettbares Widget sind unterschiedliche Design-Probleme; ein einziges System mit nur einer Anpassungsstrategie wird eines von beiden unzureichend bedienen.