Typography

Typography no Makuco UI não é um web component — são classes CSS globais aplicáveis em qualquer elemento HTML. A fonte utilizada é Plus Jakarta Sans em todas as escalas. O sistema tipográfico garante hierarquia visual consistente em toda a interface ao codificar as decisões de tamanho, peso, altura de linha e espaçamento entre letras em um conjunto de estilos pré-definidos, eliminando ambiguidade e assegurando que a mesma intenção tipográfica se repita em todos os produtos. Cada estilo segue o padrão de nomenclatura mk-typography-{grupo}-{tamanho}-{peso}, com grupos disponíveis: display, heading, title, body, caption, label.

Quando usar

Use os text styles do Makuco sempre que precisar aplicar tipografia com consistência e alinhada ao sistema de design.

• Precisar aplicar um título, subtítulo, texto de corpo, legenda ou rótulo de interface em qualquer tela do produto.
• Quiser garantir que o texto respeite a hierarquia visual definida pelo design system.
• For necessário padronizar estilos tipográficos em diferentes times ou produtos dentro do mesmo ecossistema.
• Precisar criar conteúdo editorial de alto impacto (landing pages, hero sections) — use os estilos display.

• O texto tiver um estilo completamente personalizado que não pertence à hierarquia do produto (ex.: logotipos, marcas, arte gráfica fora do sistema) — nesse caso, aplique CSS customizado fora do escopo do design system.
• For necessário usar uma família tipográfica diferente da Plus Jakarta Sans por exigência editorial específica.

Anatomia

O sistema tipográfico é organizado em 6 categorias, cada uma com propósito semântico distinto, combinadas com tamanhos e pesos para compor os tokens de estilo.

Display

Para seções hero, páginas de marketing e layouts editoriais. Use com parcimônia — no máximo uma vez por tela — reservado para momentos de grande destaque visual. Em telas de produto como formulários, tabelas e dashboards operacionais, prefira iniciar a hierarquia pelo heading.

<h1 className="mk-typography-display-xxl-bold">Título principal</h1>
<h2 className="mk-typography-display-xl-regular">Subtítulo hero</h2>

<h1 class="mk-typography-display-xxl-bold">Título principal</h1>
<h2 class="mk-typography-display-xl-regular">Subtítulo hero</h2>

Heading

Para títulos de página e seção. Correspondem à hierarquia H1–H2 do conteúdo e devem ser o ponto de partida da tipografia em telas de produto — formulários, tabelas, dashboards e interfaces operacionais.

<h1 className="mk-typography-heading-xl-bold">Página</h1>
<h2 className="mk-typography-heading-md-semi-bold">Seção</h2>

<h1 class="mk-typography-heading-xl-bold">Página</h1>
<h2 class="mk-typography-heading-md-semi-bold">Seção</h2>

Title

Para títulos de cards, dialogs e subseções. Use para títulos de escopo menor — abas, sidebars e seções internas — correspondendo à hierarquia H4 e abaixo do conteúdo.

Body

Escala padrão para texto de interface e prosa. É o estilo mais usado na interface — destinado a leitura corrida, parágrafos e descrições. Não o intercambie com label: embora os tamanhos sejam similares (16px e 14px), body é para conteúdo de leitura e label é para nomear elementos interativos.

<p className="mk-typography-body-md-regular">Texto de conteúdo principal.</p>
<p className="mk-typography-body-sm-regular">Texto de apoio ou metadados.</p>

<p class="mk-typography-body-md-regular">Texto de conteúdo principal.</p>
<p class="mk-typography-body-sm-regular">Texto de apoio ou metadados.</p>

Caption

Para legendas, notas de rodapé e texto auxiliar. Não deve ser usado para conteúdo de leitura corrida nem para mensagens críticas ou instruções de preenchimento — reservado para informações verdadeiramente auxiliares de baixa hierarquia visual.

Label

Para rótulos de controles interativos: botões, abas, campos de formulário. Texto de interface — não para leitura corrida, mas para nomear ações e elementos interativos. Não o intercambie com body: embora os tamanhos se sobreponham, label é especificamente pensado para elementos de UI que demandam ação ou identificação.

Comportamento

Os text styles são imutáveis por design — cada token encapsula todas as propriedades tipográficas (tamanho, peso, altura de linha, espaçamento entre letras) de forma indivisível. Isso significa que não é possível, por exemplo, aplicar o tamanho de body-md com o peso de heading-xl: o par grupo+tamanho+peso forma uma unidade semântica.

Ao trocar o estilo de um elemento (por exemplo, de body-md-regular para body-md-bold), apenas o peso muda — tamanho e altura de linha permanecem idênticos, garantindo estabilidade no layout. Essa característica permite criar ênfase visual dentro de um bloco de texto sem deslocar o espaçamento vertical.

A família tipográfica Plus Jakarta Sans é carregada como parte do pacote do Makuco UI. Não é necessário importar a fonte separadamente; ela estará disponível assim que o CSS do sistema for incluído na aplicação.

Composição

Os text styles funcionam de forma independente de outros tokens — podem ser aplicados em qualquer elemento HTML sem dependência de componentes específicos do Makuco. Eles compõem bem com tokens de cor (--db1-text-color-*), espaçamento (--db1-spacing-*) e os próprios componentes do sistema, que internamente já usam os text styles corretos para cada contexto.

Ao construir layouts hierárquicos, combine as categorias do sistema para criar uma progressão legível: display ou heading para o título principal, title para subdivisões, body para o conteúdo e caption ou label para metadados e ações.

Ao aplicar tipografia, use sempre um token de text style — nunca configure os valores manualmente. Ajustes manuais de tamanho, peso, altura de linha ou espaçamento entre letras quebram a consistência e dificultam atualizações globais do sistema.

Referência de pesos

Diretrizes

• Use o grupo semântico que corresponde ao papel do texto, não ao tamanho visual desejado.
• Prefira regular para texto de corpo; use semi-bold ou bold para criar hierarquia dentro de um parágrafo.
• Evite mais de dois ou três tamanhos tipográficos em uma única tela. Em geral, use no máximo 2–3 pesos diferentes na mesma tela — misturar muitos pesos fragmenta a hierarquia visual.
• Não use extra-bold em body ou caption — o ganho de peso sem aumento de tamanho gera ruído visual.
• Body vs Label: ambos têm tamanhos similares (16px e 14px), mas têm propósitos distintos: body é para leitura corrida; label é para nomear elementos interativos. Não os intercambie.
• Display é para impacto, não para estrutura: em telas de produto (formulários, tabelas, dashboards operacionais), comece a hierarquia pelo heading.

Acessibilidade

Tamanho mínimo de leitura: Body/sm (14px) é o menor tamanho recomendado para texto de conteúdo. Caption (12px) deve ser reservado para informações verdadeiramente auxiliares — nunca para mensagens críticas ou instruções de preenchimento.

Altura de linha generosa: todos os estilos body e label têm altura de linha maior ou igual a 125% do tamanho — isso garante legibilidade adequada para usuários com dislexia ou baixa visão.

Espaçamento negativo em Display e Heading: os estilos maiores usam letter-spacing negativo para melhorar a legibilidade em tamanhos grandes. Não ajuste esses valores manualmente — eles são parte integral do token.

Não use apenas variação de peso para comunicar significado: usuários com baixa visão podem não perceber a diferença entre regular e semi-bold em tamanhos pequenos. Complemente com cor, ícone ou estrutura quando precisar destacar informação crítica.