picasso-skill 2.0.0 → 2.0.2

package/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/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: picasso
-version: 2.0.0
+version: 2.0.1
 description: >
   The ultimate frontend design and UI engineering skill. Use this whenever the user asks to build, design, style, or improve any web interface, component, page, application, dashboard, landing page, artifact, poster, or visual output. Covers typography, color systems, spatial design, motion/animation, interaction design, responsive layouts, sound design, haptic feedback, icon systems, generative art, theming, React best practices, and DESIGN.md system generation. Also use when the user asks to audit, critique, polish, simplify, animate, or normalize a frontend. Triggers on any mention of "make it look good," "fix the design," "UI," "UX," "frontend," "component," "landing page," "dashboard," "artifact," "poster," "design system," "theme," "animation," "responsive," or any request to improve visual quality. Use this skill even when the user does not explicitly ask for design help but the task involves producing a visual interface.
 metadata:
@@ -74,6 +74,15 @@ Before writing any code, read the reference files relevant to the task. Each cov
 | `references/brand-and-identity.md` | Logo sizing, brand color usage, consistency, lockup variants |
 | `references/animation-performance.md` | Compositor-only props, will-change, layout thrashing, contain |
 | `references/code-typography.md` | Monospace fonts, syntax highlighting, code blocks, diff views |
+| `references/accessibility-wcag.md` | WCAG 2.2, ARIA patterns, keyboard nav, screen reader testing |
+| `references/conversion-design.md` | Landing pages, CTAs, pricing tables, friction reduction |
+| `references/data-visualization.md` | Chart selection matrix, dashboard patterns, accessible charts |
+| `references/modern-css-performance.md` | CSS nesting, :has(), View Transitions, Tailwind v4, container queries |
+| `references/performance-optimization.md` | Core Web Vitals, Lighthouse, image optimization, 45 Vercel rules |
+| `references/style-presets.md` | 22 curated design presets with exact OKLCH values and font pairings |
+| `references/tools-catalog.md` | Tool recommendations: torph, soundcn, Lucide, Facehash, better-icons |
+| `references/ux-psychology.md` | Gestalt principles, Fitts's Law, Hick's Law, cognitive load, heuristics |
+| `references/ux-writing.md` | Error messages, microcopy, terminology, voice and tone, CTAs |
 
 ---
 

package/templates/picasso-config.md

@@ -0,0 +1,53 @@
+# .picasso.md -- Project Design Configuration
+
+<!-- Drop this file in your project root. The Picasso agent reads it before every
+     audit to understand your project's design preferences. Any field left as the
+     default placeholder (brackets) will be ignored and Picasso defaults apply. -->
+
+## Brand
+<!-- Core identity. Guides tone-of-voice checks and overall aesthetic expectations. -->
+- **Name:** [Your product name]
+- **Tone:** [e.g., professional, playful, minimal, bold]
+- **Industry:** [e.g., fintech, health, creative, education, developer tools]
+
+## Typography
+<!-- Picasso flags generic fonts (Inter, Roboto, Arial) as AI-slop by default.
+     If your project intentionally uses one of those, declare it here and it
+     will be treated as an approved choice. -->
+- **Display Font:** [e.g., Satoshi, Cabinet Grotesk]
+- **Body Font:** [e.g., DM Sans, Outfit]
+- **Mono Font:** [e.g., Geist Mono, JetBrains Mono]
+- **Type Scale Ratio:** [e.g., 1.25 (Major Third)]
+
+## Color
+<!-- Picasso uses OKLCH as its default color model.
+     Declaring your palette here prevents false positives when auditing
+     color usage across the codebase. -->
+- **Primary Accent:** [e.g., oklch(0.55 0.25 250)]
+- **Neutral Tint:** [e.g., cool (blue), warm (amber), neutral]
+- **Dark Mode:** [yes/no/both]
+
+## Component Library
+<!-- Tells Picasso which component primitives and CSS framework to expect
+     so it can tailor advice and auto-fixes accordingly. -->
+- **Framework:** [e.g., shadcn/ui + Radix, Chakra, custom]
+- **CSS:** [e.g., Tailwind v4, CSS Modules, Panda CSS]
+
+## Design Settings
+<!-- These knobs control how aggressively Picasso suggests changes.
+     Scale is 1-10 for each. -->
+- **DESIGN_VARIANCE:** [1-10, default 6]
+  <!-- How far Picasso can deviate from safe/conventional choices.
+       1 = strictly conservative, 10 = experimental and opinionated. -->
+- **MOTION_INTENSITY:** [1-10, default 5]
+  <!-- Controls animation suggestions.
+       1 = almost no motion, 10 = rich choreographed animations. -->
+- **VISUAL_DENSITY:** [1-10, default 5]
+  <!-- How packed the UI should feel.
+       1 = lots of whitespace, 10 = information-dense dashboard style. -->
+
+## Constraints
+<!-- Hard requirements that override all other Picasso recommendations.
+     Add one bullet per constraint. Remove the examples below and add your own. -->
+- [e.g., "Must support IE11", "No animations", "508 compliance required"]
+- [e.g., "Match existing app at app.example.com"]

