AGENT SKILL
shadcn-ui-radix-architect
Shadcn UI 与 Radix UI 现代前端无障碍可复用组件架构规范与最佳实践指南。
- License 许可
- MIT
- 最近更新
- 2026-08-25
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- shadcn-ui-radix-architect
- description
- Shadcn UI 与 Radix UI 现代前端无障碍可复用组件架构规范与最佳实践指南。
02 资源文件 1
- 参考文档skill.json1.1 KB
03 SKILL.md 正文
Shadcn UI 与 Radix UI 现代前端组件架构规范
本规范指导 AI 生成符合工业级标准、无障碍(WAI-ARIA)就绪且高度可定制的现代 React / Next.js UI 组件。
1. 核心设计原则
- 所有权属于用户 (Own your code):组件代码直接内嵌在项目中,而非从庞大的外部黑盒 npm 库中引入。
- Radix UI 无状态原语 (Headless Primitives):负责核心状态机、键盘导航(Keyboard Navigation)、焦点捕获(Focus Trapping)与 ARIA 属性。
- CVA (Class Variance Authority):严格使用 CVA 管理组件的多变体(variants)与尺寸(sizes)。
- Tailwind Merge + Clsx:所有类名拼接必须通过
cn(...)工具函数进行合并,防止样式优先级冲突。
2. 标准组件实现模式 (以 Button 为例)
import * as React from "react";
import { Slot } from "@radix-ui/react-slot";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";
const buttonVariants = cva(
"inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 active:scale-[0.98]",
{
variants: {
variant: {
default: "bg-primary text-primary-foreground hover:bg-primary/90 shadow",
destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90 shadow-sm",
outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
ghost: "hover:bg-accent hover:text-accent-foreground",
link: "text-primary underline-offset-4 hover:underline",
},
size: {
default: "h-9 px-4 py-2",
sm: "h-8 rounded-md px-3 text-xs",
lg: "h-10 rounded-md px-8",
icon: "h-9 w-9",
},
},
defaultVariants: {
variant: "default",
size: "default",
},
}
);
export interface ButtonProps
extends React.ButtonHTMLAttributes<HTMLButtonElement>,
VariantProps<typeof buttonVariants> {
asChild?: boolean;
}
export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
({ className, variant, size, asChild = false, ...props }, ref) => {
const Comp = asChild ? Slot : "button";
return (
<Comp
className={cn(buttonVariants({ variant, size, className }))}
ref={ref}
{...props}
/>
);
}
);
Button.displayName = "Button";
3. 强制准则
- 必须支持
asChild模式:通过@radix-ui/react-slot让组件可渲染为 Link 或其他自定义元素。 - 严禁硬编码颜色值:严禁写死
#1677ff或bg-blue-600,必须使用 CSS 变量代号(如bg-primary,text-muted-foreground)。 - 微交互与无障碍:必须包含
focus-visible:ring焦点环与disabled:opacity-50禁用态。
04 同仓库更多 Skills
web-page-extractor
网页正文智能提纯与清洗工具。抓取网页并剔除 HTML 标签、脚本与样式,输出高信息密度的 Markdown。
★ 1
restful-api-standard
企业级 RESTful API 设计准则
★ 1
fetch-page
抓取网页并提取标题与正文长度,需要网络权限(默认策略为拒绝,须授权)。
★ 1
api-tester-toolkit
API 接口网络测试与耗时诊断工具包。发起 HTTP GET/POST 请求、统计响应耗时与状态码、检查响应数据。
★ 1
semver-bump
语义化版本号升级:major / minor / patch。
★ 1
translate
中英互译演示实现,内置小词典,用于演示翻译类 skill 的检索与调用。
★ 1