agent-skill-kit 3.9.135

package/.agent/skills/design-system/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: design-system
+description: >-
+  Design thinking for web UI: color theory, typography, visual effects, UX psychology, and animation.
+  Use when choosing colors, fonts, layouts, or validating UX decisions.
+  NOT for CSS implementation (use tailwind-kit) or code architecture (use react-pro).
+category: design-architecture
+triggers: ["design", "UI", "UX", "color palette", "typography", "component design"]
+coordinates_with: ["studio", "tailwind-kit", "frontend-design"]
+success_metrics: ["0 WCAG accessibility violations", "100% Hick's law compliance"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# Design System — UI Design Decisions
+
+> Every pixel has purpose. Restraint is luxury. User psychology drives decisions.
+
+---
+
+## 5 Must-Ask Questions (Socratic Gate)
+
+| # | Question | Options |
+|---|----------|---------|
+| 1 | Project Type? | SaaS / E-commerce / Portfolio / Dashboard |
+| 2 | Brand Mood? | Professional / Playful / Luxury / Minimal |
+| 3 | Light or Dark Mode? | Light / Dark / Both / User preference |
+| 4 | Target Audience? | Enterprise / Consumer / Developer / Creative |
+| 5 | Component Scope? | Full system / Color only / Typography only |
+
+---
+
+## Prerequisites
+
+**Required:** None — Design System is a knowledge-based skill with no external dependencies.
+
+---
+
+## When to Use
+
+| Situation | Action |
+|-----------|--------|
+| Color selection | Invoke color-palette; read `rules/color-system.md` |
+| Typography | Invoke typography-system; read `rules/typography-system.md` |
+| Visual effects | Invoke visual-effect; read `rules/visual-effects.md` |
+| Animation/motion | Invoke animation-select; read `rules/animation-guide.md` |
+| UX validation | Invoke ux-audit; read `rules/ux-psychology.md` |
+| Design decisions | Read `rules/decision-trees.md` |
+| Architecture review | Read `rules/engineering-spec.md` |
+
+---
+
+## System Boundaries
+
+| Owned by This Skill | NOT Owned |
+|---------------------|-----------|
+| Color theory (3 harmony types + semantic palette) | CSS/Tailwind generation (→ tailwind-kit) |
+| Typography system (max 2 families, modular scale) | AI style recommendations (→ studio) |
+| Visual effects selection criteria | Component implementation |
+| Animation principles (3 functional categories) | WCAG accessibility (→ web-design-guidelines) |
+| UX psychology audit (Hick's, Fitts's, Gestalt) | Image/asset generation (→ ai-artist) |
+| 3 design anti-pattern bans | Frontend code architecture (→ frontend-design) |
+
+**Pure decision skill:** Produces design specifications. Zero side effects (except UX audit script reads files).
+
+---
+
+## ⚠️ Anti-Pattern Bans (Enforced on ALL Outputs)
+
+| # | Ban | Reason |
+|---|-----|--------|
+| 1 | **Purple Ban** | Do not use generic purple themes (AI-generated cliché) |
+| 2 | **Bento Ban** | Do not default to Bento grids without explicit justification |
+| 3 | **Dark Mode Default** | Do not assume dark mode unless `dark_mode_requested = true` |
+
+---
+
+## Color System (Quick Reference)
+
+| Project + Mood | Harmony |
+|---------------|---------|
+| Professional / Corporate | Complementary |
+| Creative / Playful | Triadic |
+| Minimal / Luxury | Analogous |
+
+Every palette includes: primary, secondary, accent, 5 neutrals, 4 semantic (success/warning/error/info).
+
+---
+
+## Typography Rules
+
+| Rule | Constraint |
+|------|-----------|
+| Max font families | 2 (heading + body) |
+| Scale | Modular ratio (1.25 or 1.333) |
+| Line height | 1.4–1.6 for body text |
+
+---
+
+## Animation Categories
+
+| Category | Purpose | Duration |
+|----------|---------|----------|
+| **Feedback** | Confirm user action | 100–200ms |
+| **Orientation** | Guide spatial awareness | 200–400ms |
+| **Continuity** | Connect state transitions | 300–500ms |
+
+Every animation must serve one of these 3 functions. Decorative-only motion is not allowed.
+
+---
+
+## Studio Integration
+
+```bash
+# Generate complete design system
+node .agent/skills/studio/scripts/search.ts "<query>" --design-system
+
+# Search specific domain
+node .agent/skills/studio/scripts/search.ts "<query>" --domain style
+```
+
+**Available domains:** style, color, typography, landing, ux, chart, product
+
+---
+
+## Error Taxonomy
+
+| Code | Recoverable | Trigger |
+|------|-------------|---------|
+| `ERR_INVALID_REQUEST_TYPE` | No | Request type not supported |
+| `ERR_MISSING_PROJECT_TYPE` | Yes | Project type not provided |
+| `ERR_MISSING_BRAND_MOOD` | Yes | Brand mood not provided |
+| `ERR_RULE_NOT_FOUND` | No | Rule file missing |
+| `WARN_ANTI_PATTERN` | Yes | Purple/bento/dark mode ban violated |
+| `WARN_UX_VIOLATION` | Yes | UX psychology law violated |
+
+**Zero internal retries.** Deterministic; same context = same design.
+
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| [ux-psychology.md](rules/ux-psychology.md) | 🔴 **REQUIRED** — Core UX psychology laws | Always |
+| [color-system.md](rules/color-system.md) | Color theory and palette selection | Color decisions |
+| [typography-system.md](rules/typography-system.md) | Font pairing and scale | Typography |
+| [visual-effects.md](rules/visual-effects.md) | Shadows, gradients, glassmorphism | Effects selection |
+| [animation-guide.md](rules/animation-guide.md) | Motion principles | Animation |
+| [motion-graphics.md](rules/motion-graphics.md) | Advanced motion (Lottie, 3D) | Complex animation |
+| [decision-trees.md](rules/decision-trees.md) | Design decision framework | All decisions |
+| [engineering-spec.md](rules/engineering-spec.md) | Full engineering spec | Architecture review |
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/ux_audit.ts` | UX psychology audit |
+| `scripts/accessibility_checker.ts` | WCAG compliance audit |
+
+**Selective reading:** Read ONLY files relevant to the request.
+
+---
+
+## Audit Logging (OpenTelemetry)
+
+| Event | Metadata Payload | Severity |
+|-------|------------------|----------|
+| `palette_generated` | `{"harmony": "complementary", "brand_mood": "professional"}` | `INFO` |
+| `typography_selected` | `{"heading_font": "Inter", "scale_ratio": 1.25}` | `INFO` |
+| `ux_audit_completed` | `{"violations": 0, "laws_checked": ["Hicks", "Fitts"]}` | `INFO` |
+
+All design-system outputs MUST emit `palette_generated`, `typography_selected`, or `ux_audit_completed` events when applicable.
+
+---
+
+## 🔗 Related
+
+| Item | Type | Purpose |
+|------|------|---------|
+| `studio` | Skill | AI-powered design recommendations |
+| `tailwind-kit` | Skill | CSS/Tailwind implementation |
+| `frontend-design` | Skill | Frontend code architecture |
+| `/studio` | Workflow | Comprehensive design workflow |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/design-system/rules/_sections.md

@@ -0,0 +1,65 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Color System (color)
+
+**Impact:** MEDIUM  
+**Description:** Color theory, palette generation, and accessibility compliance.
+
+## 2. Motion Graphics (motion)
+
+**Impact:** MEDIUM  
+**Description:** Motion design patterns for engaging user experiences.
+
+## 3. Animation & Motion (animation)
+
+**Impact:** MEDIUM  
+**Description:** Smooth animations and motion design patterns.
+
+## 4. Decision Trees (decision)
+
+**Impact:** HIGH  
+**Description:** Structured decision-making frameworks for design choices.
+
+## 5. Design (design)
+
+**Impact:** LOW  
+**Description:** Design patterns and best practices.
+
+## 6. Engineering Specification (engineering)
+
+**Impact:** MEDIUM  
+**Description:** Full engineering specification covering contracts, security, and scalability.
+
+## 7. Spatial (spatial)
+
+**Impact:** LOW  
+**Description:** Spatial patterns and best practices.
+
+## 8. Typography System (typography)
+
+**Impact:** MEDIUM  
+**Description:** Font selection, scaling, and readability optimization.
+
+## 9. General (general)
+
+**Impact:** LOW  
+**Description:** General patterns and best practices.
+
+## 10. UX Psychology (ux)
+
+**Impact:** HIGH  
+**Description:** User experience principles based on cognitive psychology.
+
+## 11. Visual Effects (visual)
+
+**Impact:** LOW  
+**Description:** Visual enhancements and decorative effects.
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/design-system/rules/_template.md

@@ -0,0 +1,32 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/design-system/rules/animation-guide.md

@@ -0,0 +1,355 @@
+---
+name: animation-guide
+description: Animation principles — duration psychology, easing, micro-interactions, loading states, scroll animations
+title: "Animation Guidelines Reference"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: animation, guide
+---
+
+# Animation Guidelines Reference
+
+> Animation principles and timing psychology - learn to decide, not copy.
+> **No fixed durations to memorize - understand what affects timing.**
+
+---
+
+## 1. Duration Principles
+
+### What Affects Timing
+
+```
+Factors that determine animation speed:
+├── DISTANCE: Further travel = longer duration
+├── SIZE: Larger elements = slower animations
+├── COMPLEXITY: Complex = slower to process
+├── IMPORTANCE: Critical actions = clear feedback
+└── CONTEXT: Urgent = fast, luxurious = slow
+```
+
+### Duration Ranges by Purpose
+
+| Purpose | Range | Why |
+|---------|-------|-----|
+| Instant feedback | 50-100ms | Below perception threshold |
+| Micro-interactions | 100-200ms | Quick but noticeable |
+| Standard transitions | 200-300ms | Comfortable pace |
+| Complex animations | 300-500ms | Time to follow |
+| Page transitions | 400-600ms | Smooth handoff |
+| **Wow/Premium Effects** | 800ms+ | Dramatic, organic spring-based, layered |
+
+### Choosing Duration
+
+Ask yourself:
+1. How far is the element moving?
+2. How important is it to notice this change?
+3. Is the user waiting, or is this background?
+
+---
+
+## 2. Easing Principles
+
+### What Easing Does
+
+```
+Easing = how speed changes over time
+├── Linear: constant speed (mechanical, robotic)
+├── Ease-out: fast start, slow end (natural entry)
+├── Ease-in: slow start, fast end (natural exit)
+└── Ease-in-out: slow both ends (smooth, deliberate)
+```
+
+### When to Use Each
+
+| Easing | Best For | Feels Like |
+|--------|----------|------------|
+| **Ease-out** | Elements entering | Arriving, settling |
+| **Ease-in** | Elements leaving | Departing, exiting |
+| **Ease-in-out** | Emphasis, loops | Deliberate, smooth |
+| **Linear** | Continuous motion | Mechanical, constant |
+| **Bounce/Elastic** | Playful UI | Fun, energetic |
+
+### The Pattern
+
+```css
+/* Entering view = ease-out (decelerate) */
+.enter {
+  animation-timing-function: ease-out;
+}
+
+/* Leaving view = ease-in (accelerate) */
+.exit {
+  animation-timing-function: ease-in;
+}
+
+/* Continuous = ease-in-out */
+.continuous {
+  animation-timing-function: ease-in-out;
+}
+```
+
+---
+
+## 3. Micro-Interaction Principles
+
+### What Makes Good Micro-Interactions
+
+```
+Purpose of micro-interactions:
+├── FEEDBACK: Confirm the action happened
+├── GUIDANCE: Show what's possible
+├── STATUS: Indicate current state
+└── DELIGHT: Small moments of joy
+```
+
+### Button States
+
+```
+Hover → slight visual change (lift, color, scale)
+Active → pressed feeling (scale down, shadow change)
+Focus → clear indicator (outline, ring)
+Loading → progress indicator (spinner, skeleton)
+Success → confirmation (check, color)
+```
+
+### Principles
+
+1. **Respond immediately** (under 100ms perception)
+2. **Match the action** (press = `scale(0.95)`, hover = `translateY(-4px) + glow`)
+3. **Be bold but smooth** (Usta işi hissettir)
+4. **Be consistent** (same actions = same feedback)
+
+---
+
+## 4. Loading States Principles
+
+### Types by Context
+
+| Situation | Approach |
+|-----------|----------|
+| Quick load (<1s) | No indicator needed |
+| Medium (1-3s) | Spinner or simple animation |
+| Long (3s+) | Progress bar or skeleton |
+| Unknown duration | Indeterminate indicator |
+
+### Skeleton Screens
+
+```
+Purpose: Reduce perceived wait time
+├── Show layout shape immediately
+├── Animate subtly (shimmer, pulse)
+├── Replace with content when ready
+└── Feels faster than spinner
+```
+
+### Progress Indicators
+
+```
+When to show progress:
+├── User-initiated action
+├── File uploads/downloads
+├── Multi-step processes
+└── Long operations
+
+When NOT needed:
+├── Very quick operations
+├── Background tasks
+└── Initial page loads (skeleton better)
+```
+
+---
+
+## 5. Page Transitions Principles
+
+### Transition Strategy
+
+```
+Simple rule: exit fast, enter slower
+├── Outgoing content fades quickly
+├── Incoming content animates in
+└── Avoids "everything moving at once"
+```
+
+### Common Patterns
+
+| Pattern | When to Use |
+|---------|-------------|
+| **Fade** | Safe default, works everywhere |
+| **Slide** | Sequential navigation (prev/next) |
+| **Scale** | Opening/closing modals |
+| **Shared element** | Maintaining visual continuity |
+
+### Direction Matching
+
+```
+Navigation direction = animation direction
+├── Forward → slide from right
+├── Backward → slide from left
+├── Deeper → scale up from center
+├── Back up → scale down
+```
+
+---
+
+## 6. Scroll Animation Principles
+
+### Progressive Reveal
+
+```
+Content appears as user scrolls:
+├── Reduces initial cognitive load
+├── Rewards exploration
+├── Must not feel sluggish
+└── Option to disable (accessibility)
+```
+
+### Trigger Points
+
+| When to Trigger | Effect |
+|-----------------|--------|
+| Just entering viewport | Standard reveal |
+| Centered in viewport | For emphasis |
+| Partially visible | Earlier reveal |
+| Fully visible | Late trigger |
+
+### Animation Properties
+
+- Fade in (opacity)
+- Slide up (transform)
+- Scale (transform)
+- Combination of above
+
+### Performance
+
+- Use Intersection Observer
+- Animate only transform/opacity
+- Reduce on mobile if needed
+
+---
+
+## 7. Hover Effects Principles
+
+### Matching Effect to Action
+
+| Element | Effect | Intent |
+|---------|--------|--------|
+| **Clickable card** | Lift + shadow | "This is interactive" |
+| **Button** | Color/brightness change | "Press me" |
+| **Image** | Zoom/scale | "View closer" |
+| **Link** | Underline/color | "Navigate here" |
+
+### Principles
+
+1. **Signal interactivity** - hover shows it's clickable
+2. **Don't overdo it** - subtle changes work
+3. **Match importance** - bigger change = more important
+4. **Touch alternatives** - hover doesn't work on mobile
+
+---
+
+## 8. Feedback Animation Principles
+
+### Success States
+
+```
+Celebrate appropriately:
+├── Minor action → subtle check/color
+├── Major action → more pronounced animation
+├── Completion → satisfying animation
+└── Match brand personality
+```
+
+### Error States
+
+```
+Draw attention without panic:
+├── Color change (semantic red)
+├── Shake animation (brief!)
+├── Focus on error field
+└── Clear messaging
+```
+
+### Timing
+
+- Success: slightly longer (enjoy the moment)
+- Error: quick (don't delay action)
+- Loading: continuous until complete
+
+---
+
+## 9. Performance Principles
+
+### What's Cheap to Animate
+
+```
+GPU-accelerated (FAST):
+├── transform: translate, scale, rotate
+└── opacity: 0 to 1
+
+CPU-intensive (SLOW):
+├── width, height
+├── top, left, right, bottom
+├── margin, padding
+├── border-radius changes
+└── box-shadow changes
+```
+
+### Optimization Strategies
+
+1. **Animate transform/opacity** whenever possible
+2. **Avoid layout triggers** (size/position changes)
+3. **Use will-change sparingly** (hints to browser)
+4. **Test on low-end devices** (not just dev machine)
+
+### Respecting User Preferences
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  /* Honor this preference */
+  /* Essential animations only */
+  /* Reduce or remove decorative motion */
+}
+```
+
+---
+
+## 10. Animation Decision Checklist
+
+Before adding animation:
+
+- [ ] **Is there a purpose?** (feedback/guidance/delight)
+- [ ] **Is timing appropriate?** (not too fast/slow)
+- [ ] **Did you pick correct easing?** (enter/exit/emphasis)
+- [ ] **Is it performant?** (transform/opacity only)
+- [ ] **Tested reduced motion?** (accessibility)
+- [ ] **Consistent with other animations?** (same timing feel)
+- [ ] **Not your default settings?** (variety check)
+- [ ] **Asked user about style if unclear?**
+
+### Anti-Patterns
+
+- ❌ Same timing values every project
+- ❌ Animation for animation's sake
+- ❌ Ignoring reduced-motion preference
+- ❌ Animating expensive properties
+- ❌ Too many things animating at once
+- ❌ Delays that frustrate users
+
+---
+
+> **Remember**: Animation is communication. Every motion should have meaning and serve the user experience.
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [motion-graphics.md](motion-graphics.md) | Advanced Lottie, GSAP, particle effects |
+| [visual-effects.md](visual-effects.md) | CSS effects to animate |
+| [ux-psychology.md](ux-psychology.md) | Feedback psychology for micro-interactions |
+| [../SKILL.md](../SKILL.md) | Animation categories quick reference |
+
+---
+
+⚡ PikaKit v3.9.134