Separator

Overview

Separator é um divisor visual entre grupos de conteúdo. Constrói em cima do @radix-ui/react-separator, o que dá um detalhe importante de acessibilidade: o flag decorative controla se o separador é exposto a leitores de tela (role="separator" com aria-orientation) ou tratado como ornamento puro (role="none").

A pergunta que precede a inclusão de um Separator é: a respiração do espaço não está bastando? Espaçamento entre seções (space-y-6, gap-8) costuma comunicar agrupamento sem nenhum traço — só recorra ao Separator quando o agrupamento precisa ser explícito ou quando o ar disponível é escasso (sidebar de 240px, toolbar densa).

Anatomy

<Separator
  ├─ [data-slot="separator"]
  ├─ [data-orientation="horizontal" | "vertical"]
  ├─ orientation = "horizontal" (default) | "vertical"
  └─ decorative = true (default) | false
/>

A altura/largura do separador é 1px em qualquer eixo. No horizontal ocupa 100% da largura disponível; no vertical precisa de um container flex com altura definida — caso contrário ele colapsa.

Usage

import { Separator } from "@kalvner/kds/display/separator";

export function SettingsHeader() {
  return (
    <div className="space-y-1">
      <h3 className="text-sm font-semibold">Conta</h3>
      <p className="text-sm text-muted-foreground">
        Email, senha, idioma.
      </p>
      <Separator className="my-4" />
    </div>
  );
}

Props

Variants

States

Composition

When to use

• Para terminar um agrupamento dentro de um Card denso, quando a respiração natural não basta.
• Em sidebars estreitas onde o espaço para space-y-6 não cabe.
• Em toolbars horizontais para isolar grupos de ações relacionadas.
• Em listas de eventos/atividades para marcar a transição entre janelas temporais (Hoje, Ontem, Semana passada).

When not to use

• Como elemento decorativo aleatório — se a função do separador não é dividir grupos, ele vira ruído visual.
• Para separar título e descrição dentro de um mesmo bloco — tipografia e espaçamento já fazem isso.
• Como borda inferior de Card — use border-b direto no Card.
• Para dividir colunas de uma tabela — a tabela já tem grid lines.

Best practices

• Ar primeiro, separador depois. Aumente gap-* e veja se o agrupamento já fica claro. Separador é a última camada de hierarquia visual.
• Decorativo é o default certo. Em 99% dos casos, o separador não carrega significado para leitor de tela. Só passe decorative={false} quando o contexto realmente muda (Hoje vs Ontem em um feed cronológico, por exemplo).
• Vertical exige container com altura. Sem altura definida no flex parent, o separador colapsa para 0px. Use h-8, h-full ou um wrapper com altura conhecida.
• Mantenha a mesma cor (bg-border). Não invente tokens de separador — use a borda padrão do tema. Se precisar de um divisor mais forte, considere se um Card ou Section seria mais adequado.

Accessibility

Related

• Card — wrapper que costuma alojar Separators internos entre suas seções.
• Stack — quando gap resolve, o Separator não é necessário.