shadcn-ui-conventions

UI Component Conventions

The components/ui directory uses different conventions from the rest of the project. It's excluded from Biome/Ultracite linting to preserve shadcn/ui patterns.

When to use this skill

• When creating new UI components
• When modifying existing shadcn/ui components
• When implementing 8-bit retro styling
• When working with component imports and types

Linting

• Biome excludes this directory: biome.jsonc has "!components/ui" in the includes
• No Ultracite formatting: Components use their own patterns
• Run lint manually when needed: npx biome check components/ui/

Import Patterns

Base components (e.g., 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 components (e.g., 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";

Import order:

1. External libraries (class-variance-authority, @radix-ui)
2. Internal utils (@/lib/utils)
3. Base component alias (@/components/ui/component)
4. Retro stylesheet (@/components/ui/8bit/styles/retro.css)

Type Definitions

Base components: Inline props type with function

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

8bit components: Export interface separately

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

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

Ref Handling

Base components: Use 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 components: Use ref prop (React 19 pattern)

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

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

8bit Component Patterns

Retro CSS import: Required for all 8bit components

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

Base component alias: Import base component with alias

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

Variant overrides: 8bit variants often have minimal styles (borders/colors handled by CSS)

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

Reference Files

• components/ui/button.tsx - Base component example
• components/ui/8bit/button.tsx - 8bit wrapper example
• components/ui/dialog.tsx - Complex base component with Radix primitives