Communitygithub.com

ComeOnOliver/skillshub

使用 Radix UI 基本元件建立可存取的設計系統。無頭元件客製化、主題策略,以及用於生產級 UI 函式庫的複合元件模式。

skillshub 是什麼?

此技能專注於使用 Radix UI 的基本元件(primitives)來建立符合生產標準、以無障礙為優先的設計系統。Radix UI 提供無樣式、具備完整無障礙功能(WAI-ARIA 合規、鍵盤導航、螢幕閱讀器支援)的元件,讓開發人員擁有完全的控制權,可以自訂任何設計系統的外觀與風格。技能詳細說明了三種主題策略:使用 CSS 變數以獲得最大可移植性、結合 Tailwind 和 Class Variance Authority (CVA) 來處理變體、以及使用 CSS-in-JS 解決方案如 Stitches。它也涵蓋了關鍵的元件模式,例如用於狀態共享的複合元件(Compound Components)、用於保持行為的 asChild 屬性(polymorphic components)、受控與非受控元件,以及與 Framer Motion 整合的動畫。此技能支援的平台包括 React 16.8 以上版本,並且非常適合需要建立自訂、可存取元件庫,或從樣板化元件遷移到無樣式基本元件的開發者。

相容平台~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、方向鍵、Enter、Escape)
  • 螢幕閱讀器:適當的 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:使用 Context 的複合元件

使用案例:在基本元件的各個部分之間共享狀態

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

常用基本元件參考

對話框(Modal)

<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、方向鍵、Enter、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

相關技能