picasso-skill 2.5.0 → 2.6.1

package/references/animation-performance.md

@@ -1,244 +0,0 @@
-# Animation Performance Reference
-
-## Table of Contents
-1. Compositor-Only Properties
-2. Will-Change Best Practices
-3. Layout Thrashing
-4. IntersectionObserver vs Scroll Events
-5. Web Animations API
-6. Performance Measurement
-7. Testing on Low-End Devices
-8. Contain Property
-9. Common Mistakes
-
----
-
-## 1. Compositor-Only Properties
-
-Only two CSS properties can be animated without triggering layout or paint: **transform** and **opacity**. Everything else causes reflow.
-
-| Property | Layout | Paint | Composite | Animate? |
-|---|---|---|---|---|
-| `transform` | No | No | Yes | **Yes** |
-| `opacity` | No | No | Yes | **Yes** |
-| `filter` | No | Yes | Yes | Carefully |
-| `background-color` | No | Yes | No | Avoid |
-| `width`, `height` | Yes | Yes | No | **Never** |
-| `top`, `left` | Yes | Yes | No | **Never** |
-| `margin`, `padding` | Yes | Yes | No | **Never** |
-| `border-radius` | No | Yes | No | Avoid |
-
-```css
-/* Good: compositor-only */
-.slide-in {
-  transform: translateX(-100%);
-  opacity: 0;
-  transition: transform 300ms var(--ease-out), opacity 300ms var(--ease-out);
-}
-.slide-in.active {
-  transform: translateX(0);
-  opacity: 1;
-}
-
-/* Bad: triggers layout on every frame */
-.slide-in-bad {
-  left: -100%;
-  transition: left 300ms ease;
-}
-```
-
----
-
-## 2. Will-Change Best Practices
-
-`will-change` promotes an element to its own compositor layer. This speeds up animation but consumes GPU memory.
-
-Rules:
-- Add `will-change` BEFORE the animation starts (e.g., on hover, not in the animation itself).
-- Remove it AFTER the animation completes.
-- Never use `will-change: all` — it promotes everything.
-- Never apply it to more than 10 elements simultaneously.
-- Don't put it in your stylesheet permanently.
-
-```js
-// Good: apply before, remove after
-element.addEventListener('mouseenter', () => {
-  element.style.willChange = 'transform';
-});
-element.addEventListener('transitionend', () => {
-  element.style.willChange = 'auto';
-});
-```
-
-```css
-/* Acceptable: for elements that are ALWAYS animated (e.g., loading spinners) */
-.spinner { will-change: transform; }
-
-/* Bad: permanent will-change on static elements */
-.card { will-change: transform, opacity; } /* don't do this */
-```
-
----
-
-## 3. Layout Thrashing
-
-Reading layout properties then writing them in a loop forces the browser to recalculate layout on every iteration.
-
-```js
-// BAD: layout thrashing (read-write-read-write)
-elements.forEach(el => {
-  const height = el.offsetHeight;    // READ — forces layout
-  el.style.height = height + 10 + 'px'; // WRITE — invalidates layout
-});
-
-// GOOD: batch reads, then batch writes
-const heights = elements.map(el => el.offsetHeight); // all reads first
-elements.forEach((el, i) => {
-  el.style.height = heights[i] + 10 + 'px'; // all writes after
-});
-```
-
-Properties that trigger forced layout when read: `offsetHeight`, `offsetWidth`, `getBoundingClientRect()`, `scrollTop`, `clientHeight`, `getComputedStyle()`.
-
----
-
-## 4. IntersectionObserver vs Scroll Events
-
-| | `scroll` event | IntersectionObserver |
-|---|---|---|
-| Performance | Fires every pixel, blocks main thread | Async, fires on threshold crossing |
-| Throttling | Manual (requestAnimationFrame) | Built-in |
-| Use case | Scroll-linked animation (position) | Visibility detection (enter/exit) |
-| Recommendation | Almost never | Almost always |
-
-```js
-// Good: IntersectionObserver for reveal animations
-const observer = new IntersectionObserver(
-  (entries) => {
-    entries.forEach(entry => {
-      entry.target.classList.toggle('visible', entry.isIntersecting);
-    });
-  },
-  { threshold: 0.1 }
-);
-```
-
-For scroll-linked animations where you need exact scroll position, use the Scroll-Driven Animations API:
-
-```css
-@keyframes fade-in {
-  from { opacity: 0; transform: translateY(20px); }
-  to { opacity: 1; transform: translateY(0); }
-}
-
-.scroll-reveal {
-  animation: fade-in linear;
-  animation-timeline: view();
-  animation-range: entry 0% entry 100%;
-}
-```
-
----
-
-## 5. Web Animations API
-
-For complex JS-driven animations, use WAAPI instead of manual `requestAnimationFrame`:
-
-```js
-element.animate(
-  [
-    { transform: 'translateY(20px)', opacity: 0 },
-    { transform: 'translateY(0)', opacity: 1 }
-  ],
-  {
-    duration: 300,
-    easing: 'cubic-bezier(0.16, 1, 0.3, 1)',
-    fill: 'forwards'
-  }
-);
-```
-
-Benefits over CSS: programmable, cancellable, can read progress, can reverse.
-
----
-
-## 6. Performance Measurement
-
-```js
-// Measure animation frame rate
-let frames = 0;
-let lastTime = performance.now();
-
-function countFrames() {
-  frames++;
-  const now = performance.now();
-  if (now - lastTime >= 1000) {
-    console.log(`FPS: ${frames}`);
-    frames = 0;
-    lastTime = now;
-  }
-  requestAnimationFrame(countFrames);
-}
-requestAnimationFrame(countFrames);
-```
-
-Chrome DevTools:
-1. Performance tab → Record → interact with animations → Stop
-2. Look for long frames (> 16ms) in the flame chart
-3. Rendering tab → Paint flashing (green = repaint, should be minimal)
-4. Rendering tab → Layer borders (orange = composited layers)
-
-Target: 60fps = 16.67ms per frame. If ANY frame takes > 33ms, users perceive jank.
-
----
-
-## 7. Testing on Low-End Devices
-
-Your M-series Mac is not representative. Test with:
-- **Chrome DevTools CPU throttling:** Performance tab → CPU → 6x slowdown
-- **Network throttling:** Slow 3G preset to test loading animations
-- **Real device:** Test on a 3-year-old Android phone if possible
-
-If an animation stutters at 6x CPU throttle, reduce:
-1. Number of concurrent animations
-2. Element count being animated
-3. Complexity of each animation
-
----
-
-## 8. Contain Property
-
-`contain` tells the browser what NOT to recalculate when an element changes.
-
-```css
-/* Isolate layout/paint to this element */
-.card {
-  contain: layout paint;
-}
-
-/* Full isolation — best for off-screen or independent components */
-.widget {
-  contain: strict; /* = size + layout + paint + style */
-}
-
-/* Content containment — layout + paint + style (most common) */
-.list-item {
-  contain: content;
-}
-```
-
-Use `contain: content` on repeated elements (list items, cards) to prevent layout changes from propagating to siblings.
-
----
-
-## 9. Common Mistakes
-
-- **Animating `width`/`height`/`top`/`left`.** Use `transform: translate/scale` instead.
-- **`will-change` on everything.** Max 10 elements. Remove after animation completes.
-- **`addEventListener('scroll')` for visibility.** Use IntersectionObserver.
-- **Reading layout properties in animation loops.** Batch reads before writes.
-- **Testing only on fast hardware.** Use Chrome CPU throttling at 6x.
-- **No frame budget awareness.** 16ms per frame. If your JS takes 20ms, you drop frames.
-- **CSS `transition: all`.** Transitions every property including layout triggers.
-- **Forgetting `contain` on repeated elements.** One card's layout change recalculates the entire list.
-- **`requestAnimationFrame` without cancellation.** Always store the ID and `cancelAnimationFrame` on cleanup.

