Communitygithub.com

ComeOnOliver/skillshub

Construye sistemas de diseño accesibles con los componentes primitivos de Radix UI. Personalización de componentes headless, estrategias de tematización y patrones de componentes compuestos para librerías de UI de nivel de producción.

¿Qué es skillshub?

Esta habilidad te guía en la creación de sistemas de diseño accesibles y robustos utilizando Radix UI. Con Radix UI, obtienes componentes 'headless' (sin estilos predefinidos) que cumplen con WAI-ARIA, soportan navegación por teclado y son compatibles con lectores de pantalla. Es ideal para desarrolladores que buscan control total sobre el estilo y comportamiento de sus componentes, permitiendo desde la creación de un sistema de diseño personalizado hasta la implementación de componentes complejos como diálogos, menús desplegables y pestañas. La habilidad cubre desde la instalación de primitivas, pasando por patrones de composición, hasta estrategias de tematización con variables CSS, Tailwind CSS o Stitches. Se recomienda su uso en proyectos con React 16.8+ que requieran cumplimiento WCAG 2.1, pero no es adecuada si se necesitan componentes preestilizados o si el proyecto no utiliza React. Incluye ejemplos prácticos de código y una lista de verificación de accesibilidad para garantizar que cada componente cumpla con los estándares.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Sistema de Diseño con Radix UI

Construye sistemas de diseño accesibles y listos para producción utilizando los componentes primitivos de Radix UI, con control total de personalización y sin opiniones de estilo.

Resumen

Radix UI proporciona componentes accesibles sin estilo (primitivas) que puedes personalizar para que coincidan con cualquier sistema de diseño. Esta habilidad te guía en la construcción de bibliotecas de componentes escalables con Radix UI, centrándose en el diseño que prioriza la accesibilidad, la arquitectura de tematización y los patrones componibles.

Fortalezas Clave:

  • Headless por diseño: Control de estilo total sin luchar contra valores predeterminados
  • Accesibilidad incorporada: Cumplimiento WAI-ARIA, navegación por teclado, soporte para lectores de pantalla
  • Primitivas componibles: Construye componentes complejos a partir de bloques de construcción simples
  • Independiente del framework: Funciona con React, pero los estilos funcionan en cualquier lugar

Cuándo Usar Esta Habilidad

  • Crear un sistema de diseño personalizado desde cero
  • Construir bibliotecas de componentes de UI accesibles
  • Implementar componentes interactivos complejos (Diálogo, Menú Desplegable, Pestañas, etc.)
  • Migrar desde bibliotecas de componentes con estilo a primitivas sin estilo
  • Configurar sistemas de tematización con variables CSS o Tailwind
  • Necesitar control total sobre el comportamiento y estilo de los componentes
  • Construir aplicaciones que requieran cumplimiento WCAG 2.1 AA/AAA

No uses esta habilidad cuando

  • Necesites componentes preestilizados listos para usar (usa shadcn/ui, Mantine, etc.)
  • Estés construyendo páginas estáticas simples sin interactividad
  • El proyecto no utilice React 16.8+ (Radix requiere hooks)
  • Necesites componentes para frameworks que no sean React

Principios Fundamentales

1. Accesibilidad Primero

Cada primitiva de Radix está construida con la accesibilidad como base:

  • Navegación por Teclado: Soporte completo de teclado (Tabulador, Flechas, Enter, Escape)
  • Lectores de Pantalla: Atributos ARIA adecuados y regiones en vivo
  • Gestión de Enfoque: Captura y restauración automática del enfoque
  • Estados Deshabilitados: Manejo adecuado de disabled y aria-disabled

Regla: Nunca sobrescribas las funciones de accesibilidad. Mejora, no reemplaces.

2. Arquitectura Headless

Radix proporciona comportamiento, tú proporcionas apariencia:

// ❌ No luches contra componentes preestilizados
<Button className="override-everything" />

// ✅ Radix te da comportamiento, tú agregas estilo
<Dialog.Root>
  <Dialog.Trigger className="tus-estilos-boton" />
  <Dialog.Content className="tus-estilos-modal" />
</Dialog.Root>

3. Composición sobre Configuración

Construye componentes complejos a partir de primitivas simples:

// Los componentes primitivos se componen naturalmente
<Tabs.Root>
  <Tabs.List>
    <Tabs.Trigger value="tab1">Pestaña 1</Tabs.Trigger>
    <Tabs.Trigger value="tab2">Pestaña 2</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="tab1">Contenido 1</Tabs.Content>
  <Tabs.Content value="tab2">Contenido 2</Tabs.Content>
</Tabs.Root>

Comenzando

Instalación

# Instalar primitivas individuales (recomendado)
npm install @radix-ui/react-dialog @radix-ui/react-dropdown-menu

# O instalar varias a la vez
npm install @radix-ui/react-{dialog,dropdown-menu,tabs,tooltip}

# Para estilos (opcional pero común)
npm install clsx tailwind-merge class-variance-authority

