picasso-skill 1.0.0 → 1.2.0

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

package/references/motion-and-animation.md

@@ -1,260 +0,0 @@
-# Motion and Animation Reference
-
-## Table of Contents
-1. Principles
-2. Easing Functions
-3. Duration Guidelines
-4. Staggered Reveals
-5. Scroll-Triggered Animation
-6. Text Morphing
-7. Micro-Interactions
-8. Reduced Motion
-9. Common Mistakes
-
----
-
-## 1. Principles
-
-Motion serves three purposes: feedback (confirming an action), orientation (showing where something went), and delight (making the interface feel alive). If an animation does not serve one of these, remove it.
-
-### Priority of Animation Investment
-1. Page load choreography (highest impact, seen by everyone)
-2. State transitions (tabs, modals, accordions)
-3. Hover/focus states
-4. Scroll-triggered reveals
-5. Loading states and skeletons
-6. Micro-interactions (button press effects, toggle animations)
-
-Invest time in this order. A well-choreographed page load does more than fifty micro-interactions.
-
----
-
-## 2. Easing Functions
-
-### Use These
-```css
-/* Standard ease-out: elements arriving */
---ease-out: cubic-bezier(0.16, 1, 0.3, 1);
-
-/* Standard ease-in: elements departing */
---ease-in: cubic-bezier(0.55, 0.085, 0.68, 0.53);
-
-/* Standard ease-in-out: elements transforming in place */
---ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
-
-/* Spring-like (subtle): natural deceleration */
---ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
-```
-
-### Never Use
-- `linear` for UI animations (looks mechanical)
-- `ease` (the CSS default is mediocre)
-- `bounce` / elastic easing (looks dated and gimmicky)
-- Spring animations with visible oscillation (too playful for most UIs)
-
----
-
-## 3. Duration Guidelines
-
-| Type | Duration | Why |
-|---|---|---|
-| Hover state change | 100-150ms | Must feel instant |
-| Button press | 80-120ms | Tactile response |
-| Tooltip appear | 150-200ms | Quick but not jarring |
-| Fade in/out | 150-250ms | Smooth perception |
-| Slide/expand | 200-350ms | Visible movement |
-| Page transition | 300-500ms | Substantial change |
-| Complex choreography | 400-800ms total | Entrance sequence |
-
-Rule of thumb: if the user is waiting for it, it should be fast (under 200ms). If the user is watching it, it can be slower (200-500ms).
-
----
-
-## 4. Staggered Reveals
-
-The most impactful animation pattern. Elements enter one after another with increasing delay.
-
-### CSS-Only Pattern
-```css
-.reveal-item {
-  opacity: 0;
-  transform: translateY(12px);
-  animation: reveal 0.5s var(--ease-out) forwards;
-}
-
-@keyframes reveal {
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
-
-.reveal-item:nth-child(1) { animation-delay: 0ms; }
-.reveal-item:nth-child(2) { animation-delay: 60ms; }
-.reveal-item:nth-child(3) { animation-delay: 120ms; }
-.reveal-item:nth-child(4) { animation-delay: 180ms; }
-.reveal-item:nth-child(5) { animation-delay: 240ms; }
-```
-
-### Key Parameters
-- **Stagger interval**: 40-80ms between items (shorter for many items, longer for few)
-- **Translate distance**: 8-16px (subtle is better)
-- **Do not stagger more than 6-8 items**. After that, group them.
-
-### React with Motion Library
-```jsx
-import { motion } from "framer-motion";
-
-const container = {
-  hidden: {},
-  show: { transition: { staggerChildren: 0.06 } }
-};
-
-const item = {
-  hidden: { opacity: 0, y: 12 },
-  show: { opacity: 1, y: 0, transition: { duration: 0.5, ease: [0.16, 1, 0.3, 1] } }
-};
-```
-
----
-
-## 5. Scroll-Triggered Animation
-
-### CSS-Only with Scroll-Driven Animations
-```css
-@keyframes fade-in {
-  from { opacity: 0; transform: translateY(20px); }
-  to { opacity: 1; transform: translateY(0); }
-}
-
-.scroll-reveal {
-  animation: fade-in linear both;
-  animation-timeline: view();
-  animation-range: entry 0% entry 30%;
-}
-```
-
-### Intersection Observer Pattern
-```js
-const observer = new IntersectionObserver(
-  (entries) => {
-    entries.forEach(entry => {
-      if (entry.isIntersecting) {
-        entry.target.classList.add('visible');
-        observer.unobserve(entry.target);
-      }
-    });
-  },
-  { threshold: 0.15, rootMargin: '0px 0px -50px 0px' }
-);
-
-document.querySelectorAll('.animate-on-scroll').forEach(el => observer.observe(el));
-```
-
----
-
-## 6. Text Morphing
-
-For animated text transitions (changing labels, counters, status updates), use **Torph** (dependency-free).
-
-### Installation
-```
-npm i torph
-```
-
-### Usage
-```jsx
-import { TextMorph } from 'torph/react';
-
-// Automatically animates between text values
-<TextMorph>{status}</TextMorph>
-
-// Works with any dynamic text
-<button>
-  <TextMorph>{isLoading ? "Processing..." : `Buy for $${price}`}</TextMorph>
-</button>
-```
-
-Torph morphs individual characters with smooth enter/exit animations. It works with React, Vue, Svelte, and vanilla TypeScript.
-
-### When to Use
-- Tab labels that change on selection
-- Button text that updates (Add to Cart -> Added!)
-- Counter values that increment
-- Status indicators that cycle through states
-- Any text that changes in response to user action
-
----
-
-## 7. Micro-Interactions
-
-### Button Press
-```css
-button:active {
-  transform: scale(0.97);
-  transition: transform 80ms var(--ease-in);
-}
-```
-
-### Toggle Switch
-Animate the knob position and background color simultaneously. The knob should arrive slightly before the color finishes changing.
-
-### Checkbox
-Scale the checkmark from 0 to 1 with a slight overshoot:
-```css
-.checkbox-mark {
-  transform: scale(0);
-  transition: transform 200ms cubic-bezier(0.34, 1.56, 0.64, 1);
-}
-.checkbox:checked .checkbox-mark {
-  transform: scale(1);
-}
-```
-
-### Skeleton Loading
-Shimmer from left to right using a gradient animation:
-```css
-.skeleton {
-  background: linear-gradient(90deg,
-    var(--surface-2) 25%,
-    var(--surface-3) 50%,
-    var(--surface-2) 75%
-  );
-  background-size: 200% 100%;
-  animation: shimmer 1.5s infinite;
-}
-@keyframes shimmer {
-  0% { background-position: 200% 0; }
-  100% { background-position: -200% 0; }
-}
-```
-
----
-
-## 8. Reduced Motion
-
-Always respect the user's motion preference:
-```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;
-  }
-}
-```
-
-This does not mean removing all visual feedback. Opacity changes (fades) are still acceptable. Remove translation, scaling, and rotation animations.
-
----
-
-## 9. Common Mistakes
-
-- Animating everything on the page (creates visual noise, reduces perceived performance)
-- Using `animation-duration: 0` for reduced motion (some browsers behave unexpectedly; use 0.01ms)
-- Bounce/elastic easing on UI elements (acceptable only in game-like or toy-like contexts)
-- Animating layout properties (width, height, top, left) instead of transforms (causes layout thrashing)
-- Forgetting `will-change` on frequently animated elements (or overusing it on everything)
-- Staggering 20+ items with visible delays (group them or animate the container)
-- Using `transition: all 0.3s` (animates properties you did not intend; be explicit about which properties to transition)

