@champpaba/claude-agent-kit 3.5.2 → 3.6.0

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

@@ -0,0 +1,161 @@
+# Error Handling
+
+How to handle failures during design extraction.
+
+---
+
+## Critical Errors (Stop Execution)
+
+### Navigation Failures
+
+If browser navigation fails:
+
+```
+❌ Failed to load URL: {url}
+
+Error: {error.message}
+
+Check:
+- Is the URL accessible?
+- Is agent-browser installed? (npm install -g agent-browser && agent-browser install)
+- Is the site blocking automated access?
+```
+
+**Action:** Stop execution. Cannot proceed without page loaded.
+
+### Browser Not Available
+
+If agent-browser is not available:
+
+```
+❌ Browser automation not available
+
+Required: agent-browser CLI
+
+Setup:
+npm install -g agent-browser && agent-browser install
+```
+
+**Action:** Stop execution. Provide setup instructions.
+
+---
+
+## Non-Critical Errors (Continue with Fallbacks)
+
+### Extraction Failures
+
+If individual extraction steps fail:
+
+| Extraction | Fallback |
+|------------|----------|
+| Colors | `{ backgrounds: [], texts: [], borders: [] }` |
+| Typography | `{ h1: [], fonts: [], weights: [], sizes: [] }` |
+| Shadows | `{ shadows: [], borderRadii: [] }` |
+| Spacing | `{ grid_base: 8, common_values: [] }` |
+| Components | `[]` (empty array) |
+| Animations | `{ keyframes: [], transitions: [] }` |
+
+Log warning and continue:
+```
+⚠️ Color extraction failed: {error.message}
+   Using fallback empty data
+```
+
+### Screenshot Failures
+
+| Scenario | Fallback |
+|----------|----------|
+| Full-page screenshot fails | Try viewport-only screenshot |
+| Component screenshot fails | Skip component, continue with others |
+| All screenshots fail | Continue without screenshots, note in report |
+
+### CORS/Security Errors
+
+Some sites block stylesheet access:
+
+```
+⚠️ Cannot access stylesheet: {url}
+   Reason: CORS policy
+   Skipping external stylesheet
+```
+
+**Action:** Continue with inline styles and accessible stylesheets.
+
+### Element Not Found
+
+If expected elements don't exist:
+
+```
+⚠️ No buttons found on page
+   Skipping button extraction
+```
+
+**Action:** Mark section as `detected: false` in output YAML.
+
+---
+
+## Partial Success Handling
+
+### Coverage Calculation
+
+Track what was successfully extracted:
+
+```yaml
+coverage:
+  total_sections: 17
+  detected_sections: 12
+  percentage: 71
+  missing:
+    - icons_imagery
+    - navigation_patterns
+    - loading_states
+    - feedback_states
+    - accessibility
+```
+
+### Final Report with Warnings
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ EXTRACTION COMPLETE (with warnings)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 Coverage: 12/17 sections (71%)
+
+⚠️ Warnings:
+   - Color extraction partial: CORS blocked 2 stylesheets
+   - Button hover states: 1 of 3 failed
+   - Full-page screenshot failed, using viewport
+
+📁 Output:
+   ✓ design-system/extracted/example/data.yaml
+   ⚠️ design-system/extracted/example/screenshots/ (partial)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Retry Strategy
+
+For transient failures (network timeouts):
+
+1. **First attempt:** Normal extraction
+2. **If timeout:** Wait 2 seconds, retry once
+3. **If still fails:** Use fallback data, continue
+
+Do NOT retry indefinitely. Accept partial data over blocking on single failure.
+
+---
+
+## User Communication
+
+Always inform user of issues:
+
+| Severity | Format |
+|----------|--------|
+| Critical | ❌ Error message, stop |
+| Warning | ⚠️ Warning, continue |
+| Info | ℹ️ Note, continue |
+
+Never silently fail. User should know what succeeded and what didn't.

package/skills/design-extract/references/extraction-steps.md