package/references/interaction-design.md

@@ -1,162 +0,0 @@
-# Interaction Design Reference
-
-## Table of Contents
-1. Form Design
-2. Focus Management
-3. Loading Patterns
-4. Empty States
-5. Error Handling
-6. UX Writing
-7. Common Mistakes
-
----
-
-## 1. Form Design
-
-### Input Fields
-- Use visible labels above inputs, not placeholder-only labels (placeholders disappear on focus)
-- Input height: 40-48px for desktop, 48px minimum for touch
-- Group related fields visually (name + email, street + city + zip)
-- Show validation inline, not in an alert after submission
-- Use `inputmode` attribute for mobile keyboards: `inputmode="email"`, `inputmode="numeric"`, `inputmode="tel"`
-- Auto-focus the first field on page load when the form is the primary task
-
-### Field States
-Every input needs four visible states:
-1. **Default**: subtle border, neutral background
-2. **Focus**: accent border (2px), subtle glow or shadow
-3. **Error**: error-colored border, inline error message below the field
-4. **Disabled**: reduced opacity (0.5), `cursor: not-allowed`
-
-### Buttons
-- Primary action: filled, high contrast (accent color)
-- Secondary action: outlined or ghost (border only)
-- Destructive action: red/error color, requires confirmation for irreversible actions
-- Button text: verb-first ("Save changes", "Create project"), never "Submit" or "Click here"
-- Loading state: replace text with spinner or use `aria-busy="true"`, disable the button to prevent double-submission
-
----
-
-## 2. Focus Management
-
-### Focus Indicators
-Never remove focus outlines without replacement. Use a visible, high-contrast focus ring:
-```css
-:focus-visible {
-  outline: 2px solid var(--accent);
-  outline-offset: 2px;
-}
-```
-
-Use `:focus-visible` (not `:focus`) to show focus rings only for keyboard navigation, not mouse clicks.
-
-### Focus Trapping
-Modal dialogs must trap focus within them. When a modal opens:
-1. Move focus to the first focusable element inside
-2. Tab cycles within the modal
-3. Escape closes the modal
-4. Focus returns to the trigger element on close
-
-### Skip Links
-Add a skip-to-content link as the first focusable element:
-```html
-<a href="#main-content" class="skip-link">Skip to content</a>
-```
-```css
-.skip-link {
-  position: absolute;
-  top: -100%;
-  left: 0;
-}
-.skip-link:focus {
-  top: 0;
-  z-index: 1000;
-}
-```
-
----
-
-## 3. Loading Patterns
-
-### Skeleton Screens
-Replace content with gray shapes that match the expected layout. This feels faster than a spinner because the user can see the structure forming.
-
-### Progressive Loading
-Show content as it arrives. Do not wait for everything to load before showing anything. Use `Suspense` boundaries in React to show parts of the page while others load.
-
-### Optimistic Updates
-For user-initiated actions (like, save, delete), update the UI immediately and reconcile with the server response. Show a subtle undo option if the server rejects the action.
-
-### Spinner vs. Skeleton
-- **Spinner**: Use for actions that take 1-3 seconds (button submissions, API calls). Place inside the triggering element.
-- **Skeleton**: Use for content areas that take 0.5-5 seconds to load. Match the shape of the expected content.
-- **Progress bar**: Use for operations that take 5+ seconds with measurable progress (file uploads, multi-step processes).
-
----
-
-## 4. Empty States
-
-Empty states are an opportunity, not a placeholder. They should:
-1. Explain what this area will contain once populated
-2. Provide a clear action to get started
-3. Optionally include an illustration or icon for warmth
-
-```
-No projects yet.
-Create your first project to get started.
-[+ Create Project]
-```
-
-Never show a blank page, an error message, or raw "null" / "undefined" in place of empty content.
-
----
-
-## 5. Error Handling
-
-### Inline Errors
-Show errors next to the element that caused them, not in a modal or toast. Use the error color for the field border and display the message directly below.
-
-### Error Messages
-- Be specific: "Email address must include an @ symbol" not "Invalid input"
-- Be helpful: suggest the fix, not just the problem
-- Be human: "We couldn't find that page" not "404 Not Found"
-
-### Network Errors
-Show a non-blocking banner or inline message with a retry action. Never show a raw error object or stack trace.
-
-### Form Validation
-Validate on blur (when the user leaves a field), not on every keystroke. Show success indicators for valid fields (subtle checkmark or green border).
-
----
-
-## 6. UX Writing
-
-### Buttons
-- Use action verbs: "Save", "Send", "Create", "Delete"
-- Be specific: "Save changes" > "Save", "Send message" > "Send"
-- Match the action to the context: "Place order" not "Submit"
-
-### Labels
-- Clear and concise: "Full name" not "Please enter your full name"
-- Avoid jargon: "Phone number" not "Primary contact number"
-
-### Confirmations
-- State what happened: "Project created successfully"
-- Provide next step if relevant: "Project created. Add your first task?"
-
-### Destructive Actions
-- State what will happen: "This will permanently delete 3 files"
-- Require explicit confirmation: "Type DELETE to confirm"
-- Provide an out: "Cancel" should be more prominent than "Delete"
-
----
-
-## 7. Common Mistakes
-
-- Placeholder text as the only label (disappears on focus, inaccessible)
-- Disabling the submit button before all fields are filled (users do not know which field is missing)
-- Using toast notifications for errors (the user may not see them, they disappear)
-- No loading feedback after clicking a button (user clicks again, causing duplicate submissions)
-- Custom scrollbars that break native scroll behavior
-- Hover-only interactions with no keyboard or touch equivalent
-- Alert/confirm dialogs that block the entire page for minor confirmations