Communitygithub.com

ComeOnOliver/skillshub

用于构建UI组件,强制执行ShadCN UI模式、无障碍标准(Radix UI)和TailwindCSS最佳实践(2025年11月版)。

skillshub 是什么?

该技能强制遵循2025年11月版的ShadCN UI模式,用于构建UI组件。它要求使用Radix UI原语以实现内置的无障碍性(符合WCAG 2.1 AA标准),并坚持TailwindCSS优先的样式方法。该技能的核心原则包括:组件安装采用“复制粘贴而非npm”模式,使用TypeScript原生代码,并确保与Next.js 15 App Router的服务端组件兼容。它提供了常见组件(如Button、Dialog、Form)的详细使用模式,强调正确的结构(如Dialog必须包含DialogTitle)和无障碍性要求(如焦点管理、键盘导航和屏幕阅读器支持)。此外,该技能还涵盖了表单验证(使用React Hook Form和Zod)、服务端与客户端组件的区分、深色模式支持,以及常见错误的检测,例如缺少DialogTitle或不使用Form组件。它指导开发者使用Tailwind实用类和cn()辅助函数,并提供了组件的测试示例。总的来说,此技能确保所有新的Replit应用在一致性、无障碍性和可维护性方面都遵循ShadCN UI标准。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/aiskillstore/marketplace/barnhardt-enterprises-inc/shadcn-ui-patterns

在你喜欢的 AI 中提问

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

文档

ShadCN UI 模式 - 2025年11月标准

使用场景

  • 构建新的UI组件
  • 重构现有组件以使用ShadCN
  • 实现带验证的表单
  • 创建弹窗、对话框和覆盖层
  • 确保无障碍合规性

为什么选择ShadCN UI?

  • 复制粘贴,而非npm - 完全拥有组件代码
  • Radix UI 原语 - 内置无障碍性(符合WCAG 2.1 AA标准)
  • TailwindCSS优先 - 完全可定制,无需CSS-in-JS
  • TypeScript原生 - 类型安全的props和变体
  • 服务端组件兼容 - 适用于Next.js 15 App Router

核心原则

1. 组件安装模式

# 按需安装单个组件
npx shadcn@latest add button
npx shadcn@latest add dialog
npx shadcn@latest add form
npx shadcn@latest add input
npx shadcn@latest add label

组件会被复制到 src/components/ui/ 目录 —— 你拥有代码的完全控制权。

2. 组件使用模式

按钮组件

import { Button } from "@/components/ui/button"

// ✅ 正确:使用语义化变体
<Button variant="default">保存</Button>
<Button variant="destructive">删除</Button>
<Button variant="outline">取消</Button>
<Button variant="ghost">跳过</Button>
<Button variant="link">了解更多</Button>

// ✅ 正确:使用大小变体
<Button size="default">中等</Button>
<Button size="sm">小</Button>
<Button size="lg">大</Button>
<Button size="icon"><Icon /></Button>

// ❌ 错误:不使用Button组件创建自定义按钮
<button className="px-4 py-2 bg-blue-500">糟糕</button>

对话框/模态框组件

import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"

// ✅ 正确:使用正确的对话框结构(无障碍性)
<Dialog>
  <DialogTrigger asChild>
    <Button>打开设置</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>设置</DialogTitle>
      <DialogDescription>
        在此配置您的应用设置。
      </DialogDescription>
    </DialogHeader>
    {/* 对话框内容 */}
  </DialogContent>
</Dialog>

// ❌ 错误:跳过DialogHeader或DialogTitle(破坏屏幕阅读器)
<DialogContent>
  <h2>设置</h2> {/* 错误 - 应使用DialogTitle */}
</DialogContent>

表单组件(与React Hook Form + Zod配合)

