@champpaba/claude-agent-kit 3.5.2 → 3.6.0

package/skills/design-setup/references/error-handling.md

@@ -0,0 +1,157 @@
+# Error Handling
+
+How to handle failures during design setup.
+
+---
+
+## Error 1: No Extracted Data
+
+**When:** No `design-system/extracted/*/data.yaml` files found
+
+**Message:**
+```
+❌ No extracted data found
+
+Please extract at least 1 site:
+  /extract https://airbnb.com
+
+Then run: /designsetup @prd.md
+```
+
+**Action:** Stop execution.
+
+---
+
+## Error 2: AI Analysis Fails
+
+**When:** LLM call fails during context analysis or theme generation
+
+**Message:**
+```
+❌ AI analysis failed: {error.message}
+
+This may be due to:
+- Extracted data too large (try fewer sites)
+- API rate limit (wait and retry)
+- Invalid context files
+
+Retry or use --debug for details
+```
+
+**Action:** Allow retry or proceed with fallback (interactive questions).
+
+---
+
+## Error 3: User Cancels
+
+**When:** User selects "Cancel" at any point
+
+**Message:**
+```
+⚠️ Design setup cancelled
+
+Your data is preserved:
+- Extracted: design-system/extracted/
+- Options: design-system/synthesis/options/ (if any)
+
+Run /designsetup again when ready.
+```
+
+**Action:** Stop execution, preserve existing data.
+
+---
+
+## Error 4: Max Rounds Reached
+
+**When:** User has adjusted 3 times without accepting
+
+**Message:**
+```
+⚠️ ครบ 3 รอบแล้ว
+
+แนะนำ:
+1. รัน /extract กับ reference ใหม่
+2. หรือ accept แล้วค่อย manual edit ไฟล์ที่สร้าง
+```
+
+**Action:** Force decision (Yes to generate / Cancel to exit).
+
+---
+
+## Error 5: Write Fails
+
+**When:** Cannot write to design-system/ directory
+
+**Actions:**
+1. Try to save backup to `/tmp/design-system-backup/`
+2. Display error with backup location:
+
+```
+❌ Failed to write files
+
+Check permissions: design-system/
+
+Backup saved: /tmp/design-system-backup/
+```
+
+---
+
+## Error 6: Context File Not Found
+
+**When:** User-provided context file doesn't exist
+
+**Message:**
+```
+⚠️ Context file not found: {filename}
+   Skipping this file...
+```
+
+**Action:** Continue with other files, warn user.
+
+---
+
+## Error 7: Invalid Extracted Data
+
+**When:** Extracted YAML is malformed or missing required fields
+
+**Message:**
+```
+⚠️ Invalid data in {site}/data.yaml
+   Missing: {missing fields}
+   Skipping this site...
+```
+
+**Action:** Continue with other sites if available.
+
+---
+
+## Graceful Degradation
+
+| Scenario | Fallback |
+|----------|----------|
+| No context files | Use interactive questions |
+| AI analysis fails | Use interactive questions |
+| Some extractions invalid | Use valid ones only |
+| Theme generation fails | Use "Abstract" theme |
+| Pattern generation fails | Skip patterns, generate data.yaml only |
+
+---
+
+## Recovery Suggestions
+
+For persistent errors:
+
+1. **Clear and re-extract:**
+   ```bash
+   rm -rf design-system/extracted/
+   /extract https://site.com
+   ```
+
+2. **Use fewer sites:**
+   Large extractions may exceed context limits
+
+3. **Simplify context:**
+   Use shorter, focused context files
+
+4. **Manual generation:**
+   If all else fails, manually create `data.yaml` based on extraction data

package/skills/design-setup/references/generation-steps.md

