picasso-skill 1.5.1 → 2.0.0

package/references/interaction-design.md

@@ -0,0 +1,162 @@
+# 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/modern-css-performance.md

@@ -0,0 +1,361 @@
+# Modern CSS & Web Performance Reference
+
+## 1. Modern CSS Features (2024-2025)
+
+### CSS Nesting (Baseline 2024)
+Native nesting eliminates preprocessor dependency.
+
+```css
+.card {
+  padding: 1rem;
+  > h2:first-child { margin-block-start: 0; }
+  &:hover { box-shadow: 0 4px 12px rgb(0 0 0 / 0.1); }
+  @media (width >= 768px) { padding: 2rem; }
+}
+```
+
+### Cascade Layers (@layer)
+Control specificity ordering without selector wars.
+
+```css
+@layer reset, base, components, utilities;
+@layer reset { *, *::before, *::after { box-sizing: border-box; margin: 0; } }
+@layer base { body { font-family: system-ui; line-height: 1.6; } }
+@layer components { .btn { padding: 0.5rem 1rem; border-radius: 0.375rem; } }
+```
+
+### :has() Selector
+Style parents based on children.
+
+```css
+form:has(:invalid) { border-color: red; }
+.card:has(img) { grid-template-rows: auto 1fr; }
+body:has(dialog[open]) { overflow: hidden; }
+```
+
+### CSS Anchor Positioning
+Position elements relative to other elements without JS.
+
+```css
+.trigger { anchor-name: --tooltip-anchor; }
+.tooltip {
+  position: absolute;
+  position-anchor: --tooltip-anchor;
+  top: anchor(bottom);
+  left: anchor(center);
+  translate: -50% 0.5rem;
+}
+```
+
+### @scope
+Restrict styles to a DOM subtree with optional lower boundary.
+
+```css
+@scope (.card) to (.card-content) {
+  h2 { font-size: 1.25rem; font-weight: 600; }
+  p { color: var(--muted); }
+}
+```
+
+### @property (Typed Custom Properties)
+Register custom properties with type, initial value, and inheritance. Enables animating custom properties.
+
+```css
+@property --gradient-angle {
+  syntax: "<angle>";
+  initial-value: 0deg;
+  inherits: false;
+}
+.gradient-border {
+  --gradient-angle: 0deg;
+  border-image: conic-gradient(from var(--gradient-angle), #f06, #9f6, #06f) 1;
+  animation: spin 3s linear infinite;
+}
+@keyframes spin { to { --gradient-angle: 360deg; } }
+```
+
+### color-mix()
+Blend colors in any color space at runtime.
+
+```css
+.button {
+  --brand: oklch(0.65 0.25 260);
+  background: var(--brand);
+  &:hover { background: color-mix(in oklch, var(--brand) 85%, white); }
+  &:active { background: color-mix(in oklch, var(--brand) 80%, black); }
+}
+```
+
+### Logical Properties
+Write direction-agnostic layouts (LTR/RTL safe).
+
+Key mappings: `margin-left` -> `margin-inline-start`, `padding-top` -> `padding-block-start`, `width` -> `inline-size`, `height` -> `block-size`.
+
+```css
+.sidebar { margin-inline-end: 2rem; padding-block: 1rem; border-inline-start: 3px solid var(--accent); }
+```
+
+### Subgrid
+Child grids align to parent grid tracks.
+
+```css
+.grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 1rem; }
+.grid > .card {
+  display: grid;
+  grid-row: span 3;
+  grid-template-rows: subgrid;
+}
+```
+
+### Popover API
+Native popovers with light-dismiss, no JS required.
+
+```html
+<button popovertarget="info">Info</button>
+<div popover id="info">Content here. Click outside to dismiss.</div>
+```
+
+```css
+[popover] {
+  &::backdrop { background: rgb(0 0 0 / 0.25); }
+  opacity: 0; transition: opacity 0.2s, display 0.2s allow-discrete;
+  &:popover-open { opacity: 1; }
+}
+```
+
+---
+
+## 2. Core Web Vitals Optimization
+
+**Thresholds:** LCP < 2.5s | CLS < 0.1 | INP < 200ms
+
+### LCP (Largest Contentful Paint)
+- Preload hero images: `<link rel="preload" as="image" href="hero.webp" fetchpriority="high">`
+- Use `fetchpriority="high"` on the LCP `<img>` element.
+- Eliminate render-blocking CSS/JS; inline critical CSS.
+- Use CDN, compress with Brotli.
+
+### CLS (Cumulative Layout Shift)
+- Always set `width`/`height` or `aspect-ratio` on images and video.
+- Reserve space for ads/embeds with `min-height`.
+- Use `font-display: optional` (best CLS) or `swap` (best UX).
+- Avoid inserting content above the fold after load.
+
+### INP (Interaction to Next Paint)
+Replaced FID in March 2024. Measures all interactions across the page lifecycle.
+
+```js
+button.addEventListener('click', () => {
+  button.classList.add('pressed');       // instant visual feedback
+  requestAnimationFrame(() => {
+    setTimeout(() => doHeavyWork(), 0);  // yield to browser
+  });
+});
+```
+
+- Break long tasks with `scheduler.yield()` (or `setTimeout(0)` fallback).
+- Use `content-visibility: auto` for off-screen DOM.
+- Avoid layout thrashing: batch reads, then batch writes.
+
+---
+
+## 3. Image Optimization
+
+| Format | Best For | vs JPEG |
+|--------|----------|---------|
+| **AVIF** | Photos, complex images | ~50% smaller |
+| **WebP** | Photos, transparency | ~30% smaller |
+| **SVG** | Icons, logos, illustrations | Infinitely scalable |
+| **PNG** | Screenshots, pixel-precise | Lossless only |
+
+### Responsive Images Pattern
+
+```html
+<picture>
+  <source srcset="hero.avif" type="image/avif">
+  <source srcset="hero.webp" type="image/webp">
+  <img src="hero.jpg"
+    srcset="hero-400.jpg 400w, hero-800.jpg 800w, hero-1200.jpg 1200w"
+    sizes="(max-width: 600px) 100vw, (max-width: 1200px) 50vw, 33vw"
+    alt="Hero" width="1200" height="675"
+    loading="lazy" decoding="async">
+</picture>
+```
+
+**Rules:** Never lazy-load above-the-fold images (hurts LCP). Use `fetchpriority="high"` on LCP image. Always include `width`/`height` for CLS prevention.
+
+### Blur-Up Placeholder
+
+```css
+.img-placeholder {
+  background: url('data:image/webp;base64,...') center/cover;
+  aspect-ratio: 16/9;
+}
+.img-placeholder img {
+  opacity: 0; transition: opacity 0.3s;
+  &.loaded { opacity: 1; }
+}
+```
+
+---
+
+## 4. Font Performance
+
+### Optimal Loading Strategy
+
+```html
+<link rel="preload" href="/fonts/display.woff2" as="font" type="font/woff2" crossorigin>
+```
+
+```css
+@font-face {
+  font-family: 'Display';
+  src: url('/fonts/display.woff2') format('woff2');
+  font-weight: 100 900;
+  font-display: swap;
+  unicode-range: U+0000-00FF;
+}
+```
+
+### font-display Decision Guide
+- **`swap`**: shows fallback immediately, swaps when loaded. Best for body text. Causes FOUT.
+- **`optional`**: uses web font only if cached/instant. Best CLS score.
+- **`fallback`**: 100ms blank, then fallback, short swap window. Good compromise.
+- **`block`**: up to 3s invisible text (FOIT). Avoid for body text.
+
+### Variable Fonts
+One file replaces multiple weight/style files. Use when you need 3+ weights. A single variable font (~90KB) replaces 6 static files (360KB+).
+
+### Subsetting
+Strip unused glyphs with `pyftsubset` or `glyphhanger`. Can reduce 200KB+ files to 15-30KB.
+
+---
+
+## 5. Critical CSS & Resource Hints
+
+### Critical CSS Pattern
+
+```html
+<head>
+  <style>/* inlined above-the-fold styles, ~14KB max */</style>
+  <link rel="preload" href="/styles.css" as="style" onload="this.rel='stylesheet'">
+  <noscript><link rel="stylesheet" href="/styles.css"></noscript>
+</head>
+```
+
+### Resource Hints
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="dns-prefetch" href="https://analytics.example.com">
+<link rel="preload" href="/critical.woff2" as="font" crossorigin>
+<link rel="prefetch" href="/next-page.js">
+<link rel="modulepreload" href="/app.js">
+```
+
+**Build tools:** Use `critical` (npm) or `critters` (webpack/vite plugin) to auto-extract above-fold CSS at build time.
+
+---
+
+## 6. Tailwind CSS v4
+
+Released January 2025. Core rewritten in Rust (Oxide engine). Full builds 3.8x faster, incremental rebuilds up to 182x faster.
+
+### CSS-First Configuration
+
+```css
+@import "tailwindcss";
+
+@theme {
+  --color-brand: oklch(0.65 0.25 260);
+  --font-display: "Satoshi", sans-serif;
+  --breakpoint-3xl: 1920px;
+  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
+}
+```
+
+No `tailwind.config.js` needed. All customization lives in CSS via `@theme`.
+
+### Key Changes
+- **Automatic content detection** -- scans files, respects `.gitignore`.
+- **Built on `@layer`, `@property`, `color-mix()`**.
+- **Container queries** built in: `@sm:`, `@md:` variants.
+- **3D transforms**: `rotate-x-45 transform-3d perspective-distant`.
+- **`@starting-style`** support for enter/exit transitions with `transition-discrete`.
+- **`not-*` variant**: `not-hover:opacity-75`, `not-last:border-b`.
+
+---
+
+## 7. Advanced Animation APIs
+
+### View Transitions API
+
+```css
+@view-transition { navigation: auto; }
+.hero-image { view-transition-name: hero; }
+::view-transition-old(hero) { animation: fade-out 0.3s ease-out; }
+::view-transition-new(hero) { animation: fade-in 0.3s ease-in; }
+```
+
+```js
+document.startViewTransition(() => updateDOM());
+```
+
+### Scroll-Driven Animations (No JS, Off Main Thread)
+
+```css
+.progress-bar {
+  animation: grow-width linear;
+  animation-timeline: scroll();
+}
+@keyframes grow-width { from { width: 0; } to { width: 100%; } }
+
+.reveal {
+  animation: fade-slide-up linear both;
+  animation-timeline: view();
+  animation-range: entry 0% entry 100%;
+}
+@keyframes fade-slide-up {
+  from { opacity: 0; translate: 0 2rem; }
+  to { opacity: 1; translate: 0; }
+}
+```
+
+### Web Animations API (WAAPI)
+
+```js
+element.animate(
+  [{ transform: 'translateY(0)', opacity: 1 },
+   { transform: 'translateY(-20px)', opacity: 0 }],
+  { duration: 300, easing: 'ease-out', fill: 'forwards' }
+);
+```
+
+### GSAP ScrollTrigger
+
+```js
+gsap.to('.hero-title', {
+  scrollTrigger: {
+    trigger: '.hero', start: 'top top', end: 'bottom top',
+    scrub: true, pin: true
+  },
+  y: -100, opacity: 0, scale: 0.9
+});
+```
+
+---
+
+## Browser Support (Baseline 2025)
+
+| Feature | Chrome | Firefox | Safari |
+|---------|--------|---------|--------|
+| CSS Nesting | 120+ | 117+ | 17.2+ |
+| :has() | 105+ | 121+ | 15.4+ |
+| @layer | 99+ | 97+ | 15.4+ |
+| Subgrid | 117+ | 71+ | 16+ |
+| Anchor Positioning | 125+ | Nightly | No |
+| View Transitions (SPA) | 111+ | 144+ | 18+ |
+| Scroll-driven Animations | 115+ | Nightly | No |
+| Popover API | 114+ | 125+ | 17+ |
+| @property | 85+ | 128+ | 15.4+ |
+| color-mix() | 111+ | 113+ | 16.2+ |