picasso-skill 2.0.0 → 2.0.2

package/references/micro-interactions.md

@@ -0,0 +1,291 @@
+# Micro-Interactions Reference
+
+## Table of Contents
+1. Scroll-Triggered Animations
+2. Page Transitions
+3. Button and Press Feedback
+4. Toggle and Switch Animations
+5. Number and Text Morphing
+6. Magnetic and Cursor Effects
+7. Gesture-Based Interactions
+8. Animation Performance Budget
+9. Common Mistakes
+
+---
+
+## 1. Scroll-Triggered Animations
+
+Use IntersectionObserver. Never `addEventListener('scroll')` — it fires on every pixel and destroys performance.
+
+```js
+const observer = new IntersectionObserver((entries) => {
+  entries.forEach(entry => {
+    if (entry.isIntersecting) {
+      entry.target.classList.add('revealed');
+      observer.unobserve(entry.target); // animate once
+    }
+  });
+}, { threshold: 0.15, rootMargin: '0px 0px -50px 0px' });
+
+document.querySelectorAll('.reveal-on-scroll').forEach(el => observer.observe(el));
+```
+
+```css
+.reveal-on-scroll {
+  opacity: 0;
+  transform: translateY(20px);
+  transition: opacity 0.5s var(--ease-out), transform 0.5s var(--ease-out);
+}
+.reveal-on-scroll.revealed {
+  opacity: 1;
+  transform: translateY(0);
+}
+```
+
+Parallax: max 10% speed difference. More than that causes motion sickness.
+
+```css
+.parallax-slow { transform: translateY(calc(var(--scroll-y) * -0.05)); }
+```
+
+---
+
+## 2. Page Transitions
+
+View Transitions API for smooth page-to-page navigation:
+
+```css
+::view-transition-old(root) {
+  animation: fade-out 200ms ease-in forwards;
+}
+::view-transition-new(root) {
+  animation: fade-in 300ms ease-out forwards;
+}
+
+@keyframes fade-out { to { opacity: 0; } }
+@keyframes fade-in { from { opacity: 0; } }
+```
+
+```js
+// In Next.js App Router or SPA
+if (document.startViewTransition) {
+  document.startViewTransition(() => {
+    // Update DOM here
+  });
+}
+```
+
+Shared element transitions for items that persist between pages:
+
+```css
+.product-image { view-transition-name: product-hero; }
+
+::view-transition-old(product-hero),
+::view-transition-new(product-hero) {
+  animation-duration: 300ms;
+}
+```
+
+---
+
+## 3. Button and Press Feedback
+
+Combine scale + shadow reduction for a physical "press" feel:
+
+```css
+.btn {
+  transition: transform 80ms ease-out, box-shadow 80ms ease-out;
+}
+.btn:active {
+  transform: scale(0.97);
+  box-shadow: 0 1px 2px oklch(0 0 0 / 0.1); /* shadow shrinks on press */
+}
+```
+
+For icon buttons, use a radial ripple:
+
+```css
+.icon-btn {
+  position: relative;
+  overflow: hidden;
+}
+.icon-btn::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: radial-gradient(circle at var(--x, 50%) var(--y, 50%), oklch(1 0 0 / 0.1) 0%, transparent 60%);
+  opacity: 0;
+  transition: opacity 150ms;
+}
+.icon-btn:active::after { opacity: 1; }
+```
+
+---
+
+## 4. Toggle and Switch Animations
+
+```css
+.toggle-track {
+  width: 44px;
+  height: 24px;
+  border-radius: 12px;
+  background: var(--surface-3);
+  transition: background-color 200ms ease-out;
+  position: relative;
+}
+.toggle-track[aria-checked="true"] {
+  background: var(--accent);
+}
+.toggle-thumb {
+  width: 20px;
+  height: 20px;
+  border-radius: 50%;
+  background: white;
+  position: absolute;
+  top: 2px;
+  left: 2px;
+  transition: transform 200ms var(--ease-out);
+  box-shadow: 0 1px 3px oklch(0 0 0 / 0.15);
+}
+.toggle-track[aria-checked="true"] .toggle-thumb {
+  transform: translateX(20px);
+}
+```
+
+Checkbox checkmark: draw with SVG stroke-dasharray animation (150ms).
+
+---
+
+## 5. Number and Text Morphing
+
+For counters and changing text, use `torph` or CSS counter animation:
+
+```css
+@property --num {
+  syntax: '<integer>';
+  initial-value: 0;
+  inherits: false;
+}
+.counter {
+  transition: --num 1s ease-out;
+  counter-reset: num var(--num);
+}
+.counter::after {
+  content: counter(num);
+}
+```
+
+For text morphing between labels (e.g., tab switching):
+
+```jsx
+import { TextMorph } from 'torph/react';
+
+<TextMorph>{activeTab === 'overview' ? 'Overview' : 'Details'}</TextMorph>
+```
+
+---
+
+## 6. Magnetic and Cursor Effects
+
+Subtle magnetic pull toward buttons/links. Max displacement: 8px. Only on desktop (no hover on mobile).
+
+```js
+// Apply to elements with data-magnetic
+document.querySelectorAll('[data-magnetic]').forEach(el => {
+  el.addEventListener('mousemove', (e) => {
+    const rect = el.getBoundingClientRect();
+    const x = e.clientX - rect.left - rect.width / 2;
+    const y = e.clientY - rect.top - rect.height / 2;
+    el.style.transform = `translate(${x * 0.15}px, ${y * 0.15}px)`;
+  });
+  el.addEventListener('mouseleave', () => {
+    el.style.transform = '';
+    el.style.transition = 'transform 0.3s var(--ease-out)';
+  });
+});
+```
+
+Custom cursor (use sparingly — only for creative/portfolio sites):
+
+```css
+.custom-cursor {
+  cursor: none;
+}
+.cursor-dot {
+  width: 8px; height: 8px;
+  background: var(--accent);
+  border-radius: 50%;
+  position: fixed;
+  pointer-events: none;
+  z-index: 9999;
+  transition: transform 0.1s;
+  mix-blend-mode: difference;
+}
+```
+
+---
+
+## 7. Gesture-Based Interactions
+
+Mobile gestures require `touch-action` CSS to prevent browser defaults:
+
+```css
+/* Horizontal swipe area — disable horizontal scroll */
+.swipe-container { touch-action: pan-y; }
+
+/* Pinch-to-zoom area */
+.zoomable { touch-action: manipulation; }
+```
+
+Swipe detection (vanilla, no library):
+
+```js
+let startX = 0;
+el.addEventListener('touchstart', e => { startX = e.touches[0].clientX; });
+el.addEventListener('touchend', e => {
+  const diff = e.changedTouches[0].clientX - startX;
+  if (Math.abs(diff) > 50) { // 50px threshold
+    diff > 0 ? onSwipeRight() : onSwipeLeft();
+  }
+});
+```
+
+Gesture discoverability: NEVER rely on hidden gestures. Always provide a visible button alternative. Swipe should be a shortcut, not the only way.
+
+---
+
+## 8. Animation Performance Budget
+
+- **Max 3 concurrent animations** on screen at once. More causes frame drops on mid-range devices.
+- **Only animate `transform` and `opacity`** — these are compositor-only and skip layout/paint.
+- **Use `will-change` sparingly** — add before animation starts, remove after. Never `will-change: all`.
+- **16ms frame budget** — if your animation JS takes more than 16ms per frame, it drops below 60fps.
+- **Test with CPU throttling** — Chrome DevTools → Performance → CPU 6x slowdown. If it stutters there, it stutters on real phones.
+
+```css
+/* Good: compositor-only */
+.animate-enter {
+  will-change: transform, opacity;
+  animation: slide-in 300ms var(--ease-out) forwards;
+}
+.animate-enter.done { will-change: auto; } /* remove after animation */
+
+@keyframes slide-in {
+  from { opacity: 0; transform: translateY(10px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+```
+
+---
+
+## 9. Common Mistakes
+
+- **`addEventListener('scroll')` for animations.** Use IntersectionObserver.
+- **Animating `width`, `height`, `top`, `left`.** Triggers layout. Use `transform` only.
+- **More than 3 concurrent animations.** Causes jank on real devices.
+- **`will-change` on everything.** Creates a compositing layer per element. Memory hog.
+- **Parallax with large speed differences.** Max 10% or users get motion sick.
+- **Hidden gestures with no visible alternative.** Users won't discover them.
+- **No `prefers-reduced-motion` check.** Wrap all non-essential motion in the media query.
+- **Magnetic effects on mobile.** No hover on touch devices. Gate with `@media (hover: hover)`.
+- **Page transitions without fallback.** View Transitions API isn't universal. Always provide a no-transition fallback.