@@ -0,0 +1,192 @@
+# Generation Steps
+
+After user confirms selections, generate the design system files.
+
+---
+
+## STEP 5.5: Generate data.yaml
+
+### Build Tokens Data Structure
+
+**1. Meta:**
+```yaml
+meta:
+  generated_at: "{ISO timestamp}"
+  source_site: "{selectedStyle.site}"
+  style: "{selectedStyle.style}"
+  theme: "{selectedTheme.name}"
+```
+
+**2. Style:**
+```yaml
+style:
+  name: "{selectedStyle.style}"
+  confidence: {confidence}
+  characteristics: [list]
+  feel: "{feel}"
+  source_site: "{site}"
+```
+
+**3. Theme:**
+```yaml
+theme:
+  name: "{selectedTheme.name}"
+  description: "{description}"
+  feeling: "{feeling}"
+  decorative_elements:
+    use: [list of elements to use]
+    avoid: [list of elements to avoid]
+  icons_suggestion: [Lucide icon names]
+```
+
+**4. Animations:**
+```yaml
+animations:
+  enabled: true/false
+  libraries: [list]
+  selected_patterns: [user selections]
+  scroll_animations:
+    enabled: true/false
+    patterns: [list]
+  component_animations:
+    button_hover: "{effect}"
+    card_hover: "{effect}"
+    input_focus: "ring"
+  duration:
+    fast: "150ms"
+    normal: "200ms"
+    slow: "300ms"
+  easing:
+    default: "ease-in-out"
+    bounce: "cubic-bezier(0.68, -0.55, 0.265, 1.55)"
+```
+
+**5. Colors:**
+```yaml
+colors:
+  primary:
+    DEFAULT: "{hex}"
+    foreground: "#ffffff"
+    hover: "{darkened hex}"
+  secondary:
+    DEFAULT: "{hex}"
+    foreground: "#ffffff"
+  background:
+    DEFAULT: "#ffffff"
+    muted: "#f1f5f9"
+    subtle: "#f8fafc"
+  foreground:
+    DEFAULT: "#0a0a0a"
+    muted: "#64748b"
+  semantic:
+    success: "#10b981"
+    warning: "#f59e0b"
+    error: "#ef4444"
+    info: "#3b82f6"
+```
+
+**6. Typography:**
+```yaml
+typography:
+  font_family:
+    sans: "{font from extraction}"
+    mono: "'Fira Code', monospace"
+  font_size:
+    xs: "12px"
+    sm: "14px"
+    base: "16px"
+    lg: "18px"
+    xl: "20px"
+    2xl: "24px"
+  font_weight:
+    normal: "400"
+    medium: "500"
+    semibold: "600"
+    bold: "700"
+```
+
+**7. Spacing:**
+```yaml
+spacing:
+  scale: [4, 8, 12, 16, 24, 32, 48, 64]
+  grid_base: "8px"
+```
+
+**8. Psychology (from extraction):**
+```yaml
+psychology:
+  style_classification: "{style}"
+  emotions_evoked:
+    - emotion: "{emotion}"
+      reason: "{reason}"
+  target_audience:
+    primary:
+      description: "{desc}"
+      age_range: "{range}"
+  why_it_works:
+    - "{reason 1}"
+    - "{reason 2}"
+```
+
+---
+
+## STEP 5.6: Generate patterns/*.md
+
+### buttons.md
+- Primary, Secondary, Ghost, Outline, Icon variants
+- Small, Medium, Large sizes
+- Hover animations based on selection
+
+### cards.md
+- Default, Interactive, Feature, Pricing, Testimonial variants
+- Hover effects based on selection
+
+### forms.md
+- Input, Error input, Select, Checkbox
+- Form layout examples
+
+### scroll-animations.md
+- Fade In on Scroll
+- Stacking Cards (GSAP)
+- Parallax Section
+- Slide In from Side
+
+### decorations.md
+- Gradient backgrounds
+- Blob shapes
+- Grid patterns
+- Floating elements
+- Dividers
+
+Each file includes:
+- Header with source, style, when to load
+- TSX code examples
+- Usage guidelines
+
+---
+
+## STEP 5.7: Generate README.md
+
+Human-readable guide (~100 lines) with:
+
+1. **Overview** - Style + theme description
+2. **Color Palette** - All colors with usage
+3. **Typography** - Font family, sizes, weights
+4. **Spacing System** - Base unit, scale
+5. **Shadows** - Elevation levels
+6. **Border Radius** - Values and usage
+7. **Theme** - Decorative direction (USE/AVOID)
+8. **Animations** - Enabled patterns
+9. **Component Library** - Recommended (shadcn/ui)
+10. **Code Patterns** - Links to pattern files
+11. **Critical Rules** - DO and DON'T
+
+---
+
+## STEP 6: Final Report
+
+Display completion summary:
+- Style selected
+- Theme selected
+- Files created (data.yaml, README.md, patterns/*.md)
+- Next steps (/pageplan, /csetup, /cdev)

package/skills/design-setup/references/interactive-workflow.md

@@ -0,0 +1,151 @@
+# Interactive Workflow (3-Round Loop)
+
+## Overview
+
+The design setup uses a 3-round interactive loop where users can adjust and refine until satisfied (or max 3 rounds reached).
+
+---
+
+## STEP 0: Discovery & Validation
+
+### 0.1: Find Extracted Data
+
+Search for: `design-system/extracted/*/data.yaml`
+
+**If no files found:** Stop with error, instruct to run `/extract` first.
+
+### 0.2: Load Extracted Data
+
+For each extracted site:
+1. Extract site name from path
+2. Parse YAML content
+3. Store in memory (map site name → data)
+
+### 0.3: Load Context Files (Optional)
+
+If user provided `@context-files`:
+1. Remove `@` prefix
+2. Read file content
+3. Store with filename as key
+
+### 0.4: Report Discovery
+
+Display found sites, context files, and start analysis message.
+
+---
+
+## STEP 1: Context Analysis
+
+### 1.1: AI Analysis (if context files provided)
+
+Analyze context files to identify:
+- `target_audience`: age_range, demographics, tech_savvy
+- `brand_personality`: bold, professional, playful, minimal, technical
+- `product_type`: SaaS, E-commerce, Marketing, Internal Tool
+- `market_position`: differentiation strategy
+- `design_preferences`: any mentioned preferences
+
+### 1.2: Interactive Questions (fallback)
+
+If no context or analysis insufficient, ask:
+
+1. **Product Type**: SaaS Dashboard / E-commerce / Marketing Site / Internal Tool
+2. **Target Audience**: Gen Z / Millennials / Enterprise / Developers
+3. **Brand Personality** (multi-select): Bold / Professional / Playful / Minimal
+
+---
+
+## STEP 2: Interactive Selection Loop
+
+### 2.1: Style Selection
+
+For each extracted site, display:
+```
+Option [Letter]: [Style Name] [⭐ RECOMMENDED if highest score]
+Source: [site name]
+Match Score: [score]%
+
+📝 Characteristics: [list]
+🎭 Feel: [description]
+🎨 Colors: [primary colors]
+🎬 Animations: [available animations]
+📜 Scroll Patterns: [patterns]
+🖼️ Decorative Elements: [elements]
+```
+
+**Match Score Calculation:**
+- Base = confidence from extraction
+- +15 if brand includes "bold" and style is Neo-Brutalism/Playful
+- +15 if brand includes "professional" and style is Minimalist/Modern SaaS
+- +15 if brand includes "playful" and style is Playful/Creative
+- +15 if brand includes "minimal" and style is Minimalist
+- Cap at 100
+
+**User Options:**
+- Select A, B, C... → Store as selectedStyle
+- Select "Mix/Custom" → Get feedback, increment round, loop back
+
+### 2.2: Animation Selection (Multi-select)
+
+Collect all available animations from extracted sites:
+- Animation libraries (GSAP, Framer Motion, etc.)
+- Scroll patterns (parallax, fade-in, stacking-cards)
+- Component animations (button hover, card hover)
+
+Display numbered list, user selects multiple.
+
+### 2.3: Theme Selection
+
+AI recommends 3-4 themes based on project context:
+```
+Theme [Letter]: [Name]
+📝 Description: [description]
+🎭 Feeling: [feeling]
+✅ USE: [decorative elements]
+❌ AVOID: [elements to avoid]
+🎯 Icons: [Lucide suggestions]
+💡 Why: [match reason]
+```
+
+**User Options:**
+- Select A, B, C... → Store theme
+- Select "No Theme" → Use abstract/geometric
+- Select "Custom" → Input custom theme description
+
+### 2.4: Confirmation
+
+Display summary and ask:
+- "Yes, Generate" → Exit loop, proceed to generation
+- "Adjust" → Increment round, loop back
+- "Start Over" → Reset round to 1, loop back
+
+### 2.5: Max Rounds
+
+After 3 rounds, force decision:
+- "Yes" → Generate with current settings
+- "Cancel" → Exit without generating
+
+---
+
+## Loop Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     START (Round 1)                          │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Style Selection → Animation Selection → Theme Selection     │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│                       Confirmation                           │
+│  ┌─────────┐  ┌─────────┐  ┌─────────────┐                  │
+│  │   Yes   │  │ Adjust  │  │ Start Over  │                  │
+│  └────┬────┘  └────┬────┘  └──────┬──────┘                  │
+│       │            │              │                          │
+│       ↓            ↓              ↓                          │
+│   Generate     Round++        Round=1                        │
+│    Files      (max 3)        (restart)                       │
+└─────────────────────────────────────────────────────────────┘
+```

package/skills/page-planner/CLAUDE.md

@@ -0,0 +1,11 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+### Feb 3, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #184 | 11:10 PM | 🔵 | Page Planner skill generates visual UI plans with wireframes and animation blueprints | ~827 |
+</claude-mem-context>

package/skills/page-planner/SKILL.md

@@ -0,0 +1,112 @@
+# Page Planner Skill
+
+Generate visual page plans for UI implementation - component strategy, layout wireframes, animation blueprints.
+
+## Triggers
+
+- "/pageplan [@context-files...]"
+- "plan page layout"
+- "create page wireframe"
+- "วางแผนหน้าเว็บ"
+
+## Quick Usage
+
+```bash
+# With context files
+/pageplan @proposal.md @prd.md
+
+# Current change only
+/pageplan
+
+# Specify change ID
+/pageplan landing-page
+```
+
+## What Gets Generated
+
+`openspec/changes/{change-id}/page-plan.md` containing:
+
+| Section | Content |
+|---------|---------|
+| Component Plan | Reuse vs new components |
+| Page Structure | Layout composition (TSX) |
+| Layout Wireframe | ASCII art (Desktop/Tablet/Mobile) |
+| Animation Blueprint | Hover, focus, transition patterns |
+| UI States | Empty, loading, success, error states |
+| Asset Checklist | Images, icons to prepare |
+
+## Input Sources
+
+| Source | Purpose |
+|--------|---------|
+| `@context-files` | User-provided requirements |
+| `proposal.md` | Change description |
+| `tasks.md` | Page type detection |
+| `phases.md` | Phase information |
+| `design-system/data.yaml` | Design tokens |
+
+## Workflow
+
+```
+1. Detect Change → Find active change or use provided ID
+2. Read Context → Load all input sources
+3. Search Components → Find existing reusable components
+4. Generate Plan → Component plan, wireframes, animations
+5. Write Output → page-plan.md
+```
+
+## Output Sections
+
+### 1. Component Plan
+- Reuse: Found components with paths and usage
+- New Shared: Components for multiple pages
+- New Specific: Page-only components
+
+### 2. Layout Wireframe
+ASCII art for Desktop, Tablet, Mobile views with:
+- Container sizes
+- Grid breakpoints
+- Spacing details
+
+### 3. Animation Blueprint
+From data.yaml tokens:
+- Button animations (scale + shadow)
+- Card animations (shadow elevation)
+- Input animations (ring focus)
+- Navigation animations
+- Performance guidelines
+
+### 4. UI States
+For each component:
+- Empty state
+- Loading state
+- Success state
+- Error state
+- Disabled state
+
+### 5. Asset Checklist
+- Images (WebP, responsive sizes)
+- Icons (SVG preferred)
+- Performance notes
+
+## Detailed Documentation
+
+| Reference | Use When |
+|-----------|----------|
+| [references/generation-steps.md](references/generation-steps.md) | Full step-by-step process |
+| [references/wireframe-patterns.md](references/wireframe-patterns.md) | Layout wireframe examples |
+| [references/animation-patterns.md](references/animation-patterns.md) | Animation blueprint guide |
+| [templates/page-plan.md](templates/page-plan.md) | Output template |
+
+## Integration
+
+```
+/designsetup → /pageplan → /csetup → /cdev
+     ↓             ↓           ↓         ↓
+ data.yaml    page-plan.md  research  uxui-frontend
+              (visual)      checklist  reads both
+```
+
+**Separation:**
+- `/pageplan` = Visual (layout, components, animations)
+- `/csetup` = Research (best practices, content strategy)

package/skills/page-planner/references/CLAUDE.md

@@ -0,0 +1,11 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+### Feb 3, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #252 | 11:38 PM | 🔵 | Git status reveals extensive refactoring with skills migration and core context reorganization | ~682 |
+</claude-mem-context>