@@ -0,0 +1,183 @@
+# Extraction Steps
+
+Complete step-by-step guide for extracting design data from a website.
+
+---
+
+## STEP 0: Parse Input & Setup
+
+### 0.1: Validate and Normalize URL
+
+1. Check if URL argument is provided
+   - If missing, return error: "URL required. Usage: /extract https://airbnb.com"
+2. Trim whitespace from URL
+3. Add "https://" prefix if URL doesn't start with "http://" or "https://"
+4. Parse hostname and auto-detect site name:
+   - Remove "www." prefix if present
+   - Remove top-level domain (TLD) to get clean site name
+   - Example: "www.airbnb.com" → "airbnb"
+
+### 0.2: Check for Existing Extraction
+
+1. Build path: `design-system/extracted/{siteName}/data.yaml`
+2. If file exists:
+   - Read existing YAML file
+   - Extract `meta.extracted_at` field
+   - Ask user: "Site '{siteName}' was already extracted on {extractedDate}. Re-extract?"
+   - If user chooses "No", exit with message: "Extraction cancelled. Existing data preserved."
+
+### 0.3: Create Output Directories
+
+```bash
+mkdir -p design-system/extracted/{siteName}/screenshots
+```
+
+---
+
+## STEP 1: Navigate & Wait
+
+### 1.1: Navigate to URL
+
+Use agent-browser to navigate to the target URL:
+```bash
+agent-browser open {url}
+```
+
+### 1.2: Smart Wait for Page Load
+
+1. Take DOM snapshot to analyze page structure
+2. Find heading elements
+3. If headings found:
+   - Wait for first heading text (timeout: 15000ms)
+4. If no headings found:
+   - Fallback to sleep 5000ms
+
+### 1.3: Verify Document Ready
+
+1. Check document.readyState
+2. If not "complete", sleep additional 3000ms
+
+---
+
+## STEP 2: Extract CSS Data (8 Parallel Extractions)
+
+Run all extractions in parallel for speed.
+
+### 2.1: Extract Colors
+
+Extract from all elements using `window.getComputedStyle()`:
+- Background colors (skip transparent)
+- Text colors
+- Border colors
+
+Convert RGB to HEX, detect usage context, count frequency.
+
+Output: `colors.backgrounds`, `colors.texts`, `colors.borders`
+
+### 2.2: Extract Typography
+
+Extract heading styles (h1, h2, h3) and body text:
+- fontSize, fontWeight, fontFamily
+- lineHeight, letterSpacing
+
+Collect unique fonts, weights, sizes.
+
+### 2.3: Extract Shadows & Effects
+
+- boxShadow values (skip "none")
+- borderRadius values (skip "0px")
+- borderWidth values
+
+### 2.4: Extract Spacing
+
+- Padding values
+- Margin values (skip "auto")
+- Gap values
+
+Detect spacing grid pattern (usually 4px or 8px base).
+
+### 2.5: Extract Buttons
+
+Query: `button`, `a[role="button"]`, `.btn`, `[class*="button"]`
+
+For each button:
+- Add `data-extract-id` attribute
+- Extract styles: backgroundColor, color, padding, borderRadius, transition
+
+### 2.6: Extract Cards
+
+Query: `[class*="card"]`, `article`, `section`
+
+Extract: backgroundColor, padding, border, boxShadow, transition
+
+### 2.7: Extract Input Fields
+
+Query: `input[type="text"]`, `textarea`, etc.
+
+Extract: height, padding, border, borderRadius, transition
+
+### 2.8: Extract Animations
+
+1. CSS @keyframes from stylesheets
+2. Transition properties from elements
+
+---
+
+## STEP 3: Extract Component Animations
+
+For buttons, cards, and inputs:
+
+1. Find element by data-extract-id
+2. Scroll into view
+3. Screenshot default state
+4. Capture default computed styles
+5. Trigger hover/focus event
+6. Wait for transition (500ms)
+7. Screenshot hover/focus state
+8. Capture new computed styles
+9. Remove hover/focus event
+10. Compare and describe changes
+
+---
+
+## STEP 4: Full-Page Screenshot
+
+1. Try full-page screenshot first
+2. If fails, fallback to viewport-only
+3. Save to `screenshots/full-page.png` or `screenshots/viewport.png`
+
+---
+
+## STEP 5: AI Psychology Analysis
+
+Using the screenshot and extracted data, analyze:
+
+1. **style_classification**: Neo-Brutalism, Minimalist, Glassmorphism, etc.
+2. **emotions_evoked**: What feelings the design triggers
+3. **target_audience**: Who this design appeals to
+4. **visual_principles**: Key design patterns observed
+5. **why_it_works**: Strategic design decisions
+6. **design_philosophy**: Underlying beliefs
+
+---
+
+## STEP 6: Generate data.yaml
+
+1. Calculate coverage metrics (X/17 sections)
+2. Build YAML with all extracted data
+3. Include psychology analysis
+4. Write to `design-system/extracted/{siteName}/data.yaml`
+
+→ See [output-format.md](output-format.md) for complete schema
+
+---
+
+## STEP 7: Final Report
+
+Display extraction summary:
+- Coverage percentage
+- Design tokens extracted
+- Psychology analysis status
+- Screenshot count
+- Output file paths
+- Next steps

