picasso-skill 1.0.0 → 1.2.0

package/references/responsive-design.md

@@ -1,118 +0,0 @@
-# Responsive Design Reference
-
-## 1. Breakpoints
-
-Use content-driven breakpoints, not device-driven. These are sensible defaults:
-
-```css
-/* Mobile first: no media query = mobile */
-/* Small tablets / large phones */
-@media (min-width: 640px) { }
-/* Tablets / small laptops */
-@media (min-width: 768px) { }
-/* Laptops / desktops */
-@media (min-width: 1024px) { }
-/* Large desktops */
-@media (min-width: 1280px) { }
-/* Ultrawide */
-@media (min-width: 1536px) { }
-```
-
-## 2. Mobile-First Approach
-
-Start with the mobile layout (single column, stacked). Add complexity at wider breakpoints. This ensures the core experience works everywhere before enhancements.
-
-```css
-/* Base: single column */
-.grid { display: grid; gap: 1rem; }
-
-/* Tablet: two columns */
-@media (min-width: 768px) {
-  .grid { grid-template-columns: repeat(2, 1fr); }
-}
-
-/* Desktop: three columns */
-@media (min-width: 1024px) {
-  .grid { grid-template-columns: repeat(3, 1fr); }
-}
-```
-
-## 3. Fluid Design
-
-Use `clamp()` for font sizes, padding, and gaps that scale smoothly:
-
-```css
-.container {
-  padding: clamp(1rem, 4vw, 3rem);
-  max-width: 1200px;
-  margin: 0 auto;
-}
-h1 {
-  font-size: clamp(1.75rem, 4vw + 0.5rem, 3.5rem);
-}
-```
-
-## 4. Container Queries
-
-For component-level responsiveness (when the component's width, not the viewport, should determine layout):
-
-```css
-.card-container {
-  container-type: inline-size;
-}
-@container (min-width: 400px) {
-  .card { display: grid; grid-template-columns: 1fr 2fr; }
-}
-```
-
-## 5. Touch Targets
-
-Minimum touch target: 44x44px (WCAG) or 48x48px (Material). Apply to all interactive elements on mobile. If the visual element is smaller, use padding or `::before` pseudo-element to extend the hit area.
-
-```css
-.icon-button {
-  position: relative;
-  width: 24px;
-  height: 24px;
-}
-.icon-button::before {
-  content: '';
-  position: absolute;
-  inset: -12px; /* extends tap area to 48x48 */
-}
-```
-
-## 6. Responsive Typography
-
-Do not just shrink everything on mobile. Adjust the type scale:
-- Mobile: use a smaller ratio (1.2) with a 15-16px base
-- Desktop: use a larger ratio (1.25-1.333) with a 16-18px base
-- Headings should scale more aggressively than body text
-
-## 7. Navigation Patterns
-
-- **Mobile (< 768px)**: Hamburger menu, bottom tab bar, or slide-out drawer
-- **Tablet (768-1024px)**: Collapsed sidebar or icon-only navigation
-- **Desktop (> 1024px)**: Full sidebar, top navigation bar, or mega-menu
-
-## 8. Images
-
-Use `srcset` and `sizes` for responsive images. Use `loading="lazy"` for below-the-fold images. Set `aspect-ratio` to prevent layout shift:
-
-```css
-img {
-  width: 100%;
-  height: auto;
-  aspect-ratio: 16 / 9;
-  object-fit: cover;
-}
-```
-
-## 9. Common Mistakes
-
-- Hiding too much content on mobile (users expect the same information, just reorganized)
-- Using `vw` units for text without a `clamp()` minimum (becomes unreadable on small screens)
-- Horizontal scrolling on mobile (almost never acceptable)
-- Fixed-position elements that cover too much of the mobile viewport
-- Not testing at actual device widths (375px for iPhone SE, 390px for modern iPhones, 360px for Android)
-- Tables that overflow on mobile (use horizontal scroll wrapper or reformat as stacked cards)

package/references/sensory-design.md

@@ -1,125 +0,0 @@
-# Sensory Design Reference
-
-## Table of Contents
-1. UI Sound Design
-2. Haptic Feedback
-3. Multi-Sensory Integration
-
----
-
-## 1. UI Sound Design
-
-### Why Sound
-Sound provides confirmation that an action occurred, draws attention to important state changes, and adds personality to the interface. It is underused on the web but highly effective when applied with restraint.
-
-### The Soundcn Pattern
-Use inline base64 audio data URIs with the Web Audio API. This avoids external file loading, CORS issues, and runtime fetching. Each sound is a self-contained TypeScript module.
-
-```typescript
-// sounds/click-soft.ts
-export const clickSoftSound = "data:audio/wav;base64,UklGR..."; // base64 WAV
-
-// hooks/use-sound.ts
-import { useCallback, useRef } from 'react';
-
-export function useSound(src: string) {
-  const audioContextRef = useRef<AudioContext | null>(null);
-
-  const play = useCallback(() => {
-    if (!audioContextRef.current) {
-      audioContextRef.current = new AudioContext();
-    }
-    const ctx = audioContextRef.current;
-    fetch(src)
-      .then(r => r.arrayBuffer())
-      .then(buf => ctx.decodeAudioData(buf))
-      .then(decoded => {
-        const source = ctx.createBufferSource();
-        source.buffer = decoded;
-        source.connect(ctx.destination);
-        source.start(0);
-      });
-  }, [src]);
-
-  return [play] as const;
-}
-```
-
-### Usage
-```tsx
-import { useSound } from "@/hooks/use-sound";
-import { clickSoftSound } from "@/sounds/click-soft";
-
-function Button() {
-  const [play] = useSound(clickSoftSound);
-  return <button onClick={() => { play(); handleAction(); }}>Save</button>;
-}
-```
-
-### When to Use Sound
-- **Button clicks**: soft, short click sound (50-100ms)
-- **Success actions**: pleasant confirmation tone
-- **Notifications**: attention-getting but not alarming chime
-- **Errors**: subtle alert, not a harsh buzz
-- **Toggle switches**: satisfying mechanical click
-- **Transitions**: whoosh or swipe sound for page changes
-
-### Rules
-- Always provide a sound toggle in the UI (respect user preference)
-- Keep sounds under 200ms for UI interactions
-- Use the Web Audio API, not `<audio>` elements (lower latency)
-- Sound volume should be subtle by default (0.3-0.5 of max)
-- Never auto-play sounds on page load
-- Source sounds from CC0 collections (Kenney, Freesound)
-
----
-
-## 2. Haptic Feedback
-
-### The Vibration API
-```javascript
-// Check support
-if ('vibrate' in navigator) {
-  // Simple tap (10ms pulse)
-  navigator.vibrate(10);
-
-  // Success pattern (two short pulses)
-  navigator.vibrate([10, 50, 10]);
-
-  // Error pattern (one longer pulse)
-  navigator.vibrate(30);
-
-  // Warning (three quick pulses)
-  navigator.vibrate([10, 30, 10, 30, 10]);
-}
-```
-
-### When to Use Haptics
-- **Button press confirmation**: 10ms pulse on touch
-- **Toggle switch**: 10ms pulse on state change
-- **Destructive action confirmation**: 30ms pulse before confirmation dialog
-- **Pull-to-refresh threshold**: 10ms pulse when the threshold is reached
-- **Drag and drop**: 10ms pulse on pickup and drop
-
-### Rules
-- Gate behind feature detection (`'vibrate' in navigator`)
-- Respect `prefers-reduced-motion` by disabling haptics when motion is reduced
-- Keep durations very short (10-30ms for taps, never longer than 100ms)
-- Do not use haptics for every interaction, only pivotal moments
-- Mobile only: haptics have no effect on desktop
-
-### iOS Considerations
-The Vibration API has limited support on iOS Safari. For broader iOS support, use the experimental Haptic Feedback API or accept that haptics are Android-primary.
-
----
-
-## 3. Multi-Sensory Integration
-
-The strongest UI moments combine visual, auditory, and haptic feedback simultaneously:
-
-1. User taps "Complete" button
-2. **Visual**: checkmark animation scales in with a satisfying bounce
-3. **Sound**: soft success chime (100ms)
-4. **Haptic**: double-pulse pattern (10ms, 50ms gap, 10ms)
-
-This triple feedback creates a moment of certainty that a single visual change cannot match. Use it sparingly, for milestone moments (order placed, task completed, level achieved).

package/references/spatial-design.md

@@ -1,176 +0,0 @@
-# Spatial Design Reference
-
-## Table of Contents
-1. Spacing Scale
-2. Grid Systems
-3. Visual Hierarchy
-4. Whitespace
-5. Layout Patterns
-6. Common Mistakes
-
----
-
-## 1. Spacing Scale
-
-Use a consistent spacing scale based on a 4px unit. Never use arbitrary values like 13px or 7px.
-
-```css
-:root {
-  --space-1: 0.25rem;   /* 4px  - tight inline gaps */
-  --space-2: 0.5rem;    /* 8px  - icon-to-text, compact lists */
-  --space-3: 0.75rem;   /* 12px - form field padding */
-  --space-4: 1rem;      /* 16px - standard element spacing */
-  --space-5: 1.25rem;   /* 20px - card padding */
-  --space-6: 1.5rem;    /* 24px - section padding */
-  --space-8: 2rem;      /* 32px - group separation */
-  --space-10: 2.5rem;   /* 40px - major section gaps */
-  --space-12: 3rem;     /* 48px - large section spacing */
-  --space-16: 4rem;     /* 64px - page-level spacing */
-  --space-20: 5rem;     /* 80px - hero-level breathing room */
-  --space-24: 6rem;     /* 96px - dramatic separation */
-}
-```
-
-### When to Use Which Size
-- **1-2 (4-8px)**: Internal component spacing (icon + label, badge padding)
-- **3-4 (12-16px)**: Component padding, list item spacing
-- **5-6 (20-24px)**: Card padding, form group margins
-- **8-10 (32-40px)**: Section separation within a page
-- **12-16 (48-64px)**: Major content blocks, above/below fold
-- **20-24 (80-96px)**: Hero areas, page-level breathing room
-
----
-
-## 2. Grid Systems
-
-### CSS Grid Defaults
-```css
-.grid {
-  display: grid;
-  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
-  gap: var(--space-6);
-}
-```
-
-### 12-Column Grid
-For dashboard and editorial layouts:
-```css
-.page-grid {
-  display: grid;
-  grid-template-columns: repeat(12, 1fr);
-  gap: var(--space-6);
-  max-width: 1200px;
-  margin: 0 auto;
-  padding: 0 var(--space-6);
-}
-```
-
-### Asymmetric Grids
-For editorial and portfolio layouts, break the 12-column grid:
-```css
-.editorial-grid {
-  display: grid;
-  grid-template-columns: 2fr 1fr;  /* 2:1 ratio */
-  gap: var(--space-8);
-}
-.portfolio-grid {
-  display: grid;
-  grid-template-columns: 3fr 2fr;  /* golden-ish ratio */
-  gap: var(--space-6);
-}
-```
-
----
-
-## 3. Visual Hierarchy
-
-Hierarchy is established through size, weight, color, and space. Not all four at once. Pick two.
-
-### Hierarchy Techniques (in order of strength)
-1. **Size difference**: The fastest way to establish priority
-2. **Weight difference**: Bold vs. regular within the same size
-3. **Color contrast**: Primary vs. secondary text color
-4. **Spatial separation**: More space around important elements
-5. **Position**: Top-left gets seen first (in LTR languages)
-
-### Rules
-- If everything is bold, nothing is bold. Limit bold to headings and key data points.
-- If everything is the same size, the eye has nowhere to land. Vary size by at least 1.5x between hierarchy levels.
-- Use secondary/tertiary text colors for supporting information (timestamps, metadata, helper text).
-- Reduce visual weight of labels and increase weight of values in data-heavy UIs.
-
----
-
-## 4. Whitespace
-
-Whitespace is not wasted space. It is a design element.
-
-### Internal vs. External Spacing
-- **Internal**: Padding inside a component (card padding, button padding). Relates to the component's own content.
-- **External**: Margin between components. Relates to the component's relationship with siblings.
-
-### Gestalt Grouping
-Elements that are closer together are perceived as related. Use tighter spacing within groups and wider spacing between groups. The ratio between intra-group and inter-group spacing should be at least 2:1 (e.g., 8px within, 24px between).
-
-### Generous vs. Dense
-- **Generous**: Marketing pages, portfolios, editorial content. Use 80-120px between major sections.
-- **Dense**: Dashboards, admin panels, data tables. Use 16-32px between sections but maintain consistent rhythm.
-
----
-
-## 5. Layout Patterns
-
-### Centered Content
-Max-width container with auto margins. Standard max-widths: 640px (narrow/reading), 960px (medium), 1200px (wide), 1440px (ultrawide).
-
-### Sidebar + Main
-```css
-.layout {
-  display: grid;
-  grid-template-columns: 260px 1fr;
-  min-height: 100vh;
-}
-```
-
-### Sticky Header + Scrollable Content
-```css
-.header { position: sticky; top: 0; z-index: 10; }
-.main { overflow-y: auto; }
-```
-
-### Bento Grid
-Irregular grid with varied cell sizes:
-```css
-.bento {
-  display: grid;
-  grid-template-columns: repeat(4, 1fr);
-  grid-auto-rows: 200px;
-  gap: var(--space-4);
-}
-.bento .featured {
-  grid-column: span 2;
-  grid-row: span 2;
-}
-```
-
-### Overlap/Layer
-Elements that break out of the grid create visual tension:
-```css
-.overlap-element {
-  position: relative;
-  z-index: 2;
-  margin-top: -3rem;  /* pulls up into previous section */
-}
-```
-
----
-
-## 6. Common Mistakes
-
-- Using inconsistent spacing values (17px here, 23px there)
-- Centering everything on the page (creates a vertical highway with no anchor points)
-- Not using max-width on content (text that spans 1400px is unreadable)
-- Applying the same padding to all components regardless of their content
-- Putting too many items in a row on mobile (three columns at 375px is almost never right)
-- Using margin-top and margin-bottom on the same element (pick one direction, usually bottom, and stick with it throughout the project)
-- Neglecting the space between the last element and the container edge

package/references/typography.md

@@ -1,168 +0,0 @@
-# Typography Reference
-
-## Table of Contents
-1. Font Selection
-2. Type Scale
-3. Font Pairing
-4. Line Height and Spacing
-5. OpenType Features
-6. Pixel and Display Fonts
-7. Web Font Loading
-8. Common Mistakes
-
----
-
-## 1. Font Selection
-
-### Banned Defaults
-Never use these as primary typefaces: Inter, Roboto, Arial, Helvetica, system-ui, sans-serif (as the only declaration), Space Grotesk (overused in AI contexts), or any font that ships as a browser default.
-
-### Where to Find Good Fonts
-- Google Fonts: vast but requires curation. Sort by trending, not popular.
-- Bunny Fonts: privacy-friendly Google Fonts mirror.
-- Fontshare: free, high-quality fonts from Indian Type Foundry.
-- Atipo Foundry: distinctive display and text faces.
-- CDN: `https://fonts.cdnfonts.com` for broader selection.
-
-### Selection Criteria
-A good typeface for a project should:
-- Match the emotional register of the content (a legal dashboard should not use a playful rounded sans)
-- Have sufficient weight range (at minimum: regular, medium, bold)
-- Include tabular figures if displaying data
-- Support the required character sets
-- Feel distinct from the last 5 things you built
-
-### The Geist System
-Vercel's Geist family offers three complementary typefaces:
-- **Geist Sans**: clean, geometric sans for UI text
-- **Geist Mono**: monospaced for code and data
-- **Geist Pixel**: bitmap-inspired display font with 5 variants (Square, Grid, Circle, Triangle, Line), useful for banners, experimental layouts, and product moments where typography becomes part of the interface language
-
-Install via `npm i geist`. Each variant has its own CSS variable (e.g., `--font-geist-pixel-square`).
-
----
-
-## 2. Type Scale
-
-Use a modular scale. Pick a ratio and apply it consistently.
-
-| Ratio | Name | Use Case |
-|---|---|---|
-| 1.125 | Major Second | Dense data UIs, admin panels |
-| 1.200 | Minor Third | General purpose, balanced |
-| 1.250 | Major Third | Most common, works broadly |
-| 1.333 | Perfect Fourth | Editorial, generous spacing |
-| 1.500 | Perfect Fifth | Display-heavy, marketing |
-| 1.618 | Golden Ratio | High-impact landing pages |
-
-### Calculating Sizes
-Base size: 16px (1rem). Multiply up for headings, divide down for captions.
-
-```
-Caption:  0.75rem (12px)
-Small:    0.875rem (14px)
-Body:     1rem (16px)
-Large:    1.125rem (18px)
-H4:       1.25rem (20px)
-H3:       1.563rem (25px)
-H2:       1.953rem (31px)
-H1:       2.441rem (39px)
-Display:  3.052rem (49px)
-```
-
-For fluid type, use `clamp()`:
-```css
-h1 { font-size: clamp(2rem, 5vw + 1rem, 3.5rem); }
-```
-
----
-
-## 3. Font Pairing
-
-### Principles
-- Pair fonts with contrasting structures: a serif display with a sans body, or a geometric sans heading with a humanist sans body.
-- Never pair fonts that are too similar (two geometric sans faces will fight).
-- One display font is enough. Two is almost always too many.
-- The body font does the heavy lifting. It must be supremely readable at 16px.
-
-### Proven Pairs
-- **Display serif + sans body**: Playfair Display / Source Sans 3
-- **Geometric sans + humanist sans**: Outfit / Nunito Sans
-- **Slab + grotesque**: Zilla Slab / Work Sans
-- **Monospace accent + sans body**: JetBrains Mono / DM Sans
-- **Variable display + clean body**: Instrument Serif / Instrument Sans
-
----
-
-## 4. Line Height and Spacing
-
-| Context | Line Height | Letter Spacing |
-|---|---|---|
-| Body text | 1.5 to 1.6 | 0 to 0.01em |
-| Headings (large) | 1.1 to 1.2 | -0.02 to -0.01em |
-| Headings (small) | 1.2 to 1.3 | 0 |
-| Captions | 1.4 | 0.02 to 0.05em |
-| All caps text | 1.2 | 0.08 to 0.15em |
-| Monospace/code | 1.5 to 1.7 | 0 |
-
-### Paragraph Spacing
-Use margin-bottom on paragraphs, not margin-top. Space between paragraphs should equal roughly the line-height value (1.5em works well). Never use `<br>` for spacing.
-
----
-
-## 5. OpenType Features
-
-When the font supports them, enable:
-```css
-.body-text {
-  font-feature-settings: "liga" 1, "kern" 1;
-  font-variant-ligatures: common-ligatures;
-}
-.data-table {
-  font-variant-numeric: tabular-nums;
-}
-.legal-text {
-  font-variant-numeric: oldstyle-nums;
-}
-.heading {
-  font-feature-settings: "ss01" 1; /* Stylistic set */
-}
-```
-
----
-
-## 6. Pixel and Display Fonts
-
-Pixel fonts are useful for specific moments: retro interfaces, game UIs, terminal aesthetics, or when the digital nature of the medium should be emphasized. They are not novelty fonts when used with system thinking.
-
-Key principles for pixel fonts:
-- Only use at sizes that align with the pixel grid (multiples of the font's design size)
-- Disable anti-aliasing for crisp rendering: `font-smooth: never; -webkit-font-smoothing: none;`
-- Pair with a clean sans for body text
-- Use for headings, labels, badges, or UI accents, not paragraphs
-
----
-
-## 7. Web Font Loading
-
-Use `font-display: swap` to prevent invisible text during load. Preload critical fonts:
-
-```html
-<link rel="preload" href="/fonts/display.woff2" as="font" type="font/woff2" crossorigin>
-```
-
-Subset fonts to the characters actually used. For Google Fonts, append `&text=` with the specific characters or use `&subset=latin`.
-
-Self-host when possible. CDN fonts introduce a third-party dependency and a DNS lookup.
-
----
-
-## 8. Common Mistakes
-
-- Using more than 3 font families on a page
-- Setting body text below 16px on desktop or 14px on mobile
-- Applying letter-spacing to body text (it reduces readability)
-- Using light (300) font weight for body text on low-contrast backgrounds
-- Centering long paragraphs (center alignment works for 1-2 lines maximum)
-- Forgetting to set `max-width` on text blocks (ideal: 60-75 characters per line, roughly 600-750px)
-- Using all caps for more than a few words without increasing letter-spacing