package/references/navigation-patterns.md

@@ -0,0 +1,247 @@
+# Navigation Patterns Reference
+
+## Table of Contents
+1. Breadcrumb Systems
+2. Sidebar and Drawer Navigation
+3. Tab Navigation vs Button Groups
+4. Mobile Bottom Bar vs Hamburger
+5. Sticky Headers
+6. Mega Menus
+7. Skip Links
+8. Common Mistakes
+
+---
+
+## 1. Breadcrumb Systems
+
+```html
+<nav aria-label="Breadcrumb">
+  <ol class="flex items-center gap-1.5 text-sm">
+    <li><a href="/" class="text-muted hover:text-primary">Home</a></li>
+    <li aria-hidden="true" class="text-muted">/</li>
+    <li><a href="/products" class="text-muted hover:text-primary">Products</a></li>
+    <li aria-hidden="true" class="text-muted">/</li>
+    <li><span aria-current="page" class="text-primary font-medium">Widget Pro</span></li>
+  </ol>
+</nav>
+```
+
+Rules:
+- Use `<nav aria-label="Breadcrumb">` with `<ol>` (ordered list).
+- Mark current page with `aria-current="page"`. Don't make it a link.
+- Separator (`/` or `>`) gets `aria-hidden="true"`.
+- Show 3-5 levels max. Truncate middle levels with `...` on mobile.
+
+---
+
+## 2. Sidebar and Drawer Navigation
+
+Desktop: fixed sidebar, 240-280px width. Mobile: off-canvas drawer with overlay.
+
+```jsx
+<aside className={`fixed inset-y-0 left-0 w-[260px] bg-surface-1 border-r border-border
+  transform transition-transform duration-200 z-50
+  ${mobileOpen ? 'translate-x-0' : '-translate-x-full'} md:translate-x-0`}>
+  <nav aria-label="Main navigation">
+    {/* nav items */}
+  </nav>
+</aside>
+
+{/* Mobile overlay */}
+{mobileOpen && (
+  <div className="fixed inset-0 bg-black/50 z-40 md:hidden"
+    onClick={() => setMobileOpen(false)} />
+)}
+```
+
+Active state: use background tint + accent color text, not bold weight (weight change shifts text width).
+
+```css
+.nav-item { padding: 7px 12px; border-radius: 6px; transition: background 100ms; }
+.nav-item:hover { background: oklch(1 0 0 / 0.04); }
+.nav-item.active { background: oklch(0.65 0.15 230 / 0.1); color: var(--accent); }
+```
+
+Section labels: 10px, uppercase, `tracking-[0.12em]`, muted color. Group related items visually.
+
+---
+
+## 3. Tab Navigation vs Button Groups
+
+**Tabs:** switch between views of the SAME content. One is always active. Use `role="tablist"`.
+
+```html
+<div role="tablist" aria-label="Account sections">
+  <button role="tab" aria-selected="true" aria-controls="panel-profile" id="tab-profile">
+    Profile
+  </button>
+  <button role="tab" aria-selected="false" aria-controls="panel-billing" id="tab-billing">
+    Billing
+  </button>
+</div>
+<div role="tabpanel" id="panel-profile" aria-labelledby="tab-profile">
+  <!-- content -->
+</div>
+```
+
+**Button groups:** trigger independent ACTIONS. Multiple can be active (toggle group) or none.
+
+```html
+<div role="group" aria-label="View options">
+  <button aria-pressed="true">Grid</button>
+  <button aria-pressed="false">List</button>
+</div>
+```
+
+Decision: if clicking switches what you see → tabs. If clicking does something → button group.
+
+---
+
+## 4. Mobile Bottom Bar vs Hamburger
+
+Bottom bar outperforms hamburger for engagement. Hamburger hides navigation behind a tap, reducing discoverability.
+
+**When to use bottom bar:**
+- 3-5 primary destinations
+- Mobile-first app (not marketing site)
+- User needs to switch between sections frequently
+
+**When to use hamburger:**
+- 6+ navigation items
+- Marketing/content site with hierarchical nav
+- Secondary navigation (settings, help)
+
+```css
+.bottom-bar {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  height: 56px; /* 48px min for touch, 56px comfortable */
+  padding-bottom: env(safe-area-inset-bottom); /* notch-safe */
+  display: flex;
+  justify-content: space-around;
+  align-items: center;
+  background: var(--surface-1);
+  border-top: 1px solid var(--border);
+  z-index: 50;
+}
+
+.bottom-bar-item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 2px;
+  min-width: 64px;
+  padding: 4px 12px;
+  font-size: 10px;
+}
+```
+
+---
+
+## 5. Sticky Headers
+
+Keep slim: 48-56px height. Hide on scroll-down, reveal on scroll-up.
+
+```js
+let lastScroll = 0;
+const header = document.querySelector('header');
+
+window.addEventListener('scroll', () => {
+  const current = window.scrollY;
+  if (current > lastScroll && current > 80) {
+    header.style.transform = 'translateY(-100%)';
+  } else {
+    header.style.transform = 'translateY(0)';
+  }
+  lastScroll = current;
+}, { passive: true });
+```
+
+```css
+header {
+  position: sticky;
+  top: 0;
+  height: 56px;
+  z-index: 40;
+  backdrop-filter: blur(12px);
+  background: oklch(var(--bg-l) var(--bg-c) var(--bg-h) / 0.8);
+  border-bottom: 1px solid var(--border);
+  transition: transform 200ms ease-out;
+}
+```
+
+---
+
+## 6. Mega Menus
+
+For sites with 20+ navigation items. Two approaches:
+
+**Full-width panel** (preferred): Flyout spans full viewport width. Organized in columns.
+
+```css
+.mega-menu {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  padding: 2rem;
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: 2rem;
+  background: var(--surface-1);
+  border-top: 1px solid var(--border);
+  box-shadow: var(--shadow-lg);
+}
+```
+
+**Alternatives to mega menus:**
+- Search-first navigation (Command+K palette)
+- Two-level sidebar (category → items)
+- Card-based navigation page
+
+Keep mega menu hover delay at 200-300ms to prevent accidental opens.
+
+---
+
+## 7. Skip Links
+
+First focusable element on the page. Visually hidden until focused.
+
+```html
+<a href="#main-content" class="skip-link">Skip to main content</a>
+<!-- header, nav, etc -->
+<main id="main-content" tabindex="-1">
+```
+
+```css
+.skip-link {
+  position: absolute;
+  top: -100%;
+  left: 1rem;
+  z-index: 100;
+  padding: 0.5rem 1rem;
+  background: var(--accent);
+  color: white;
+  border-radius: 0 0 8px 8px;
+  font-weight: 600;
+}
+.skip-link:focus {
+  top: 0;
+}
+```
+
+---
+
+## 8. Common Mistakes
+
+- **Hamburger as the only mobile navigation.** Bottom bar is better for primary destinations.
+- **Active nav state using `font-weight: bold`.** Shifts text width. Use background/color instead.
+- **Sidebar over 300px wide.** Steals too much screen. 240-280px is ideal.
+- **Sticky header over 64px.** Takes too much vertical space. 48-56px max.
+- **No `aria-current="page"` on breadcrumbs.** Screen readers can't identify current page.
+- **Tabs without `role="tablist"`/`role="tab"`.** Not accessible.
+- **Mega menu without hover delay.** Opens accidentally when moving mouse across nav.
+- **No skip link.** Keyboard users must tab through entire header to reach content.
+- **Bottom bar without `safe-area-inset-bottom`.** Content hides behind iPhone notch.