@tinkcarlos/skillora 0.2.0

package/.claude/skills/frontend-design/references/pre-delivery-checklist.md

@@ -0,0 +1,153 @@
+# Pre-Delivery Checklist
+
+专业 UI 交付前的强制检查清单，按优先级分类。
+
+---
+
+## 🔴 CRITICAL - 可访问性 (Accessibility)
+
+必须 100% 通过，否则不能交付。
+
+| # | 检查项 | 验证方法 |
+|---|--------|----------|
+| 1 | 颜色对比度 ≥ 4.5:1 (正文) / ≥ 3:1 (大文本) | Chrome DevTools > Lighthouse |
+| 2 | 所有图片有 alt 属性 | `img:not([alt])` 选择器检查 |
+| 3 | 所有表单元素有关联 label | `input:not([id])` 或缺少 for 属性 |
+| 4 | 键盘可完全导航 | Tab 键遍历所有交互元素 |
+| 5 | 焦点状态可见 | 检查 :focus 样式 |
+| 6 | 不仅依赖颜色传达信息 | 图标+文字组合 |
+| 7 | 语义化 HTML 结构 | header, nav, main, footer |
+| 8 | 标题层级正确 (H1→H2→H3) | 每页一个 H1 |
+
+---
+
+## 🔴 CRITICAL - 触摸与交互 (Touch & Interaction)
+
+| # | 检查项 | 标准 |
+|---|--------|------|
+| 1 | 触摸目标尺寸 | ≥ 44x44px |
+| 2 | 按钮有 cursor: pointer | 所有可点击元素 |
+| 3 | 悬停状态 | 所有交互元素有 :hover |
+| 4 | 禁用状态 | opacity: 0.5 + cursor: not-allowed |
+| 5 | 加载状态 | 异步操作显示 spinner |
+| 6 | 点击反馈 | :active 状态或动画 |
+
+---
+
+## 🟠 HIGH - 性能 (Performance)
+
+| # | 检查项 | 目标值 |
+|---|--------|--------|
+| 1 | First Contentful Paint | < 1.8s |
+| 2 | Largest Contentful Paint | < 2.5s |
+| 3 | Cumulative Layout Shift | < 0.1 |
+| 4 | First Input Delay | < 100ms |
+| 5 | 图片懒加载 | loading="lazy" |
+| 6 | 图片尺寸预留 | width/height 属性 |
+
+---
+
+## 🟠 HIGH - 布局 (Layout)
+
+| # | 检查项 | 验证方法 |
+|---|--------|----------|
+| 1 | 响应式断点测试 | 320px, 768px, 1024px, 1440px |
+| 2 | 无水平滚动 | 所有断点检查 |
+| 3 | 内容不溢出 | overflow 检查 |
+| 4 | 间距一致 | 使用设计系统 spacing |
+| 5 | 对齐正确 | 网格/Flexbox 对齐 |
+
+---
+
+## 🟡 MEDIUM - 视觉一致性 (Visual Consistency)
+
+| # | 检查项 | 标准 |
+|---|--------|------|
+| 1 | 颜色使用设计系统变量 | CSS 变量 |
+| 2 | 字体使用设计系统 | font-family 变量 |
+| 3 | 圆角一致 | border-radius 变量 |
+| 4 | 阴影一致 | box-shadow 变量 |
+| 5 | 图标风格统一 | 同一图标库 |
+
+---
+
+## 🟡 MEDIUM - 表单 (Forms)
+
+| # | 检查项 | 标准 |
+|---|--------|------|
+| 1 | 错误状态样式 | 红色边框 + 错误消息 |
+| 2 | 成功状态样式 | 绿色确认 |
+| 3 | 占位符不作为标签 | 有独立 label |
+| 4 | 必填字段标记 | * 或 "required" |
+| 5 | 输入类型正确 | email, tel, number |
+
+---
+
+## 🟢 LOW - 微交互 (Micro-interactions)
+
+| # | 检查项 | 标准 |
+|---|--------|------|
+| 1 | 过渡动画 | transition: 0.2-0.3s |
+| 2 | 骨架屏加载 | 替代 spinner |
+| 3 | 空状态设计 | 友好提示 + 操作引导 |
+| 4 | Toast 通知 | 3-5s 自动消失 |
+
+---
+
+## 🟢 LOW - 图表 (Charts)
+
+| # | 检查项 | 标准 |
+|---|--------|------|
+| 1 | 图例可见 | 不遮挡数据 |
+| 2 | 颜色可区分 | 色盲友好 |
+| 3 | 数据标签 | 关键数据点标注 |
+| 4 | 响应式 | 小屏幕适配 |
+
+---
+
+## ❌ 绝对禁止 (NEVER DO)
+
+| # | 禁止项 | 原因 |
+|---|--------|------|
+| 1 | Emoji 作为功能图标 | 跨平台不一致 |
+| 2 | 纯图标按钮无 tooltip | 可访问性问题 |
+| 3 | 自动播放视频/音频 | 用户体验差 |
+| 4 | 禁用浏览器缩放 | 可访问性违规 |
+| 5 | 移除焦点轮廓 | 键盘用户无法导航 |
+| 6 | 闪烁内容 (>3次/秒) | 可能引发癫痫 |
+| 7 | 固定像素字体大小 | 无法缩放 |
+| 8 | 无限滚动无"回到顶部" | 用户体验差 |
+
+---
+
+## 快速验证命令
+
+```bash
+# Lighthouse 审计
+npx lighthouse http://localhost:3000 --view
+
+# 可访问性检查
+npx axe http://localhost:3000
+
+# 对比度检查
+# Chrome DevTools > Elements > Styles > 点击颜色值
+```
+
+---
+
+## 交付前最终确认
+
+```markdown
+## 交付检查清单
+
+- [ ] 🔴 可访问性检查全部通过
+- [ ] 🔴 触摸目标 ≥ 44px
+- [ ] 🔴 所有按钮有 cursor: pointer
+- [ ] 🔴 所有交互元素有 hover 状态
+- [ ] 🟠 Lighthouse 性能分数 ≥ 90
+- [ ] 🟠 响应式测试通过 (320px-1440px)
+- [ ] 🟡 设计系统变量使用一致
+- [ ] 🟡 表单验证状态完整
+- [ ] 🟢 过渡动画流畅
+- [ ] ❌ 无禁止项违规
+```

