shadcn-ui-conventions

用途

该技能用于指导在项目中创建和修改 UI 组件，尤其是 shadcn/ui 组件以及 8-bit 复古风格的界面元素。它明确了 components/ui 目录与项目其他部分不同的开发约定。

主要能力

说明 components/ui 目录被排除在 Biome/Ultracite 代码检查之外，以保留 shadcn/ui 的原有模式。
规定基础组件与 8bit 组件的导入顺序与写法。
区分基础组件与 8bit 组件在类型定义、ref 处理上的不同约定。
给出 8bit 组件的特定模式，包括复古样式表导入、基础组件别名导入、变体样式覆盖方式。

使用方式

何时使用

创建新的 UI 组件时。
修改现有的 shadcn/ui 组件时。
实现 8-bit 复古样式时。
处理组件导入与类型时。

代码检查

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";

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";

导入顺序：

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

类型定义

基础组件：内联 props 类型与函数一起定义。

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

8bit 组件：单独导出 interface。

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 prop（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 原语的复杂基础组件

适用场景

适用于维护或扩展采用 shadcn/ui 与 8-bit 复古风格混合的项目，尤其是需要保持 components/ui 目录约定一致、避免代码检查工具干扰组件原有模式的开发工作。

限制

资料未提供该技能对具体框架版本、构建工具或运行环境的额外限制说明。