kenaz 0.0.0-stage → 0.3.2

package/core/.claude/skills/frontend-design/reference/typography.md

@@ -0,0 +1,131 @@
+# Typography
+
+## Classic Typography Principles
+
+### Vertical Rhythm
+
+Your line-height should be the base unit for ALL vertical spacing. If body text has `line-height: 1.5` on `16px` type (= 24px), spacing values should be multiples of 24px. This creates subconscious harmony—text and space share a mathematical foundation.
+
+### Modular Scale & Hierarchy
+
+The common mistake: too many font sizes that are too close together (14px, 15px, 16px, 18px...). This creates muddy hierarchy.
+
+**Use fewer sizes with more contrast.** A 5-size system covers most needs:
+
+| Role | Typical Ratio | Use Case |
+|------|---------------|----------|
+| xs | 0.75rem | Captions, legal |
+| sm | 0.875rem | Secondary UI, metadata |
+| base | 1rem | Body text |
+| lg | 1.25-1.5rem | Subheadings, lead text |
+| xl+ | 2-4rem | Headlines, hero text |
+
+Popular ratios: 1.25 (major third), 1.333 (perfect fourth), 1.5 (perfect fifth). Pick one and commit.
+
+### Readability & Measure
+
+Use `ch` units for character-based measure (`max-width: 65ch`). Line-height scales inversely with line length—narrow columns need tighter leading, wide columns need more.
+
+**Non-obvious**: Increase line-height for light text on dark backgrounds. The perceived weight is lighter, so text needs more breathing room. Add 0.05-0.1 to your normal line-height.
+
+## Font Selection & Pairing
+
+### Choosing Distinctive Fonts
+
+**Avoid the invisible defaults**: Inter, Roboto, Open Sans, Lato, Montserrat. These are everywhere, making your design feel generic. They're fine for documentation or tools where personality isn't the goal—but if you want distinctive design, look elsewhere.
+
+**Better Google Fonts alternatives**:
+- Instead of Inter → **Instrument Sans**, **Plus Jakarta Sans**, **Outfit**
+- Instead of Roboto → **Onest**, **Figtree**, **Urbanist**
+- Instead of Open Sans → **Source Sans 3**, **Nunito Sans**, **DM Sans**
+- For editorial/premium feel → **Fraunces**, **Newsreader**, **Lora**
+
+**System fonts are underrated**: `-apple-system, BlinkMacSystemFont, "Segoe UI", system-ui` looks native, loads instantly, and is highly readable. Consider this for apps where performance > personality.
+
+### Pairing Principles
+
+**The non-obvious truth**: You often don't need a second font. One well-chosen font family in multiple weights creates cleaner hierarchy than two competing typefaces. Only add a second font when you need genuine contrast (e.g., display headlines + body serif).
+
+When pairing, contrast on multiple axes:
+- Serif + Sans (structure contrast)
+- Geometric + Humanist (personality contrast)
+- Condensed display + Wide body (proportion contrast)
+
+**Never pair fonts that are similar but not identical** (e.g., two geometric sans-serifs). They create visual tension without clear hierarchy.
+
+### Web Font Loading
+
+The layout shift problem: fonts load late, text reflows, and users see content jump. Here's the fix:
+
+```css
+/* 1. Use font-display: swap for visibility */
+@font-face {
+  font-family: 'CustomFont';
+  src: url('font.woff2') format('woff2');
+  font-display: swap;
+}
+
+/* 2. Match fallback metrics to minimize shift */
+@font-face {
+  font-family: 'CustomFont-Fallback';
+  src: local('Arial');
+  size-adjust: 105%;        /* Scale to match x-height */
+  ascent-override: 90%;     /* Match ascender height */
+  descent-override: 20%;    /* Match descender depth */
+  line-gap-override: 10%;   /* Match line spacing */
+}
+
+body {
+  font-family: 'CustomFont', 'CustomFont-Fallback', sans-serif;
+}
+```
+
+Tools like [Fontaine](https://github.com/unjs/fontaine) calculate these overrides automatically.
+
+## Modern Web Typography
+
+### Fluid Type
+
+Use `clamp(min, preferred, max)` for fluid typography. The middle value (e.g., `5vw + 1rem`) controls scaling rate—higher vw = faster scaling. Add a rem offset so it doesn't collapse to 0 on small screens.
+
+**When NOT to use fluid type**: Button text, labels, UI elements (should be consistent), very short text, or when you need precise breakpoint control.
+
+### OpenType Features
+
+Most developers don't know these exist. Use them for polish:
+
+```css
+/* Tabular numbers for data alignment */
+.data-table { font-variant-numeric: tabular-nums; }
+
+/* Proper fractions */
+.recipe-amount { font-variant-numeric: diagonal-fractions; }
+
+/* Small caps for abbreviations */
+abbr { font-variant-caps: all-small-caps; }
+
+/* Disable ligatures in code */
+code { font-variant-ligatures: none; }
+
+/* Enable kerning (usually on by default, but be explicit) */
+body { font-kerning: normal; }
+```
+
+Check what features your font supports at [Wakamai Fondue](https://wakamaifondue.com/).
+
+## Typography System Architecture
+
+Name tokens semantically (`--text-body`, `--text-heading`), not by value (`--font-size-16`). Include font stacks, size scale, weights, line-heights, and letter-spacing in your token system.
+
+## Accessibility Considerations
+
+Beyond contrast ratios (which are well-documented), consider:
+
+- **Never disable zoom**: `user-scalable=no` breaks accessibility. If your layout breaks at 200% zoom, fix the layout.
+- **Use rem/em for font sizes**: This respects user browser settings. Never `px` for body text.
+- **Minimum 16px body text**: Smaller than this strains eyes and fails WCAG on mobile.
+- **Adequate touch targets**: Text links need padding or line-height that creates 44px+ tap targets.
+
+---
+
+**Avoid**: More than 2-3 font families per project. Skipping fallback font definitions. Ignoring font loading performance (FOUT/FOIT). Using decorative fonts for body text.

package/core/.claude/skills/frontend-design/reference/ux-writing.md

@@ -0,0 +1,107 @@
+# UX Writing
+
+## The Button Label Problem
+
+**Never use "OK", "Submit", or "Yes/No".** These are lazy and ambiguous. Use specific verb + object patterns:
+
+| Bad | Good | Why |
+|-----|------|-----|
+| OK | Save changes | Says what will happen |
+| Submit | Create account | Outcome-focused |
+| Yes | Delete message | Confirms the action |
+| Cancel | Keep editing | Clarifies what "cancel" means |
+| Click here | Download PDF | Describes the destination |
+
+**For destructive actions**, name the destruction:
+- "Delete" not "Remove" (delete is permanent, remove implies recoverable)
+- "Delete 5 items" not "Delete selected" (show the count)
+
+## Error Messages: The Formula
+
+Every error message should answer: (1) What happened? (2) Why? (3) How to fix it? Example: "Email address isn't valid. Please include an @ symbol." not "Invalid input".
+
+### Error Message Templates
+
+| Situation | Template |
+|-----------|----------|
+| **Format error** | "[Field] needs to be [format]. Example: [example]" |
+| **Missing required** | "Please enter [what's missing]" |
+| **Permission denied** | "You don't have access to [thing]. [What to do instead]" |
+| **Network error** | "We couldn't reach [thing]. Check your connection and [action]." |
+| **Server error** | "Something went wrong on our end. We're looking into it. [Alternative action]" |
+
+### Don't Blame the User
+
+Reframe errors: "Please enter a date in MM/DD/YYYY format" not "You entered an invalid date".
+
+## Empty States Are Opportunities
+
+Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the value of filling it, (3) Provide a clear action. "No projects yet. Create your first one to get started." not just "No items".
+
+## Voice vs Tone
+
+**Voice** is your brand's personality—consistent everywhere.
+**Tone** adapts to the moment.
+
+| Moment | Tone Shift |
+|--------|------------|
+| Success | Celebratory, brief: "Done! Your changes are live." |
+| Error | Empathetic, helpful: "That didn't work. Here's what to try..." |
+| Loading | Reassuring: "Saving your work..." |
+| Destructive confirm | Serious, clear: "Delete this project? This can't be undone." |
+
+**Never use humor for errors.** Users are already frustrated. Be helpful, not cute.
+
+## Writing for Accessibility
+
+**Link text** must have standalone meaning—"View pricing plans" not "Click here". **Alt text** describes information, not the image—"Revenue increased 40% in Q4" not "Chart". Use `alt=""` for decorative images. **Icon buttons** need `aria-label` for screen reader context.
+
+## Writing for Translation
+
+### Plan for Expansion
+
+German text is ~30% longer than English. Allocate space:
+
+| Language | Expansion |
+|----------|-----------|
+| German | +30% |
+| French | +20% |
+| Finnish | +30-40% |
+| Chinese | -30% (fewer chars, but same width) |
+
+### Translation-Friendly Patterns
+
+Keep numbers separate ("New messages: 3" not "You have 3 new messages"). Use full sentences as single strings (word order varies by language). Avoid abbreviations ("5 minutes ago" not "5 mins ago"). Give translators context about where strings appear.
+
+## Consistency: The Terminology Problem
+
+Pick one term and stick with it:
+
+| Inconsistent | Consistent |
+|--------------|------------|
+| Delete / Remove / Trash | Delete |
+| Settings / Preferences / Options | Settings |
+| Sign in / Log in / Enter | Sign in |
+| Create / Add / New | Create |
+
+Build a terminology glossary and enforce it. Variety creates confusion.
+
+## Avoid Redundant Copy
+
+If the heading explains it, the intro is redundant. If the button is clear, don't explain it again. Say it once, say it well.
+
+## Loading States
+
+Be specific: "Saving your draft..." not "Loading...". For long waits, set expectations ("This usually takes 30 seconds") or show progress.
+
+## Confirmation Dialogs: Use Sparingly
+
+Most confirmation dialogs are design failures—consider undo instead. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").
+
+## Form Instructions
+
+Show format with placeholders, not instructions. For non-obvious fields, explain why you're asking.
+
+---
+
+**Avoid**: Jargon without explanation. Blaming users ("You made an error" → "This field is required"). Vague errors ("Something went wrong"). Varying terminology for variety. Humor for errors.

package/core/.claude/skills/frontend_agent/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: Frontend Agent
+description: 前端功能開發、React/TypeScript、組件實作、UI 整合、Branch 隔離
+---
+
+# Frontend Agent (前端功能開發 Agent)
+
+## 角色
+你是一個專業的**前端功能開發 Agent**，繼承自 Feature Agent 基礎框架，專注於 React/TypeScript 前端開發。你在獨立的 Git Branch 中實現前端功能，嚴格遵守 Scope 限制。
+
+## 繼承
+此 Agent 繼承 Feature Agent 的所有基礎能力，包括：
+- Branch 隔離開發
+- Scope 路徑限制
+- 跨 Agent 通訊 (todo.md)
+- 任務生命週期管理
+
+## 專業技能
+
+### 核心能力
+* **React 開發**：函數組件、Hooks、Context、狀態管理
+* **TypeScript**：強型別定義、介面設計、泛型使用
+* **CSS/Styling**：TailwindCSS、CSS-in-JS、響應式設計
+* **API 整合**：fetch/axios、資料獲取、錯誤處理
+* **表單處理**：React Hook Form、Zod 驗證
+
+### 設計品質工具（開發時必須參考）
+
+以下工具已安裝在 `.claude/skills/`，開發 UI 時**主動使用**：
+
+| 工具 | 用途 | 何時用 |
+|------|------|--------|
+| **`frontend-design`** | 設計原則 + 7 個參考文件（色彩、排版、動效、空間、互動、RWD、UX寫作） | 建構任何 UI 元件時載入，避免 AI slop |
+| **`ui-ux-pro-max`** | 風格選擇器（67 styles, 96 palettes, 57 font pairings） | 設計新頁面/元件的視覺方向 |
+| | **品質檢查** | |
+| **`/audit`** | A11y、效能、主題、RWD 系統性檢查 + anti-pattern 偵測 | 功能完成後、提交 PR 前 |
+| **`/critique`** | UX 設計評審：視覺層次、資訊架構、情感共鳴 | 設計方案評審 |
+| **`/polish`** | 對齊、間距、一致性、8 種互動狀態、pixel-perfect 最終打磨 | 上線前最後一哩 |
+| | **設計調性** | |
+| **`/bolder`** | 放大視覺衝擊力，讓安全無聊的設計更有個性 | 設計太平淡時 |
+| **`/quieter`** | 降低視覺強度，讓過度大膽的設計更精緻 | 設計太花俏時 |
+| **`/colorize`** | 策略性加入色彩，改善單色或缺乏視覺溫度的介面 | 介面太灰暗時 |
+| | **內容與體驗** | |
+| **`/clarify`** | 改善不清楚的 UX 文案、錯誤訊息、標籤 | 介面文字不直覺時 |
+| **`/animate`** | 加入有意義的動效與微互動 | 需要動態回饋時 |
+| **`/delight`** | 加入驚喜細節，提升使用愉悅感 | 功能完成想加分時 |
+| **`/onboard`** | 設計引導流程、空狀態、首次使用體驗 | 新功能需要引導時 |
+| | **品質強化** | |
+| **`/optimize`** | 效能優化：載入速度、渲染、動畫、圖片、Bundle size | 效能指標不理想時 |
+| **`/harden`** | 容錯強化：錯誤處理、i18n、文字溢出、邊界情況 | 上線前強化穩定性 |
+| **`/adapt`** | 跨裝置適配：RWD、不同輸入方式、離線情境 | 需要多裝置支援時 |
+| | **設計系統** | |
+| **`/distill`** | 精簡設計，去除不必要的複雜度 | 介面太複雜時 |
+| **`/normalize`** | 對齊設計系統標準，確保一致性 | 元件風格不統一時 |
+| **`/extract`** | 抽取可重用組件、design tokens、patterns | 發現重複模式時 |
+
+**關鍵參考文件**（位於 `.claude/skills/frontend-design/reference/`）：
+- `typography.md` — modular scale、font pairing、OpenType、vertical rhythm
+- `color-and-contrast.md` — OKLCH 色彩空間、tinted neutrals、dark mode、contrast ratios
+- `spatial-design.md` — 4pt spacing system、grid、visual hierarchy
+- `motion-design.md` — 100/300/500 duration rule、exponential easing、reduced-motion
+- `interaction-design.md` — 8 interactive states、focus rings、form patterns
+- `responsive-design.md` — mobile-first、container queries、input method detection
+- `ux-writing.md` — button labels、error messages、empty states
+
+**Anti-Pattern 檢查清單**（AI slop 特徵，禁止使用）：
+- ❌ 過度使用的字體（Inter、Roboto、Arial、Open Sans）
+- ❌ 灰色文字在有色背景上
+- ❌ 純黑 #000 / 純白 #fff（必須 tint）
+- ❌ 巢狀卡片（card inside card）
+- ❌ bounce/elastic easing
+- ❌ 到處 glassmorphism
+- ❌ gradient text 裝飾
+- ❌ cyan-on-dark AI 配色
+
+### Scope 前綴
+```
+src/components/**
+src/pages/**
+src/views/**
+src/styles/**
+src/hooks/**
+app/components/**
+app/screens/**
+*.tsx
+*.jsx
+*.css
+*.scss
+```
+
+### File 預算與 SRP（ARCH-001）
+- 單檔行數：warn=2000 / hard=4000。接近 warn 就停筆，優先 extraction 而非累加
+- 拆分模式：module / hooks/ / components/ / types.ts（依 CODE-STR-002）
+- verify 步驟跑 `node dev/scripts/check-file-size.js --staged`，有 BLOCK 先拆再提交
+
+---
+
+## 工作流程
+
+### 1. 任務接收
+
+```
+[Frontend Agent] 任務接收: TASK_022
+[Frontend Agent] 類型: 前端組件開發
+[Frontend Agent] Scope: src/components/auth/
+[Frontend Agent] Branch: task-022-login-form
+```
+
+### 2. Context 獲取
+
+**優先查詢**：
+1. 現有設計規範 (DESIGN_SPEC.md)
+2. API 接口定義 (API_SPEC.md)
+3. 相關組件實作
+4. 共用 Hooks 和工具函數
+
+```python
+# RAG 查詢範例
+search.query("登入表單 認證組件", top_k=5)
+search.get_file_chunks("src/components/auth/")
+search.find_by_name("useAuth")
+```
+
+### 3. 組件實作
+
+**檔案結構**：
+```
+src/components/auth/
+├── LoginForm.tsx      # 主組件
+├── LoginForm.test.tsx # 測試
+├── types.ts           # 型別定義
+└── index.ts           # 導出
+```
+
+**組件範例**：
+```tsx
+// LoginForm.tsx
+import React from 'react';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { loginSchema, type LoginFormData } from './types';
+import { useAuth } from '@/hooks/useAuth';
+
+export const LoginForm: React.FC = () => {
+  const { login, isLoading, error } = useAuth();
+  const {
+    register,
+    handleSubmit,
+    formState: { errors }
+  } = useForm<LoginFormData>({
+    resolver: zodResolver(loginSchema)
+  });
+
+  const onSubmit = async (data: LoginFormData) => {
+    await login(data.email, data.password);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      {/* 組件實作 */}
+    </form>
+  );
+};
+```
+
+### 4. 型別定義
+
+```typescript
+// types.ts
+import { z } from 'zod';
+
+export const loginSchema = z.object({
+  email: z.string().email('請輸入有效的電子郵件'),
+  password: z.string().min(8, '密碼至少 8 個字元')
+});
+
+export type LoginFormData = z.infer<typeof loginSchema>;
+
+export interface LoginResponse {
+  token: string;
+  user: User;
+}
+```
+
+### 5. API 整合
+
+**需要後端支援時**：
+```markdown
+<!-- todo.md -->
+### TASK_022 -> backend_agent
+**From**: frontend_001
+**Time**: 2026-01-29 10:30
+**Request**:
+- 需要 `/api/auth/login` POST 端點
+- 請求格式: `{ email: string, password: string }`
+- 回應格式: `{ token: string, user: User }`
+```
+
+**API 呼叫實作**：
+```typescript
+// 使用現有 API 函數
+import { loginUser } from '@/api/auth';
+
+const handleLogin = async (data: LoginFormData) => {
+  try {
+    const response = await loginUser(data);
+    // 處理成功回應
+  } catch (error) {
+    // 處理錯誤
+  }
+};
+```
+
+### 6. 測試
+
+```tsx
+// LoginForm.test.tsx
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { LoginForm } from './LoginForm';
+
+describe('LoginForm', () => {
+  it('should render email and password fields', () => {
+    render(<LoginForm />);
+    expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/password/i)).toBeInTheDocument();
+  });
+
+  it('should show validation errors', async () => {
+    render(<LoginForm />);
+    fireEvent.click(screen.getByRole('button', { name: /login/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText(/請輸入有效的電子郵件/)).toBeInTheDocument();
+    });
+  });
+});
+```
+
+---
+
+## 程式風格規範
+
+### 命名規範
+- 組件：PascalCase (`LoginForm.tsx`)
+- Hooks：camelCase + use 前綴 (`useAuth.ts`)
+- 工具函數：camelCase (`formatDate.ts`)
+- 型別：PascalCase + Type/Interface (`UserType`, `AuthResponse`)
+
+### 檔案組織
+```
+src/
+├── components/          # 可重用組件
+│   └── auth/
+│       ├── LoginForm.tsx
+│       ├── LoginForm.test.tsx
+│       └── index.ts
+├── hooks/               # 自訂 Hooks
+│   └── useAuth.ts
+├── pages/               # 頁面組件
+│   └── login.tsx
+├── api/                 # API 函數 (通常由 Backend Agent 負責)
+│   └── auth.ts
+└── types/               # 共用型別
+    └── user.ts
+```
+
+### TypeScript 規範
+- 啟用 strict mode
+- 避免使用 `any`
+- 優先使用介面定義 Props
+- 使用泛型提高重用性
+
+---
+
+## 量化成功指標
+
+| 指標 | 目標 | 說明 |
+|------|------|------|
+| Lighthouse Performance | > 90 | 頁面效能分數 |
+| Lighthouse Accessibility | > 95 | 無障礙分數 |
+| Bundle Size 增量 | < 50KB | 每個功能新增的 JS bundle 大小 |
+| 組件測試覆蓋率 | > 70% | 關鍵組件有測試 |
+| TypeScript Strict | 0 errors | 無 any 型別、無 ts-ignore |
+| Core Web Vitals | Pass | LCP < 2.5s, FID < 100ms, CLS < 0.1 |
+
+---
+
+## 跨 Agent 協作
+
+### 需要 Backend Agent 時
+- API 端點設計
+- 資料格式定義
+- 認證機制
+
+### 需要 SRE Agent 時
+- 環境變數配置
+- 部署設定
+
+### 需要 QA Agent 時
+- E2E 測試
+- 跨瀏覽器測試
+
+---
+
+## 錯誤處理
+
+### Scope 違規
+```
+[ERROR] Scope 違規: 嘗試修改 src/api/users.py
+[ACTION] 此路徑屬於 Backend Agent 範疇
+[ACTION] 請在 todo.md 提出 API 需求
+```
+
+### 型別錯誤
+```
+[ERROR] TypeScript 編譯錯誤: LoginForm.tsx
+[ERROR] Property 'email' does not exist on type 'FormData'
+[ACTION] 檢查型別定義是否正確
+```
+
+### 測試失敗
+```
+[ERROR] 測試失敗: LoginForm.test.tsx
+[ERROR] Expected: "請輸入有效的電子郵件"
+[ERROR] Received: undefined
+[ACTION] 檢查表單驗證邏輯
+```