package/skills/design-extract/references/output-format.md

@@ -0,0 +1,250 @@
+# Output Format: data.yaml
+
+Complete schema for the extracted design data file.
+
+---
+
+## File Location
+
+```
+design-system/extracted/{site-name}/data.yaml
+```
+
+---
+
+## Complete Schema
+
+```yaml
+# Design Extraction: {siteName}
+# Extracted: {ISO timestamp}
+# URL: {url}
+
+meta:
+  site_name: "airbnb"
+  url: "https://airbnb.com"
+  extracted_at: "2026-02-03T15:30:00Z"
+  extractor_version: "2.1.0"
+  coverage:
+    total_sections: 17
+    detected_sections: 15
+    percentage: 88
+
+psychology:
+  style_classification: "Modern SaaS"
+
+  emotions_evoked:
+    - emotion: "Trust"
+      reason: "Clean typography and ample whitespace"
+    - emotion: "Excitement"
+      reason: "Vibrant accent colors on CTAs"
+
+  target_audience:
+    primary:
+      description: "Young professionals"
+      age_range: "25-40"
+      tech_savvy: "high"
+    secondary:
+      description: "Families"
+      age_range: "30-50"
+
+  visual_principles:
+    - name: "Hierarchy"
+      description: "Clear visual hierarchy through size and weight"
+    - name: "Whitespace"
+      description: "Generous padding creates breathing room"
+
+  why_it_works:
+    - "Large hero images create emotional connection"
+    - "Simple navigation reduces cognitive load"
+
+  design_philosophy:
+    core_belief: "Design should feel human and approachable"
+    key_principles:
+      - "Simplicity over complexity"
+      - "Content-first approach"
+
+sections:
+  overview:
+    detected: true
+    style: "Modern SaaS"
+    tech_stack: "Framework-agnostic"
+
+  color_palette:
+    detected: true
+    primary:
+      - hex: "#FF5A5F"
+        rgb: "rgb(255, 90, 95)"
+        usage: "brand-primary"
+        count: 23
+      - hex: "#00A699"
+        rgb: "rgb(0, 166, 153)"
+        usage: "brand-secondary"
+        count: 12
+    text_colors:
+      - hex: "#484848"
+        usage: "body-text"
+        count: 156
+      - hex: "#767676"
+        usage: "muted-text"
+        count: 89
+    border_colors:
+      - hex: "#EBEBEB"
+        usage: "divider"
+        count: 45
+
+  typography:
+    detected: true
+    fonts:
+      - "Circular"
+      - "Cereal"
+      - "-apple-system"
+    weights: ["400", "500", "600", "700", "800"]
+    sizes: ["12px", "14px", "16px", "18px", "22px", "26px", "32px"]
+    h1:
+      - text: "Find places to stay"
+        fontSize: "32px"
+        fontWeight: "800"
+        fontFamily: "Circular, sans-serif"
+    h2:
+      - fontSize: "22px"
+        fontWeight: "600"
+    body:
+      - fontSize: "16px"
+        fontWeight: "400"
+        lineHeight: "1.5"
+
+  spacing_system:
+    detected: true
+    grid_base: 8
+    common_values: [8, 16, 24, 32, 48, 64]
+    paddings: ["8px", "16px", "24px", "32px", "48px"]
+    margins: ["8px", "16px", "24px", "32px"]
+    gaps: ["8px", "16px", "24px"]
+
+  component_styles:
+    detected: true
+    buttons:
+      - id: "button-0"
+        text: "Search"
+        backgroundColor: "rgb(255, 90, 95)"
+        color: "rgb(255, 255, 255)"
+        padding: "14px 24px"
+        borderRadius: "8px"
+        fontSize: "16px"
+        fontWeight: "600"
+        transition: "all 0.2s ease"
+        hover_animation: "Background darkens + Shadow appears"
+    cards:
+      - id: "card-0"
+        backgroundColor: "rgb(255, 255, 255)"
+        padding: "16px"
+        borderRadius: "12px"
+        boxShadow: "0 2px 8px rgba(0, 0, 0, 0.1)"
+        transition: "all 0.3s ease"
+        hover_animation: "Shadow increases + Slight lift"
+    inputs:
+      - id: "input-0"
+        type: "text"
+        height: "48px"
+        padding: "0 16px"
+        borderRadius: "8px"
+        border: "1px solid #EBEBEB"
+        fontSize: "16px"
+        transition: "border-color 0.2s ease"
+        focus_animation: "Border color changes to primary"
+
+  shadows_elevation:
+    detected: true
+    values:
+      - "0 1px 2px rgba(0, 0, 0, 0.08)"
+      - "0 2px 8px rgba(0, 0, 0, 0.1)"
+      - "0 4px 16px rgba(0, 0, 0, 0.12)"
+      - "0 8px 28px rgba(0, 0, 0, 0.15)"
+
+  animations_transitions:
+    detected: true
+    keyframes:
+      - name: "fadeIn"
+        css: "@keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }"
+    transitions:
+      - duration: "0.2s"
+        timing: "ease"
+        property: "all"
+      - duration: "0.3s"
+        timing: "ease-out"
+        property: "transform"
+
+  border_radius:
+    detected: true
+    values: ["4px", "8px", "12px", "16px", "24px", "50%"]
+
+  border_styles:
+    detected: true
+    widths: ["1px", "2px"]
+    colors: ["#EBEBEB", "#DDDDDD"]
+
+  layout_patterns:
+    detected: true
+    container_width: "1280px"
+    grid_columns: 12
+    breakpoints:
+      - name: "mobile"
+        max_width: "744px"
+      - name: "tablet"
+        max_width: "1128px"
+      - name: "desktop"
+        min_width: "1128px"
+
+# Detailed animation states
+animations:
+  button-0:
+    type: "button"
+    description: "Background darkens + Shadow appears"
+    transition: "all 0.2s ease"
+    states:
+      default:
+        background: "rgb(255, 90, 95)"
+        boxShadow: "none"
+        transform: "none"
+      hover:
+        background: "rgb(230, 80, 85)"
+        boxShadow: "0 2px 8px rgba(255, 90, 95, 0.3)"
+        transform: "none"
+  card-0:
+    type: "card"
+    description: "Shadow increases + Slight lift"
+    transition: "all 0.3s ease"
+    states:
+      default:
+        boxShadow: "0 2px 8px rgba(0, 0, 0, 0.1)"
+        transform: "translateY(0)"
+      hover:
+        boxShadow: "0 4px 16px rgba(0, 0, 0, 0.15)"
+        transform: "translateY(-2px)"
+```
+
+---
+
+## 17 Standard Sections
+
+| # | Section | Description |
+|---|---------|-------------|
+| 1 | overview | Style classification, tech stack |
+| 2 | color_palette | Primary, text, border colors |
+| 3 | typography | Fonts, weights, sizes |
+| 4 | spacing_system | Grid base, common values |
+| 5 | component_styles | Buttons, cards, inputs |
+| 6 | shadows_elevation | Box shadow values |
+| 7 | animations_transitions | Keyframes, transitions |
+| 8 | border_radius | Radius values |
+| 9 | border_styles | Widths, colors |
+| 10 | layout_patterns | Container, grid, breakpoints |
+| 11 | icons_imagery | Icon style (if detected) |
+| 12 | navigation_patterns | Nav structure (if detected) |
+| 13 | form_patterns | Form layouts (if detected) |
+| 14 | feedback_states | Error, success states |
+| 15 | loading_states | Spinners, skeletons |
+| 16 | motion_design | Complex animations |
+| 17 | accessibility | Focus states, contrast |
+
+Coverage percentage = detected / 17 * 100