agent/.opencode/skills/design/shadcn-visual-standards/SKILL.md

name, description, tags

name	description	tags
shadcn-visual-standards	Visual design standards for Shadcn UI + Tailwind CSS projects	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 焦点样式?