@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/animation-patterns.md

@@ -0,0 +1,224 @@
+---
+name: animation-patterns
+description: Animation patterns with CSS transitions, Framer Motion, GSAP, reduced-motion support, and performance optimization.
+---
+
+# Animation Patterns
+
+## When to Use
+Apply when animations serve a purpose: guiding attention, showing state changes, indicating loading, or providing feedback. Never animate just for decoration. Every animation should answer "what does this help the user understand?"
+
+## How It Works
+
+### CSS Transitions -- The Default Choice
+
+Use CSS transitions for simple state changes. They are hardware-accelerated, require no JavaScript, and are the most performant option:
+
+```css
+/* Only animate transform and opacity (GPU-composited) */
+.card {
+  transition: transform 200ms ease-out, opacity 200ms ease-out;
+}
+.card:hover {
+  transform: translateY(-4px);
+  opacity: 0.95;
+}
+
+/* Meaningful easing -- not everything should be linear */
+:root {
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);      /* entering */
+  --ease-in: cubic-bezier(0.7, 0, 0.84, 0);        /* exiting */
+  --ease-in-out: cubic-bezier(0.87, 0, 0.13, 1);   /* moving */
+  --spring: cubic-bezier(0.34, 1.56, 0.64, 1);     /* playful bounce */
+}
+
+.modal {
+  transition: transform 300ms var(--ease-out), opacity 300ms var(--ease-out);
+}
+.modal[data-state="closed"] { transform: translateY(16px); opacity: 0; }
+.modal[data-state="open"] { transform: translateY(0); opacity: 1; }
+```
+
+### Framer Motion -- React Animation Library
+
+Use for complex React animations: layout transitions, gesture-driven, and orchestrated sequences:
+
+```tsx
+import { motion, AnimatePresence } from "framer-motion";
+
+// Enter/exit animations
+function Toast({ message, onClose }: ToastProps) {
+  return (
+    <AnimatePresence>
+      {message && (
+        <motion.div
+          initial={{ opacity: 0, y: 50, scale: 0.95 }}
+          animate={{ opacity: 1, y: 0, scale: 1 }}
+          exit={{ opacity: 0, y: 20, scale: 0.95 }}
+          transition={{ type: "spring", damping: 25, stiffness: 300 }}
+        >
+          {message}
+          <button onClick={onClose}>Dismiss</button>
+        </motion.div>
+      )}
+    </AnimatePresence>
+  );
+}
+
+// Layout animations -- elements smoothly reflow when order changes
+function SortableList({ items }: { items: Item[] }) {
+  return (
+    <ul>
+      {items.map((item) => (
+        <motion.li key={item.id} layout transition={{ type: "spring", damping: 30 }}>
+          {item.name}
+        </motion.li>
+      ))}
+    </ul>
+  );
+}
+
+// Staggered children -- list items enter one by one
+const container = {
+  hidden: {},
+  visible: { transition: { staggerChildren: 0.05 } },
+};
+const item = {
+  hidden: { opacity: 0, y: 20 },
+  visible: { opacity: 1, y: 0 },
+};
+
+<motion.ul variants={container} initial="hidden" animate="visible">
+  {items.map((i) => (
+    <motion.li key={i.id} variants={item}>{i.name}</motion.li>
+  ))}
+</motion.ul>
+```
+
+### GSAP -- Complex Timelines
+
+Use for scroll-triggered sequences, SVG morphing, or animations needing precise timeline control:
+
+```typescript
+import { gsap } from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+
+gsap.registerPlugin(ScrollTrigger);
+
+// Timeline -- orchestrate multiple elements
+const tl = gsap.timeline({ defaults: { duration: 0.6, ease: "power3.out" } });
+tl.from(".hero-title", { y: 60, opacity: 0 })
+  .from(".hero-subtitle", { y: 40, opacity: 0 }, "-=0.3")
+  .from(".hero-cta", { scale: 0.9, opacity: 0 }, "-=0.2");
+
+// Scroll-triggered animation
+gsap.from(".feature-card", {
+  scrollTrigger: {
+    trigger: ".features-section",
+    start: "top 80%",
+    toggleActions: "play none none reverse",
+  },
+  y: 60,
+  opacity: 0,
+  stagger: 0.15,
+  duration: 0.8,
+});
+```
+
+### CSS Scroll-Driven Animations
+
+Native CSS scroll-driven animations -- no JavaScript, maximum performance:
+
+```css
+/* Progress bar tied to scroll position */
+.scroll-progress {
+  position: fixed;
+  top: 0;
+  left: 0;
+  height: 3px;
+  background: var(--brand);
+  transform-origin: left;
+  animation: grow-bar linear;
+  animation-timeline: scroll();
+}
+@keyframes grow-bar {
+  from { transform: scaleX(0); }
+  to { transform: scaleX(1); }
+}
+
+/* Fade in on scroll using view() timeline */
+.reveal {
+  animation: fade-in linear both;
+  animation-timeline: view();
+  animation-range: entry 0% entry 100%;
+}
+@keyframes fade-in {
+  from { opacity: 0; transform: translateY(30px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+```
+
+### Reduced Motion
+
+Respect user preferences. Some users experience motion sickness from animations:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+```tsx
+import { useReducedMotion } from "framer-motion";
+
+function AnimatedCard({ children }: PropsWithChildren) {
+  const prefersReduced = useReducedMotion();
+  return (
+    <motion.div
+      initial={prefersReduced ? false : { opacity: 0, y: 20 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={prefersReduced ? { duration: 0 } : { type: "spring" }}
+    >
+      {children}
+    </motion.div>
+  );
+}
+```
+
+### Performance Rules
+
+```
+DO animate:  transform, opacity (composited, GPU-accelerated)
+AVOID:       width, height, top, left, margin (trigger layout recalculation)
+CAUTION:     box-shadow, clip-path, filter (trigger paint, OK in small doses)
+
+- Keep UI feedback under 300ms, transitions under 500ms
+- 60fps = 16.6ms per frame budget
+- Avoid animating more than 2 properties simultaneously on mobile
+```
+
+## Examples
+
+| Need | Tool | Why |
+|------|------|-----|
+| Button hover effect | CSS transition | Zero JS, 2 lines |
+| Modal enter/exit | Framer Motion AnimatePresence | Handles mount/unmount |
+| List reorder | Framer Motion layout | Auto-detects position changes |
+| Landing page scroll reveal | GSAP ScrollTrigger | Frame-perfect scroll sync |
+| Scroll progress bar | CSS `animation-timeline: scroll()` | Zero JS, native perf |
+| Page transition | Framer Motion + AnimatePresence | Smooth SPA transitions |
+
+## Checklist
+- [ ] Only transform and opacity animated for 60fps performance
+- [ ] `prefers-reduced-motion` respected with instant or no animation
+- [ ] Animations have clear purpose (feedback, attention, state change)
+- [ ] Duration 150-300ms for interactions, up to 500ms for transitions
+- [ ] Easing matches intent (ease-out for enter, ease-in for exit)
+- [ ] No layout-triggering properties animated
+- [ ] AnimatePresence wraps conditionally rendered animated elements
+- [ ] Tested on low-end Android devices

