@sylix/coworker 2.0.11 → 2.0.14

package/dist/skills/defaults/frontend/design-system-patterns.md

@@ -0,0 +1,337 @@
+---
+name: design-system-patterns
+description: Build scalable design systems with design tokens, theming infrastructure, and component architecture patterns. Use when creating design tokens, implementing theme switching, building component libraries, or establishing design system foundations.
+---
+
+# Design System Patterns
+
+Master design system architecture to create consistent, maintainable, and scalable UI foundations across web and mobile applications.
+
+## When to Use This Skill
+
+- Creating design tokens for colors, typography, spacing, and shadows
+- Implementing light/dark theme switching with CSS custom properties
+- Building multi-brand theming systems
+- Architecting component libraries with consistent APIs
+- Establishing design-to-code workflows with Figma tokens
+- Creating semantic token hierarchies (primitive, semantic, component)
+- Setting up design system documentation and guidelines
+
+## Core Capabilities
+
+### 1. Design Tokens
+
+- Primitive tokens (raw values: colors, sizes, fonts)
+- Semantic tokens (contextual meaning: text-primary, surface-elevated)
+- Component tokens (specific usage: button-bg, card-border)
+- Token naming conventions and organization
+- Multi-platform token generation (CSS, iOS, Android)
+
+### 2. Theming Infrastructure
+
+- CSS custom properties architecture
+- Theme context providers in React
+- Dynamic theme switching
+- System preference detection (prefers-color-scheme)
+- Persistent theme storage
+- Reduced motion and high contrast modes
+
+### 3. Component Architecture
+
+- Compound component patterns
+- Polymorphic components (as prop)
+- Variant and size systems
+- Slot-based composition
+- Headless UI patterns
+- Style props and responsive variants
+
+### 4. Token Pipeline
+
+- Figma to code synchronization
+- Style Dictionary configuration
+- Token transformation and formatting
+- CI/CD integration for token updates
+
+## Quick Start
+
+```typescript
+// Design tokens with CSS custom properties
+const tokens = {
+  colors: {
+    // Primitive tokens
+    gray: {
+      50: "#fafafa",
+      100: "#f5f5f5",
+      900: "#171717",
+    },
+    blue: {
+      500: "#3b82f6",
+      600: "#2563eb",
+    },
+  },
+  // Semantic tokens (reference primitives)
+  semantic: {
+    light: {
+      "text-primary": "var(--color-gray-900)",
+      "text-secondary": "var(--color-gray-600)",
+      "surface-default": "var(--color-white)",
+      "surface-elevated": "var(--color-gray-50)",
+      "border-default": "var(--color-gray-200)",
+      "interactive-primary": "var(--color-blue-500)",
+    },
+    dark: {
+      "text-primary": "var(--color-gray-50)",
+      "text-secondary": "var(--color-gray-400)",
+      "surface-default": "var(--color-gray-900)",
+      "surface-elevated": "var(--color-gray-800)",
+      "border-default": "var(--color-gray-700)",
+      "interactive-primary": "var(--color-blue-400)",
+    },
+  },
+};
+```
+
+## Key Patterns
+
+### Pattern 1: Token Hierarchy
+
+```css
+/* Layer 1: Primitive tokens (raw values) */
+:root {
+  --color-blue-500: #3b82f6;
+  --color-blue-600: #2563eb;
+  --color-gray-50: #fafafa;
+  --color-gray-900: #171717;
+
+  --space-1: 0.25rem;
+  --space-2: 0.5rem;
+  --space-4: 1rem;
+
+  --font-size-sm: 0.875rem;
+  --font-size-base: 1rem;
+  --font-size-lg: 1.125rem;
+
+  --radius-sm: 0.25rem;
+  --radius-md: 0.5rem;
+  --radius-lg: 1rem;
+}
+
+/* Layer 2: Semantic tokens (meaning) */
+:root {
+  --text-primary: var(--color-gray-900);
+  --text-secondary: var(--color-gray-600);
+  --surface-default: white;
+  --interactive-primary: var(--color-blue-500);
+  --interactive-primary-hover: var(--color-blue-600);
+}
+
+/* Layer 3: Component tokens (specific usage) */
+:root {
+  --button-bg: var(--interactive-primary);
+  --button-bg-hover: var(--interactive-primary-hover);
+  --button-text: white;
+  --button-radius: var(--radius-md);
+  --button-padding-x: var(--space-4);
+  --button-padding-y: var(--space-2);
+}
+```
+
+### Pattern 2: Theme Switching with React
+
+```tsx
+import { createContext, useContext, useEffect, useState } from "react";
+
+type Theme = "light" | "dark" | "system";
+
+interface ThemeContextValue {
+  theme: Theme;
+  resolvedTheme: "light" | "dark";
+  setTheme: (theme: Theme) => void;
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const [theme, setTheme] = useState<Theme>(() => {
+    if (typeof window !== "undefined") {
+      return (localStorage.getItem("theme") as Theme) || "system";
+    }
+    return "system";
+  });
+
+  const [resolvedTheme, setResolvedTheme] = useState<"light" | "dark">("light");
+
+  useEffect(() => {
+    const root = document.documentElement;
+
+    const applyTheme = (isDark: boolean) => {
+      root.classList.remove("light", "dark");
+      root.classList.add(isDark ? "dark" : "light");
+      setResolvedTheme(isDark ? "dark" : "light");
+    };
+
+    if (theme === "system") {
+      const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+      applyTheme(mediaQuery.matches);
+
+      const handler = (e: MediaQueryListEvent) => applyTheme(e.matches);
+      mediaQuery.addEventListener("change", handler);
+      return () => mediaQuery.removeEventListener("change", handler);
+    } else {
+      applyTheme(theme === "dark");
+    }
+  }, [theme]);
+
+  useEffect(() => {
+    localStorage.setItem("theme", theme);
+  }, [theme]);
+
+  return (
+    <ThemeContext.Provider value={{ theme, resolvedTheme, setTheme }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+export const useTheme = () => {
+  const context = useContext(ThemeContext);
+  if (!context) throw new Error("useTheme must be used within ThemeProvider");
+  return context;
+};
+```
+
+### Pattern 3: Variant System with CVA
+
+```tsx
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/utils";
+
+const buttonVariants = cva(
+  // Base styles
+  "inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        outline:
+          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        sm: "h-9 px-3 text-sm",
+        md: "h-10 px-4 text-sm",
+        lg: "h-11 px-8 text-base",
+        icon: "h-10 w-10",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "md",
+    },
+  },
+);
+
+interface ButtonProps
+  extends
+    React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean;
+}
+
+export function Button({ className, variant, size, ...props }: ButtonProps) {
+  return (
+    <button
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  );
+}
+```
+
+### Pattern 4: Style Dictionary Configuration
+
+```javascript
+// style-dictionary.config.js
+module.exports = {
+  source: ["tokens/**/*.json"],
+  platforms: {
+    css: {
+      transformGroup: "css",
+      buildPath: "dist/css/",
+      files: [
+        {
+          destination: "variables.css",
+          format: "css/variables",
+          options: {
+            outputReferences: true, // Preserve token references
+          },
+        },
+      ],
+    },
+    scss: {
+      transformGroup: "scss",
+      buildPath: "dist/scss/",
+      files: [
+        {
+          destination: "_variables.scss",
+          format: "scss/variables",
+        },
+      ],
+    },
+    ios: {
+      transformGroup: "ios-swift",
+      buildPath: "dist/ios/",
+      files: [
+        {
+          destination: "DesignTokens.swift",
+          format: "ios-swift/class.swift",
+          className: "DesignTokens",
+        },
+      ],
+    },
+    android: {
+      transformGroup: "android",
+      buildPath: "dist/android/",
+      files: [
+        {
+          destination: "colors.xml",
+          format: "android/colors",
+          filter: { attributes: { category: "color" } },
+        },
+      ],
+    },
+  },
+};
+```
+
+## Best Practices
+
+1. **Name Tokens by Purpose**: Use semantic names (text-primary) not visual descriptions (dark-gray)
+2. **Maintain Token Hierarchy**: Primitives > Semantic > Component tokens
+3. **Document Token Usage**: Include usage guidelines with token definitions
+4. **Version Tokens**: Treat token changes as API changes with semver
+5. **Test Theme Combinations**: Verify all themes work with all components
+6. **Automate Token Pipeline**: CI/CD for Figma-to-code synchronization
+7. **Provide Migration Paths**: Deprecate tokens gradually with clear alternatives
+
+## Common Issues
+
+- **Token Sprawl**: Too many tokens without clear hierarchy
+- **Inconsistent Naming**: Mixed conventions (camelCase vs kebab-case)
+- **Missing Dark Mode**: Tokens that don't adapt to theme changes
+- **Hardcoded Values**: Using raw values instead of tokens
+- **Circular References**: Tokens referencing each other in loops
+- **Platform Gaps**: Tokens missing for some platforms (web but not mobile)
+
+## Resources
+
+- [Style Dictionary Documentation](https://amzn.github.io/style-dictionary/)
+- [Tokens Studio for Figma](https://tokens.studio/)
+- [Design Tokens W3C Spec](https://design-tokens.github.io/community-group/format/)
+- [Radix UI Themes](https://www.radix-ui.com/themes)
+- [shadcn/ui Theming](https://ui.shadcn.com/docs/theming)

package/dist/skills/defaults/frontend/interaction-design.md

@@ -0,0 +1,327 @@
+---
+name: interaction-design
+description: Design and implement microinteractions, motion design, transitions, and user feedback patterns. Use when adding polish to UI interactions, implementing loading states, or creating delightful user experiences.
+---
+
+# Interaction Design
+
+Create engaging, intuitive interactions through motion, feedback, and thoughtful state transitions that enhance usability and delight users.
+
+## When to Use This Skill
+
+- Adding microinteractions to enhance user feedback
+- Implementing smooth page and component transitions
+- Designing loading states and skeleton screens
+- Creating gesture-based interactions
+- Building notification and toast systems
+- Implementing drag-and-drop interfaces
+- Adding scroll-triggered animations
+- Designing hover and focus states
+
+## Core Principles
+
+### 1. Purposeful Motion
+
+Motion should communicate, not decorate:
+
+- **Feedback**: Confirm user actions occurred
+- **Orientation**: Show where elements come from/go to
+- **Focus**: Direct attention to important changes
+- **Continuity**: Maintain context during transitions
+
+### 2. Timing Guidelines
+
+| Duration  | Use Case                                  |
+| --------- | ----------------------------------------- |
+| 100-150ms | Micro-feedback (hovers, clicks)           |
+| 200-300ms | Small transitions (toggles, dropdowns)    |
+| 300-500ms | Medium transitions (modals, page changes) |
+| 500ms+    | Complex choreographed animations          |
+
+### 3. Easing Functions
+
+```css
+/* Common easings */
+--ease-out: cubic-bezier(0.16, 1, 0.3, 1); /* Decelerate - entering */
+--ease-in: cubic-bezier(0.55, 0, 1, 0.45); /* Accelerate - exiting */
+--ease-in-out: cubic-bezier(0.65, 0, 0.35, 1); /* Both - moving between */
+--spring: cubic-bezier(0.34, 1.56, 0.64, 1); /* Overshoot - playful */
+```
+
+## Quick Start: Button Microinteraction
+
+```tsx
+import { motion } from "framer-motion";
+
+export function InteractiveButton({ children, onClick }) {
+  return (
+    <motion.button
+      onClick={onClick}
+      whileHover={{ scale: 1.02 }}
+      whileTap={{ scale: 0.98 }}
+      transition={{ type: "spring", stiffness: 400, damping: 17 }}
+      className="px-4 py-2 bg-blue-600 text-white rounded-lg"
+    >
+      {children}
+    </motion.button>
+  );
+}
+```
+
+## Interaction Patterns
+
+### 1. Loading States
+
+**Skeleton Screens**: Preserve layout while loading
+
+```tsx
+function CardSkeleton() {
+  return (
+    <div className="animate-pulse">
+      <div className="h-48 bg-gray-200 rounded-lg" />
+      <div className="mt-4 h-4 bg-gray-200 rounded w-3/4" />
+      <div className="mt-2 h-4 bg-gray-200 rounded w-1/2" />
+    </div>
+  );
+}
+```
+
+**Progress Indicators**: Show determinate progress
+
+```tsx
+function ProgressBar({ progress }: { progress: number }) {
+  return (
+    <div className="h-2 bg-gray-200 rounded-full overflow-hidden">
+      <motion.div
+        className="h-full bg-blue-600"
+        initial={{ width: 0 }}
+        animate={{ width: `${progress}%` }}
+        transition={{ ease: "easeOut" }}
+      />
+    </div>
+  );
+}
+```
+
+### 2. State Transitions
+
+**Toggle with smooth transition**:
+
+```tsx
+function Toggle({ checked, onChange }) {
+  return (
+    <button
+      role="switch"
+      aria-checked={checked}
+      onClick={() => onChange(!checked)}
+      className={`
+        relative w-12 h-6 rounded-full transition-colors duration-200
+        ${checked ? "bg-blue-600" : "bg-gray-300"}
+      `}
+    >
+      <motion.span
+        className="absolute top-1 left-1 w-4 h-4 bg-white rounded-full shadow"
+        animate={{ x: checked ? 24 : 0 }}
+        transition={{ type: "spring", stiffness: 500, damping: 30 }}
+      />
+    </button>
+  );
+}
+```
+
+### 3. Page Transitions
+
+**Framer Motion layout animations**:
+
+```tsx
+import { AnimatePresence, motion } from "framer-motion";
+
+function PageTransition({ children, key }) {
+  return (
+    <AnimatePresence mode="wait">
+      <motion.div
+        key={key}
+        initial={{ opacity: 0, y: 20 }}
+        animate={{ opacity: 1, y: 0 }}
+        exit={{ opacity: 0, y: -20 }}
+        transition={{ duration: 0.3 }}
+      >
+        {children}
+      </motion.div>
+    </AnimatePresence>
+  );
+}
+```
+
+### 4. Feedback Patterns
+
+**Ripple effect on click**:
+
+```tsx
+function RippleButton({ children, onClick }) {
+  const [ripples, setRipples] = useState([]);
+
+  const handleClick = (e) => {
+    const rect = e.currentTarget.getBoundingClientRect();
+    const ripple = {
+      x: e.clientX - rect.left,
+      y: e.clientY - rect.top,
+      id: Date.now(),
+    };
+    setRipples((prev) => [...prev, ripple]);
+    setTimeout(() => {
+      setRipples((prev) => prev.filter((r) => r.id !== ripple.id));
+    }, 600);
+    onClick?.(e);
+  };
+
+  return (
+    <button onClick={handleClick} className="relative overflow-hidden">
+      {children}
+      {ripples.map((ripple) => (
+        <span
+          key={ripple.id}
+          className="absolute bg-white/30 rounded-full animate-ripple"
+          style={{ left: ripple.x, top: ripple.y }}
+        />
+      ))}
+    </button>
+  );
+}
+```
+
+### 5. Gesture Interactions
+
+**Swipe to dismiss**:
+
+```tsx
+function SwipeCard({ children, onDismiss }) {
+  return (
+    <motion.div
+      drag="x"
+      dragConstraints={{ left: 0, right: 0 }}
+      onDragEnd={(_, info) => {
+        if (Math.abs(info.offset.x) > 100) {
+          onDismiss();
+        }
+      }}
+      className="cursor-grab active:cursor-grabbing"
+    >
+      {children}
+    </motion.div>
+  );
+}
+```
+
+## CSS Animation Patterns
+
+### Keyframe Animations
+
+```css
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.5;
+  }
+}
+
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.animate-fadeIn {
+  animation: fadeIn 0.3s ease-out;
+}
+.animate-pulse {
+  animation: pulse 2s ease-in-out infinite;
+}
+.animate-spin {
+  animation: spin 1s linear infinite;
+}
+```
+
+### CSS Transitions
+
+```css
+.card {
+  transition:
+    transform 0.2s ease-out,
+    box-shadow 0.2s ease-out;
+}
+
+.card:hover {
+  transform: translateY(-4px);
+  box-shadow: 0 12px 24px rgba(0, 0, 0, 0.1);
+}
+```
+
+## Accessibility Considerations
+
+```css
+/* Respect user motion preferences */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+```tsx
+function AnimatedComponent() {
+  const prefersReducedMotion = window.matchMedia(
+    "(prefers-reduced-motion: reduce)",
+  ).matches;
+
+  return (
+    <motion.div
+      animate={{ opacity: 1 }}
+      transition={{ duration: prefersReducedMotion ? 0 : 0.3 }}
+    />
+  );
+}
+```
+
+## Best Practices
+
+1. **Performance First**: Use `transform` and `opacity` for smooth 60fps
+2. **Reduce Motion Support**: Always respect `prefers-reduced-motion`
+3. **Consistent Timing**: Use a timing scale across the app
+4. **Natural Physics**: Prefer spring animations over linear
+5. **Interruptible**: Allow users to cancel long animations
+6. **Progressive Enhancement**: Work without JS animations
+7. **Test on Devices**: Performance varies significantly
+
+## Common Issues
+
+- **Janky Animations**: Avoid animating `width`, `height`, `top`, `left`
+- **Over-animation**: Too much motion causes fatigue
+- **Blocking Interactions**: Never prevent user input during animations
+- **Memory Leaks**: Clean up animation listeners on unmount
+- **Flash of Content**: Use `will-change` sparingly for optimization
+
+## Resources
+
+- [Framer Motion Documentation](https://www.framer.com/motion/)
+- [CSS Animation Guide](https://web.dev/animations-guide/)
+- [Material Design Motion](https://m3.material.io/styles/motion/overview)
+- [GSAP Animation Library](https://greensock.com/gsap/)