# 样式与自定义

关于主题、CSS 变量以及添加自定义颜色，请参阅 [customization.md](../customization.md)。

## 目录

- 语义化颜色
- 优先使用内置变体
- className 仅用于布局
- 避免 space-x-* / space-y-*
- 宽高相等时优先使用 size-*
- 优先使用 truncate 简写
- 不要手动覆写 dark: 颜色
- 使用 cn() 处理条件类名
- 浮层组件上不要手动设置 z-index

---

## 语义化颜色

**错误写法：**

```tsx
<div className="bg-blue-500 text-white">
  <p className="text-gray-600">辅助文本</p>
</div>
```

**正确写法：**

```tsx
<div className="bg-primary text-primary-foreground">
  <p className="text-muted-foreground">辅助文本</p>
</div>
```

---

## 状态/状态指示器不要使用原始颜色值

对于正向、负向或状态指示器，应使用 Badge 变体、`text-destructive` 等语义化标记，或定义自定义 CSS 变量——不要直接使用 Tailwind 原始颜色。

**错误写法：**

```tsx
<span className="text-emerald-600">+20.1%</span>
<span className="text-green-500">活跃</span>
<span className="text-red-600">-3.2%</span>
```

**正确写法：**

```tsx
<Badge variant="secondary">+20.1%</Badge>
<Badge>活跃</Badge>
<span className="text-destructive">-3.2%</span>
```

如果需要的成功/正向颜色不存在对应的语义化标记，请使用 Badge 变体，或请用户向主题中添加自定义 CSS 变量（参见 [customization.md](../customization.md)）。

---

## 优先使用内置变体

**错误写法：**

```tsx
<Button className="border border-input bg-transparent hover:bg-accent">
  点击我
</Button>
```

**正确写法：**

```tsx
<Button variant="outline">点击我</Button>
```

---

## className 仅用于布局

使用 `className` 处理布局（例如 `max-w-md`、`mx-auto`、`mt-4`），**不要**用它覆写组件的颜色或排版。如需修改颜色，请使用语义化标记、内置变体或 CSS 变量。

**错误写法：**

```tsx
<Card className="bg-blue-100 text-blue-900 font-bold">
  <CardContent>仪表盘</CardContent>
</Card>
```

**正确写法：**

```tsx
<Card className="max-w-md mx-auto">
  <CardContent>仪表盘</CardContent>
</Card>
```

若要自定义组件的外观，请按以下顺序优先选择：
1. **内置变体**——`variant="outline"`、`variant="destructive"` 等。
2. **语义化颜色标记**——`bg-primary`、`text-muted-foreground`。
3. **CSS 变量**——在全局 CSS 文件中定义自定义颜色（参见 [customization.md](../customization.md)）。

---

## 避免 space-x-* / space-y-*

请改用 `gap-*`。`space-y-4` → `flex flex-col gap-4`。`space-x-2` → `flex gap-2`。

```tsx
<div className="flex flex-col gap-4">
  <Input />
  <Input />
  <Button>提交</Button>
</div>
```

---

## 宽高相等时优先使用 size-*

使用 `size-10` 而非 `w-10 h-10`。适用于图标、头像、骨架屏等场景。

---

## 优先使用 truncate 简写

使用 `truncate` 而非 `overflow-hidden text-ellipsis whitespace-nowrap`。

---

## 不要手动覆写 dark: 颜色

使用语义化标记——它们通过 CSS 变量处理亮色/暗色主题。使用 `bg-background text-foreground` 而非 `bg-white dark:bg-gray-950`。

---

## 使用 cn() 处理条件类名

使用项目中的 `cn()` 工具函数处理条件性或合并的类名字符串。不要在 className 字符串中手动编写三元表达式。

**错误写法：**

```tsx
<div className={`flex items-center ${isActive ? "bg-primary text-primary-foreground" : "bg-muted"}`}>
```

**正确写法：**

```tsx
import { cn } from "@/lib/utils"

<div className={cn("flex items-center", isActive ? "bg-primary text-primary-foreground" : "bg-muted")}>
```

---

## 浮层组件上不要手动设置 z-index

`Dialog`、`Sheet`、`Drawer`、`AlertDialog`、`DropdownMenu`、`Popover`、`Tooltip`、`HoverCard` 会自行处理层叠顺序。切勿添加 `z-50` 或 `z-[999]`。