package/assets/skills/api-design.md

@@ -0,0 +1,218 @@
+---
+name: api-design
+description: Design consistent, predictable REST APIs with proper resource naming, pagination, errors, and versioning.
+---
+
+# REST API Design
+
+## When to Use
+
+Apply these patterns when designing any HTTP API — public or internal. Consistent
+API design reduces integration friction, prevents breaking changes, and makes
+your API self-documenting. Decide these conventions before writing the first
+endpoint, not after shipping twenty.
+
+## How It Works
+
+### 1. Resource Naming
+
+Use plural nouns for collections. Nest only one level deep.
+
+```
+GET    /users              → list users
+POST   /users              → create user
+GET    /users/:id          → get user
+PATCH  /users/:id          → partial update
+DELETE /users/:id          → delete user
+GET    /users/:id/orders   → list orders for user
+```
+
+Avoid: verbs in URLs (`/getUser`), deep nesting (`/users/:id/orders/:oid/items/:iid`),
+inconsistent pluralization.
+
+For actions that don't map to CRUD, use a sub-resource verb:
+
+```
+POST /users/:id/deactivate
+POST /orders/:id/refund
+```
+
+### 2. Pagination
+
+Always paginate list endpoints. Use cursor-based pagination for large or
+frequently changing datasets.
+
+```
+GET /users?cursor=eyJpZCI6MTAwfQ&limit=25
+
+{
+  "data": [...],
+  "pagination": {
+    "next_cursor": "eyJpZCI6MTI1fQ",
+    "has_more": true,
+    "limit": 25
+  }
+}
+```
+
+For simpler use cases, offset pagination works:
+
+```
+GET /users?page=3&per_page=25
+
+{
+  "data": [...],
+  "pagination": {
+    "page": 3,
+    "per_page": 25,
+    "total": 237,
+    "total_pages": 10
+  }
+}
+```
+
+### 3. Filtering and Sorting
+
+Use query parameters. Keep operators simple.
+
+```
+GET /orders?status=pending&created_after=2025-01-01&sort=-created_at&limit=50
+```
+
+Conventions:
+- `-` prefix means descending: `sort=-created_at`
+- Comma-separated for multiple sort fields: `sort=-priority,created_at`
+- Use `_after`, `_before` suffixes for date ranges
+- Use `q` for full-text search: `?q=typescript`
+
+### 4. Error Responses
+
+Return a consistent error envelope with machine-readable codes.
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      {
+        "field": "email",
+        "code": "INVALID_FORMAT",
+        "message": "Must be a valid email address"
+      },
+      {
+        "field": "age",
+        "code": "OUT_OF_RANGE",
+        "message": "Must be between 13 and 150"
+      }
+    ]
+  }
+}
+```
+
+Status code mapping:
+| Code | Use |
+|------|-----|
+| 400 | Validation errors, malformed request |
+| 401 | Missing or invalid authentication |
+| 403 | Authenticated but not authorized |
+| 404 | Resource not found |
+| 409 | Conflict (duplicate, state violation) |
+| 422 | Semantically invalid (parseable but wrong) |
+| 429 | Rate limited |
+| 500 | Server error (never leak stack traces) |
+
+### 5. Versioning
+
+Use URL path versioning for simplicity and cache-friendliness.
+
+```
+/api/v1/users
+/api/v2/users
+```
+
+Rules:
+- Additive changes (new fields, new endpoints) do NOT require a new version
+- Removing or renaming fields, changing types, altering behavior: new version
+- Support previous version for at least 6 months after deprecation notice
+- Return `Deprecation` and `Sunset` headers on deprecated versions
+
+### 6. HATEOAS — Hypermedia Links
+
+Include links to related resources and available actions.
+
+```json
+{
+  "data": {
+    "id": "usr_abc123",
+    "name": "Alice",
+    "email": "alice@example.com",
+    "_links": {
+      "self": "/api/v1/users/usr_abc123",
+      "orders": "/api/v1/users/usr_abc123/orders",
+      "deactivate": "/api/v1/users/usr_abc123/deactivate"
+    }
+  }
+}
+```
+
+At minimum, include `self` on every resource. Add action links for discoverable
+workflows.
+
+### 7. Rate Limiting Headers
+
+```
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 742
+X-RateLimit-Reset: 1700000000
+Retry-After: 30
+```
+
+### 8. Idempotency
+
+Support `Idempotency-Key` header for non-idempotent operations (POST).
+
+```
+POST /api/v1/payments
+Idempotency-Key: req_abc123
+
+→ First call: creates payment, stores result keyed to req_abc123
+→ Retry with same key: returns stored result, no duplicate payment
+```
+
+## Examples
+
+```typescript
+// Express router following these patterns
+router.get('/api/v1/orders', authenticate, async (req, res) => {
+  const { cursor, limit = 25, status, sort = '-created_at' } = req.query;
+
+  const orders = await orderService.list({
+    cursor: cursor as string,
+    limit: Math.min(Number(limit), 100),
+    filter: { status: status as string },
+    sort: parseSort(sort as string),
+  });
+
+  res.json({
+    data: orders.items.map(toOrderResponse),
+    pagination: {
+      next_cursor: orders.nextCursor,
+      has_more: orders.hasMore,
+      limit: orders.limit,
+    },
+  });
+});
+```
+
+## Checklist
+
+- [ ] All endpoints use plural nouns, no verbs in URLs
+- [ ] Every list endpoint is paginated with documented default and max limits
+- [ ] Error responses use a consistent envelope with `code`, `message`, `details`
+- [ ] API version is in the URL path (`/api/v1/`)
+- [ ] Rate limit headers are present on every response
+- [ ] POST endpoints accept `Idempotency-Key` for safe retries
+- [ ] Sorting uses `-field` convention for descending
+- [ ] No stack traces or internal details leak in production error responses
+- [ ] 401 vs 403 is correctly distinguished (authentication vs authorization)