Os dois design systems da Stripe e por que eles divergem

As superfícies de produto da própria Stripe (o Dashboard, o site de marketing, a documentação) rodam em um sistema interno que foi referido ao longo dos anos por vários nomes e nunca foi lançado como um pacote público. Não há npm install, nem Storybook, nem exportação de tokens. Se era isso que você procurava, não está disponível, e reconstruções de terceiros são inferências baseadas em screenshots.

O que a Stripe publica, e documenta minuciosamente, são dois sistemas voltados para desenvolvedores que integram com a Stripe. Eles geralmente são discutidos separadamente porque estão em cantos diferentes da documentação. Lidos juntos, eles são uma pequena masterclass em limites de design system.

A linha entre eles não é técnica. É um limite de confiança. Quando sua UI reside na superfície da Stripe, a Stripe não pode permitir que um app de terceiro mal estilizado faça o Dashboard parecer quebrado, por isso ela remove essa capacidade. Quando a UI da Stripe reside na sua superfície, um formulário de pagamento que ignore o seu design pareceria um problema de segurança, então a Stripe entrega o controle a você. Mesma empresa, mesmos valores de design, padrões opostos, porque a questão não é "como isso deve parecer", mas sim "quem é o responsável por sua aparência".

O toolkit de UI do Stripe Apps oferece um conjunto de componentes (views, layout, navegação, conteúdo, formulários, gráficos), além de uma primitiva Box com uma prop css. A prop css parece uma saída de emergência de estilização, mas não é. Ela aceita tokens nomeados, e nada mais.

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

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

O vocabulário de espaçamento possui sete etapas e um zero, documentado com valores fixos em pixels: xxsmall 2px, xsmall 4px, small 8px, medium 16px, large 24px, xlarge 32px, xxlarge 48px. O dimensionamento é fracionado (metades, terços, quartos, quintos, sextos, doze avos, além de fill) com opções de min, max e fit baseadas no conteúdo.

A parte interessante é o que acontece acima do Box. Componentes que não sejam Box ou Inline possuem estilos predefinidos, e a documentação é explícita ao dizer que alguns deles não podem ser sobrescritos de forma alguma: um componente que muda de aparência com base em quais callbacks ele implementa não permitirá que você o contradiga, pois a aparência carrega significado. Outros expõem um pequeno enum: Button possui primary, default e destructive, e essa é a lista completa. Alguns expõem apenas uma propriedade, como o Icon aceitando fill.

Existe também um conjunto documentado de restrições de hierarquia de componentes: regras sobre quais componentes podem conter quais. Isso é o equivalente de layout da mesma ideia: não é um conselho sobre boa estrutura, mas uma restrição que faz uma estrutura ruim falhar em vez de ser implementada.

Quase todo design system é um projeto de documentação. Ele diz para usar os tokens e, depois, entrega uma prop className que aceita qualquer coisa, e seis meses depois metade do codebase tem valores hex arbitrários porque alguém estava com pressa em uma sexta-feira.

O Stripe Apps remove essa opção. Não há caminho de "estar com pressa" para #3c82f6, porque a prop não aceitará isso. Isso é uma garantia muito mais forte do que uma regra de lint e infinitamente mais forte do que um parágrafo em uma wiki. Se você mantém um sistema que precisa sobreviver a contribuidores que não leram a documentação — que são todos eles — este é o caminho.

A Appearance API resolve o problema oposto. Um formulário de pagamento precisa parecer nativo de um site que ninguém na Stripe viu, ao mesmo tempo em que mantém um layout que a Stripe controla por razões de conversão e conformidade. A resposta da Stripe é uma escada com três degraus, e a documentação diz para você subí-la em ordem.

1. 1

   Escolha um tema

   Três pontos de partida pré-construídos: stripe, night, flat. Uma linha, e a maioria das integrações que só precisam não conflitar já estão prontas aqui.

   Copy

   const appearance = { theme: 'night' }

