Interfaces sem ruído

Um DSL nativo para interfaces acessíveis.

Interfaces sem ruído

O Valence é o design system de Web Components que sustenta o Portfoliable.js. Construído no Storybook, ele usa custom elements nativos em vez de prender o sistema a um único framework. Um componente pode ser consumido pelo Portfoliable hoje e continuar disponível para outra aplicação JavaScript amanhã.^[1][2]

Os componentes encapsulam comportamento e estilos por meio de Shadow DOM. Os estilos da aplicação não reescrevem acidentalmente um botão, e um componente pode evoluir sem obrigar cada consumidor a copiar seu CSS. Também mantém o design system próximo do modelo nativo do navegador — atributos, slots, eventos e HTML semântico.

import '@portfoliablejs/valence';

const button = document.createElement('ds-button');
button.setAttribute('label', 'Abrir case');
button.setAttribute('variant', 'primary');
document.querySelector('#actions').append(button);

Uma estrutura que acompanha a interface

A biblioteca segue um vocabulário de Atomic Design, mas o utiliza como mapa de engenharia, e não como uma taxonomia por si só:

Essa separação torna as mudanças mais fáceis de raciocinar. Um ajuste de espaçamento pertence a um token; uma interação de teclado pertence ao componente que a possui; uma decisão de fluxo de leitura pertence ao template consumidor.

Storybook como superfície de desenvolvimento

O Storybook é mais do que um catálogo. É o lugar onde API, casos extremos, estados visuais e comportamento acessível se tornam inspecionáveis. O Canvas dá feedback imediato; a aba Docs explica o contrato; os controles permitem testar combinações reais de props sem primeiro conectar uma aplicação inteira.

export const Reflow = {
  args: {
    label: 'reflow',
    count: 3,
    background: '#7ED321'
  }
};

Esse fluxo muda o ciclo de feedback. Em vez de perguntar se um componente funciona apenas dentro de uma página, a equipe pode fazer perguntas melhores mais cedo: um label longo se reorganiza? O estado de foco está visível? O que acontece quando a quantidade muda? A mesma API representa os estados de carregamento e desabilitado?

Acessibilidade como capacidade global

O Valence trata acessibilidade como uma preocupação do sistema. A aplicação consumidora pode alternar modos a partir da raiz do documento e deixar que a biblioteca responda de forma consistente:

<html class="a11y-dark-mode a11y-focus-mode">
  <body>
    <ds-header></ds-header>
  </body>
</html>

Os modos incluem tema escuro, alto contraste, texto grande, redução de movimento, tipografia amigável para dislexia, foco visível, forced colors, destaque de live regions e simulações de deficiências visuais.

No Storybook, esses modos aparecem como controles globais, permitindo avaliar acessibilidade como parte do desenvolvimento normal, e não apenas como auditoria final. Com o Portfoliable, o runtime pode cuidar da preferência e do estado da pessoa usuária, enquanto o Valence cuida da resposta visual.

Integração sem perder fronteiras

O Portfoliable consome o Valence por meio de contratos comuns da Web Platform. Estados simples viajam por atributos; conteúdo rico entra por slots; ações da pessoa usuária retornam como eventos customizados com namespace:

<ds-case-view
  title-text="Criando um onboarding mais claro"
  show-language-menu="true">
  <article slot="content">
    <h2>Resultado</h2>
    <p>A narrativa do case continua pertencendo à aplicação.</p>
  </article>
</ds-case-view>

Essa divisão mantém as responsabilidades claras. O Valence fornece a superfície de interação e a linguagem visual; o Portfoliable fornece dados dos cases, rotas, localização e contexto do produto.

O resultado

• Uma base reutilizável: componentes podem ser consumidos pelo Portfoliable e por outras aplicações web.
• Um feedback mais curto: Canvas, Docs e Controls tornam o comportamento visível cedo.
• Acessibilidade desde a construção: modos e estados de interação são testados como parte do sistema.
• Uma colaboração mais clara: decisões de design viram tokens, APIs e padrões documentados.

O Valence é a camada que permite ao Portfoliable ser coerente sem fazer cada case parecer igual. Ele transforma o cuidado com a interface em infraestrutura compartilhada — mantendo-a próxima da web aberta.

O que eu faria diferente

Se eu começasse o Valence novamente, faria algumas escolhas de forma mais explícita desde o início:

• Definiria um orçamento de performance: mediria o custo de cada componente, estilo e modo de acessibilidade e criaria limites para JavaScript, CSS e fontes antes que o sistema crescesse.
• Estabeleceria governança mais cedo: documentaria o processo para propor, revisar, depreciar e versionar componentes, tokens e mudanças de API.
• Testaria com uma matriz real de contextos: combinaria navegadores, tamanhos de tela, tecnologias assistivas, preferências de movimento e modos de contraste em testes automatizados e manuais.
• Seria mais criterioso com a granularidade: nem toda diferença precisa virar um componente ou uma propriedade. Manteria a API pequena para evitar combinações difíceis de documentar e manter.
• Validaria os componentes em produtos reais mais cedo: usaria fluxos completos do Portfoliable desde o começo, em vez de depender principalmente de estados isolados no Storybook.

Essas mudanças não alterariam a direção do projeto, mas tornariam suas decisões mais sustentáveis. O objetivo seria preservar a portabilidade dos Web Components e a acessibilidade como capacidade global, reduzindo ao mesmo tempo o peso, a complexidade e o custo de evolução do sistema.

Conheça o repositório do Valence ou veja como ele sustenta o runtime do Portfoliable.