82 lines
3.5 KiB
Markdown
82 lines
3.5 KiB
Markdown
---
|
||
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 焦点样式?
|