@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/skill-orchestration.md

@@ -0,0 +1,143 @@
+# 多技能协作协议 (Multi-Skill Orchestration Protocol)
+
+本文档定义了代码审查过程中何时、如何调用其他技能的规范来进行专业审查。
+
+## 核心原则
+
+**代码审查需要多领域专业知识。** 审查涉及前端、后端、数据库、安全、性能等多个领域，单凭通用规则无法覆盖所有专业细节。本协议确保在审查时引用正确的专业技能规范。
+
+## 技能规范路由表 (Skill Standards Router)
+
+### 按代码类型 → 引用对应技能规范
+
+| 代码类型 | 引用技能规范 | 审查重点 |
+|----------|-------------|----------|
+| **前端 UI/组件** | `frontend-design` | 组件设计、状态管理、样式规范 |
+| **前端状态管理** | `react-state-management` | Redux/Zustand/Jotai 模式 |
+| **React 组件** | `react-state-management` + `tailwind-design-system` | Hooks、生命周期、样式 |
+| **Next.js 代码** | `nextjs-app-router-patterns` | SSR/SSG、RSC、路由 |
+| **Python 后端** | `async-python-patterns` + `fastapi-templates` | 异步模式、API 设计 |
+| **Node.js 后端** | `nodejs-backend-patterns` + `typescript-advanced-types` | 中间件、类型安全 |
+| **API 设计** | `api-design-principles` | RESTful/GraphQL 规范、契约 |
+| **数据库变更** | `database-migration` + `postgresql-table-design` | 迁移安全、索引设计 |
+| **SQL 查询** | `sql-optimization-patterns` | 性能、N+1、索引使用 |
+| **认证授权** | `auth-implementation-patterns` | JWT/OAuth2/RBAC |
+| **AI/LLM 代码** | `langchain-architecture` + `prompt-engineering-patterns` | Agent 设计、Prompt 优化 |
+| **RAG 实现** | `rag-implementation` + `embedding-strategies` | 检索策略、分块 |
+| **微服务** | `microservices-patterns` + `distributed-tracing` | 服务边界、追踪 |
+| **异步/并发** | `async-python-patterns` / `go-concurrency-patterns` | 竞态、锁、异步模式 |
+| **测试代码** | `python-testing-patterns` / `javascript-testing-patterns` | 测试模式、覆盖率 |
+
+### 强制引用规则
+
+| 触发条件 | 必须引用的技能规范 | 审查要点 |
+|----------|-------------------|----------|
+| 包含 React/Vue 组件 | `frontend-design` | 组件设计是否符合规范 |
+| 包含 API 端点 | `api-design-principles` | API 设计是否符合 REST/GraphQL 规范 |
+| 包含 ORM 模型变更 | `database-migration` | 迁移是否安全、是否有回滚策略 |
+| 包含 SQL 查询 | `sql-optimization-patterns` | 是否有 N+1、索引使用是否正确 |
+| 包含认证/授权逻辑 | `auth-implementation-patterns` | 安全实现是否正确 |
+| 包含异步/并发代码 | `async-python-patterns` / 对应语言技能 | 异步模式是否正确 |
+| 包含 LLM/AI 代码 | `langchain-architecture` | Agent 设计是否合理 |
+
+## 审查流程中的技能引用
+
+```
+代码审查开始
+       │
+       ▼
+┌──────────────────────────────────────────────────────┐
+│ Phase 0: 识别代码类型 + 选择技能规范                  │
+│ ─────────────────────────────────────────────────────│
+│ 1. 分析变更文件，识别代码类型                         │
+│ 2. 查询技能规范路由表                                 │
+│ 3. 加载对应技能的规范作为审查标准                     │
+└──────────────────────────────────────────────────────┘
+       │
+       ▼
+┌──────────────────────────────────────────────────────┐
+│ Phase 1-6: 按技能规范审查                             │
+│ ─────────────────────────────────────────────────────│
+│ 前端代码 → 按 frontend-design 规范审查               │
+│ 后端代码 → 按 api-design-principles 规范审查         │
+│ 数据库 → 按 database-migration 规范审查              │
+│ 安全 → 按 auth-implementation-patterns 规范审查      │
+└──────────────────────────────────────────────────────┘
+       │
+       ▼
+┌──────────────────────────────────────────────────────┐
+│ Phase 7: 输出审查报告 + 技能规范引用报告              │
+│ ─────────────────────────────────────────────────────│
+│ 记录引用了哪些技能规范                                │
+│ 标注哪些发现来自哪个技能规范                          │
+└──────────────────────────────────────────────────────┘
+```
+
+## 技能规范审查检查清单
+
+### 前端代码审查 (引用 `frontend-design`)
+
+| 检查项 | 来源技能 | P 级别 |
+|--------|----------|--------|
+| 组件是否遵循单一职责 | `frontend-design` | P2 |
+| 状态管理是否合理 | `react-state-management` | P1 |
+| 是否有适当的 loading/error/empty 状态 | `frontend-design` | P1 |
+| 样式是否遵循设计系统 | `tailwind-design-system` | P2 |
+| 是否有无障碍支持 | `frontend-design` | P2 |
+
+### 后端代码审查 (引用 `api-design-principles`)
+
+| 检查项 | 来源技能 | P 级别 |
+|--------|----------|--------|
+| API 路径是否符合 RESTful 规范 | `api-design-principles` | P2 |
+| 是否有适当的输入验证 | `api-design-principles` | P1 |
+| 错误响应格式是否一致 | `api-design-principles` | P2 |
+| 是否有适当的认证授权 | `auth-implementation-patterns` | P0 |
+
+### 数据库代码审查 (引用 `database-migration`)
+
+| 检查项 | 来源技能 | P 级别 |
+|--------|----------|--------|
+| 迁移是否可回滚 | `database-migration` | P0 |
+| 是否有数据备份策略 | `database-migration` | P1 |
+| 索引设计是否合理 | `postgresql-table-design` | P1 |
+| 是否有 N+1 查询问题 | `sql-optimization-patterns` | P1 |
+
+### 异步/并发代码审查 (引用对应语言技能)
+
+| 检查项 | 来源技能 | P 级别 |
+|--------|----------|--------|
+| 是否正确使用 async/await | `async-python-patterns` | P1 |
+| 是否有竞态条件 | `async-python-patterns` | P0 |
+| 资源是否正确释放 | `async-python-patterns` | P1 |
+| 超时是否合理设置 | `async-python-patterns` | P1 |
+
+## 技能协作输出模板
+
+审查报告必须包含技能规范引用部分：
+
+```markdown
+## 🔄 技能规范引用报告
+
+### 引用的技能规范
+| 技能规范 | 引用原因 | 应用于 |
+|----------|----------|--------|
+| `frontend-design` | 包含 React 组件 | Header.tsx, Modal.tsx |
+| `api-design-principles` | 包含 API 端点 | routes/users.py |
+| `database-migration` | 包含迁移文件 | alembic/versions/*.py |
+
+### 基于技能规范的发现
+| 发现 | 来源技能规范 | 违反的规范 |
+|------|-------------|-----------|
+| 缺少 loading 状态 | `frontend-design` | "必须有 loading/error/empty 状态" |
+| API 路径不规范 | `api-design-principles` | "使用复数名词，避免动词" |
+```
+
+## Definition of Done
+
+审查完成前，确认：
+
+- [ ] 已识别所有代码类型并查询技能规范路由表
+- [ ] 已加载对应技能规范作为审查标准
+- [ ] 审查发现已标注来源技能规范
+- [ ] 技能规范引用报告已输出