2. 2

   Defina variáveis

   Um pequeno conjunto de valores que se propagam por toda parte. Esta é a camada de tokens, e é onde acontece a maior parte da customização 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

   Adicione regras, apenas se ainda precisar

   Um mapeamento de seletores estilo CSS para propriedades CSS, alcançando componentes e estados individuais. Este é o escape hatch, e é deliberadamente o último.

   Copy

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

A ordem é o design. Cada degrau é mais poderoso e mais caro de manter do que o degrau abaixo, e a documentação empurra você para baixo na escada, em vez de para cima. Uma equipe que começa em rules escreve quarenta seletores e é dona deles para sempre; uma equipe que começa em theme escreve uma linha e só desce quando realmente precisa.

Entre as variáveis, duas merecem atenção porque são bases derivadas, em vez de valores. spacingUnit é descrita como a unidade base da qual todos os outros espaçamentos derivam: aumente-a e todo o componente se torna mais espaçoso. fontSizeBase define o tamanho raiz, e as outras variáveis de tamanho de fonte escalam a partir dela em rem.

Compare isso com a abordagem usual, onde um design system publica de --space-1 a --space-12 como doze valores independentes e fixos. Ambos oferecem uma escala. Apenas um oferece um seletor. Se um cliente precisar de um formulário mais denso, a versão derivada é um único número; a versão enumerada exige doze edições e uma decisão subjetiva em cada uma.

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

A documentação da Appearance API afirma que colorPrimary, colorBackground, colorText, colorSuccess, colorDanger e colorWarning não suportam a sintaxe rgba() ou var(--myVariable), enquanto outras variáveis suportam. Também observa que a API não se aplica a Elements de métodos de pagamento individuais como o CardElement, que utilizam um objeto Style separado.

Essas são inconsistências pouco glamorosas, e publicá-las é a decisão correta. Uma API de customização que falha silenciosamente em um subconjunto de inputs custa ao integrador uma tarde de depuração confusa; uma que avisa isso na tabela custa a ele trinta segundos. Se o seu próprio sistema tem uma regra que só funciona em alguns lugares, a documentação é o lugar onde isso deve estar, não o changelog.

Ambos os sistemas foram projetados para desenvolvedores humanos lendo documentação. A questão interessante em 2026 é o que muda quando o desenvolvedor é um agente de código, e a resposta é que a postura do Stripe Apps se torna mais forte, enquanto a postura do Elements se torna mais fraca.

Um agente não tem incentivo para cortar caminho em uma sexta-feira, mas também não tem memória de suas convenções entre sessões. Dê a ele um vocabulário fechado e ele usará o vocabulário, de forma confiável, para sempre. Dê a ele uma prop className e um parágrafo dizendo "prefira os tokens" e ele usará os tokens aproximadamente com a mesma frequência que os dados de treinamento, o que quer dizer, às vezes.

Amostramos 299 arquivos DESIGN.md publicados para leitura de agentes de IA. 86% especificavam cores como valores hex brutos, sem nenhum papel semântico associado, e 76% não continham nenhuma proibição. Esses dois números descrevem um arquivo que diz a um modelo quais cores existem e nada sobre o que elas significam ou o que é proibido: o exato oposto de ambos os sistemas da Stripe, que são quase inteiramente sobre significado e restrição.

Essa é a ideia do Stripe Apps transposta para prosa: você não pode dar um erro de tipo a um agente, mas pode dizer a ele o que seria um. A ideia do Elements também se transfere como uma ordenação: declare primeiro os padrões do nível de tema, depois os tokens e, por fim, as exceções específicas, para que um modelo que leia de cima para baixo encontre a regra geral antes do caso especial.

A maioria das equipes que constroem um design system escolhe uma postura e a aplica em todo lugar. A documentação da Stripe é uma demonstração de que a postura deve seguir a fronteira. Em superfícies pelas quais você é responsável, feche o vocabulário e torne as violações impossíveis. Em superfícies pelas quais outra pessoa é responsável, publique uma escada e deixe que subam apenas até onde for necessário.

A maioria dos produtos possui ambos os tipos de superfície. A ferramenta de administração interna e o widget incorporável não são o mesmo problema de design, e um sistema único com uma única estratégia de customização atenderá mal a um deles.