picasso-skill 1.1.0 → 1.3.0

package/skills/picasso/references/typography.md

@@ -8,7 +8,9 @@
 5. OpenType Features
 6. Pixel and Display Fonts
 7. Web Font Loading
-8. Common Mistakes
+8. Curated Font Pairings
+9. Variable Fonts
+10. Common Mistakes
 
 ---
 
@@ -157,7 +159,209 @@ Self-host when possible. CDN fonts introduce a third-party dependency and a DNS
 
 ---
 
-## 8. Common Mistakes
+## 8. Curated Font Pairings
+
+Twelve tested pairings using 2025-2026 trending typefaces. Each listing includes the source, ideal use case, and the CSS declaration with proper fallbacks.
+
+### 8.1 Clash Display + Satoshi
+- **Source**: Fontshare (free)
+- **Use case**: SaaS landing pages, startup marketing sites
+- **CSS**:
+```css
+--font-display: 'Clash Display', 'Arial Black', sans-serif;
+--font-body: 'Satoshi', 'Helvetica Neue', Helvetica, sans-serif;
+```
+
+### 8.2 Cabinet Grotesk + General Sans
+- **Source**: Fontshare (free)
+- **Use case**: Creative agencies, portfolio sites, design tools
+- **CSS**:
+```css
+--font-display: 'Cabinet Grotesk', 'Trebuchet MS', sans-serif;
+--font-body: 'General Sans', 'Helvetica Neue', Helvetica, sans-serif;
+```
+
+### 8.3 Cal Sans + Geist Sans
+- **Source**: Cal Sans from cal.com (free, OFL). Geist via `npm i geist`.
+- **Use case**: Developer tools, open-source project sites, technical SaaS
+- **CSS**:
+```css
+--font-display: 'Cal Sans', 'Arial Black', sans-serif;
+--font-body: 'Geist', system-ui, -apple-system, sans-serif;
+```
+
+### 8.4 Instrument Serif + Instrument Sans
+- **Source**: Google Fonts (free)
+- **Use case**: Editorial, content platforms, long-form reading, magazines
+- **CSS**:
+```css
+--font-display: 'Instrument Serif', Georgia, 'Times New Roman', serif;
+--font-body: 'Instrument Sans', 'Helvetica Neue', Helvetica, sans-serif;
+```
+
+### 8.5 Clash Display + DM Sans
+- **Source**: Clash Display from Fontshare. DM Sans from Google Fonts.
+- **Use case**: Fintech dashboards, professional SaaS, enterprise tools
+- **CSS**:
+```css
+--font-display: 'Clash Display', 'Arial Black', sans-serif;
+--font-body: 'DM Sans', 'Helvetica Neue', Helvetica, sans-serif;
+```
+
+### 8.6 Plus Jakarta Sans + Plus Jakarta Sans
+- **Source**: Google Fonts (free)
+- **Use case**: Clean SaaS apps, admin panels, health and wellness platforms. Use weight contrast (700+ for headings, 400-500 for body) instead of two families.
+- **CSS**:
+```css
+--font-display: 'Plus Jakarta Sans', 'Helvetica Neue', Helvetica, sans-serif;
+--font-body: 'Plus Jakarta Sans', 'Helvetica Neue', Helvetica, sans-serif;
+```
+
+### 8.7 Satoshi + Outfit
+- **Source**: Satoshi from Fontshare. Outfit from Google Fonts.
+- **Use case**: Consumer apps, onboarding flows, friendly dashboards
+- **CSS**:
+```css
+--font-display: 'Satoshi', 'Helvetica Neue', Helvetica, sans-serif;
+--font-body: 'Outfit', 'Segoe UI', sans-serif;
+```
+
+### 8.8 Cabinet Grotesk + DM Sans
+- **Source**: Cabinet Grotesk from Fontshare. DM Sans from Google Fonts.
+- **Use case**: E-commerce, product marketing, brand-heavy pages
+- **CSS**:
+```css
+--font-display: 'Cabinet Grotesk', 'Trebuchet MS', sans-serif;
+--font-body: 'DM Sans', 'Helvetica Neue', Helvetica, sans-serif;
+```
+
+### 8.9 Instrument Serif + General Sans
+- **Source**: Instrument Serif from Google Fonts. General Sans from Fontshare.
+- **Use case**: Luxury, editorial commerce, lifestyle brands
+- **CSS**:
+```css
+--font-display: 'Instrument Serif', Georgia, 'Times New Roman', serif;
+--font-body: 'General Sans', 'Helvetica Neue', Helvetica, sans-serif;
+```
+
+### 8.10 Geist Sans + Geist Mono
+- **Source**: `npm i geist` (free, Vercel)
+- **Use case**: Developer platforms, CLI tools, documentation sites, code-heavy interfaces
+- **CSS**:
+```css
+--font-body: 'Geist', system-ui, -apple-system, sans-serif;
+--font-mono: 'Geist Mono', 'Cascadia Code', 'Fira Code', monospace;
+```
+
+### 8.11 Clash Display + JetBrains Mono (accent)
+- **Source**: Clash Display from Fontshare. JetBrains Mono from Google Fonts or jetbrains.com.
+- **Use case**: Technical marketing, API product pages, developer-facing landing pages
+- **CSS**:
+```css
+--font-display: 'Clash Display', 'Arial Black', sans-serif;
+--font-mono: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace;
+--font-body: 'Satoshi', 'Helvetica Neue', Helvetica, sans-serif;
+```
+
+### 8.12 General Sans + Commit Mono
+- **Source**: General Sans from Fontshare. Commit Mono from commitmono.com (free).
+- **Use case**: Data-heavy dashboards, analytics platforms, dev tools with mixed prose and code
+- **CSS**:
+```css
+--font-body: 'General Sans', 'Helvetica Neue', Helvetica, sans-serif;
+--font-mono: 'Commit Mono', 'Berkeley Mono', 'SF Mono', monospace;
+```
+
+### Monospace Quick Reference
+| Font | Source | Ligatures | Notes |
+|---|---|---|---|
+| Geist Mono | npm i geist | No | Clean, pairs with Geist Sans |
+| JetBrains Mono | Google Fonts / jetbrains.com | Yes | Best ligature set, great for code blocks |
+| Berkeley Mono | berkeleygraphics.com (paid) | No | Premium feel, excellent for terminals and data |
+| Commit Mono | commitmono.com | No | Neutral, smart kerning, variable font |
+
+---
+
+## 9. Variable Fonts
+
+### What They Are
+Variable fonts pack an entire family (all weights, widths, italics, optical sizes) into a single file. Instead of loading separate files for Regular, Medium, Bold, and Black, you load one `.woff2` that contains a continuous range of values along design axes.
+
+### Core Axes
+| Axis | Tag | Range (typical) | Description |
+|---|---|---|---|
+| Weight | wght | 100-900 | Thin to Black |
+| Width | wdth | 75-125 | Condensed to Expanded |
+| Italic | ital | 0-1 | Upright to Italic |
+| Slant | slnt | -12 to 0 | Oblique angle |
+| Optical Size | opsz | 8-144 | Adjust for text size |
+
+### Basic Usage
+```css
+@font-face {
+  font-family: 'Satoshi';
+  src: url('/fonts/Satoshi-Variable.woff2') format('woff2-variations');
+  font-weight: 100 900;
+  font-display: swap;
+}
+
+h1 { font-weight: 750; }       /* fractional weights */
+body { font-weight: 420; }     /* precise control */
+caption { font-weight: 350; }  /* lighter than regular */
+```
+
+### Weight Animation on Hover
+```css
+.nav-link {
+  font-weight: 400;
+  font-variation-settings: 'wght' 400;
+  transition: font-variation-settings 0.2s ease;
+}
+.nav-link:hover {
+  font-variation-settings: 'wght' 650;
+}
+```
+
+Use `font-variation-settings` for animation because `font-weight` transitions are not smooth in all browsers. The `font-variation-settings` property animates along the continuous axis.
+
+### Width Animation
+```css
+.expandable-label {
+  font-variation-settings: 'wdth' 90;
+  transition: font-variation-settings 0.3s ease;
+}
+.expandable-label:hover {
+  font-variation-settings: 'wdth' 110;
+}
+```
+
+### Custom Axes
+Some variable fonts include custom axes (always uppercase tags). Example with Recursive:
+```css
+.code-block {
+  font-family: 'Recursive', monospace;
+  font-variation-settings: 'MONO' 1, 'CASL' 0, 'wght' 400;
+}
+.code-comment {
+  font-variation-settings: 'MONO' 1, 'CASL' 1, 'wght' 300, 'slnt' -12;
+}
+```
+
+### Recommended Variable Fonts
+| Font | Axes | Source | Notes |
+|---|---|---|---|
+| Satoshi Variable | wght (300-900) | Fontshare | Best all-around variable sans for UI |
+| General Sans Variable | wght (200-700) | Fontshare | Wide weight range, clean geometry |
+| Plus Jakarta Sans | wght (200-800) | Google Fonts | Full variable support, friendly geometry |
+| Instrument Sans | wght (400-700) | Google Fonts | Pairs with Instrument Serif variable |
+| Commit Mono | wght (400-700) | commitmono.com | Monospace with smart kerning axis |
+
+### Performance Benefit
+A single variable font file (typically 50-120KB for Latin subset) replaces 4-8 static files (each 15-40KB). This reduces HTTP requests and total download size, especially when using more than 3 weights.
+
+---
+
+## 10. Common Mistakes
 
 - Using more than 3 font families on a page
 - Setting body text below 16px on desktop or 14px on mobile