Patrón Básico de Componente

Cada componente de Radix sigue este patrón:

import * as Dialog from '@radix-ui/react-dialog';

export function MiDialogo() {
  return (
    <Dialog.Root>
      {/* Disparador del diálogo */}
      <Dialog.Trigger asChild>
        <button className="estilos-disparador">Abrir</button>
      </Dialog.Trigger>

      {/* Portal renderiza fuera de la jerarquía del DOM */}
      <Dialog.Portal>
        {/* Superposición (fondo) */}
        <Dialog.Overlay className="estilos-superposicion" />
        
        {/* Contenido (modal) */}
        <Dialog.Content className="estilos-contenido">
          <Dialog.Title>Título</Dialog.Title>
          <Dialog.Description>Descripción</Dialog.Description>
          
          {/* Tu contenido aquí */}
          
          <Dialog.Close asChild>
            <button>Cerrar</button>
          </Dialog.Close>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

Estrategias de Tematización

Estrategia 1: Variables CSS (Independiente del Framework)

Mejor para: Portabilidad máxima, compatible con 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%;
}
// Component.tsx
<Dialog.Content 
  className="
    bg-[hsl(var(--color-surface))]
    rounded-[var(--radius-base)]
    shadow-[var(--shadow-lg)]
  "
/>

Estrategia 2: Tailwind + CVA (Class Variance Authority)

Mejor para: Proyectos con Tailwind, componentes con muchas 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>
  );
}

Estrategia 3: Stitches (CSS-in-JS)

Mejor para: Tematización en tiempo de ejecución, estilos con ámbito

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',
  },
});

Patrones de Componentes

Patrón 1: Componentes Compuestos con Contexto

Caso de uso: Compartir estado entre partes primitivas

// Select.tsx
import * as Select from '@radix-ui/react-select';
import { CheckIcon, ChevronDownIcon } from '@radix-ui/react-icons';

export function SelectorPersonalizado({ items, placeholder, onValueChange }) {
  return (
    <Select.Root onValueChange={onValueChange}>
      <Select.Trigger className="disparador-select">
        <Select.Value placeholder={placeholder} />
        <Select.Icon>
          <ChevronDownIcon />
        </Select.Icon>
      </Select.Trigger>

      <Select.Portal>
        <Select.Content className="contenido-select">
          <Select.Viewport>
            {items.map((item) => (
              <Select.Item 
                key={item.value} 
                value={item.value}
                className="item-select"
              >
                <Select.ItemText>{item.label}</Select.ItemText>
                <Select.ItemIndicator>
                  <CheckIcon />
                </Select.ItemIndicator>
              </Select.Item>
            ))}
          </Select.Viewport>
        </Select.Content>
      </Select.Portal>
    </Select.Root>
  );
}

Patrón 2: Componentes Polimórficos con asChild

Caso de uso: Renderizar como diferentes elementos sin perder comportamiento

// ✅ Renderizar como un enlace de Next.js pero mantener el comportamiento de Radix
<Dialog.Trigger asChild>
  <Link href="/settings">Abrir Configuración</Link>
</Dialog.Trigger>

// ✅ Renderizar como componente personalizado
<DropdownMenu.Item asChild>
  <TuBotonPersonalizado icon={<Icon />}>Acción</TuBotonPersonalizado>
</DropdownMenu.Item>

Por qué asChild es importante: Previene problemas de anidamiento de botones/enlaces en el árbol de accesibilidad.

Patrón 3: Controlado vs No Controlado

// No controlado (Radix gestiona el estado)
<Tabs.Root defaultValue="tab1">
  <Tabs.Trigger value="tab1">Pestaña 1</Tabs.Trigger>
</Tabs.Root>

// Controlado (Tú gestionas el estado)
const [activeTab, setActiveTab] = useState('tab1');

<Tabs.Root value={activeTab} onValueChange={setActiveTab}>
  <Tabs.Trigger value="tab1">Pestaña 1</Tabs.Trigger>
</Tabs.Root>

Regla: Usa controlado cuando necesites sincronizar con estado externo (URL, Redux, etc.).

Patrón 4: Animación con Framer Motion

import * as Dialog from '@radix-ui/react-dialog';
import { motion, AnimatePresence } from 'framer-motion';

export function DialogoAnimado({ 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="superposicion-dialogo"
                />
              </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="contenido-dialogo"
                >
                  {/* Contenido */}
                </motion.div>
              </Dialog.Content>
            </>
          )}
        </AnimatePresence>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

Referencia de Primitivas Comunes

Diálogo (Modal)

<Dialog.Root> {/* Contenedor de estado */}
  <Dialog.Trigger /> {/* Abre el diálogo */}
  <Dialog.Portal> {/* Renderiza en un portal */}
    <Dialog.Overlay /> {/* Fondo */}
    <Dialog.Content> {/* Contenido del modal */}
      <Dialog.Title /> {/* Requerido para accesibilidad */}
      <Dialog.Description /> {/* Requerido para accesibilidad */}
      <Dialog.Close /> {/* Cierra el diálogo */}
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

