Los dos sistemas de diseño de Stripe y por qué difieren

Las propias interfaces de producto de Stripe —el Dashboard, el sitio de marketing, la documentación— funcionan con un sistema interno que a lo largo de los años ha recibido diversos nombres y que nunca se ha distribuido como un paquete público. No existe un npm install, ni Storybook, ni exportación de design tokens. Si es eso lo que busca, no está disponible, y cualquier reconstrucción de terceros se basa en inferencias a partir de capturas de pantalla.

Lo que Stripe sí publica, y documenta exhaustivamente, son dos sistemas dirigidos a desarrolladores que se integran con Stripe. Normalmente se analizan por separado porque se encuentran en secciones distintas de la documentación. Leídos en conjunto, constituyen una pequeña clase magistral sobre los límites de un sistema de diseño.

La línea que los separa no es técnica. Es un límite de confianza. Cuando su interfaz de usuario reside en la superficie de Stripe, Stripe no puede permitir que una aplicación de terceros con un estilo deficiente haga que el Dashboard parezca roto, por lo que elimina esa capacidad. Cuando la interfaz de usuario de Stripe reside en su superficie, un formulario de pago que ignore su diseño parecería un problema de seguridad, por lo que Stripe cede el control. Misma empresa, mismos valores de diseño, valores predeterminados opuestos, porque la pregunta no es «cómo debería verse esto», sino «quién es responsable de su apariencia».

El toolkit de UI de Stripe Apps le proporciona un conjunto de componentes —vistas, diseño, navegación, contenido, formularios, gráficos— además de una primitiva Box con una propiedad css. La propiedad css parece una vía de escape de estilo, pero no lo es. Acepta tokens con nombre y nada más.

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

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

El vocabulario de espaciado consta de siete pasos y un cero, documentado con valores de píxeles fijos: xxsmall 2px, xsmall 4px, small 8px, medium 16px, large 24px, xlarge 32px, xxlarge 48px. El dimensionamiento es fraccionario —mitades, tercios, cuartos, quintos, sextos, doceavos, además de fill— con opciones de min, max y fit basadas en el contenido.

Lo interesante es lo que ocurre por encima de Box. Los componentes que no son Box ni Inline incluyen estilos predefinidos, y la documentación especifica que algunos de ellos no se pueden anular en absoluto: un componente que cambia su apariencia según los callbacks que implemente no permitirá contradecir dicho comportamiento, ya que la apariencia transmite un significado. Otros exponen un enum reducido: Button tiene primary, el valor predeterminado y destructive, y esa es la lista completa. Algunos pocos exponen una sola propiedad, como Icon, que acepta fill.

También existe un conjunto documentado de restricciones en la jerarquía de componentes: reglas sobre qué componentes pueden contener a cuáles. Es el equivalente de diseño de la misma idea: no es un consejo sobre una buena estructura, sino una restricción que hace que una mala estructura falle en lugar de publicarse.

Casi todos los sistemas de diseño son proyectos de documentación. Dicen que use los tokens y luego entregan una propiedad className que acepta cualquier cosa, y seis meses después la mitad del código base tiene valores hex arbitrarios porque alguien tenía prisa un viernes.

Stripe Apps elimina esa opción. No hay un camino desde «tener prisa» hasta #3c82f6, porque la propiedad no lo aceptará. Esa es una garantía mucho más sólida que una regla de linting y una infinitamente más fuerte que un párrafo en una wiki. Si mantiene un sistema que tiene que sobrevivir a colaboradores que no leyeron la documentación —que son todos ellos—, este es el camino a seguir.

La Appearance API resuelve el problema opuesto. Un formulario de pago tiene que sentirse nativo en un sitio que nadie en Stripe ha visto, manteniendo al mismo tiempo un diseño que Stripe controla por razones de conversión y cumplimiento. La respuesta de Stripe es una escalera con tres peldaños, y la documentación le indica que debe subirla en orden.

1. 1

   Elija un tema

   Tres puntos de partida preconstruidos: stripe, night, flat. Una línea, y la mayoría de las integraciones que solo necesitan no chocar con el diseño original quedan resueltas aquí.

   Copy

   const appearance = { theme: 'night' }

