Communitygithub.com

ComeOnOliver/skillshub

使用 Radix UI 原语构建可访问的设计系统。掌握无头组件定制、主题策略以及复合组件模式,以打造生产级 UI 库。

skillshub 是什么?

该技能指导开发者使用 Radix UI 原语构建可访问、可定制的设计系统。Radix UI 提供无样式、符合 WAI-ARIA 标准的组件,让开发者完全掌控样式与交互,无需对抗框架默认样式。技能涵盖从核心原则(无障碍优先、无头架构、组合优于配置)到实际构建的完整流程,包括多种主题策略(CSS 变量、Tailwind + CVA、Stitches)、复合组件模式(上下文共享、多态组件、受控/非受控、动画),并提供对话框、下拉菜单等常用原语参考和完整的无障碍检查清单。它适用于创建自定义设计系统、构建复杂交互组件或需要 WCAG 合规性的 React 项目,但不适用于需要预置样式组件或非 React 框架的场景。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Radix UI 设计系统

使用 Radix UI 原语构建生产就绪、可访问的设计系统,拥有完全的定制控制权且无样式偏见。

概述

Radix UI 提供了无样式的、可访问的组件(原语),您可以对其进行定制以匹配任何设计系统。此技能指导您使用 Radix UI 构建可扩展的组件库,重点在于无障碍优先设计、主题架构和可组合模式。

主要优势:

  • 无头设计:完全控制样式,无需对抗默认值
  • 内建无障碍:符合 WAI-ARIA 规范,支持键盘导航和屏幕阅读器
  • 可组合原语:通过简单的构建块构建复杂组件
  • 框架无关:与 React 配合使用,但样式可随处应用

何时使用此技能

  • 从头创建自定义设计系统
  • 构建可访问的 UI 组件库
  • 实现复杂的交互式组件(对话框、下拉菜单、选项卡等)
  • 从样式化组件库迁移到无样式原语
  • 使用 CSS 变量或 Tailwind 设置主题系统
  • 需要完全控制组件行为和样式
  • 构建需要符合 WCAG 2.1 AA/AAA 标准的应用程序

不使用此技能的情况

  • 需要开箱即用的预样式组件(请使用 shadcn/ui、Mantine 等)
  • 构建无需交互的简单静态页面
  • 项目不使用 React 16.8+(Radix 需要 hooks)
  • 需要用于非 React 框架的组件

核心原则

1. 无障碍优先

每个 Radix 原语都以无障碍为基石:

  • 键盘导航:完整的键盘支持(Tab、方向键、回车、退出)
  • 屏幕阅读器:正确的 ARIA 属性和动态区域
  • 焦点管理:自动焦点捕获和恢复
  • 禁用状态:正确处理 disabled 和 aria-disabled

规则:永远不要覆盖无障碍功能。增强,而非替代。

2. 无头架构

Radix 提供行为,您提供外观:

// ❌ 不要与预样式组件对抗
<Button className="override-everything" />

// ✅ Radix 给您行为,您添加样式
<Dialog.Root>
  <Dialog.Trigger className="your-button-styles" />
  <Dialog.Content className="your-modal-styles" />
</Dialog.Root>

3. 组合而非配置

从简单的原语构建复杂组件:

// 原语组件自然组合
<Tabs.Root>
  <Tabs.List>
    <Tabs.Trigger value="tab1">标签 1</Tabs.Trigger>
    <Tabs.Trigger value="tab2">标签 2</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="tab1">内容 1</Tabs.Content>
  <Tabs.Content value="tab2">内容 2</Tabs.Content>
</Tabs.Root>

入门指南

安装

# 推荐:单独安装每个原语
npm install @radix-ui/react-dialog @radix-ui/react-dropdown-menu

# 或者一次安装多个
npm install @radix-ui/react-{dialog,dropdown-menu,tabs,tooltip}

# 样式相关(可选但常见)
npm install clsx tailwind-merge class-variance-authority

基本组件模式

每个 Radix 组件遵循此模式:

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

export function MyDialog() {
  return (
    <Dialog.Root>
      {/* 触发对话框 */}
      <Dialog.Trigger asChild>
        <button className="trigger-styles">打开</button>
      </Dialog.Trigger>

      {/* Portal 在 DOM 层次结构外渲染 */}
      <Dialog.Portal>
        {/* 覆盖层(背景) */}
        <Dialog.Overlay className="overlay-styles" />
        
        {/* 内容(模态框) */}
        <Dialog.Content className="content-styles">
          <Dialog.Title>标题</Dialog.Title>
          <Dialog.Description>描述</Dialog.Description>
          
          {/* 您的内容放在这里 */}
          
          <Dialog.Close asChild>
            <button>关闭</button>
          </Dialog.Close>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

主题策略

策略 1:CSS 变量(框架无关)

最佳适用:最大可移植性,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)]
  "
/>

策略 2:Tailwind + CVA (Class Variance Authority)

最佳适用:Tailwind 项目,变体丰富的组件

// button.tsx
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';

const buttonVariants = cva(
  // 基础样式
  "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>
  );
}

策略 3:Stitches (CSS-in-JS)

最佳适用:运行时主题,作用域样式

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

组件模式

模式 1:带上下文的复合组件

使用场景:在原语部分之间共享状态

// 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>
  );
}

模式 2:带 asChild 的多态组件