import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import * as z from "zod"
import {
  Form,
  FormControl,
  FormDescription,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from "@/components/ui/form"
import { Input } from "@/components/ui/input"
import { Button } from "@/components/ui/button"

// ✅ 正确:首先定义Zod模式(验证)
const formSchema = z.object({
  email: z.string().email("无效的电子邮件地址"),
  password: z.string().min(8, "密码长度至少为8个字符"),
})

function LoginForm() {
  const form = useForm<z.infer<typeof formSchema>>({
    resolver: zodResolver(formSchema),
    defaultValues: {
      email: "",
      password: "",
    },
  })

  async function onSubmit(values: z.infer<typeof formSchema>) {
    // 类型安全的已验证数据
    console.log(values)
  }

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
        <FormField
          control={form.control}
          name="email"
          render={({ field }) => (
            <FormItem>
              <FormLabel>电子邮件</FormLabel>
              <FormControl>
                <Input placeholder="[email protected]" {...field} />
              </FormControl>
              <FormDescription>
                我们绝不会分享您的电子邮件。
              </FormDescription>
              <FormMessage />
            </FormItem>
          )}
        />

        <FormField
          control={form.control}
          name="password"
          render={({ field }) => (
            <FormItem>
              <FormLabel>密码</FormLabel>
              <FormControl>
                <Input type="password" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <Button type="submit">登录</Button>
      </form>
    </Form>
  )
}

// ❌ 错误:使用无验证的非受控表单
<form>
  <input name="email" /> {/* 无验证 */}
</form>

3. 服务端组件 vs 客户端组件

// ✅ 正确:对静态对话框使用服务端组件
import { Dialog, DialogContent } from "@/components/ui/dialog"

export default function ServerDialog() {
  // 无需 'use client'
  return <Dialog>...</Dialog>
}

// ✅ 正确:当需要状态时使用客户端组件
'use client'

import { useState } from 'react'
import { Dialog, DialogContent } from "@/components/ui/dialog"

export function ClientDialog() {
  const [open, setOpen] = useState(false)

  return (
    <Dialog open={open} onOpenChange={setOpen}>
      <DialogContent>...</DialogContent>
    </Dialog>
  )
}

4. 无障碍性要求

焦点管理

// ✅ 正确:使用带有 asChild 的 DialogTrigger 进行正确的焦点管理
<DialogTrigger asChild>
  <Button>打开</Button>
</DialogTrigger>

// ❌ 错误:在无正确焦点处理的情况下手动触发
<Button onClick={() => setOpen(true)}>打开</Button>

键盘导航

// ✅ ShadCN 自动处理:
// - ESC 关闭对话框
// - Tab 在可聚焦元素间导航
// - Enter/Space 激活按钮
// - 箭头键在菜单中导航

// ❌ 错误:在无充分理由的情况下覆盖默认键盘行为

屏幕阅读器支持

// ✅ 正确:始终包含 DialogTitle(ARIA 必需)
<DialogHeader>
  <DialogTitle>删除项目</DialogTitle>
  <DialogDescription>
    此操作无法撤消。
  </DialogDescription>
</DialogHeader>

// ❌ 错误:错误地使用视觉隐藏标题
<DialogTitle className="sr-only">删除</DialogTitle>
// 仅在存在清晰的视觉替代方案时隐藏

5. 常用组件

组件使用场景关键Props
Button所有可点击操作variant, size, asChild
Dialog模态框、确认框open, onOpenChange
Sheet侧边面板、抽屉side, open, onOpenChange
Popover工具提示、菜单open, onOpenChange
Form所有表单form (来自 useForm)
Input文本输入type, placeholder
Select下拉菜单value, onValueChange
Checkbox布尔值输入checked, onCheckedChange
RadioGroup单选value, onValueChange
Table数据表格table (来自 TanStack Table)
Card内容容器CardHeader, CardContent, CardFooter
Toast通知title, description, variant
Command命令面板onSelect
Tabs标签导航value, onValueChange

6. TailwindCSS 最佳实践

// ✅ 正确:使用 Tailwind 实用类
<Button className="w-full mt-4">提交</Button>

// ✅ 正确:使用 cn() 辅助函数处理条件类
import { cn } from "@/lib/utils"

<Button className={cn(
  "w-full",
  isLoading && "opacity-50 cursor-not-allowed"
)}>
  提交
</Button>

// ❌ 错误:使用内联样式
<Button style={{ width: '100%', marginTop: '16px' }}>提交</Button>

// ❌ 错误:为组件创建自定义CSS文件
// styles.css
.my-button { width: 100%; }

7. 深色模式支持

// ✅ 正确:使用 Tailwind 深色模式类
<div className="bg-white dark:bg-gray-900 text-black dark:text-white">
  内容
</div>

// ✅ ShadCN 组件内置深色模式支持
<Button variant="default">
  {/* 自动为深色模式设置样式 */}
</Button>

常见错误排查

❌ 缺少 DialogTitle(无障碍违规)

// 错误
<DialogContent>
  <h2>设置</h2>
  <p>内容</p>
</DialogContent>

// 正确
<DialogContent>
  <DialogHeader>
    <DialogTitle>设置</DialogTitle>
  </DialogHeader>
  <p>内容</p>
</DialogContent>

❌ 不为表单使用 Form 组件

// 错误 - 无验证,体验差
<form>
  <input name="email" />
  <button type="submit">提交</button>
</form>

// 正确 - 验证、错误信息、无障碍性
<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <FormField name="email" ... />
  </form>
</Form>

❌ 硬编码颜色而不是使用变体

// 错误
<Button className="bg-red-500 hover:bg-red-600">删除</Button>

// 正确
<Button variant="destructive">删除</Button>

❌ 没有为触发器使用 asChild

// 错误 - 创建不必要的嵌套按钮
<DialogTrigger>
  <Button>打开</Button>
</DialogTrigger>
// 渲染为:<button><button>打开</button></button> (无效的HTML)

// 正确 - 将props合并为单个按钮
<DialogTrigger asChild>
  <Button>打开</Button>
</DialogTrigger>
// 渲染为:<button>打开</button>

测试 ShadCN 组件

import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { Dialog, DialogTrigger, DialogContent } from '@/components/ui/dialog'

describe('Dialog', () => {
  it('应该在被触发时打开', async () => {
    const user = userEvent.setup()

    render(
      <Dialog>
        <DialogTrigger asChild>
          <button>打开</button>
        </DialogTrigger>
        <DialogContent>
          <div>对话框内容</div>
        </DialogContent>
      </Dialog>
    )

    // 对话框内容最初不应可见
    expect(screen.queryByText('对话框内容')).not.toBeInTheDocument()

    // 点击触发器
    await user.click(screen.getByText('打开'))

    // 对话框内容现在应可见
    expect(screen.getByText('对话框内容')).toBeInTheDocument()
  })

  it('应该按ESC键关闭', async () => {
    const user = userEvent.setup()

    render(
      <Dialog defaultOpen>
        <DialogContent>对话框内容</DialogContent>
      </Dialog>
    )

    expect(screen.getByText('对话框内容')).toBeInTheDocument()

    await user.keyboard('{Escape}')

    expect(screen.queryByText('对话框内容')).not.toBeInTheDocument()
  })
})

资源

2025年11月说明

截至2025年11月,ShadCN UI 是React组件库的行业标准。所有新的 Quetrex 应用必须使用 ShadCN UI,以确保一致性、无障碍性和可维护性。

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

相关技能