Menú Desplegable

<DropdownMenu.Root>
  <DropdownMenu.Trigger />
  <DropdownMenu.Portal>
    <DropdownMenu.Content>
      <DropdownMenu.Item />
      <DropdownMenu.Separator />
      <DropdownMenu.CheckboxItem />
      <DropdownMenu.RadioGroup>
        <DropdownMenu.RadioItem />
      </DropdownMenu.RadioGroup>
      <DropdownMenu.Sub> {/* Menús anidados */}
        <DropdownMenu.SubTrigger />
        <DropdownMenu.SubContent />
      </DropdownMenu.Sub>
    </DropdownMenu.Content>
  </DropdownMenu.Portal>
</DropdownMenu.Root>

Pestañas

<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 del tooltip
        <Tooltip.Arrow />
      </Tooltip.Content>
    </Tooltip.Portal>
  </Tooltip.Root>
</Tooltip.Provider>

Popover

<Popover.Root>
  <Popover.Trigger />
  <Popover.Portal>
    <Popover.Content side="bottom" align="start">
      Contenido
      <Popover.Arrow />
      <Popover.Close />
    </Popover.Content>
  </Popover.Portal>
</Popover.Root>

Lista de Verificación de Accesibilidad

Cada Componente Debe Tener:

  • Gestión de Enfoque: Indicadores de enfoque visibles en todos los elementos interactivos
  • Navegación por Teclado: Soporte completo de teclado (Tabulador, Flechas, Enter, Esc)
  • Etiquetas ARIA: Etiquetas significativas para lectores de pantalla
  • Contraste de Color: Mínimo WCAG AA (4.5:1 para texto, 3:1 para UI)
  • Estados de Error: Mensajes de error claros con aria-invalid y aria-describedby
  • Estados de Carga: aria-busy adecuado durante operaciones asíncronas

Específico para Diálogos:

  • Dialog.Title está presente (requerido para lectores de pantalla)
  • Dialog.Description proporciona contexto
  • El enfoque está atrapado dentro del modal cuando está abierto
  • La tecla Escape cierra el diálogo
  • El enfoque vuelve al disparador al cerrar

Específico para Menús Desplegables:

  • Las flechas navegan entre los elementos
  • La búsqueda por escritura funciona
  • Comportamiento de envoltura del primer/último elemento
  • El estado seleccionado se indica visualmente y con ARIA

Mejores Prácticas

✅ Haz Esto

  1. Usa siempre asChild para evitar divs envolventes

    <Dialog.Trigger asChild>
      <button>Abrir</button>
    </Dialog.Trigger>
    
  2. Proporciona HTML semántico

    <Dialog.Content asChild>
      <article role="dialog" aria-labelledby="title">
        {/* contenido */}
      </article>
    </Dialog.Content>
    
  3. Usa variables CSS para tematización

    .dialog-content {
      background: hsl(var(--surface));
      color: hsl(var(--on-surface));
    }
    
  4. Compón primitivas para componentes complejos

    function PaletaDeComandos() {
      return (
        <Dialog.Root>
          <Dialog.Content>
            <Combobox /> {/* Combobox de Radix dentro del Diálogo */}
          </Dialog.Content>
        </Dialog.Root>
      );
    }
    

❌ No Hagas Esto

  1. No omitas las partes de accesibilidad

    // ❌ Faltan Título y Descripción
    <Dialog.Content>
      <div>Contenido</div>
    </Dialog.Content>
    
  2. No luches contra las primitivas

    // ❌ Sobrescribir el comportamiento interno
    <Dialog.Content onClick={(e) => e.stopPropagation()}>
    
  3. No mezcles controlado y no controlado

    // ❌ Gestión de estado inconsistente
    <Tabs.Root defaultValue="tab1" value={activeTab}>
    
  4. No ignores la navegación por teclado

    // ❌ Deshabilitar comportamiento del teclado
    <DropdownMenu.Item onKeyDown={(e) => e.preventDefault()}>
    

Referencia Rápida de Composición

Primitiva BaseComponentes CompuestosCaso de Uso
DiálogoPaleta de Comandos, Confirmación, Formulario ModalModales, superposiciones
Menú DesplegableMenú de Acciones, Menú de Contexto, SelectorMenús, acciones contextuales
PestañasPanel de Configuración, Navegación por PestañasAlternar vistas, paneles de configuración
TooltipAyuda en Línea, Ayuda para IconosInformación contextual, sugerencias
PopoverMenú de Perfil, Selector de FechaSuperposiciones ligeras, formularios rápidos
SelectSelector de Tema, Menú desplegable de TipoSelección de opciones, filtros
SwitchAlternar Notificaciones, Alternar Modo OscuroAlternar binarios, preferencias
SliderControl de Volumen, Control de RangoRangos de valores, filtros

Recursos Relacionados

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

Skills relacionados