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 Grenze 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 das aussehen“, sondern „wer ist dafür verantwortlich, wie es aussieht“.

Das Stripe Apps UI-Toolkit bietet einen Komponentensatz (Views, Layout, Navigation, Content, Formulare, Charts) sowie ein Box-Primitiv mit einer css-Prop. Die css-Prop wirkt wie ein Styling-Escape-Hatch, 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 von Constraints für die Komponentenhierarchie: 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, da die Prop diesen Wert nicht akzeptiert. Das ist eine weitaus stärkere Garantie als eine Linting-Regel und eine unendlich stärkere als ein Absatz in einem Wiki. Wenn man ein System pflegt, das von Mitwirkenden ü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 kollidieren sollen, sind damit erledigt.

   Copy

   const appearance = { theme: 'night' }

2. 2

   Variablen setzen

   Ein kleiner Satz von 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 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 erfordert 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 sie zu veröffentlichen, ist die richtige Entscheidung. 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 das eigene 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 ist, dass die Strategie von Stripe Apps stärker wird, während die von Elements an Bedeutung verliert.

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 Prosa formuliert: Man kann einem Agenten keinen Typfehler übergeben, aber man kann ihm sagen, was einer wäre. Auch der Ansatz von Elements lässt sich als Anordnung übertragen: Zuerst die Standardwerte auf Theme-Ebene angeben, dann die Tokens und schließlich die spezifischen Ausnahmen. So stößt ein Modell, das von oben nach unten liest, zuerst auf die allgemeine Regel und erst danach auf den Sonderfall.

Die meisten Teams, die ein Designsystem entwickeln, wählen eine einzige Strategie und wenden diese überall an. Die Dokumentation von Stripe zeigt, dass die Strategie der Grenzziehung folgen sollte. Auf Oberflächen, für die Sie verantwortlich sind, schließen Sie das Vokabular ab und machen Verstöße unmöglich. Auf Oberflächen, für die jemand anderes verantwortlich ist, bieten Sie eine Leiter an und lassen die Nutzer nur so weit steigen, wie es absolut notwendig ist.

Die meisten Produkte haben beide Arten von Oberflächen. Das interne Admin-Tool und das einbettbare Widget sind nicht dasselbe Designproblem; ein einziges System mit nur einer Anpassungsstrategie würde eines von beiden schlecht bedienen.