Communitygithub.com

Sistema de Design Radix UI

Crie sistemas de design acessíveis com primitivas Radix UI. Customização de componentes headless, estratégias de theming e padrões de componentes compostos para bibliotecas de UI de nível profissional.

O que é Sistema de Design Radix UI?

Esta skill capacita desenvolvedores a construir sistemas de design robustos e acessíveis utilizando as primitivas headless do Radix UI. Ideal para projetos que exigem controle total sobre estilos e comportamento, sem as opiniões estéticas de bibliotecas pré-estilizadas, ela fornece um guia completo sobre arquitetura headless, composição de componentes, e estratégias de theming usando CSS Variables, Tailwind + CVA ou Stitches. O foco principal é acessibilidade desde a base, com componentes que seguem as diretrizes WAI-ARIA e oferecem suporte nativo a teclado e leitores de tela. Perfeita para quem precisa criar sistemas de design personalizados, migrar de bibliotecas estilizadas ou implementar componentes interativos complexos com conformidade WCAG 2.1, a skill cobre desde padrões básicos (como Dialog e Dropdown) até técnicas avançadas como componentes polimórficos com `asChild`, animações com Framer Motion e gerenciamento de estado controlado vs. não controlado. Ela funciona exclusivamente com React 16.8+ e é compatível com qualquer framework de estilos, sendo uma referência essencial para times que buscam profissionalismo e acessibilidade em suas interfaces.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/aiskillstore/marketplace/sickn33/radix-ui-design-system

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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-invalid e aria-describedby
  • Estados de Carregamento: aria-busy adequado durante operações assíncronas

Específico do Dialog:

  • Dialog.Title está presente (obrigatório para leitores de tela)
  • Dialog.Description fornece 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

  1. Sempre use asChild para evitar divs wrapper

    <Dialog.Trigger asChild>
      <button>Abrir</button>
    </Dialog.Trigger>
    
  2. Forneça HTML semântico

    <Dialog.Content asChild>
      <article role="dialog" aria-labelledby="title">
        {/* conteúdo */}
      </article>
    </Dialog.Content>
    
  3. Use variáveis CSS para theming

    .dialog-content {
      background: hsl(var(--surface));
      color: hsl(var(--on-surface));
    }
    
  4. 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

  1. Não pule partes de acessibilidade

    // ❌ Faltando Title e Description
    <Dialog.Content>
      <div>Conteúdo</div>
    </Dialog.Content>
    
  2. Não lute contra as primitivas

    // ❌ Sobrescrevendo comportamento interno
    <Dialog.Content onClick={(e) => e.stopPropagation()}>
    
  3. Não misture controlado e não controlado

    // ❌ Gerenciamento de estado inconsistente
    <Tabs.Root defaultValue="tab1" value={activeTab}>
    
  4. 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

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

Habilidades Relacionadas