shadcn-ui-conventions

UI 组件约定

components/ui 目录使用的约定与项目其余部分不同。为保留 shadcn/ui 的模式，该目录不参与 Biome/Ultracite lint 检查。

何时使用此技能

• 创建新的 UI 组件时
• 修改现有 shadcn/ui 组件时
• 实现 8-bit 复古风格时
• 处理组件导入和类型时

Lint 检查

• Biome 排除该目录：biome.jsonc 的 includes 中有 "!components/ui"
• 不使用 Ultracite 格式化：组件使用自己的模式
• 需要时手动运行 lint：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";

8bit 组件（例如 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;
  })

8bit 组件：单独导出接口

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

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

Ref 处理

基础组件：使用 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;

8bit 组件：使用 ref 属性（React 19 模式）

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

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

8bit 组件模式

导入复古 CSS：所有 8bit 组件都必须导入

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

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

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

变体覆盖：8bit 变体通常只包含少量样式（边框/颜色由 CSS 处理）

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

参考文件

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