package/.claude/skills/code-review/references/ui-ux-review.md

@@ -0,0 +1,470 @@
+# UI/UX Design Review Criteria
+
+Comprehensive visual design and user experience review guidelines for frontend code review.
+
+## Visual Design Review
+
+### Typography Issues
+
+| Issue | What to Look For | Fix |
+|-------|------------------|-----|
+| **Too many fonts** | >3 font families | Limit to 2-3 max |
+| **Inconsistent sizes** | Random px values | Use type scale (14, 16, 18, 20, 24, 30, 36, 48) |
+| **Poor readability** | Body text <14px | Min 16px for body |
+| **Line height** | Tight or loose | 1.4-1.6 for body, 1.2-1.3 for headings |
+| **Line length** | >80 characters | 50-75 characters optimal |
+| **Font weight contrast** | No hierarchy | Use 400 for body, 500/600/700 for headings |
+
+```css
+/* 🚫 Typography chaos */
+.title { font-size: 23px; font-weight: 500; }
+.subtitle { font-size: 17px; font-weight: 400; }
+.body { font-size: 14px; line-height: 1.2; }
+
+/* ✅ Systematic typography */
+:root {
+  --font-size-sm: 0.875rem;   /* 14px */
+  --font-size-base: 1rem;      /* 16px */
+  --font-size-lg: 1.125rem;    /* 18px */
+  --font-size-xl: 1.25rem;     /* 20px */
+  --font-size-2xl: 1.5rem;     /* 24px */
+  --font-size-3xl: 1.875rem;   /* 30px */
+  
+  --line-height-tight: 1.25;
+  --line-height-normal: 1.5;
+  --line-height-relaxed: 1.75;
+}
+```
+
+### Color Issues
+
+| Issue | What to Look For | Fix |
+|-------|------------------|-----|
+| **Inconsistent palette** | Random hex values | Define color tokens |
+| **Poor contrast** | Text hard to read | WCAG AA: 4.5:1 for text |
+| **Too many colors** | Rainbow UI | 1 primary + 1-2 accents + neutrals |
+| **Semantic confusion** | Red for success | Use consistent semantic colors |
+| **No dark mode support** | Hardcoded colors | Use CSS variables |
+
+```css
+/* 🚫 Color chaos */
+.button { background: #3b82f6; }
+.link { color: #2563eb; }
+.card { border-color: #60a5fa; }
+/* Three different blues! */
+
+/* ✅ Systematic colors */
+:root {
+  --color-primary-50: #eff6ff;
+  --color-primary-100: #dbeafe;
+  --color-primary-500: #3b82f6;
+  --color-primary-600: #2563eb;
+  --color-primary-700: #1d4ed8;
+  
+  --color-success: #10b981;
+  --color-warning: #f59e0b;
+  --color-error: #ef4444;
+}
+```
+
+### Spacing Issues
+
+| Issue | What to Look For | Fix |
+|-------|------------------|-----|
+| **Inconsistent spacing** | Random px values | Use 4/8px grid |
+| **Cramped UI** | Elements too close | Min 8px between elements |
+| **Unbalanced whitespace** | Uneven padding | Consistent inner padding |
+| **No breathing room** | Dense content | Adequate margins between sections |
+
+```css
+/* 🚫 Random spacing */
+.card { padding: 17px; margin-bottom: 23px; }
+.button { padding: 9px 14px; margin-right: 7px; }
+
+/* ✅ Spacing scale (4px base) */
+:root {
+  --space-1: 0.25rem;  /* 4px */
+  --space-2: 0.5rem;   /* 8px */
+  --space-3: 0.75rem;  /* 12px */
+  --space-4: 1rem;     /* 16px */
+  --space-6: 1.5rem;   /* 24px */
+  --space-8: 2rem;     /* 32px */
+  --space-12: 3rem;    /* 48px */
+}
+
+.card { padding: var(--space-6); margin-bottom: var(--space-6); }
+.button { padding: var(--space-2) var(--space-4); }
+```
+
+### Visual Hierarchy
+
+```
+Check for clear hierarchy:
+1. What's most important? (Should be most prominent)
+2. What's the reading order? (Should flow naturally)
+3. Are related items grouped?
+4. Is there clear separation between sections?
+```
+
+**Hierarchy Tools**:
+- Size (larger = more important)
+- Weight (bolder = more important)
+- Color (brighter/saturated = more attention)
+- Position (top/left = seen first)
+- Whitespace (more space around = more emphasis)
+
+## Layout Review
+
+### Alignment Issues
+
+```css
+/* 🚫 Inconsistent alignment */
+.form-group { text-align: left; }
+.form-group:nth-child(2) { text-align: center; }
+/* Why different? */
+
+/* 🚫 Jagged edges */
+.card { margin-left: 20px; }
+.sidebar { padding-left: 24px; }
+/* Items don't line up */
+```
+
+**Check**:
+- [ ] All text left-aligned (except centered headings/CTAs)
+- [ ] Grid items align to common grid
+- [ ] Buttons in groups are same width or auto-sized consistently
+- [ ] Form labels align consistently (top/left)
+
+### Container Issues
+
+```css
+/* 🚫 Full-width content (hard to read) */
+.content { width: 100%; }
+/* 200+ character lines on wide screens */
+
+/* ✅ Max-width for readability */
+.content {
+  max-width: 65ch; /* ~65 characters */
+  margin: 0 auto;
+  padding: 0 var(--space-4);
+}
+```
+
+```css
+/* 🚫 Fixed width breaking mobile */
+.card { width: 400px; }
+/* Overflows on mobile */
+
+/* ✅ Responsive constraints */
+.card {
+  width: 100%;
+  max-width: 400px;
+}
+```
+
+## User Experience Review
+
+### Loading States
+
+| Scenario | Bad UX | Good UX |
+|----------|--------|---------|
+| **Button submit** | Nothing happens | Button disabled + spinner |
+| **Page load** | Blank page | Skeleton screen |
+| **Data fetch** | Spinner forever | Skeleton + timeout message |
+| **Image load** | Layout shift | Placeholder with aspect ratio |
+
+```tsx
+/* 🚫 No loading state */
+<button onClick={submit}>Submit</button>
+
+/* ✅ Loading state */
+<button onClick={submit} disabled={isLoading}>
+  {isLoading ? <Spinner /> : 'Submit'}
+</button>
+
+/* 🚫 Spinner only */
+{isLoading && <Spinner />}
+
+/* ✅ Skeleton for content */
+{isLoading ? (
+  <div className="skeleton skeleton-text" />
+) : (
+  <p>{content}</p>
+)}
+```
+
+### Error States
+
+| Error Type | What to Show |
+|------------|--------------|
+| **Form validation** | Inline error under field + red border |
+| **API error** | Toast/banner with retry option |
+| **Not found** | Helpful message + navigation options |
+| **Permission denied** | Explain why + what to do |
+| **Network error** | Offline indicator + retry |
+
+```tsx
+/* 🚫 Generic error */
+<div className="error">Error occurred</div>
+
+/* ✅ Helpful error */
+<div className="error" role="alert">
+  <strong>Unable to save changes</strong>
+  <p>Your session may have expired. Please refresh the page and try again.</p>
+  <button onClick={retry}>Retry</button>
+</div>
+```
+
+### Empty States
+
+```tsx
+/* 🚫 Blank space */
+{items.length === 0 && null}
+
+/* ✅ Helpful empty state */
+{items.length === 0 && (
+  <div className="empty-state">
+    <img src="/empty-inbox.svg" alt="" />
+    <h3>No messages yet</h3>
+    <p>When you receive messages, they'll appear here.</p>
+    <button>Compose message</button>
+  </div>
+)}
+```
+
+### Feedback & Confirmation
+
+| Action | Required Feedback |
+|--------|-------------------|
+| **Form submit** | Success toast + clear form or redirect |
+| **Delete** | Confirmation dialog + success message |
+| **Copy** | "Copied!" tooltip |
+| **Save** | Autosave indicator or save confirmation |
+| **Error** | Error message + how to fix |
+
+```tsx
+/* 🚫 No feedback on delete */
+<button onClick={() => deleteItem(id)}>Delete</button>
+
+/* ✅ Confirmation + feedback */
+<button onClick={() => setShowConfirm(true)}>Delete</button>
+{showConfirm && (
+  <Dialog>
+    <p>Delete this item? This action cannot be undone.</p>
+    <button onClick={() => setShowConfirm(false)}>Cancel</button>
+    <button onClick={async () => {
+      await deleteItem(id);
+      toast.success('Item deleted');
+      setShowConfirm(false);
+    }}>Delete</button>
+  </Dialog>
+)}
+```
+
+## Interaction Design
+
+### Button States
+
+Every button needs these states:
+- **Default**: Normal appearance
+- **Hover**: Visual change on mouse over
+- **Focus**: Visible focus ring (keyboard nav)
+- **Active**: Pressed state
+- **Disabled**: Grayed out + cursor not-allowed
+- **Loading**: Spinner + disabled
+
+```css
+.button {
+  /* Default */
+  background: var(--color-primary-500);
+  cursor: pointer;
+  
+  /* Focus (required for a11y) */
+  &:focus-visible {
+    outline: 2px solid var(--color-primary-500);
+    outline-offset: 2px;
+  }
+  
+  /* Hover */
+  &:hover:not(:disabled) {
+    background: var(--color-primary-600);
+  }
+  
+  /* Active */
+  &:active:not(:disabled) {
+    transform: scale(0.98);
+  }
+  
+  /* Disabled */
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+```
+
+### Form UX
+
+| Issue | Bad | Good |
+|-------|-----|------|
+| **Label visibility** | Placeholder only | Visible label + placeholder |
+| **Error timing** | On submit only | On blur + on submit |
+| **Required indicator** | None | Asterisk or "(required)" |
+| **Password** | No visibility toggle | Toggle show/hide |
+| **Long form** | Single page | Multi-step with progress |
+
+```tsx
+/* 🚫 Placeholder as label */
+<input placeholder="Email" />
+
+/* ✅ Proper label */
+<label htmlFor="email">Email *</label>
+<input 
+  id="email"
+  placeholder="you@example.com"
+  aria-describedby="email-error"
+/>
+{error && <span id="email-error" className="error">{error}</span>}
+```
+
+### Animation & Motion
+
+| Principle | Implementation |
+|-----------|----------------|
+| **Purpose** | Animation should convey meaning |
+| **Duration** | 150-300ms for micro-interactions |
+| **Easing** | ease-out for enter, ease-in for exit |
+| **Reduced motion** | Respect prefers-reduced-motion |
+
+```css
+/* ✅ Meaningful transition */
+.modal {
+  transform: scale(0.95);
+  opacity: 0;
+  transition: transform 200ms ease-out, opacity 200ms ease-out;
+}
+.modal.open {
+  transform: scale(1);
+  opacity: 1;
+}
+
+/* ✅ Respect user preference */
+@media (prefers-reduced-motion: reduce) {
+  .modal {
+    transition: none;
+  }
+}
+```
+
+## Dark Mode Review
+
+### Common Issues
+
+```css
+/* 🚫 Hardcoded colors */
+.card { background: white; color: #333; }
+/* Doesn't adapt to dark mode */
+
+/* ✅ CSS variables */
+:root {
+  --bg-primary: #ffffff;
+  --text-primary: #1a1a1a;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg-primary: #1a1a1a;
+    --text-primary: #ffffff;
+  }
+}
+.card { background: var(--bg-primary); color: var(--text-primary); }
+```
+
+```css
+/* 🚫 Pure black background */
+body { background: #000000; }
+/* Too harsh, causes eye strain */
+
+/* ✅ Soft dark */
+body { background: #1a1a1a; } /* Or #121212 */
+```
+
+```css
+/* 🚫 Same shadows in dark mode */
+.card { box-shadow: 0 2px 4px rgba(0,0,0,0.1); }
+/* Invisible in dark mode */
+
+/* ✅ Adaptive shadows */
+.card {
+  box-shadow: 0 2px 4px var(--shadow-color);
+}
+:root { --shadow-color: rgba(0,0,0,0.1); }
+:root[data-theme="dark"] { --shadow-color: rgba(0,0,0,0.4); }
+```
+
+## Mobile UX Checklist
+
+- [ ] **Touch targets**: Min 44x44px
+- [ ] **Thumb zones**: Important actions within easy reach
+- [ ] **No hover-dependent UI**: All hover interactions have tap alternatives
+- [ ] **Scrolling**: Smooth, no janky scroll
+- [ ] **Forms**: Appropriate keyboard types (email, tel, number)
+- [ ] **Navigation**: Easy to reach, not hidden
+- [ ] **Text input**: No zoom on focus (min 16px font)
+- [ ] **Images**: Responsive, not overflowing
+- [ ] **Modals**: Full-screen or well-sized for mobile
+- [ ] **Tables**: Horizontally scrollable or card layout
+
+```html
+<!-- ✅ Appropriate input types -->
+<input type="email" inputmode="email" autocomplete="email" />
+<input type="tel" inputmode="tel" autocomplete="tel" />
+<input type="number" inputmode="numeric" pattern="[0-9]*" />
+```
+
+## Design System Compliance
+
+### Checklist
+
+- [ ] Using defined color tokens (not hex values)
+- [ ] Using defined spacing scale
+- [ ] Using defined typography scale
+- [ ] Using defined border-radius tokens
+- [ ] Using defined shadow tokens
+- [ ] Components follow naming conventions
+- [ ] States match documented patterns
+- [ ] Icons from approved icon set
+- [ ] Illustrations match style guide
+
+### Token Usage
+
+```css
+/* 🚫 Custom values */
+.card {
+  padding: 22px;
+  border-radius: 6px;
+  box-shadow: 0 1px 3px rgba(0,0,0,0.12);
+}
+
+/* ✅ Design tokens */
+.card {
+  padding: var(--space-6);
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-sm);
+}
+```
+
+## UX Heuristics Checklist (Nielsen's 10)
+
+| # | Heuristic | What to Check |
+|---|-----------|---------------|
+| 1 | **Visibility of system status** | Loading states, progress indicators |
+| 2 | **Match real world** | Familiar language, logical order |
+| 3 | **User control & freedom** | Undo, cancel, back navigation |
+| 4 | **Consistency** | Same patterns throughout |
+| 5 | **Error prevention** | Confirmations, constraints |
+| 6 | **Recognition over recall** | Visible options, recent items |
+| 7 | **Flexibility** | Shortcuts for power users |
+| 8 | **Aesthetic & minimal** | No clutter, essential info only |
+| 9 | **Error recovery** | Clear messages, solutions |
+| 10 | **Help & documentation** | Tooltips, help text |
+