使用场景:渲染为不同元素而不丢失行为

// ✅ 渲染为 Next.js Link 但保留 Radix 行为
<Dialog.Trigger asChild>
  <Link href="/settings">打开设置</Link>
</Dialog.Trigger>

// ✅ 渲染为自定义组件
<DropdownMenu.Item asChild>
  <YourCustomButton icon={<Icon />}>操作</YourCustomButton>
</DropdownMenu.Item>

为什么 asChild 很重要:防止在无障碍树中出现嵌套按钮/链接问题。

模式 3:受控 vs 非受控

// 非受控(Radix 管理状态)
<Tabs.Root defaultValue="tab1">
  <Tabs.Trigger value="tab1">标签 1</Tabs.Trigger>
</Tabs.Root>

// 受控(您管理状态)
const [activeTab, setActiveTab] = useState('tab1');

<Tabs.Root value={activeTab} onValueChange={setActiveTab}>
  <Tabs.Trigger value="tab1">标签 1</Tabs.Trigger>
</Tabs.Root>

规则:当需要与外部状态(URL、Redux 等)同步时,使用受控模式。

模式 4:使用 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"
                >
                  {/* 内容 */}
                </motion.div>
              </Dialog.Content>
            </>
          )}
        </AnimatePresence>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

常见原语参考

对话框(模态框)

<Dialog.Root> {/* 状态容器 */}
  <Dialog.Trigger /> {/* 打开对话框 */}
  <Dialog.Portal> {/* 在 portal 中渲染 */}
    <Dialog.Overlay /> {/* 背景 */}
    <Dialog.Content> {/* 模态框内容 */}
      <Dialog.Title /> {/* 无障碍必需 */}
      <Dialog.Description /> {/* 无障碍必需 */}
      <Dialog.Close /> {/* 关闭对话框 */}
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

下拉菜单

<DropdownMenu.Root>
  <DropdownMenu.Trigger />
  <DropdownMenu.Portal>
    <DropdownMenu.Content>
      <DropdownMenu.Item />
      <DropdownMenu.Separator />
      <DropdownMenu.CheckboxItem />
      <DropdownMenu.RadioGroup>
        <DropdownMenu.RadioItem />
      </DropdownMenu.RadioGroup>
      <DropdownMenu.Sub> {/* 嵌套菜单 */}
        <DropdownMenu.SubTrigger />
        <DropdownMenu.SubContent />
      </DropdownMenu.Sub>
    </DropdownMenu.Content>
  </DropdownMenu.Portal>
</DropdownMenu.Root>

选项卡

<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.Provider delayDuration={200}>
  <Tooltip.Root>
    <Tooltip.Trigger />
    <Tooltip.Portal>
      <Tooltip.Content side="top" align="center">
        工具提示文本
        <Tooltip.Arrow />
      </Tooltip.Content>
    </Tooltip.Portal>
  </Tooltip.Root>
</Tooltip.Provider>

弹出框

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

无障碍检查清单

每个组件必须包含:

  • 焦点管理:所有交互元素上的可见焦点指示器
  • 键盘导航:完整的键盘支持(Tab、方向键、回车、Esc)
  • ARIA 标签:为屏幕阅读器提供有意义的标签
  • 颜色对比度:符合 WCAG AA 最低要求(文本 4.5:1,UI 元素 3:1)
  • 错误状态:使用 aria-invalid 和 aria-describedby 提供清晰的错误消息
  • 加载状态:异步操作期间使用适当的 aria-busy

对话框特定:

  • Dialog.Title 已存在(屏幕阅读器必需)
  • Dialog.Description 提供上下文
  • 模态框打开时焦点被捕获在内部
  • 按 Escape 键关闭对话框
  • 关闭后焦点返回到触发器

下拉菜单特定:

  • 方向键导航项目
  • 输入搜索功能正常
  • 首/尾项目包裹行为
  • 选中状态通过视觉和 ARIA 指示

最佳实践

✅ 应做事项

  1. 始终使用 asChild 避免包装 div

    <Dialog.Trigger asChild>
      <button>打开</button>
    </Dialog.Trigger>
    
  2. 提供语义化 HTML

    <Dialog.Content asChild>
      <article role="dialog" aria-labelledby="title">
        {/* 内容 */}
      </article>
    </Dialog.Content>
    
  3. 使用 CSS 变量进行主题设置

    .dialog-content {
      background: hsl(var(--surface));
      color: hsl(var(--on-surface));
    }
    
  4. 组合原语构建复杂组件

    function CommandPalette() {
      return (
        <Dialog.Root>
          <Dialog.Content>
            <Combobox /> {/* 对话框内的 Radix Combobox */}
          </Dialog.Content>
        </Dialog.Root>
      );
    }
    

❌ 不应做事项

  1. 不要跳过无障碍部分

    // ❌ 缺少 Title 和 Description
    <Dialog.Content>
      <div>内容</div>
    </Dialog.Content>
    
  2. 不要与原语对抗

    // ❌ 覆盖内部行为
    <Dialog.Content onClick={(e) => e.stopPropagation()}>
    
  3. 不要混合受控和非受控

    // ❌ 状态管理不一致
    <Tabs.Root defaultValue="tab1" value={activeTab}>
    
  4. 不要忽略键盘导航

    // ❌ 禁用键盘行为
    <DropdownMenu.I
    
}```

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

相关技能