设计系统组件

构建可复用的组件，利用Surface原语和CVA（class-variance-authority）来使用设计令牌。

使用场景

- 使用设计令牌构建组件库
需要基于变体的样式（尺寸、颜色、状态）
创建具有一致表面的分层UI
需要类型安全的组件API

模式1：Surface原语

适用于所有分层表面的单一组件：

tsx
import { cva, type VariantProps } from class-variance-authority;
import { cn } from @/lib/utils;

const surfaceVariants = cva(
rounded-lg backdrop-blur-sm transition-colors,
{
variants: {
layer: {
panel: bg-tone-cadet/40 border border-tone-jordy/10 shadow-card,
tile: bg-tone-midnight/60 border border-tone-jordy/5,
chip: bg-tone-cyan/10 border border-tone-cyan/20 rounded-full,
deep: bg-tone-void/80,
metric: bg-tone-cadet/20 border border-tone-jordy/8,
glass: bg-glass-bg backdrop-blur-lg border border-glass-border,
},
interactive: {
true: cursor-pointer hover:bg-tone-cadet/50 active:scale-[0.98],
false: ,
},
glow: {
true: shadow-glow,
false: ,
},
},
defaultVariants: {
layer: tile,
interactive: false,
glow: false,
},
}
);

interface SurfaceProps
extends React.HTMLAttributes,
VariantProps {}

export function Surface({
layer,
interactive,
glow,
className,
...props
}: SurfaceProps) {
return (
className={cn(surfaceVariants({ layer, interactive, glow }), className)}
{...props}
/>
);
}

使用示例

tsx

仪表盘

活跃

$1,234.56

模式2：CVA按钮变体

tsx
const buttonVariants = cva(
inline-flex items-center justify-center rounded-md font-medium transition-all focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50,
{
variants: {
variant: {
default: bg-primary text-primary-foreground hover:bg-primary/90,
destructive: bg-destructive text-destructive-foreground hover:bg-destructive/90,
outline: border border-input bg-background hover:bg-accent hover:text-accent-foreground,
ghost: hover:bg-accent hover:text-accent-foreground,
link: text-primary underline-offset-4 hover:underline,
cyber: bg-gradient-to-r from-tone-cadet to-tone-azure text-white border border-tone-cyan/30 shadow-glow hover:shadow-glow-lg,
},
size: {
default: h-10 px-4 py-2,
sm: h-9 rounded-md px-3,
lg: h-11 rounded-md px-8,
icon: h-10 w-10,
},
},
defaultVariants: {
variant: default,
size: default,
},
}
);

模式3：指标显示组件

tsx
const metricVariants = cva(
font-mono tabular-nums,
{
variants: {
size: {
lg: text-3xl font-bold tracking-tight,
md: text-xl font-semibold,
sm: text-base font-medium,
},
trend: {
positive: text-success,
negative: text-destructive,
neutral: text-foreground,
},
},
defaultVariants: {
size: md,
trend: neutral,
},
}
);

interface MetricProps extends VariantProps {
value: string | number;
label?: string;
prefix?: string;
suffix?: string;
}

export function Metric({
value,
label,
prefix = ,
suffix = ,
size,
trend,
}: MetricProps) {
return (

{label && (

{label}

)}

{prefix}{value}{suffix}

);
}

模式4：带标题的卡片

tsx
interface CardProps {
title?: string;
description?: string;
action?: React.ReactNode;
children: React.ReactNode;
}

export function Card({ title, description, action, children }: CardProps) {
return (

{(title || action) && (

{title && (

{title}

)}
{description && (

{description}

)}

{action}

)}

{children}

);
}

模式5：徽章/标签变体

tsx
const badgeVariants = cva(
inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium transition-colors,
{
variants: {
variant: {
default: bg-primary/10 text-primary border border-primary/20,
success: bg-success/10 text-success border border-success/20,
warning: bg-warning/10 text-warning border border-warning/20,
destructive: bg-destructive/10 text-destructive border border-destructive/20,
outline: border border-input text-foreground,
},
},
defaultVariants: {
variant: default,
},
}
);

模式6：组合变体

将CVA与条件类结合：

tsx
function StatusIndicator({
status,
size = md
}: {
status: online | offline | away;
size?: sm | md | lg;
}) {
const sizeClasses = {
sm: size-2,
md: size-3,
lg: size-4,
};

const statusClasses = {
online: bg-success animate-pulse,
offline: bg-muted-foreground,
away: bg-warning,
};

return (
className={cn(
rounded-full,
sizeClasses[size],
statusClasses[status]
)}
/>
);
}

禁止事项

- 构建自定义卡片容器 — 使用Surface原语
在组件中硬编码颜色 — 使用设计令牌
跳过变体类型 — CVA提供类型安全
混合样式方法 — 选择CVA或cn()，不要随机使用内联样式
忘记默认变体 — 组件应在不传props时也能正常工作

快速参考

tsx
// 1. 使用CVA定义变体
const variants = cva(base-classes, {
variants: {
size: { sm: ..., md: ..., lg: ... },
color: { primary: ..., secondary: ... },
},
defaultVariants: { size: md, color: primary },
});

// 2. 从变体类型化props
interface Props extends VariantProps {}

// 3. 在组件中应用

设计系统组件