package/.claude/skills/frontend-design/references/responsive-design.md

@@ -0,0 +1,555 @@
+# Responsive Design Guide
+
+防止窗口大小变化导致元素错乱、重叠、变形的完整指南。
+
+## 🔴 核心原则
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  响应式设计黄金法则                                          │
+├─────────────────────────────────────────────────────────────┤
+│  ✅ 使用相对单位 (%, rem, vw, vh, fr)                        │
+│  ✅ 使用弹性布局 (Flexbox, Grid)                             │
+│  ✅ 使用 CSS 函数 (clamp, min, max, minmax)                  │
+│  ✅ 使用 Container Queries (@container)                      │
+│  ❌ 避免固定宽高 (px)                                        │
+│  ❌ 避免绝对定位 (position: absolute)                        │
+│  ❌ 避免 overflow: hidden 隐藏问题                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 1. 防止元素重叠
+
+### 问题原因
+- 使用固定宽度 + 绝对定位
+- 多个元素竞争同一空间
+- z-index 管理混乱
+
+### 解决方案
+
+```css
+/* ❌ 错误: 固定宽度 + 绝对定位 */
+.sidebar { width: 300px; position: absolute; left: 0; }
+.content { margin-left: 300px; }
+
+/* ✅ 正确: Flexbox 自动分配 */
+.container { display: flex; }
+.sidebar { flex: 0 0 auto; min-width: 200px; max-width: 300px; }
+.content { flex: 1 1 auto; min-width: 0; }
+
+/* ✅ 正确: Grid 自动分配 */
+.container {
+  display: grid;
+  grid-template-columns: minmax(200px, 300px) 1fr;
+}
+```
+
+## 2. 防止元素变形
+
+### 问题原因
+- 图片/视频没有设置 aspect-ratio
+- 容器被内容撑破
+- 文字溢出
+
+### 解决方案
+
+```css
+/* 图片保持比例 */
+img {
+  max-width: 100%;
+  height: auto;
+  object-fit: cover; /* 或 contain */
+  aspect-ratio: 16 / 9; /* 固定比例 */
+}
+
+/* 容器防止撑破 */
+.card {
+  min-width: 0; /* Flexbox 子元素必须 */
+  overflow-wrap: break-word;
+  word-break: break-word;
+}
+
+/* 文字截断 */
+.title {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* 多行截断 */
+.description {
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+```
+
+## 3. 防止元素错乱
+
+### 问题原因
+- 断点设置不合理
+- 没有使用 min/max 约束
+- 布局没有降级方案
+
+### 解决方案
+
+```css
+/* ✅ 使用 clamp() 自适应 */
+.container {
+  width: clamp(320px, 90vw, 1200px);
+  padding: clamp(1rem, 3vw, 3rem);
+  font-size: clamp(14px, 2vw, 18px);
+}
+
+/* ✅ Grid 自动换行 */
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: 1rem;
+}
+
+/* ✅ Flexbox 自动换行 */
+.flex-wrap {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1rem;
+}
+.flex-wrap > * {
+  flex: 1 1 280px; /* 最小 280px，自动增长 */
+  max-width: 100%;
+}
+```
+
+## 4. Container Queries (2024+ 推荐)
+
+基于容器大小而非视口大小响应：
+
+```css
+/* 定义容器 */
+.card-container {
+  container-type: inline-size;
+  container-name: card;
+}
+
+/* 基于容器宽度响应 */
+@container card (min-width: 400px) {
+  .card { flex-direction: row; }
+}
+
+@container card (max-width: 399px) {
+  .card { flex-direction: column; }
+}
+```
+
+**Tailwind CSS 语法**:
+```html
+<div class="@container">
+  <div class="flex flex-col @md:flex-row">
+    <!-- 容器 >= 448px 时变为横向 -->
+  </div>
+</div>
+```
+
+## 5. 断点策略
+
+### 推荐断点 (Mobile-First)
+
+```css
+/* 基础样式 (移动端) */
+.element { ... }
+
+/* 平板 */
+@media (min-width: 640px) { ... }
+
+/* 小桌面 */
+@media (min-width: 768px) { ... }
+
+/* 桌面 */
+@media (min-width: 1024px) { ... }
+
+/* 大桌面 */
+@media (min-width: 1280px) { ... }
+```
+
+### Tailwind 断点
+
+| 前缀 | 最小宽度 | 典型设备 |
+|------|----------|----------|
+| (无) | 0px | 手机 |
+| `sm:` | 640px | 大手机 |
+| `md:` | 768px | 平板 |
+| `lg:` | 1024px | 笔记本 |
+| `xl:` | 1280px | 桌面 |
+| `2xl:` | 1536px | 大桌面 |
+
+## 6. 常见布局模式
+
+### 圣杯布局 (Header + Sidebar + Content + Footer)
+
+```css
+.layout {
+  display: grid;
+  grid-template-rows: auto 1fr auto;
+  grid-template-columns: minmax(200px, 250px) 1fr;
+  min-height: 100vh;
+}
+
+.header { grid-column: 1 / -1; }
+.footer { grid-column: 1 / -1; }
+
+@media (max-width: 768px) {
+  .layout { grid-template-columns: 1fr; }
+  .sidebar { display: none; } /* 或改为抽屉 */
+}
+```
+
+### 卡片网格 (自适应列数)
+
+```css
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+  gap: 1.5rem;
+}
+```
+
+### 居中容器
+
+```css
+.container {
+  width: min(90%, 1200px);
+  margin-inline: auto;
+  padding-inline: 1rem;
+}
+```
+
+## 7. 防止大片空白 & 动态高度
+
+### 问题原因
+- 固定高度导致内容少时出现空白
+- 容器高度不随内容变化
+- 长内容拉长整个页面
+
+### 解决方案
+
+```css
+/* ✅ 动态高度: 根据内容自适应 */
+.card {
+  height: auto;           /* 默认自适应 */
+  min-height: fit-content; /* 至少容纳内容 */
+}
+
+/* ✅ 限制最大高度 + 滚动 */
+.content-area {
+  max-height: 60vh;       /* 最大占视口 60% */
+  overflow-y: auto;       /* 超出时滚动 */
+}
+
+/* ✅ 弹性填充剩余空间 */
+.layout {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+}
+.main { flex: 1; }        /* 自动填充剩余空间 */
+.footer { flex-shrink: 0; }
+
+/* ✅ Grid 自动行高 */
+.grid {
+  display: grid;
+  grid-template-rows: auto 1fr auto; /* header/main/footer */
+  grid-auto-rows: min-content;       /* 其他行按内容 */
+}
+```
+
+### Tailwind CSS 语法
+
+```html
+<!-- 动态高度 -->
+<div class="h-auto min-h-fit">...</div>
+
+<!-- 限制高度 + 滚动 -->
+<div class="max-h-[60vh] overflow-y-auto">...</div>
+
+<!-- 弹性填充 -->
+<div class="flex flex-col min-h-screen">
+  <header class="shrink-0">...</header>
+  <main class="flex-1">...</main>
+  <footer class="shrink-0">...</footer>
+</div>
+```
+
+## 8. 滚动容器最佳实践
+
+### 何时使用滚动
+
+| 场景 | 方案 |
+|------|------|
+| 长列表 (>10项) | `max-height` + `overflow-y: auto` |
+| 聊天/日志 | 固定高度 + 滚动 + `scroll-snap` |
+| 表格数据 | 表头固定 + 表体滚动 |
+| 侧边栏 | `max-height: 100vh` + `overflow-y: auto` |
+
+### 滚动容器模式
+
+```css
+/* ✅ 基础滚动容器 */
+.scroll-container {
+  max-height: 400px;      /* 或 50vh */
+  overflow-y: auto;
+  overscroll-behavior: contain; /* 防止滚动穿透 */
+}
+
+/* ✅ 平滑滚动 */
+.smooth-scroll {
+  scroll-behavior: smooth;
+}
+
+/* ✅ 滚动吸附 (卡片/轮播) */
+.snap-container {
+  overflow-x: auto;
+  scroll-snap-type: x mandatory;
+  -webkit-overflow-scrolling: touch; /* iOS 惯性滚动 */
+}
+.snap-item {
+  scroll-snap-align: start;
+}
+
+/* ✅ 自定义滚动条 */
+.custom-scrollbar::-webkit-scrollbar {
+  width: 6px;
+}
+.custom-scrollbar::-webkit-scrollbar-thumb {
+  background: rgba(0,0,0,0.2);
+  border-radius: 3px;
+}
+```
+
+### Tailwind CSS 滚动
+
+```html
+<!-- 基础滚动 -->
+<div class="max-h-96 overflow-y-auto overscroll-contain">...</div>
+
+<!-- 横向滚动吸附 -->
+<div class="overflow-x-auto snap-x snap-mandatory">
+  <div class="snap-start">...</div>
+</div>
+
+<!-- 平滑滚动 -->
+<div class="scroll-smooth">...</div>
+```
+
+## 9. 浏览器缩放适配 (Zoom Adaptation)
+
+### 🔴 缩放级别测试要求
+
+必须在以下缩放级别测试 UI 正常显示：
+
+| 缩放级别 | 测试重点 |
+|----------|----------|
+| 50% | 元素是否过小、文字是否可读 |
+| 75% | 布局是否完整、间距是否合理 |
+| 100% | 基准测试 |
+| 125% | 常见 Windows 缩放，元素是否溢出 |
+| 150% | 高 DPI 显示器，布局是否错乱 |
+| 200% | 极端测试，是否出现重叠 |
+
+### 缩放安全 CSS 模式
+
+```css
+/* ✅ 缩放安全的基础设置 */
+html {
+  font-size: 100%; /* 不要用 px，让浏览器缩放生效 */
+  -webkit-text-size-adjust: 100%;
+  text-size-adjust: 100%;
+}
+
+/* ✅ 使用 rem 而非 px */
+.container {
+  padding: 1.5rem;      /* 随缩放变化 */
+  margin: 2rem auto;
+  max-width: 75rem;     /* 1200px at 100% */
+}
+
+/* ✅ 缩放安全的最小尺寸 */
+.button {
+  min-height: 2.75rem;  /* 44px 触摸目标 */
+  min-width: 2.75rem;
+  padding: 0.5rem 1rem;
+}
+
+/* ✅ 缩放安全的间距系统 */
+:root {
+  --space-xs: 0.25rem;  /* 4px */
+  --space-sm: 0.5rem;   /* 8px */
+  --space-md: 1rem;     /* 16px */
+  --space-lg: 1.5rem;   /* 24px */
+  --space-xl: 2rem;     /* 32px */
+  --space-2xl: 3rem;    /* 48px */
+}
+
+/* ✅ 缩放安全的字体大小 */
+:root {
+  --text-xs: 0.75rem;   /* 12px */
+  --text-sm: 0.875rem;  /* 14px */
+  --text-base: 1rem;    /* 16px */
+  --text-lg: 1.125rem;  /* 18px */
+  --text-xl: 1.25rem;   /* 20px */
+  --text-2xl: 1.5rem;   /* 24px */
+  --text-3xl: 1.875rem; /* 30px */
+}
+```
+
+### 缩放问题排查
+
+```css
+/* ❌ 问题: 固定 px 值在高缩放下过小 */
+.icon { width: 16px; height: 16px; }
+
+/* ✅ 解决: 使用 rem 或 em */
+.icon { width: 1rem; height: 1rem; }
+
+/* ❌ 问题: 固定视口单位在缩放时不变 */
+.hero { height: 100vh; font-size: 5vw; }
+
+/* ✅ 解决: 结合 clamp 限制范围 */
+.hero {
+  min-height: 100vh;
+  font-size: clamp(1.5rem, 5vw, 4rem);
+}
+
+/* ❌ 问题: 绝对定位在缩放时错位 */
+.tooltip { position: absolute; top: 30px; left: 50px; }
+
+/* ✅ 解决: 使用 transform 或相对单位 */
+.tooltip {
+  position: absolute;
+  top: 1.875rem;
+  left: 3.125rem;
+  transform: translateX(-50%);
+}
+```
+
+## 10. 8px 间距系统
+
+### 为什么使用 8px 系统
+
+- 8 可被 2、4 整除，适合各种缩放
+- 与常见屏幕分辨率对齐
+- 视觉一致性更强
+
+### 间距比例表
+
+| 级别 | rem | px (100%) | 用途 |
+|------|-----|-----------|------|
+| 0 | 0 | 0 | 无间距 |
+| 1 | 0.25rem | 4px | 图标与文字 |
+| 2 | 0.5rem | 8px | 紧凑元素间 |
+| 3 | 0.75rem | 12px | 表单元素间 |
+| 4 | 1rem | 16px | 段落间 |
+| 5 | 1.25rem | 20px | 卡片内边距 |
+| 6 | 1.5rem | 24px | 区块间 |
+| 8 | 2rem | 32px | 大区块间 |
+| 10 | 2.5rem | 40px | 页面区域间 |
+| 12 | 3rem | 48px | 主要分隔 |
+| 16 | 4rem | 64px | 页面顶部/底部 |
+
+### Tailwind 间距映射
+
+```html
+<!-- 8px 系统对应 Tailwind -->
+<div class="p-2">8px padding</div>
+<div class="p-4">16px padding</div>
+<div class="p-6">24px padding</div>
+<div class="p-8">32px padding</div>
+
+<div class="gap-2">8px gap</div>
+<div class="gap-4">16px gap</div>
+<div class="gap-6">24px gap</div>
+
+<div class="space-y-2">8px vertical spacing</div>
+<div class="space-y-4">16px vertical spacing</div>
+```
+
+## 11. 响应式断点测试矩阵
+
+### 必测断点
+
+| 断点 | 宽度 | 设备类型 | 测试重点 |
+|------|------|----------|----------|
+| xs | 320px | iPhone SE | 最小可用宽度 |
+| sm | 375px | iPhone 12/13 | 主流手机 |
+| md | 768px | iPad | 平板竖屏 |
+| lg | 1024px | iPad Pro/笔记本 | 平板横屏/小桌面 |
+| xl | 1280px | 桌面 | 标准桌面 |
+| 2xl | 1440px | 大桌面 | 设计稿基准 |
+| 3xl | 1920px | 全高清 | 大屏测试 |
+
+### 测试检查表
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  响应式测试检查表 (每个断点都要检查)                              │
+├─────────────────────────────────────────────────────────────────┤
+│  □ 导航栏: 是否正确折叠/展开                                     │
+│  □ 卡片网格: 列数是否正确变化                                    │
+│  □ 表格: 是否有横向滚动或响应式处理                              │
+│  □ 表单: 输入框宽度是否合适                                      │
+│  □ 图片: 是否正确缩放，无变形                                    │
+│  □ 文字: 是否可读，无溢出                                        │
+│  □ 按钮: 是否可点击，间距足够                                    │
+│  □ 模态框: 是否居中，不超出屏幕                                  │
+│  □ 侧边栏: 是否正确隐藏/显示                                     │
+│  □ 页脚: 是否在底部，内容完整                                    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 12. 完整检查清单
+
+每次实现 UI 时必须检查：
+
+### 布局检查
+- [ ] 所有宽度使用相对单位或 clamp/min/max
+- [ ] 图片设置 max-width: 100% 和 aspect-ratio
+- [ ] Flexbox 子元素设置 min-width: 0
+- [ ] 长文本有截断或换行策略
+- [ ] Grid 使用 auto-fit/auto-fill + minmax
+- [ ] 无大片空白区域
+- [ ] 动态高度随内容变化
+
+### 响应式检查
+- [ ] 测试 320px ~ 1920px 全范围
+- [ ] 测试窗口缩放时无元素重叠
+- [ ] 测试内容过长时无溢出
+- [ ] 长内容区域使用 max-height + 滚动
+
+### 缩放检查 (新增)
+- [ ] 测试浏览器缩放 50% - 200%
+- [ ] 所有尺寸使用 rem 而非 px
+- [ ] 间距遵循 8px 系统
+- [ ] 字体大小使用相对单位
+- [ ] 触摸目标至少 44px (2.75rem)
+
+### 间距检查 (新增)
+- [ ] 内边距遵循 8px 倍数
+- [ ] 外边距遵循 8px 倍数
+- [ ] 元素间距一致
+- [ ] 无过大或过小的间距
+
+## 13. 调试技巧
+
+```css
+/* 临时显示所有元素边界 */
+* { outline: 1px solid red !important; }
+
+/* 检查溢出 */
+* { outline: 1px solid rgba(255,0,0,0.2); }
+body { overflow-x: hidden; } /* 如果出现横向滚动条，说明有溢出 */
+```
+
+**浏览器工具**:
+- Chrome DevTools → 设备模式 → 响应式测试
+- Firefox → 响应式设计模式
+- 拖动窗口边缘测试实时响应