picasso-skill 1.5.1 → 2.0.0

package/skills/picasso/references/tables-and-forms.md

@@ -0,0 +1,227 @@
+# Tables and Forms Reference
+
+## Table of Contents
+1. Sortable Tables
+2. Responsive Tables
+3. Inline Editing
+4. Multi-Select Patterns
+5. Form Validation
+6. Multi-Step Forms
+7. Complex Inputs
+8. Common Mistakes
+
+---
+
+## 1. Sortable Tables
+
+```html
+<table>
+  <thead>
+    <tr>
+      <th aria-sort="ascending">
+        <button>Name <span aria-hidden="true">↑</span></button>
+      </th>
+      <th aria-sort="none">
+        <button>Date <span aria-hidden="true">↕</span></button>
+      </th>
+    </tr>
+  </thead>
+</table>
+```
+
+- Use `aria-sort` on `<th>`: `ascending`, `descending`, or `none`.
+- Sort icon: `↑` ascending, `↓` descending, `↕` unsorted. Use `aria-hidden="true"` on the icon.
+- Sortable headers must be `<button>` inside `<th>`, not clickable `<th>`.
+- Default sort: most recent first for dates, alphabetical for names.
+
+---
+
+## 2. Responsive Tables
+
+**Option A: Horizontal scroll** (preferred for data tables)
+
+```css
+.table-container {
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+}
+
+/* Fade edge to hint scrollability */
+.table-container::after {
+  content: '';
+  position: absolute;
+  right: 0;
+  top: 0;
+  bottom: 0;
+  width: 40px;
+  background: linear-gradient(to left, var(--surface-1), transparent);
+  pointer-events: none;
+}
+```
+
+**Option B: Stacked cards** (for simple tables on mobile)
+
+```css
+@media (max-width: 640px) {
+  table, thead, tbody, th, td, tr { display: block; }
+  thead { display: none; }
+  td { padding: 8px 16px; text-align: right; }
+  td::before {
+    content: attr(data-label);
+    float: left;
+    font-weight: 600;
+    color: var(--text-secondary);
+  }
+}
+```
+
+---
+
+## 3. Inline Editing
+
+Click to edit pattern: display text, click reveals input, blur/Enter saves.
+
+```jsx
+function EditableCell({ value, onSave }) {
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState(value);
+
+  if (!editing) return (
+    <span onClick={() => setEditing(true)} className="cursor-text hover:bg-surface-2 px-2 py-1 rounded">
+      {value}
+    </span>
+  );
+
+  return (
+    <input
+      value={draft}
+      onChange={e => setDraft(e.target.value)}
+      onBlur={() => { onSave(draft); setEditing(false); }}
+      onKeyDown={e => { if (e.key === 'Enter') { onSave(draft); setEditing(false); } if (e.key === 'Escape') setEditing(false); }}
+      autoFocus
+      className="input-base w-full"
+    />
+  );
+}
+```
+
+Show a subtle pencil icon on row hover. Use `opacity-0 group-hover:opacity-100` pattern.
+
+---
+
+## 4. Multi-Select Patterns
+
+- **Checkbox column**: leftmost column, always visible.
+- **Shift-click range select**: select from last checked to current.
+- **Select all**: checkbox in header, toggles all visible (filtered) rows.
+- **Bulk action bar**: appears when 1+ rows selected. Shows count + actions.
+
+```jsx
+<div className={`fixed bottom-4 left-1/2 -translate-x-1/2 bg-surface-2 rounded-xl px-4 py-2
+  flex items-center gap-4 shadow-lg border border-border transition-transform
+  ${selectedCount > 0 ? 'translate-y-0' : 'translate-y-[200%]'}`}>
+  <span className="text-sm font-medium">{selectedCount} selected</span>
+  <button className="btn-ghost text-sm">Export</button>
+  <button className="btn-ghost text-sm text-red">Delete</button>
+</div>
+```
+
+---
+
+## 5. Form Validation
+
+**When to validate:**
+
+| Trigger | Use For |
+|---|---|
+| On blur | Email format, required fields, min/max length |
+| On submit | All fields, server-side checks |
+| Real-time (on change) | Password strength, username availability |
+| Never on keystroke | Don't interrupt typing. Wait for blur or 500ms debounce. |
+
+```jsx
+<div className="space-y-1.5">
+  <label htmlFor="email" className="text-sm font-medium">Email</label>
+  <input
+    id="email"
+    type="email"
+    aria-invalid={error ? "true" : undefined}
+    aria-describedby={error ? "email-error" : undefined}
+    className={`input-base ${error ? 'border-red' : ''}`}
+  />
+  {error && (
+    <p id="email-error" role="alert" className="text-xs text-red flex items-center gap-1">
+      <svg className="w-3.5 h-3.5" aria-hidden="true">...</svg>
+      {error}
+    </p>
+  )}
+</div>
+```
+
+Error messages: specific and helpful. "Enter a valid email" not "Invalid input."
+
+---
+
+## 6. Multi-Step Forms
+
+Show a progress indicator. Allow back navigation. Validate per step, not all at once.
+
+```jsx
+<div className="flex items-center gap-2 mb-8">
+  {steps.map((step, i) => (
+    <Fragment key={i}>
+      <div className={`flex items-center justify-center h-8 w-8 rounded-full text-sm font-bold
+        ${i < currentStep ? 'bg-accent text-white' :
+          i === currentStep ? 'border-2 border-accent text-accent' :
+          'border border-border text-muted'}`}>
+        {i < currentStep ? '✓' : i + 1}
+      </div>
+      {i < steps.length - 1 && (
+        <div className={`flex-1 h-0.5 ${i < currentStep ? 'bg-accent' : 'bg-border'}`} />
+      )}
+    </Fragment>
+  ))}
+</div>
+```
+
+Rules:
+- Save progress per step (don't lose data on back).
+- Validate step before advancing (disable Next if invalid).
+- Show step count: "Step 2 of 4".
+- Allow clicking completed steps to go back.
+- Final step: show summary before submit.
+
+---
+
+## 7. Complex Inputs
+
+**Date pickers:** Use native `<input type="date">` first. Custom picker only if design requires it. Always allow manual text entry as fallback.
+
+**File upload:** Show progress, preview (for images), allow removal.
+
+```jsx
+<label className="flex flex-col items-center gap-2 p-8 border-2 border-dashed border-border
+  rounded-xl cursor-pointer hover:border-accent hover:bg-accent/5 transition-colors">
+  <svg>...</svg>
+  <span className="text-sm text-secondary">Drop files or click to upload</span>
+  <input type="file" className="hidden" onChange={handleUpload} />
+</label>
+```
+
+**Address autocomplete:** Use Google Places API or similar. Show suggestions in a dropdown. Parse into structured fields (street, city, state, zip).
+
+---
+
+## 8. Common Mistakes
+
+- **Sortable `<th>` without `<button>`.** Clicking a `<th>` isn't keyboard accessible.
+- **No `aria-sort` on sortable columns.** Screen readers can't announce sort state.
+- **Validating on every keystroke.** Annoying. Use blur or 500ms debounce.
+- **Error messages without `role="alert"`.** Screen readers won't announce them.
+- **Multi-step form losing data on back.** Save each step's state.
+- **No horizontal scroll hint on tables.** Users don't know content is hidden. Add fade gradient.
+- **Custom date picker without text input fallback.** Some users prefer typing dates.
+- **Select all selecting ALL rows, not just filtered.** Only select what's visible.
+- **Labels as placeholder text.** Labels must be visible above the input, always.

package/skills/picasso/references/tools-catalog.md

@@ -0,0 +1,103 @@
+# Tools & Libraries Catalog
+
+Consolidated reference for animation libraries, design tools, and utilities. Quick lookup when generating or recommending tools.
+
+## Animation Libraries
+
+### React Bits (reactbits.dev)
+126 animated React components. 37.5K GitHub stars.
+- **Text (23):** Split Text, Blur Text, Shiny Text, Gradient Text, Glitch Text, Scrambled Text, Count Up, etc.
+- **Animations (28):** Electric Border, Glare Hover, Magnet Lines, Click Spark, Pixel Trail, Meta Balls, etc.
+- **Components (36):** Magic Bento, Fluid Glass, Tilted Card, Dock, Gooey Nav, Elastic Slider, etc.
+- **Backgrounds (39):** Liquid Ether, Silk, Aurora, Plasma, Hyperspeed, Iridescence, Balatro, etc.
+- **Tools:** Background Studio, Shape Magic, Texture Lab
+
+### Animate UI (animate-ui.com)
+shadcn-registry-based animation components built on Motion (Framer Motion).
+- Animated primitives (ported from Radix UI, Base UI, Headless UI)
+- Components with baseline styles inspired by shadcn/ui
+- Animated Lucide icons
+- Install: follows shadcn pattern (copy source, customize)
+
+### Cursify (cursify.ui-layouts.com)
+11 React cursor animation effects:
+Fairydust, Smooth Following, Canvas, Bubble, Character, Snowflake, Rainbow, Follow, Spotlight, Springy, Neural Glow.
+Best for: portfolio sites, creative agencies, landing pages (not productivity tools).
+
+### Motion (formerly Framer Motion)
+React animation library with gesture support, spring physics, layout animations.
+Use for: complex choreography, gesture-driven interactions, shared layout transitions.
+
+### Torph (npm torph)
+Character-level text morph animations. Dependency-free. React, Vue, Svelte, vanilla TS.
+
+## Visual Effects
+
+### Radiant Shaders (radiant-shaders.com)
+80+ production-ready WebGL/Canvas shaders. 0 dependencies, MIT license. Copy source, integrate, ship. Similar to shadcn's approach but for visual effects.
+
+## Layout & Interaction
+
+### Hit Area Utilities (bazza.dev)
+Tailwind classes expanding clickable areas without affecting visual layout.
+Install: `npx shadcn@latest add https://bazza.dev/r/hit-area`
+Classes: `hit-area-6`, `hit-area-x-4`, `hit-area-l-8`, `hit-area-debug`
+
+### WebHaptics (npm web-haptics)
+Haptic feedback for mobile web. React, Vue, Svelte, TypeScript.
+Patterns: success, warning, error, light, medium, heavy, soft, rigid, selection.
+```jsx
+import { useWebHaptics } from "web-haptics/react";
+const { trigger } = useWebHaptics();
+```
+
+### Pretext (@chenglou/pretext)
+500x faster text measurement than DOM. Pure TypeScript, ~15KB.
+Two-function API: `prepare()` (one-time) + `layout()` (hot path, pure arithmetic).
+Universal: DOM, Canvas, SVG, WebGL, server-side. CJK, Arabic, Hebrew, Thai support.
+
+## Design References
+
+### Component Gallery (component.gallery)
+60 interface components, 95 design systems, 2,676 examples.
+Cross-reference the same component across 95+ design systems for naming conventions and patterns.
+
+### Checklist Design (checklist.design)
+56 design checklists:
+- 13 page checklists (404, Login, Pricing, Sign Up, etc.)
+- 24 component checklists (Button, Card, Modal, Table, Toast, etc.)
+- 13 flow checklists (Adding to cart, Resetting password, etc.)
+- 3 topic checklists (Responsiveness, Dark Mode, UX Copy)
+- 3 brand checklists (Logo, Typography, Tone of Voice)
+Also: Figma plugin for in-context checking.
+
+## Design Tools
+
+### Google Stitch (stitch.withgoogle.com)
+AI design tool: text prompts -> high-fidelity UI designs with production code.
+Features: AI canvas, voice interaction, DESIGN.md export, instant prototyping.
+MCP server + SDK for coding agent integration. 350 free generations/month.
+
+### Subframe (subframe.com)
+Drag-and-drop visual editor connected to coding agents via MCP.
+AI generates -> you visually refine -> clean code flows back.
+
+### Variant (variant.com)
+AI design generator with infinite scroll exploration. Enter idea, scroll for endless options.
+
+## CSS & Font Tools
+- **pyftsubset** / **glyphhanger** -- font subsetting
+- **svgo** -- SVG optimization (`svgo --precision=1 --multipass`)
+- **critical** (npm) / **critters** (webpack/vite) -- critical CSS extraction
+
+## Sound & Haptics
+- **soundcn** -- 700+ CC0 UI sounds
+- **Kenney.nl** -- free CC0 UI sound packs
+- **Freesound.org** -- CC0 filtered sounds
+- **Tone.js** -- procedural runtime synthesis
+
+## Utilities
+- **facehash** -- deterministic avatar faces from any string (~3KB)
+- **better-icons** -- 200K+ icons from 150+ icon sets
+- **Lucide React** -- default icon library (tree-shakeable)
+- **better-all** -- dependency-based parallel data fetching

package/skills/picasso/references/typography.md

@@ -10,7 +10,9 @@
 7. Web Font Loading
 8. Curated Font Pairings
 9. Variable Fonts
-10. Common Mistakes
+10. Dark Mode Font Weight
+11. Metric-Matched Font Fallbacks
+12. Common Mistakes
 
 ---
 
@@ -361,7 +363,46 @@ A single variable font file (typically 50-120KB for Latin subset) replaces 4-8 s
 
 ---
 
-## 10. Common Mistakes
+## 10. Dark Mode Font Weight
+
+Light text on a dark background appears optically heavier than the same weight on white. Compensate by reducing body font weight in dark mode:
+
+```css
+:root[data-theme="dark"] {
+  --body-weight: 350;
+}
+.body {
+  font-weight: var(--body-weight, 400);
+}
+```
+
+Also increase line-height by 0.05-0.1 for light-on-dark text to improve readability. This is a subtle refinement that separates polished dark themes from rushed ones.
+
+---
+
+## 11. Metric-Matched Font Fallbacks (Eliminate CLS)
+
+Custom fonts cause Cumulative Layout Shift when the fallback and custom font have different metrics. Fix this with `@font-face` override descriptors that match the fallback to the custom font:
+
+```css
+@font-face {
+  font-family: 'CustomFont-Fallback';
+  src: local('Arial');
+  size-adjust: 105%;
+  ascent-override: 90%;
+  descent-override: 20%;
+  line-gap-override: 10%;
+}
+
+/* Use in the font stack */
+--font-body: 'Satoshi', 'CustomFont-Fallback', sans-serif;
+```
+
+Measure your custom font's metrics against the fallback (tools like `fontpie` or the Chrome DevTools font panel help) and tune these four values. The result: zero layout shift on font load, even with `font-display: swap`.
+
+---
+
+## 12. Common Mistakes
 
 - Using more than 3 font families on a page
 - Setting body text below 16px on desktop or 14px on mobile
@@ -370,3 +411,5 @@ A single variable font file (typically 50-120KB for Latin subset) replaces 4-8 s
 - 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
+- Not adjusting font weight for dark mode (light-on-dark text appears heavier)
+- Missing metric-matched fallbacks (causes CLS on font load)