package/references/react-patterns.md

@@ -1,216 +0,0 @@
-# React Patterns Reference
-
-## Table of Contents
-1. Component Architecture
-2. State Management
-3. Performance
-4. Composition Patterns
-5. Data Fetching
-6. Styling
-7. Common Mistakes
-
----
-
-## 1. Component Architecture
-
-### Server vs. Client Components
-Default to Server Components. Add `'use client'` only when the component needs:
-- Event handlers (onClick, onChange, etc.)
-- useState, useEffect, useRef, or other hooks
-- Browser APIs (window, document, navigator)
-- Third-party libraries that use hooks or browser APIs
-
-### File Organization
-Colocate related files. Keep components, styles, tests, and types in the same directory:
-```
-components/
-  user-card/
-    user-card.tsx
-    user-card.test.tsx
-    user-card.module.css
-    types.ts
-```
-
-### Naming
-- Components: PascalCase (`UserCard`, `DashboardHeader`)
-- Files: kebab-case (`user-card.tsx`, `dashboard-header.tsx`)
-- Hooks: camelCase with `use` prefix (`useAuth`, `useMediaQuery`)
-- Event handlers: `handle` + event (`handleClick`, `handleSubmit`)
-- Boolean props: `is`/`has`/`should` prefix (`isLoading`, `hasError`)
-
-### Export Patterns
-- **Default export**: page/route components and layout components
-- **Named export**: everything else (utilities, hooks, shared components)
-
----
-
-## 2. State Management
-
-### Where State Lives
-1. **URL state**: filters, pagination, search queries (use `searchParams`)
-2. **Server state**: data from APIs (use React Query, SWR, or server components)
-3. **Local state**: form inputs, UI toggles, hover/focus state (use `useState`)
-4. **Shared local state**: state needed by siblings (lift to parent, or use context)
-5. **Global state**: rarely needed (auth user, theme preference, feature flags)
-
-### Rules
-- Do not store derived state. Compute it during render.
-- Do not sync state between sources. Pick one source of truth.
-- Prefer `useReducer` over `useState` when the next state depends on the previous state or when managing more than 3 related state variables.
-
-```tsx
-// Bad: storing derived state
-const [items, setItems] = useState(data);
-const [filteredItems, setFilteredItems] = useState([]);
-useEffect(() => {
-  setFilteredItems(items.filter(i => i.active));
-}, [items]);
-
-// Good: compute during render
-const [items, setItems] = useState(data);
-const filteredItems = items.filter(i => i.active);
-```
-
----
-
-## 3. Performance
-
-### Rendering
-- Use `React.memo` only for components that re-render often with the same props
-- Use `useMemo` for expensive computations, not for every variable
-- Use `useCallback` for callbacks passed to memoized children
-- Use `key` props correctly (stable, unique identifiers, never array indices for reorderable lists)
-
-### Code Splitting
-```tsx
-import dynamic from 'next/dynamic';
-
-const Chart = dynamic(() => import('./chart'), {
-  loading: () => <ChartSkeleton />,
-  ssr: false,
-});
-```
-
-### Virtualization
-For lists with 100+ items, use `react-window` or `@tanstack/virtual`:
-```tsx
-import { FixedSizeList } from 'react-window';
-
-<FixedSizeList height={600} itemCount={items.length} itemSize={48} width="100%">
-  {({ index, style }) => <Row style={style} item={items[index]} />}
-</FixedSizeList>
-```
-
-### Image Optimization
-Use `next/image` in Next.js or `loading="lazy"` with explicit `width`/`height` attributes. Always set `aspect-ratio` to prevent layout shift.
-
----
-
-## 4. Composition Patterns
-
-### Compound Components
-Components that share implicit state through context:
-```tsx
-<Select value={value} onChange={setValue}>
-  <Select.Trigger>Choose a fruit</Select.Trigger>
-  <Select.Content>
-    <Select.Item value="apple">Apple</Select.Item>
-    <Select.Item value="banana">Banana</Select.Item>
-  </Select.Content>
-</Select>
-```
-
-### Slot Pattern
-Flexible component composition through named children:
-```tsx
-function Card({ header, children, footer }) {
-  return (
-    <div className="card">
-      {header && <div className="card-header">{header}</div>}
-      <div className="card-body">{children}</div>
-      {footer && <div className="card-footer">{footer}</div>}
-    </div>
-  );
-}
-```
-
-### Render Props (when needed)
-For components that need to share behavior, not UI:
-```tsx
-<DataFetcher url="/api/users">
-  {({ data, isLoading }) => isLoading ? <Skeleton /> : <UserList users={data} />}
-</DataFetcher>
-```
-
----
-
-## 5. Data Fetching
-
-### Server Components (preferred)
-```tsx
-async function UserList() {
-  const users = await fetch('/api/users').then(r => r.json());
-  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
-}
-```
-
-### Client-Side with Suspense
-```tsx
-function Dashboard() {
-  return (
-    <Suspense fallback={<DashboardSkeleton />}>
-      <DashboardContent />
-    </Suspense>
-  );
-}
-```
-
-### Error Boundaries
-Wrap data-fetching components in error boundaries:
-```tsx
-<ErrorBoundary fallback={<ErrorMessage />}>
-  <Suspense fallback={<Skeleton />}>
-    <DataComponent />
-  </Suspense>
-</ErrorBoundary>
-```
-
----
-
-## 6. Styling
-
-### Tailwind Best Practices
-- Use Tailwind's core utility classes (pre-defined classes only in Claude artifacts)
-- Extract repeated patterns into component variants, not `@apply` rules
-- Use CSS variables for theme values, Tailwind utilities for everything else
-- Never use more than ~10 utility classes on a single element; extract a component instead
-
-### CSS Modules
-For non-Tailwind projects:
-```tsx
-import styles from './button.module.css';
-<button className={styles.primary}>Click</button>
-```
-
-### Semantic HTML
-Use the right element, not just `div` with classes:
-- `<nav>` for navigation
-- `<main>` for primary content
-- `<section>` for thematic grouping
-- `<article>` for self-contained content
-- `<aside>` for tangentially related content
-- `<header>` and `<footer>` for their semantic purpose
-- `<button>` for clickable actions, `<a>` for navigation
-
----
-
-## 7. Common Mistakes
-
-- Using `useEffect` for derived state (compute during render instead)
-- Putting everything in global state (most state should be local or server-derived)
-- Using `index` as `key` for dynamic lists
-- Wrapping every component in `React.memo`
-- Using `any` in TypeScript (defeats the purpose of type safety)
-- Fetching data in `useEffect` when a server component would suffice
-- Not using Suspense boundaries (the whole page flashes instead of parts loading independently)
-- Prop drilling through 5+ levels (use composition or context)