shadcn-ui组件约定Skill shadcn-ui-conventions

---

name: shadcn-ui-conventions description: UI 组件约定，适用于 8 位风格组件。在使用 shadcn/ui 组件或实现复古风格 UI 元素时使用。

UI 组件约定

components/ui 目录使用了与项目其余部分不同的约定。它被排除在 Biome/Ultracite 代码检查之外，以保留 shadcn/ui 的模式。

何时使用此技能

• 当创建新的 UI 组件时
• 当修改现有的 shadcn/ui 组件时
• 当实现 8 位复古样式时
• 当处理组件导入和类型时

代码检查

• Biome 排除此目录：biome.jsonc 在 includes 中有 "!components/ui"
• 无 Ultracite 格式化：组件使用自己的模式
• 需要时手动运行代码检查：npx biome check components/ui/

导入模式

基础组件（例如，button.tsx）：

import type * as React from "react";

import { Slot } from "@radix-ui/react-slot";
import { type VariantProps, cva } from "class-variance-authority";

import { cn } from "@/lib/utils";

8位组件（例如，8bit/button.tsx）：

import { type VariantProps, cva } from "class-variance-authority";

import { cn } from "@/lib/utils";

import { Button as ShadcnButton } from "@/components/ui/button";

import "@/components/ui/8bit/styles/retro.css";

导入顺序：

1. 外部库（class-variance-authority, @radix-ui）
2. 内部工具（@/lib/utils）
3. 基础组件别名（@/components/ui/component）
4. 复古样式表（@/components/ui/8bit/styles/retro.css）

类型定义

基础组件：内联 props 类型与函数

function Button({
  className,
  variant,
  ...props
}: React.ComponentProps<"button"> &
  VariantProps<typeof buttonVariants> & {
    asChild?: boolean;
  })

8位组件：单独导出接口

export interface BitButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean;
  ref?: React.Ref<HTMLButtonElement>;
}

function Button({ children, asChild, ...props }: BitButtonProps)

引用处理

基础组件：使用 React.forwardRef

const DialogOverlay = React.forwardRef<
  React.ComponentRef<typeof DialogPrimitive.Overlay>,
  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay>
>(({ className, ...props }, ref) => (
  <DialogPrimitive.Overlay ref={ref} {...props} />
));
DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;

8位组件：使用 ref prop（React 19 模式）

export interface BitButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  ref?: React.Ref<HTMLButtonElement>;
}

function Button({ ref, ...props }: BitButtonProps) {
  return <ShadcnButton ref={ref} {...props} />
}

8位组件模式

复古 CSS 导入：所有 8位组件必需

import "@/components/ui/8bit/styles/retro.css";

基础组件别名：使用别名导入基础组件

import { Button as ShadcnButton } from "@/components/ui/button";

变体覆盖：8位变体通常具有最小样式（边框/颜色由 CSS 处理）

export const buttonVariants = cva("", {
  variants: {
    variant: {
      default: "bg-foreground",
      // ...
    },
  },
});

参考文件

• components/ui/button.tsx - 基础组件示例
• components/ui/8bit/button.tsx - 8位包装器示例
• components/ui/dialog.tsx - 使用 Radix 原语的复杂基础组件