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

Las superficies de producto propias de Stripe (el Dashboard, el sitio de marketing, la documentación) funcionan con un sistema interno que ha recibido varios nombres a lo largo de los años y que nunca se ha lanzado como paquete público. No hay npm install, ni Storybook, ni exportación de tokens. Si es eso lo que busca, no está disponible, y las reconstrucciones de terceros son inferencias basadas en 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 Stripe reside en su superficie, un formulario de pago que ignore su diseño parecería un problema de seguridad, por lo que Stripe le 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 el responsable de cómo se ve".

El kit de herramientas 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 para el estilo, pero no lo es. Acepta design 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 niveles y un cero, documentados 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, más fill) con opciones de min, max y fit basadas en el contenido.

La parte interesante es lo que ocurre por encima de Box. Los componentes que no son Box ni Inline llevan estilos predefinidos, y la documentación es explícita al señalar que algunos de ellos no se pueden anular en absoluto: un componente que cambia de apariencia según los callbacks que implemente no le permitirá contradecir eso, porque 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 de jerarquía de componentes: reglas sobre qué componentes pueden contener a cuáles. Es el equivalente de diseño para la misma idea: no es un consejo sobre una buena estructura, sino una restricción que hace que una estructura incorrecta falle en lugar de publicarse.

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

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

La API de Appearance resuelve el problema opuesto. Un formulario de pago debe 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 de tres peldaños, y la documentación le indica que los suba en orden.

1. 1

   Elija un tema

   Tres puntos de partida predefinidos: stripe, night, flat. Una línea de código, y la mayoría de las integraciones que solo necesitan no desentonar quedan resueltas aquí.

   Copy

   const appearance = { theme: 'night' }

2. 2

   Defina variables

   Un conjunto reducido de valores que se propagan por todas partes. Esta es la capa de design 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 sigue siendo necesario

   Un mapa de selectores similares a CSS hacia propiedades CSS, llegando a componentes y estados individuales. Esta es la vía de escape, y deliberadamente es la última opción.

   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 anterior, y la documentación le empuja a bajar por la escalera en lugar de subirla. Un equipo que empieza por rules escribe cuarenta selectores y es dueño de ellos para siempre; un equipo que empieza por 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 derivan todos los demás espaciados: si se 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 esto con el enfoque habitual, donde un sistema de diseño publica desde --space-1 hasta --space-12 como doce valores independientes codificados. Ambos le dan una escala. Solo uno le da un dial de control. 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 una decisión subjetiva para 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 API de Appearance establece que colorPrimary, colorBackground, colorText, colorSuccess, colorDanger y colorWarning no admiten la sintaxis rgba() o var(--myVariable), mientras que otras variables sí lo hacen. 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.

Estas 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 al integrador una tarde de depuración confusa; una que lo indica en la tabla le cuesta treinta segundos. Si su propio sistema tiene una regla que solo funciona en algunos lugares, la documentación es donde debe figurar, 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 utilizará ese vocabulario, de forma fiable, para siempre. Dele una propiedad className y un párrafo que diga "prefiera los design tokens" y utilizará los tokens aproximadamente con la misma frecuencia que lo hacen los datos de entrenamiento, es decir, a veces.

Analizamos 299 archivos DESIGN.md publicados para que los lean agentes de IA. El 86% especificaba los colores como valores hexadecimales puros sin ningún rol semántico asociado, y el 76% no contenía prohibición alguna. Esos dos números describen un archivo que le dice al modelo qué colores existen, pero nada sobre qué significan o qué está prohibido: exactamente lo opuesto a ambos sistemas de Stripe, que tratan casi enteramente sobre el significado y la 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.