---
name: shadcn-visual-standards
description: Visual design standards for Shadcn UI + Tailwind CSS projects
tags: [design, shadcn, tailwind, ui]
---

# 🎨 Shadcn UI + Tailwind CSS 视觉设计标准

## 核心设计理念

1. **原子化优先**: 所有样式必须通过 Tailwind Utility Classes 实现，严禁手写 CSS/SASS 文件。
2. **极简主义**: 遵循 Shadcn 默认的黑白灰基调，强调排版与留白，通过 `ring-offset` 和 `muted-foreground` 等细节提升质感。
3. **可定制主题**: 所有颜色引用必须基于 CSS 变量（如 `bg-primary`, `text-secondary`），严禁使用 Hex/RGB 硬编码，以支持深色模式切换。

## 🧩 组件视觉规范

### 1. 颜色系统 (Color System)
- **Primary**: 主色调，用于主要按钮、激活状态。
- **Secondary**: 次级色，用于次要操作、非强调背景。
- **Destructive**: 破坏性操作（如删除），通常为红色系。
- **Muted**: 弱化文本与背景，用于辅助说明。
- **Accent**: 强调色，用于 Hover、Focus 状态。
- **Background/Foreground**: 页面背景与主文本色。

**开发约束**:
- ✅ 正确: `<div class="bg-primary text-primary-foreground">`
- ❌ 错误: `<div class="bg-[#000] text-white">`

### 2. 布局与间距 (Layout & Spacing)
- **Container**: 必须使用 `container mx-auto` 进行主内容居中。
- **Grid System**: 使用 `grid-cols-1 md:grid-cols-3` 等响应式网格。
- **Spacing**:
  - 小间距: `gap-2` (0.5rem)
  - 组件间距: `gap-4` (1rem)
  - 区块间距: `py-8` / `my-10`
- **Radius**: 全局圆角统一使用 `rounded-md` 或 `rounded-lg`，保持风格一致。

### 3. 排版 (Typography)
- **Headings**:
  - H1: `text-4xl font-extrabold tracking-tight lg:text-5xl`
  - H2: `text-3xl font-semibold tracking-tight first:mt-0`
  - H3: `text-2xl font-semibold tracking-tight`
- **Body**: `leading-7 [&:not(:first-child)]:mt-6`
- **Small/Muted**: `text-sm text-muted-foreground`

### 4. 交互反馈 (Interaction)
- **Hover**: 所有可交互元素必须有 hover 态。
  - 按钮: `hover:bg-primary/90`
  - 卡片: `hover:bg-accent hover:text-accent-foreground`
- **Focus**: 必须保留键盘焦点的可见性。
  - 标准: `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`
- **Disabled**: `disabled:pointer-events-none disabled:opacity-50`

---

## 🔍 代码审计要点 (@code-spec)

当 @code-spec 执行审计时，必须检查以下条目：

1. **硬编码颜色检查**: 
   - 检查是否使用了 `#ffffff`, `rgb(0,0,0)` 等硬编码颜色值? (必须替换为 `bg-background` 等)
2. **Tailwind 冲突检查**:
   - 检查是否混用了 `style={{ ... }}` 和 `className`? (应完全移除 `style`)
   - 检查是否使用了 `cn()` 合并类名? (例如组件封装时)
3. **响应式断点**:
   - 检查主要的布局容器是否包含了移动端优先的类名 (e.g. `w-full md:w-auto`)?

---

## 🧪 测试与验收标准 (@qa-tester)

当 @qa-tester 执行测试时，必须验证以下指标：

1. **深色模式 (Dark Mode)**
   - 切换到深色模式后，所有背景是否自动变黑? 文字是否自动变白?
   - 检查是否有难以辨认的低对比度文本（如深灰色字在黑色背景上）。
2. **移动端适配**
   - 在 375px 宽度下，Grid 布局是否自动堆叠为单列 (`grid-cols-1`)?
   - 没有任何横向滚动条出现。
3. **无障碍 (a11y)**
   - 使用 Tab 键能否遍历所有按钮和链接，并且有明显的 Ring 焦点样式?