Back to Details

shadcn-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

shadcn/ui Patterns

shadcn/ui 组件模式

Beautifully designed, accessible components you own and customize.
由你自主拥有并可定制的、设计精美且具备可访问性的组件。

Core Pattern: CVA (Class Variance Authority)

核心模式：CVA（Class Variance Authority）

Declarative, type-safe variant definitions:
tsx
import { cva, type VariantProps } from 'class-variance-authority'

const buttonVariants = cva(
  // Base classes (always applied)
  'inline-flex items-center justify-center rounded-md font-medium transition-colors',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground',
        outline: 'border border-input bg-background hover:bg-accent',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
      },
      size: {
        default: 'h-10 px-4 py-2',
        sm: 'h-9 px-3',
        lg: 'h-11 px-8',
        icon: 'h-10 w-10',
      },
    },
    compoundVariants: [
      { variant: 'outline', size: 'lg', className: 'border-2' },
    ],
    defaultVariants: {
      variant: 'default',
      size: 'default',
    },
  }
)

// Type-safe props
interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {}
声明式、类型安全的变体定义：
tsx
import { cva, type VariantProps } from 'class-variance-authority'

const buttonVariants = cva(
  // Base classes (always applied)
  'inline-flex items-center justify-center rounded-md font-medium transition-colors',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground',
        outline: 'border border-input bg-background hover:bg-accent',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
      },
      size: {
        default: 'h-10 px-4 py-2',
        sm: 'h-9 px-3',
        lg: 'h-11 px-8',
        icon: 'h-10 w-10',
      },
    },
    compoundVariants: [
      { variant: 'outline', size: 'lg', className: 'border-2' },
    ],
    defaultVariants: {
      variant: 'default',
      size: 'default',
    },
  }
)

// Type-safe props
interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {}

Core Pattern: cn() Utility

核心模式：cn() 工具函数

Combines 
clsx
+ 
tailwind-merge
for conflict resolution:
tsx
import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

// Usage - later classes win
cn('px-4 py-2', 'px-6') // => 'py-2 px-6'
cn('text-red-500', condition && 'text-blue-500')
结合
clsx
与
tailwind-merge
解决样式冲突：
tsx
import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

// Usage - later classes win
cn('px-4 py-2', 'px-6') // => 'py-2 px-6'
cn('text-red-500', condition && 'text-blue-500')

OKLCH Theming (2026 Standard)

OKLCH 主题配置（2026标准）

Modern perceptually uniform color space:
css
:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --border: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  --radius: 0.625rem;
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.985 0 0);
  --destructive: oklch(0.396 0.141 25.723);
}
Why OKLCH?
  • Perceptually uniform (equal steps look equal)
  • Better dark mode contrast
  • Wide gamut support
  • Format: 
    oklch(lightness chroma hue)
现代感知一致的色彩空间：
css
:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --border: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  --radius: 0.625rem;
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.985 0 0);
  --destructive: oklch(0.396 0.141 25.723);
}
为什么选择OKLCH？
  • 感知一致性（色彩步进视觉效果一致）
  • 更优的暗色模式对比度
  • 支持广色域
  • 格式：
    oklch(亮度 色度 色相)

Component Extension Strategy

组件扩展策略

Wrap, don't modify source:
tsx
import { Button as ShadcnButton } from '@/components/ui/button'

// Extend with new variants
const Button = React.forwardRef<
  React.ElementRef<typeof ShadcnButton>,
  React.ComponentPropsWithoutRef<typeof ShadcnButton> & {
    loading?: boolean
  }
>(({ loading, children, disabled, ...props }, ref) => (
  <ShadcnButton ref={ref} disabled={disabled || loading} {...props}>
    {loading && <Spinner className="mr-2" />}
    {children}
  </ShadcnButton>
))
包装组件，而非修改源码：
tsx
import { Button as ShadcnButton } from '@/components/ui/button'

// Extend with new variants
const Button = React.forwardRef<
  React.ElementRef<typeof ShadcnButton>,
  React.ComponentPropsWithoutRef<typeof ShadcnButton> & {
    loading?: boolean
  }
>(({ loading, children, disabled, ...props }, ref) => (
  <ShadcnButton ref={ref} disabled={disabled || loading} {...props}>
    {loading && <Spinner className="mr-2" />}
    {children}
  </ShadcnButton>
))

Quick Reference

快速参考

bash
undefined
bash
undefined

Add components

Add components

npx shadcn@latest add button npx shadcn@latest add dialog
npx shadcn@latest add button npx shadcn@latest add dialog

Initialize in project

Initialize in project

npx shadcn@latest init
undefined
npx shadcn@latest init
undefined

Key Decisions

关键决策

DecisionRecommendation
Color formatOKLCH for perceptually uniform theming
Class mergingAlways use cn() for Tailwind conflicts
Extending componentsWrap, don't modify source files
VariantsUse CVA for type-safe multi-axis variants
决策项推荐方案
颜色格式采用OKLCH实现感知一致的主题配置
类名合并始终使用cn()解决Tailwind样式冲突
组件扩展包装组件，而非修改源文件
变体管理使用CVA实现类型安全的多轴变体系统

Related Skills

相关技能

  • radix-primitives
    - Underlying accessibility primitives
  • design-system-starter
    - Design system patterns
  • biome-linting
    - Code quality for components
  • radix-primitives
    - 底层可访问性基础组件
  • design-system-starter
    - 设计系统模式
  • biome-linting
    - 组件代码质量保障

References

参考资料

  • CVA Variant System - CVA patterns
  • OKLCH Theming - Modern color space
  • cn() Utility - Class merging
  • Component Extension - Extending components
  • Dark Mode - next-themes integration
  • CVA变体系统 - CVA相关模式
  • OKLCH主题配置 - 现代色彩空间
  • cn()工具函数 - 类名合并方案
  • 组件扩展 - 组件扩展方法
  • 暗色模式 - next-themes集成方案