2. 2

   Configure las variables

   Un pequeño conjunto de valores que se propagan por todas partes. Esta es la capa de tokens, y es donde ocurre la mayor parte de la personalización real.

   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

   Añada reglas, solo si todavía lo necesita

   Un mapa de selectores de tipo CSS a propiedades CSS, que llega a componentes y estados individuales. Esta es la vía de escape, y está deliberadamente al final.

   Copy

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

El orden es el diseño. Cada peldaño es más potente y más costoso de mantener que el inferior, y la documentación le empuja hacia abajo en la escalera en lugar de hacia arriba. Un equipo que comienza en rules escribe cuarenta selectores y es dueño de ellos para siempre; un equipo que comienza en theme escribe una línea y solo desciende cuando realmente es necesario.

Entre las variables, dos merecen atención porque son bases derivadas en lugar de valores. spacingUnit se describe como la unidad base de la que deriva todo el demás espaciado: si la aumenta, todo el componente se vuelve más espacioso. fontSizeBase establece el tamaño raíz, y las demás variables de tamaño de fuente escalan a partir de ella en rem.

Compare eso con el enfoque habitual, donde un sistema de diseño publica desde --space-1 hasta --space-12 como doce valores independientes codificados de forma fija. Ambos le ofrecen una escala. Solo uno le ofrece un dial. Si un cliente necesita un formulario más denso, la versión derivada es un único número; la versión enumerada requiere doce ediciones y un juicio subjetivo en cada una.

/* 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);

La documentación de la Appearance API establece que colorPrimary, colorBackground, colorText, colorSuccess, colorDanger y colorWarning no admiten la sintaxis rgba() o var(--myVariable), mientras que otras variables sí la admiten. También señala que la API no se aplica a Elements de métodos de pago individuales como CardElement, que utilizan un objeto Style independiente.

Esas son inconsistencias poco glamurosas, y publicarlas es la decisión correcta. Una API de personalización que falla silenciosamente en un subconjunto de entradas le cuesta a un integrador una tarde de depuración confusa; una que lo indique en la tabla les cuesta treinta segundos. Si su propio sistema tiene una regla que solo funciona en algunos lugares, la documentación es donde debe estar, no el registro de cambios.

Ambos sistemas fueron diseñados para desarrolladores humanos que leen documentación. La pregunta interesante en 2026 es qué cambia cuando el desarrollador es un agente de código, y la respuesta es que la postura de Stripe Apps se fortalece mientras que la de Elements se debilita.

Un agente no tiene incentivos para tomar atajos un viernes, pero tampoco tiene memoria de sus convenciones entre sesiones. Dele un vocabulario cerrado y lo usará, de forma fiable, para siempre. Dele una propiedad className y un párrafo que diga «prefiera los tokens» y usará los tokens aproximadamente con la misma frecuencia con la que lo hace el conjunto de datos de entrenamiento, es decir, a veces.

Muestreamos 299 archivos DESIGN.md publicados para que los lean agentes de IA. El 86% especificaba colores como valores hex puros sin ningún rol semántico asociado, y el 76% no contenía ninguna prohibición en absoluto. Esos dos números describen un archivo que le dice a un modelo qué colores existen y nada sobre lo que significan o lo que está prohibido; exactamente lo contrario de ambos sistemas de Stripe, que tratan casi por completo sobre significado y restricción.

Esa es la idea de Stripe Apps trasladada a prosa: no se puede darle a un agente un error de tipo, pero se le puede decir qué sería uno. La idea de Elements también se transfiere como un orden: declarar primero los valores predeterminados a nivel de tema, luego los tokens y, por último, las excepciones específicas, para que un modelo que lea de arriba abajo encuentre la regla general antes que el caso especial.

La mayoría de los equipos que crean un sistema de diseño eligen una postura y la aplican en todas partes. La documentación de Stripe es una demostración de que la postura debe seguir el límite. En las superficies de las que usted es responsable, cierre el vocabulario y haga que las infracciones sean imposibles. En las superficies de las que es responsable otra persona, publique una escala y permita que suban solo hasta donde sea necesario.

La mayoría de los productos tienen ambos tipos de superficie. La herramienta de administración interna y el widget embebible no son el mismo problema de diseño, y un sistema único con una sola estrategia de personalización servirá mal a uno de ellos.