O que Sistema de Design Radix UI faz?
Construa sistemas de design prontos para produção, acessíveis, usando primitivas Radix UI com controle total de customização e zero opiniões de estilo.
Visão Geral
O Radix UI fornece componentes acessíveis e não estilizados (primitivas) que você pode customizar para atender a qualquer sistema de design. Esta skill guia você na construção de bibliotecas de componentes escaláveis com Radix UI, com foco em design acessível, arquitetura de temas e padrões composíveis.
Principais Pontos Fortes:
- Headless por design: Controle total de estilo sem lutar contra valores padrão
- Acessibilidade embutida: Conformidade WAI-ARIA, navegação por teclado, suporte a leitores de tela
- Primitivas composíveis: Construa componentes complexos a partir de blocos de construção simples
- Independente de framework: Funciona com React, mas estilos funcionam em qualquer lugar
Quando Usar Esta Skill
- Criando um sistema de design personalizado do zero
- Construindo bibliotecas de componentes de UI acessíveis
- Implementando componentes interativos complexos (Dialog, Dropdown, Tabs, etc.)
- Migrando de bibliotecas de componentes estilizados para primitivas não estilizadas
- Configurando sistemas de theming com variáveis CSS ou Tailwind
- Precisando de controle total sobre o comportamento e estilo dos componentes
- Construindo aplicações que exigem conformidade WCAG 2.1 AA/AAA
Não use esta skill quando
- Você precisa de componentes pré-estilizados prontos para uso (use shadcn/ui, Mantine, etc.)
- Construindo páginas estáticas simples sem interatividade
- O projeto não usa React 16.8+ (Radix exige hooks)
- Você precisa de componentes para frameworks que não sejam React
Princípios Centrais
1. Acessibilidade em Primeiro Lugar
Cada primitiva Radix é construída com a acessibilidade como base:
- Navegação por Teclado: Suporte completo de teclado (Tab, setas, Enter, Escape)
- Leitores de Tela: Atributos ARIA e regiões ativas apropriadas
- Gerenciamento de Foco: Captura e restauração automática do foco
- Estados Desabilitados: Tratamento adequado de disabled e aria-disabled
Regra: Nunca substitua as funcionalidades de acessibilidade. Aprimore, não substitua.
2. Arquitetura Headless
O Radix fornece comportamento, você fornece aparência:
// ❌ Não lute contra componentes pré-estilizados
<Button className="override-everything" />
// ✅ Radix fornece o comportamento, você adiciona o estilo
<Dialog.Root>
<Dialog.Trigger className="your-button-styles" />
<Dialog.Content className="your-modal-styles" />
</Dialog.Root>
3. Composição Sobre Configuração
Construa componentes complexos a partir de primitivas simples:
// Primitivas compõem naturalmente
<Tabs.Root>
<Tabs.List>
<Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
<Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="tab1">Conteúdo 1</Tabs.Content>
<Tabs.Content value="tab2">Conteúdo 2</Tabs.Content>
</Tabs.Root>
Primeiros Passos
Instalação
# Instale primitivas individuais (recomendado)
npm install @radix-ui/react-dialog @radix-ui/react-dropdown-menu
# Ou instale várias de uma vez
npm install @radix-ui/react-{dialog,dropdown-menu,tabs,tooltip}
# Para estilização (opcional, mas comum)
npm install clsx tailwind-merge class-variance-authority
Padrão Básico de Componente
Todo componente Radix segue este padrão:
import * as Dialog from '@radix-ui/react-dialog';
export function MyDialog() {
return (
<Dialog.Root>
{/* Aciona o diálogo */}
<Dialog.Trigger asChild>
<button className="trigger-styles">Abrir</button>
</Dialog.Trigger>
{/* Portal renderiza fora da hierarquia DOM */}
<Dialog.Portal>
{/* Overlay (fundo) */}
<Dialog.Overlay className="overlay-styles" />
{/* Conteúdo (modal) */}
<Dialog.Content className="content-styles">
<Dialog.Title>Título</Dialog.Title>
<Dialog.Description>Descrição</Dialog.Description>
{/* Seu conteúdo aqui */}
<Dialog.Close asChild>
<button>Fechar</button>
</Dialog.Close>
</Dialog.Content>
</Dialog.Portal>
</Dialog.Root>
);
}
Estratégias de Theming
Estratégia 1: Variáveis CSS (Independente de Framework)
Melhor para: Portabilidade máxima, compatível com SSR
/* globals.css */
:root {
--color-primary: 220 90% 56%;
--color-surface: 0 0% 100%;
--radius-base: 0.5rem;
--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
}
[data-theme="dark"] {
--color-primary: 220 90% 66%;
--color-surface: 222 47% 11%;
}
// Componente.tsx
<Dialog.Content
className="
bg-[hsl(var(--color-surface))]
rounded-[var(--radius-base)]
shadow-[var(--shadow-lg)]
"
/>
Estratégia 2: Tailwind + CVA (Class Variance Authority)
Melhor para: Projetos Tailwind, componentes com muitas variantes
// button.tsx
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';
const buttonVariants = cva(
// Estilos base
"inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none disabled:pointer-events-none disabled:opacity-50",
{
variants: {
variant: {
default: "bg-primary text-primary-foreground hover:bg-primary/90",
destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
outline: "border border-input bg-background hover:bg-accent",
ghost: "hover:bg-accent hover:text-accent-foreground",
},
size: {
default: "h-10 px-4 py-2",
sm: "h-9 rounded-md px-3",
lg: "h-11 rounded-md px-8",
icon: "h-10 w-10",
},
},
defaultVariants: {
variant: "default",
size: "default",
},
}
);
interface ButtonProps extends VariantProps<typeof buttonVariants> {
children: React.ReactNode;
}
export function Button({ variant, size, children }: ButtonProps) {
return (
<button className={cn(buttonVariants({ variant, size }))}>
{children}
</button>
);
}
Estratégia 3: Stitches (CSS-in-JS)
Melhor para: Theming em tempo de execução, estilos com escopo
import { styled } from '@stitches/react';
import * as Dialog from '@radix-ui/react-dialog';
const StyledContent = styled(Dialog.Content, {
backgroundColor: '$surface',
borderRadius: '$md',
padding: '$6',
variants: {
size: {
small: { width: '300px' },
medium: { width: '500px' },
large: { width: '700px' },
},
},
defaultVariants: {
size: 'medium',
},
});
Padrões de Componentes
Padrão 1: Componentes Compostos com Contexto
Caso de uso: Compartilhar estado entre partes primitivas
// Select.tsx
import * as Select from '@radix-ui/react-select';
import { CheckIcon, ChevronDownIcon } from '@radix-ui/react-icons';
export function CustomSelect({ items, placeholder, onValueChange }) {
return (
<Select.Root onValueChange={onValueChange}>
<Select.Trigger className="select-trigger">
<Select.Value placeholder={placeholder} />
<Select.Icon>
<ChevronDownIcon />
</Select.Icon>
</Select.Trigger>
<Select.Portal>
<Select.Content className="select-content">
<Select.Viewport>
{items.map((item) => (
<Select.Item
key={item.value}
value={item.value}
className="select-item"
>
<Select.ItemText>{item.label}</Select.ItemText>
<Select.ItemIndicator>
<CheckIcon />
</Select.ItemIndicator>
</Select.Item>
))}
</Select.Viewport>
</Select.Content>
</Select.Portal>
</Select.Root>
);
}
Padrão 2: Componentes Polimórficos com asChild
Caso de uso: Renderizar como elementos diferentes sem perder o comportamento
// ✅ Renderizar como Link do Next.js mantendo o comportamento Radix
<Dialog.Trigger asChild>
<Link href="/settings">Abrir Configurações</Link>
</Dialog.Trigger>
// ✅ Renderizar como componente customizado
<DropdownMenu.Item asChild>
<YourCustomButton icon={<Icon />}>Ação</YourCustomButton>
</DropdownMenu.Item>
Por que asChild é importante: Evita problemas de aninhamento de botões/links na árvore de acessibilidade.
Padrão 3: Controlado vs Não Controlado
// Não controlado (Radix gerencia o estado)
<Tabs.Root defaultValue="tab1">
<Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
</Tabs.Root>
// Controlado (Você gerencia o estado)
const [activeTab, setActiveTab] = useState('tab1');
<Tabs.Root value={activeTab} onValueChange={setActiveTab}>
<Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
</Tabs.Root>
Regra: Use controlado quando precisar sincronizar com estado externo (URL, Redux, etc.).
Padrão 4: Animação com Framer Motion
import * as Dialog from '@radix-ui/react-dialog';
import { motion, AnimatePresence } from 'framer-motion';
export function AnimatedDialog({ open, onOpenChange }) {
return (
<Dialog.Root open={open} onOpenChange={onOpenChange}>
<Dialog.Portal forceMount>
<AnimatePresence>
{open && (
<>
<Dialog.Overlay asChild>
<motion.div
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
className="dialog-overlay"
/>
</Dialog.Overlay>
<Dialog.Content asChild>
<motion.div
initial={{ opacity: 0, scale: 0.95 }}
animate={{ opacity: 1, scale: 1 }}
exit={{ opacity: 0, scale: 0.95 }}
className="dialog-content"
>
{/* Conteúdo */}
</motion.div>
</Dialog.Content>
</>
)}
</AnimatePresence>
</Dialog.Portal>
</Dialog.Root>
);
}
Referência de Primitivas Comuns
Dialog (Modal)
<Dialog.Root> {/* Container de estado */}
<Dialog.Trigger /> {/* Abre o diálogo */}
<Dialog.Portal> {/* Renderiza em portal */}
<Dialog.Overlay /> {/* Fundo */}
<Dialog.Content> {/* Conteúdo do modal */}
<Dialog.Title /> {/* Obrigatório para a11y */}
<Dialog.Description /> {/* Obrigatório para a11y */}
<Dialog.Close /> {/* Fecha o diálogo */}
</Dialog.Content>
</Dialog.Portal>
</Dialog.Root>
Menu Dropdown
<DropdownMenu.Root>
<DropdownMenu.Trigger />
<DropdownMenu.Portal>
<DropdownMenu.Content>
<DropdownMenu.Item />
<DropdownMenu.Separator />
<DropdownMenu.CheckboxItem />
<DropdownMenu.RadioGroup>
<DropdownMenu.RadioItem />
</DropdownMenu.RadioGroup>
<DropdownMenu.Sub> {/* Menus aninhados */}
<DropdownMenu.SubTrigger />
<DropdownMenu.SubContent />
</DropdownMenu.Sub>
</DropdownMenu.Content>
</DropdownMenu.Portal>
</DropdownMenu.Root>
Tabs
<Tabs.Root defaultValue="tab1">
<Tabs.List>
<Tabs.Trigger value="tab1" />
<Tabs.Trigger value="tab2" />
</Tabs.List>
<Tabs.Content value="tab1" />
<Tabs.Content value="tab2" />
</Tabs.Root>
Tooltip
<Tooltip.Provider delayDuration={200}>
<Tooltip.Root>
<Tooltip.Trigger />
<Tooltip.Portal>
<Tooltip.Content side="top" align="center">
Texto da dica
<Tooltip.Arrow />
</Tooltip.Content>
</Tooltip.Portal>
</Tooltip.Root>
</Tooltip.Provider>
Popover
<Popover.Root>
<Popover.Trigger />
<Popover.Portal>
<Popover.Content side="bottom" align="start">
Conteúdo
<Popover.Arrow />
<Popover.Close />
</Popover.Content>
</Popover.Portal>
</Popover.Root>
Checklist de Acessibilidade
Todo Componente Deve Ter:
- Gerenciamento de Foco: Indicadores de foco visíveis em todos os elementos interativos
- Navegação por Teclado: Suporte completo de teclado (Tab, Setas, Enter, Esc)
- Rótulos ARIA: Rótulos significativos para leitores de tela
- Contraste de Cor: Mínimo WCAG AA (4.5:1 para texto, 3:1 para UI)
- Estados de Erro: Mensagens de erro claras com
aria-invalidearia-describedby - Estados de Carregamento:
aria-busyadequado durante operações assíncronas
Específico do Dialog:
-
Dialog.Titleestá presente (obrigatório para leitores de tela) -
Dialog.Descriptionfornece contexto - Foco fica preso dentro do modal quando aberto
- Tecla Escape fecha o diálogo
- Foco retorna ao acionador ao fechar
Específico do Dropdown:
- Teclas de seta navegam entre os itens
- Busca por digitação funciona
- Comportamento de wrapping do primeiro/último item
- Estado selecionado indicado visualmente e com ARIA
Melhores Práticas
✅ Faça Isso
-
Sempre use
asChildpara evitar divs wrapper<Dialog.Trigger asChild> <button>Abrir</button> </Dialog.Trigger> -
Forneça HTML semântico
<Dialog.Content asChild> <article role="dialog" aria-labelledby="title"> {/* conteúdo */} </article> </Dialog.Content> -
Use variáveis CSS para theming
.dialog-content { background: hsl(var(--surface)); color: hsl(var(--on-surface)); } -
Componha primitivas para componentes complexos
function CommandPalette() { return ( <Dialog.Root> <Dialog.Content> <Combobox /> {/* Combobox Radix dentro do Dialog */} </Dialog.Content> </Dialog.Root> ); }
❌ Não Faça Isso
-
Não pule partes de acessibilidade
// ❌ Faltando Title e Description <Dialog.Content> <div>Conteúdo</div> </Dialog.Content> -
Não lute contra as primitivas
// ❌ Sobrescrevendo comportamento interno <Dialog.Content onClick={(e) => e.stopPropagation()}> -
Não misture controlado e não controlado
// ❌ Gerenciamento de estado inconsistente <Tabs.Root defaultValue="tab1" value={activeTab}> -
Não ignore a navegação por teclado
// ❌ Desabilitando comportamento de teclado <DropdownMenu.Item onKeyDown={(e) => e.preventDefault()}>
Solução de Problemas
Problema: Estilos não estão sendo aplicados
Causa: Primitivas Radix são headless - elas não vêm com estilos. Solução: Aplique suas próprias classes ou estilos.
// Você precisa adicionar estilos explicitamente
<Dialog.Content className="bg-white p-6 rounded-lg shadow-lg" />
Problema: asChild não está funcionando
Causa: O elemento filho pode não estar aceitando uma ref.
Solução: Certifique-se de que o componente filho usa React.forwardRef.
// ✅ Componente customizado com forwardRef
const CustomButton = React.forwardRef(({ children, ...props }, ref) => (
<button ref={ref} {...props}>{children}</button>
));
Problema: Animações não funcionam
Causa: Radix remove elementos do DOM imediatamente.
Solução: Use forceMount no Portal com AnimatePresence.
<Dialog.Portal forceMount>
<AnimatePresence>
{open && <Dialog.Content asChild>...</Dialog.Content>}
</AnimatePresence>
</Dialog.Portal>
Links e Referências
- Documentação Radix UI: radix-ui.com/primitives
- shadcn/ui: ui.shadcn.com (Componentes estilizados construídos sobre Radix)
- Class Variance Authority (CVA): cva.style
- Tailwind CSS: tailwindcss.com
- Stitches: stitches.dev
- Framer Motion: framermotion.framer.website