package/checklists/pre-ship.md

@@ -1,83 +0,0 @@
-# Pre-Ship Design Checklist
-
-Run through before shipping any frontend work. Each item is a concrete pass/fail check, not a guideline.
-
----
-
-## Typography
-- [ ] Primary font is NOT Inter, Roboto, Arial, Helvetica, or system-ui
-- [ ] Heading hierarchy is correct (h1 > h2 > h3, no skipping)
-- [ ] Body text line-height is 1.5-1.6
-- [ ] Large headings have negative letter-spacing (-0.01 to -0.02em)
-- [ ] Prose max-width is ~65ch or 640px
-- [ ] `tabular-nums` on any data/numbers displayed
-- [ ] Font loading is optimized (preload, font-display)
-
-## Color & Contrast
-- [ ] No pure black (#000) or pure gray -- neutrals are tinted
-- [ ] Body text passes 4.5:1 contrast ratio
-- [ ] Large text passes 3:1 contrast ratio
-- [ ] UI components pass 3:1 contrast ratio
-- [ ] Colors defined in OKLCH (not hex or HSL)
-- [ ] Dark mode tested (if applicable)
-- [ ] Accent color is not a Tailwind default
-
-## Spatial Design
-- [ ] Spacing follows 4px scale consistently
-- [ ] Intra-group spacing < inter-group spacing (2:1 ratio)
-- [ ] No uniform padding/margin everywhere
-- [ ] Layout is NOT just centered columns
-- [ ] Cards are not nested within cards
-
-## Depth & Elevation
-- [ ] Important elements are visually elevated
-- [ ] Shadow hierarchy exists (not same shadow everywhere)
-- [ ] Hover states show elevation change where appropriate
-- [ ] Dark mode shadows are adjusted (more opacity or border-based)
-
-## Motion & Animation
-- [ ] `prefers-reduced-motion` is respected
-- [ ] No `transition: all` (specific properties only)
-- [ ] Easing is NOT linear or default `ease`
-- [ ] Page load has some choreography (staggered reveals)
-- [ ] Animations use `transform` and `opacity` only (GPU-composited)
-
-## Interaction
-- [ ] All interactive elements have hover, focus, active, disabled states
-- [ ] Focus indicators are visible (`:focus-visible`, 2px outline)
-- [ ] Touch targets are 44x44px minimum
-- [ ] Forms have proper labels (not just placeholders)
-- [ ] Error messages are inline and descriptive
-- [ ] Destructive actions have confirmation or undo
-- [ ] Loading states use skeletons (not just spinners)
-
-## Accessibility
-- [ ] Semantic HTML used (`<button>`, `<a>`, `<nav>`, `<main>`, etc.)
-- [ ] All images have meaningful alt text (or `alt=""` for decorative)
-- [ ] Keyboard navigation works throughout (Tab, Enter, Escape)
-- [ ] Skip link exists for main content
-- [ ] Page works at 200% zoom
-- [ ] Color is not the only means of conveying information
-
-## Responsive
-- [ ] Mobile-first CSS (`min-width` queries)
-- [ ] Tested on real mobile viewport (not just DevTools)
-- [ ] `dvh` used with `vh` fallback for full-height sections
-- [ ] Hover effects scoped with `@media (hover: hover)`
-- [ ] Safe areas handled for notched devices
-- [ ] Tables are scrollable or stacked on mobile
-
-## Performance
-- [ ] Hero image has `fetchpriority="high"`
-- [ ] Below-fold images have `loading="lazy"`
-- [ ] No barrel file imports (direct imports only)
-- [ ] Critical CSS is inlined or prioritized
-- [ ] Fonts are subsetted and self-hosted where possible
-- [ ] SVGs are optimized (svgo)
-
-## Anti-Slop Final Check
-- [ ] The 3-Second Test: Would someone identify this as "AI-generated"?
-- [ ] The Squint Test: Can you see hierarchy and groupings when blurred?
-- [ ] No 3+ AI fingerprints present simultaneously
-- [ ] At least ONE memorable design choice exists
-- [ ] Design varies between projects (not converging on same look)