package/skills/picasso/references/ux-psychology.md

@@ -0,0 +1,235 @@
+# UX Psychology & Cognitive Design Reference
+
+## 1. Gestalt Principles Applied to UI
+
+### Proximity
+Elements near each other are perceived as related. Spacing is the primary grouping mechanism.
+
+```css
+.form-group     { margin-bottom: 32px; }   /* between groups */
+.form-group input { margin-bottom: 8px; }  /* within a group  */
+```
+
+**Rule:** Inner spacing (within a group) should be at most half of outer spacing (between groups). A 2:1 or 3:1 ratio is safest.
+
+### Similarity
+Elements that look alike are perceived as belonging together. Use shared color, size, shape, or weight.
+
+**Rule:** Keep a maximum of 3 distinct visual "families" of interactive elements per screen.
+
+### Closure
+The brain fills in gaps to see complete shapes. Use this for progress indicators, icon design, and loading states.
+
+### Continuity
+The eye follows smooth lines and curves. Align elements along a clear axis.
+
+**Rule:** Use a strict column grid. Every element edge should snap to a grid line. Misaligned elements break continuity and create visual friction.
+
+### Figure-Ground
+Users must instantly distinguish foreground content from background. Contrast, elevation, and blur create separation.
+
+```css
+.modal-backdrop { background: rgba(0,0,0,0.5); backdrop-filter: blur(4px); }
+.modal          { background: #fff; border-radius: 12px; box-shadow: 0 24px 48px rgba(0,0,0,0.16); }
+```
+
+**Rule:** Overlays need a minimum contrast shift of 40% luminance between foreground and background.
+
+### Common Region
+Borders or background fills create perceived groups, even without proximity.
+
+**Rule:** Cards and sections should use either a border OR a fill, rarely both. Doubling cues wastes visual weight.
+
+---
+
+## 2. Cognitive Laws
+
+### Fitts's Law -- Target Sizing & Placement
+
+Time to reach a target = f(distance, size). Larger and closer targets are faster to hit.
+
+| Context | Minimum Target Size |
+|---------|-------------------|
+| Touch (mobile) | 48 x 48 dp |
+| Touch (iOS) | 44 x 44 pt |
+| WCAG 2.5.5 | 44 x 44 CSS px |
+| Desktop click | 32 x 32 px |
+| Spacing between targets | >= 8px gap |
+
+**Rules:**
+- Primary actions go in bottom-right (desktop) or bottom-center (mobile) where the thumb rests.
+- Destructive actions go far from confirm buttons to prevent accidental taps.
+- Edge-anchored targets (menus flush to screen edges) have effectively infinite size on one axis.
+
+### Hick's Law -- Reducing Choices
+
+Decision time increases logarithmically with the number of options.
+
+**Rules:**
+- Limit primary navigation items to 5-7.
+- For longer lists, chunk into categories.
+- Highlight a recommended/default option to collapse the decision tree.
+- Use progressive disclosure to defer secondary options.
+
+### Miller's Law -- Chunking
+
+Working memory holds roughly 7 +/- 2 items. Group information into digestible chunks.
+
+**Rules:**
+- Phone numbers: `(555) 123-4567` not `5551234567`.
+- Credit card fields: 4 groups of 4 digits.
+- Break long forms into multi-step wizards with 3-5 fields per step.
+- Dashboard metrics: group into cards of 3-4 related KPIs.
+
+### Jakob's Law -- Convention Over Invention
+
+Users spend most of their time on other sites. Match existing mental models.
+
+**Conventions:**
+- Logo top-left, linking to home.
+- Primary navigation horizontal at top or vertical at left.
+- Search bar top-center or top-right.
+- Shopping cart icon top-right with badge count.
+- Underlined blue text = link.
+- Forms: labels above inputs, submit button bottom-right.
+
+### Doherty Threshold -- Response Time
+
+Productivity soars when system response is under 400ms.
+
+| Response Time | User Perception | UI Treatment |
+|--------------|----------------|--------------|
+| < 100ms | Instantaneous | No feedback needed |
+| 100-400ms | Slight delay | Subtle state change |
+| 400ms-1s | Noticeable | Show spinner |
+| 1-5s | Waiting | Skeleton screen / progress bar |
+| > 5s | Frustrated | Progress % and time estimate |
+
+**Rules:**
+- Optimistic UI updates for actions under 1s.
+- Skeleton screens always beat loading spinners for perceived performance.
+- Animate transitions at 200-300ms; under 100ms feels jumpy, over 500ms feels sluggish.
+
+### Peak-End Rule
+
+People judge an experience by its most intense moment (peak) and its final moment (end).
+
+**Rules:**
+- End flows with a moment of delight: confetti on signup completion, a clear success state with next steps.
+- Eliminate negative peaks: never show an error without a recovery path.
+- Onboarding should front-load a quick win within the first 60 seconds.
+
+---
+
+## 3. Visual Scanning Patterns
+
+### F-Pattern (Text-Heavy Pages)
+Users scan horizontally across the top, shorter horizontal sweep partway down, then vertically down the left edge.
+
+**Design responses:**
+- Put critical information in the first two paragraphs.
+- Start headings and bullet points with information-carrying words (front-load keywords).
+- Use bold for scannable anchor phrases.
+- Break walls of text with subheadings every 3-5 paragraphs.
+
+### Z-Pattern (Sparse / Marketing Pages)
+Users scan top-left to top-right, diagonal to bottom-left, then across to bottom-right.
+
+**Design responses:**
+- Logo/brand mark: top-left.
+- Navigation/CTA: top-right.
+- Hero content/value prop: center (the diagonal).
+- Primary CTA button: bottom-right.
+
+### Layer-Cake Pattern
+Users scan only headings and subheadings, skipping body text entirely. Headings must be self-sufficient.
+
+### Serial Position Effect
+Users remember the first and last items in a list best.
+
+**Rule:** Put the most important nav items first and last. Bury less critical items in the middle.
+
+---
+
+## 4. Decision Architecture
+
+### Progressive Disclosure
+Show only what is needed at each step; reveal complexity on demand.
+
+**Implementation patterns:**
+- Accordion sections for secondary settings.
+- "Show advanced options" toggle.
+- Multi-step forms with 3-5 fields per step.
+- Tooltip/popover for contextual help vs. inline text.
+
+**Rule:** Primary display should cover 80% of user needs. The remaining 20% is disclosed progressively.
+
+### Default Bias
+Users overwhelmingly accept pre-set defaults. Use this ethically.
+
+**Rules:**
+- Pre-select the most common/safest option.
+- Toggle switches should default to the privacy-respecting state.
+- Pre-fill forms with smart defaults (country from IP, timezone from browser).
+
+### Anchoring
+The first piece of information presented becomes the reference point for all subsequent judgments.
+
+**Rules:**
+- Show the higher-priced plan first in pricing tables.
+- Display original price before discount to establish anchor.
+- Show "most popular" labels on the plan you want users to choose.
+
+### Social Proof Placement
+Place social proof adjacent to decision points, not buried in separate sections.
+
+**Rules:**
+- Testimonials directly below or beside pricing CTAs.
+- User counts near signup forms.
+- Trust badges next to checkout buttons.
+- Star ratings visible without scrolling on product cards.
+
+---
+
+## 5. Emotional Design
+
+### Color & Emotion
+
+| Emotion | Color Family | Usage |
+|---------|-------------|-------|
+| Trust/Security | Blue | Finance, SaaS, healthcare |
+| Urgency/Error | Red | Alerts, destructive actions, sales |
+| Success/Growth | Green | Confirmations, positive metrics |
+| Warning/Caution | Amber | Non-blocking alerts |
+| Calm/Premium | Neutral + generous whitespace | Luxury, editorial |
+| Energy/Optimism | Yellow/Orange | CTAs, highlights |
+
+### Typography & Emotion
+
+| Feeling | Typeface Characteristics |
+|---------|------------------------|
+| Trust/Authority | Serif or geometric sans |
+| Modern/Clean | Geometric sans-serif |
+| Friendly/Approachable | Rounded sans-serif |
+| Technical/Precise | Monospace or condensed sans |
+
+### Spacing & Calm
+More whitespace = more premium/calm. Dense layouts signal "tool"; spacious layouts signal "product."
+
+### Motion & Delight
+Enter transitions should be slightly slower than exit transitions (users need time to register new content). Stagger list item animations by 30-50ms per item, cap total duration at 500ms.
+
+---
+
+## Quick-Reference Cheat Sheet
+
+| Principle | Key Number | Action |
+|-----------|-----------|--------|
+| Fitts's Law | 44-48px min | Size touch targets appropriately |
+| Hick's Law | 5-7 max | Limit choices per decision point |
+| Miller's Law | 7 +/- 2 | Chunk information into groups |
+| Doherty Threshold | < 400ms | Keep responses under 400ms |
+| Color ratio | 60-30-10 | Dominant/secondary/accent |
+| F-pattern | top 2 lines | Front-load critical content |
+| Proximity ratio | 2:1 or 3:1 | Inner vs outer spacing |
+| First impression | 50ms | Users judge in 50 milliseconds |