Pular para o conteúdo principal

Primeiros passos

O Tangram é o Design System dos produtos RD Station. Aqui você encontra os princípios fundamentais, padrões de interface e nossos componentes detalhados, desde os conceitos até suas aplicações.

O objetivo do Tangram é dar mais autonomia aos times e pessoas desenvolvedoras, para que possam criar rapidamente experiências consistentes e de alta qualidade.

Instalação​

Para utilizar o Tangram, você precisa adicionar o seguinte pacote ao seu projeto NPM:

yarn add @resultadosdigitais/tangram-components

Tipografia​

Para adicionar a tipografia padrão do Tangram, cole o seguinte código no <head> do seu HTML:

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,wght@0,500;0,700;0,900;1,500;1,700;1,900&display=swap"
  rel="stylesheet"
/>

Ou utilize a diretiva @import em seu arquivo de estilo:

@import url('https://fonts.googleapis.com/css2?family=DM+Sans:ital,wght@0,500;0,700;0,900;1,500;1,700;1,900&display=swap');

Usando o Tangram​

Uma vez que o Tangram é instalado como dependência no seu projeto, você precisa definir o tema na raiz da sua aplicação utilizando o componente Theme e o Reset:

import { Theme, Reset } from '@resultadosdigitais/tangram-components';

function App() {
  return (
    <Theme>
      <Reset />
      {/* Defina o resto da sua aplicação aqui */}
    </Theme>
  );
}

Com o tema aplicado você consegue usar os componentes em seu código assim:

import {
  Card,
  Text,
  ButtonGroup,
  Button
} from '@resultadosdigitais/tangram-components';

function MyFancyComponent() {
  return (
    <Card>
      <Text token={Text.tokens.TEXT_XL_BOLD}>Boas-vindas</Text>
      <ButtonGroup>
        <Button>Primeiros passos</Button>
        <Button kind={Button.kinds.secondary}>Como funciona</Button>
      </ButtonGroup>
    </Card>
  );
}

Boas-vindas

Importação next​

O que é a importação next?​

A importação /next permite o acesso antecipado a novas versões de componentes ou recursos do Tangram dentro da versão atual (estável) da biblioteca.

Este mecanismo introduz implementações futuras antes que elas substituam oficialmente as atuais, permitindo a coexistência temporária e uma transição gradual.

Na prática, isso possibilita o uso de novos recursos mesmo que incompatíveis com a implementação existente e facilita a identificação de ajustes e correções antes da adoção definitiva.

Para garantir a estabilidade, esses recursos são publicados em um ponto de entrada separado /next. Assim, melhorias ou mudanças de API são introduzidas sem impactar o código já existente.

Quando a nova versão for lançada, o recurso disponível em /next passa a ser a implementação padrão, substituindo a versão atual. Esse modelo permite que as aplicações adotem as evoluções de forma progressiva, reduzindo riscos e facilitando a migração antes da mudança definitiva no Tangram.

Ou seja:

  • A versão atual continua funcionando normalmente;
  • A nova versão é disponibilizada via importação /next;
  • Ambas convivem na mesma versão do Tangram;
  • Na próxima versão major, os recursos em /next substituem a versão atual.

Compromissos do Tangram com a next​

Disponibilizando um recurso via /next, o Tangram assume os seguintes compromissos:

  • Antecipação de mudanças major
    • Recursos em /next representam a próxima versão oficial daquele recurso.
  • Durante a versão atual
    • O recurso atual continua disponível;
    • A nova versão fica disponível em /next.
  • Quando uma nova versão major do Tangram for lançada
    • Os recursos em /next passam a ser o padrão;
    • A versão antiga é substituída.
  • Previsibilidade para migração
    • Os times podem começar a usar a nova versão antes da mudança oficial, facilitando assim a transição.
Informação

O conteúdo em next faz parte da API oficial do Tangram e está garantido na versão atual, assim como os componentes do ponto de entrada padrão. Ele segue as regras de semantic versioning, sem mudanças inesperadas de API. É apenas um ponto de entrada alternativo para suportar a migração gradual e continuará com suporte até a próxima versão major.

Como importar componentes /next?​

Imagine que o componente Dropdown passará por uma reformulação completa de API. Para utilizá-lo, a implementação deverá seguir o novo padrão abaixo.

Versão atual do Tangram:

import { Dropdown } from '@resultadosdigitais/tangram-components';

Nova versão (via /next):

import { Dropdown } from '@resultadosdigitais/tangram-components/next';

Caso seja necessário utilizar diferentes versões do mesmo componente na mesma página (ou no mesmo contexto), é possível renomeá-los no momento da importação, conforme o exemplo abaixo:

import { Dropdown as DeprecatedDropdown } from '@resultadosdigitais/tangram-components';
import { Dropdown } from '@resultadosdigitais/tangram-components/next';

Nossa sugestão é renomear o componente antigo, para deixar claro que ele será substituído em breve.

Quando usar?​

A importação /next é recomendada quando:

  • Seu time quer adotar antecipadamente novas versões de componentes
  • Seu time quer utilizar melhorias que ainda não estão disponíveis na importação principal
  • Está preparando a migração para a próxima versão do Tangram
  • Precisa utilizar um recurso que não é compatível com a versão atual
Informação

A entrada /next está disponível a partir da versão 8.21.0 do pacote @resultadosdigitais/tangram-components. A lista de recursos disponíveis nessa entrada deve ser consultada em nossas releases.

Configuração de lint​

Por padrão, versões antigas da biblioteca @resultadosdigitais/frontend-quality-assurance para a validação de código (lint, quality checks, etc) podem bloquear importações com /next, gerando alguns erros no console ou no CI.

Caso o lint quebre ou a pipeline do CI falhe ao tentar importar algo com /next, é necessário atualizar a biblioteca @resultadosdigitais/eslint-config-react no seu projeto para a versão 3.1.0 ou superior, que inclui o suporte necessário para esse tipo de importação.

Problemas com os testes​

Ao adicionar componentes da importação /next do Tangram, podem surgir alguns erros durante a execução dos testes relacionados ao Jest. Esse erro geralmente está relacionado à interpretação de módulos ESM e dependências com configuração próprias de Babel que não são transformadas por padrão pelo Jest.

Para resolver esse problema, é necessário ajustar a configuração do jest para permitir a transformação dessas dependências específicas.

Modifique o arquivo jest.config.js:

transformIgnorePatterns: ['/node_modules/(?!(@resultadosdigitais|styled-components|@babel/runtime)/)']

Feedback​

Para reportar algum problema ou sugerir alterações, use nosso formulário de melhorias ou, se preferir, abra uma issue no nosso Github.