picasso-skill 1.0.0

package/references/spatial-design.md

@@ -0,0 +1,176 @@
+# 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

@@ -0,0 +1,168 @@
+# 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

package/skills/picasso/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: picasso
+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.
+---
+
+# Picasso
+
+The ultimate design skill for producing distinctive, production-grade frontend interfaces, visual artifacts, and design systems. This skill consolidates best practices from Anthropic's frontend-design, canvas-design, algorithmic-art, and theme-factory skills, Impeccable's 7-domain reference system, VoltAgent's DESIGN.md format, Vercel's React and typography standards, and specialized libraries for sound, haptics, icons, and text animation.
+
+Every output should look like it was built by a senior design engineer who spent days refining it, not generated by an AI in seconds.
+
+---
+
+## Configurable Settings
+
+These three dials (1-10) control the overall character of the output. Adjust based on what is being built. The user can set these explicitly or they can be inferred from context.
+
+- **DESIGN_VARIANCE** (default: 6) — How experimental the layout is. 1-3: clean, centered, conventional. 4-6: considered asymmetry, intentional breaks. 7-10: avant-garde, overlapping elements, unconventional grids.
+- **MOTION_INTENSITY** (default: 5) — How much animation is present. 1-3: hover states and fades only. 4-6: staggered reveals, scroll-triggered, text morphing. 7-10: magnetic cursors, parallax, complex choreography.
+- **VISUAL_DENSITY** (default: 5) — How much content fits on one screen. 1-3: spacious, luxury, breathing room. 4-6: balanced, structured whitespace. 7-10: dense dashboards, data-heavy, compact.
+
+When the user says "make it premium" or "luxury feel," drop VISUAL_DENSITY to 2-3 and MOTION_INTENSITY to 4-5. When they say "dashboard" or "admin panel," raise VISUAL_DENSITY to 7-8. When they say "make it pop" or "wow factor," raise DESIGN_VARIANCE and MOTION_INTENSITY to 7-8.
+
+---
+
+## Step 0: Read the Right References
+
+Before writing any code, read the reference files relevant to the task. Each covers a domain in depth with rules, examples, and anti-patterns. Load only what you need.
+
+| Reference File | When to Read |
+|---|---|
+| `references/typography.md` | Any task involving text, fonts, headings, or type hierarchy |
+| `references/color-and-contrast.md` | Color palettes, dark mode, accessibility, tinted neutrals |
+| `references/spatial-design.md` | Layout, spacing, grids, visual hierarchy, whitespace |
+| `references/motion-and-animation.md` | Transitions, scroll effects, text morphing, micro-interactions |
+| `references/interaction-design.md` | Forms, focus states, loading, empty states, error handling |
+| `references/responsive-design.md` | Mobile-first, fluid, container queries, touch targets |
+| `references/sensory-design.md` | UI sound effects, haptic feedback, multi-sensory interfaces |
+| `references/react-patterns.md` | React/Next.js component architecture, hooks, performance |
+| `references/anti-patterns.md` | Explicit list of what NOT to do (the most important reference) |
+| `references/design-system.md` | Generating DESIGN.md files, theming, systematic tokens |
+| `references/generative-art.md` | Algorithmic art, p5.js, seeded randomness, flow fields |
+| `references/component-patterns.md` | Standard component naming, taxonomy, and state patterns |
+
+---
+
+## Step 1: Design Thinking
+
+Before writing a single line of code, answer these questions internally:
+
+**Purpose.** What problem does this interface solve? Who uses it? What is the single most important action?
+
+**Tone.** Commit to a specific aesthetic direction. Not "clean and modern" (that is meaningless). Pick something with teeth: brutalist, editorial, retro-terminal, luxury serif, toy-like, industrial, organic, Swiss grid, art deco, vaporwave, newspaper broadsheet, scientific journal, or something entirely original. The direction should be informed by the content, not applied generically.
+
+**Differentiation.** What makes this unforgettable? What is the one thing someone will remember after closing the tab? If there is no answer, the design is not ready.
+
+**Constraints.** Framework requirements, accessibility targets, performance budgets, existing design tokens.
+
+---
+
+## Step 2: Aesthetic Execution
+
+### Typography
+
+Choose fonts that are distinctive, not default. Never use Inter, Roboto, Arial, or system fonts as primary choices. Pair a display font with a body font. Use a modular type scale (1.25 or 1.333 ratio). Set line heights between 1.4 and 1.6 for body text. Use OpenType features (ligatures, tabular numbers, small caps) when the font supports them. See `references/typography.md` for the full system.
+
+### Color
+
+Build palettes with intention. Use OKLCH for perceptually uniform color manipulation. Always tint neutrals (never use pure gray or pure black). Dominant color with sharp accent outperforms evenly distributed palettes. Test contrast ratios: 4.5:1 minimum for body text, 3:1 for large text and UI elements. See `references/color-and-contrast.md`.
+
+### Spatial Composition
+
+Use a spacing scale (4px base: 4, 8, 12, 16, 24, 32, 48, 64, 96). Asymmetric layouts, overlapping elements, diagonal flow, and grid-breaking moments create visual interest. Generous negative space communicates confidence. Dense layouts need careful rhythm. See `references/spatial-design.md`.
+
+### Backgrounds and Visual Depth
+
+Never default to flat solid colors. Create atmosphere with gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, grain overlays, or subtle backdrop filters. Depth comes from elevation systems: consistent shadow scales, surface hierarchy, and z-index discipline.
+
+### Motion
+
+One well-orchestrated page load with staggered reveals (using animation-delay) creates more impact than scattered micro-interactions. Use CSS transitions for simple state changes. Use `framer-motion` or the Motion library for React when choreography matters. Never use bounce or elastic easing (it looks dated). Respect `prefers-reduced-motion`. See `references/motion-and-animation.md`.
+
+### Text Animation
+
+For text morphing effects (counters, status changes, tab labels), use `torph` (dependency-free, works with React/Vue/Svelte). Import as `import { TextMorph } from 'torph/react'` and wrap any text that changes dynamically.
+
+### Sound
+
+For UI sound feedback (clicks, notifications, transitions), use the soundcn pattern: inline base64 audio data URIs with a `useSound` hook via Web Audio API. Zero dependencies. See `references/sensory-design.md`.
+
+### Haptics
+
+For mobile web, use the WebHaptics pattern via the Vibration API (`navigator.vibrate()`) to provide tactile feedback on button presses, toggles, and destructive actions. Always gate behind feature detection and user preference. See `references/sensory-design.md`.
+
+### Icons
+
+Use Lucide React as the default icon library (`lucide-react`). For broader searches across 200K+ icons from 150+ collections, use the `better-icons` CLI pattern: search by keyword, retrieve SVG, sync to project. Prefer outline style for UI, solid for emphasis.
+
+### Avatars and Identity
+
+For deterministic avatar generation from strings (usernames, emails, UUIDs), use the Facehash pattern: a React component that generates unique face avatars. Same input always produces the same face. Zero external assets.
+
+---
+
+## Step 3: Implementation Standards
+
+### Single-File Artifacts
+
+When building for claude.ai artifacts (HTML or React), everything goes in one file. No external CSS files, no separate JS. Inline everything. For HTML artifacts, import external scripts only from `https://cdnjs.cloudflare.com`. For React artifacts, use only available libraries (lucide-react, recharts, d3, Three.js r128, Tone, shadcn/ui, Tailwind core utilities, lodash, mathjs, papaparse, Chart.js).
+
+### React Best Practices
+
+Follow these rules (see `references/react-patterns.md` for details):
+
+- Server Components by default, `'use client'` only when needed
+- Colocate state with the component that uses it
+- Prefer composition over prop drilling
+- Use `Suspense` boundaries with meaningful fallbacks
+- Never store derived state, compute it during render
+- Use semantic HTML elements, not `div` soup
+- Memoize expensive computations, not everything
+- Default export for page/route components, named exports for utilities
+
+### CSS Variables for Theming
+
+Always define a CSS variable system for colors, spacing, typography, and shadows. This makes themes swappable and dark mode trivial.
+
+```css
+:root {
+  --color-surface: #fafaf9;
+  --color-text: #1c1917;
+  --color-accent: #dc2626;
+  --radius: 8px;
+  --shadow-sm: 0 1px 2px oklch(0% 0 0 / 0.05);
+}
+```
+
+### Accessibility Defaults
+
+Every interface must include: visible focus indicators (never `outline: none` without replacement), sufficient color contrast, keyboard navigability, ARIA labels on interactive elements without visible text, and `alt` text on meaningful images. Do not treat accessibility as optional.
+
+---
+
+## Step 4: Audit and Polish
+
+Before delivering any interface, run this mental checklist:
+
+1. **Typography audit.** Is there a clear type hierarchy? Are fonts loaded and rendering? Is body text readable at default zoom?
+2. **Color audit.** Does the palette feel cohesive? Do accents draw the eye to the right places? Does it work in both light and dark contexts?
+3. **Spatial audit.** Is spacing consistent? Are elements aligned to an invisible grid? Is there breathing room?
+4. **Interaction audit.** Do all interactive elements have hover, focus, and active states? Are transitions smooth? Is there loading feedback?
+5. **Responsive audit.** Does it work on 375px wide screens? Does it scale gracefully to ultrawide?
+6. **Motion audit.** Does the page load feel choreographed? Are transitions purposeful? Does `prefers-reduced-motion` disable non-essential animation?
+7. **Accessibility audit.** Can you tab through the entire interface? Are contrast ratios sufficient? Do screen readers make sense of the structure?
+
+---
+
+## Step 5: Design System Generation
+
+When asked to create a design system or DESIGN.md, follow the VoltAgent/Stitch format. See `references/design-system.md` for the complete template covering: visual theme and atmosphere, color palette with semantic roles, typography hierarchy, component styling (buttons, cards, inputs, navigation with states), layout principles, depth and elevation system, explicit dos and don'ts, responsive behavior, and an agent prompt guide.
+
+---
+
+## Step 6: Generative and Canvas Art
+
+When the task involves algorithmic art, generative visuals, or static poster/print design, see `references/generative-art.md`. The process: write an algorithmic philosophy (4-6 paragraphs), then express it through p5.js code with seeded randomness, parameter controls, and seed navigation.
+
+---
+
+## Commands
+
+These optional directives can be used to steer design refinement:
+
+| Command | Effect |
+|---|---|
+| `/audit` | Technical quality check: accessibility, performance, responsive |
+| `/critique` | UX design review: hierarchy, clarity, emotional resonance |
+| `/polish` | Final pass: refine spacing, transitions, copy |
+| `/simplify` | Strip to essence, remove visual noise |
+| `/animate` | Add purposeful motion and transitions |
+| `/bolder` | Amplify timid designs with stronger visual choices |
+| `/quieter` | Tone down overly aggressive designs |
+| `/normalize` | Align with design system standards |
+| `/theme` | Generate or apply a color/font theme |
+| `/sound` | Add UI sound effects to interactions |
+| `/haptics` | Add haptic feedback for mobile web |
+| `/redesign` | Audit an existing project, identify design problems, fix them systematically |
+| `/soft` | Apply premium soft aesthetic: generous whitespace, depth, smooth spring animations |
+| `/minimalist` | Apply editorial minimalism: monochrome, crisp borders, inspired by Linear/Notion |
+| `/brutalist` | Apply raw mechanical aesthetic: Swiss typography meets CRT terminal |
+| `/stitch` | Generate a Google Stitch-compatible DESIGN.md for the current project |
+
+---
+
+## The Non-Negotiables
+
+1. No design should ever look like "AI made this." No purple gradients on white. No Inter font. No centered everything. No cards nested in cards. No gray text on colored backgrounds.
+2. Every design must have a clear aesthetic point of view. If it could belong to any product, it belongs to none.
+3. Match implementation complexity to vision. Maximalist designs need elaborate code. Minimalist designs need surgical precision. Both require the same level of care.
+4. Text is always a design element, never an afterthought.
+5. Every detail matters. The shadow radius, the letter spacing, the hover transition duration, the border color in dark mode. These are not small decisions.

package/skills/picasso/references/anti-patterns.md

@@ -0,0 +1,95 @@
+# Anti-Patterns Reference
+
+This is the most important reference file. These are the patterns that make AI-generated interfaces immediately recognizable. Avoid all of them.
+
+---
+
+## Typography Anti-Patterns
+
+- **Inter everywhere.** The default safe choice. It signals "I did not think about fonts."
+- **Roboto, Arial, Helvetica, system-ui as primary.** Same problem.
+- **Space Grotesk on repeat.** Overused in AI/crypto contexts. Pick something else.
+- **Light (300) weight for body text.** Hard to read on most screens.
+- **Centered paragraphs.** Center alignment works for 1-2 lines (headings, quotes). Never for body text.
+- **No max-width on text.** Lines spanning 1400px are unreadable. Cap at 600-750px for body text.
+- **All caps without letter-spacing.** All-caps text needs 0.08-0.15em spacing to be legible.
+- **More than 3 font families.** Two is ideal. Three is the maximum.
+- **Font size under 14px for body text.** Especially on mobile.
+
+---
+
+## Color Anti-Patterns
+
+- **Purple gradient on white background.** The signature AI slop aesthetic.
+- **Pure black text (#000000).** Always use tinted near-black (e.g., oklch(0.15 0.02 260)).
+- **Pure gray (#808080, #cccccc).** Always tint neutrals toward the palette hue.
+- **Gray text on colored backgrounds.** Creates low contrast and looks washed out.
+- **Full-saturation brand colors for large surfaces.** Reserve maximum chroma for small accents. Large areas need reduced saturation.
+- **Too many accent colors.** One primary, one secondary maximum. More creates visual chaos.
+- **Using opacity instead of actual color values.** opacity:0.5 on colored elements creates inconsistent results depending on background.
+- **No dark mode consideration.** Even if not implementing dark mode, design with the possibility in mind.
+
+---
+
+## Layout Anti-Patterns
+
+- **Everything centered vertically and horizontally.** Creates a lifeless vertical highway. Use left-aligned content with intentional centering for specific elements.
+- **Cards nested inside cards.** One level of card is usually enough. Nesting creates visual confusion about hierarchy.
+- **Wrapping everything in cards.** Not every piece of content needs a container with rounded corners and a shadow. Sometimes flat sections, dividers, or whitespace work better.
+- **Uniform rounded corners on everything.** Vary border-radius by context: pills for tags (999px), subtle rounding for cards (8-12px), sharper for data elements (4px).
+- **Equal spacing everywhere.** Groups need tighter internal spacing and wider external spacing. Without this, there is no visual structure.
+- **Three or four equal columns at every breakpoint.** Asymmetric grids (2:1, 3:2) are more interesting and create clearer hierarchy.
+- **Content that could belong to any product.** If the layout has no personality, the design is not done.
+
+---
+
+## Motion Anti-Patterns
+
+- **Bounce/elastic easing.** Feels dated and gimmicky. Use ease-out curves.
+- **Animating everything on the page.** Creates visual noise. Animate the important moments.
+- **transition: all 0.3s.** Animates properties you did not intend. Be specific: `transition: opacity 0.2s, transform 0.3s`.
+- **No loading feedback.** User clicks a button and nothing happens for 2 seconds. Always show progress.
+- **Spinner for content areas.** Use skeleton screens instead. Spinners should be reserved for small inline actions.
+- **Animation without prefers-reduced-motion handling.** Always provide a reduced-motion path.
+
+---
+
+## Interaction Anti-Patterns
+
+- **Placeholder text as the only label.** Disappears on focus. Inaccessible.
+- **outline: none without replacement.** Keyboard users lose all orientation.
+- **Hover-only interactions.** Must have keyboard and touch equivalents.
+- **Custom scrollbars that break native behavior.** Users expect scrolling to work natively.
+- **Toast notifications for errors.** They disappear. Use inline error messages instead.
+- **Alert/confirm dialogs for minor actions.** Blocking the entire page for "Are you sure?" on non-destructive actions.
+- **No focus trapping in modals.** Tab key escapes the modal and the user gets lost.
+- **Links that look like buttons and buttons that look like links.** Use the correct element for the correct purpose.
+
+---
+
+## Code Anti-Patterns
+
+- **div soup.** Use semantic HTML: nav, main, section, article, aside, header, footer.
+- **Inline styles for everything.** Use CSS variables, modules, or Tailwind. Inline styles cannot be overridden or themed.
+- **!important everywhere.** If specificity requires !important, the CSS architecture is broken.
+- **z-index: 9999.** Use a z-index scale (1, 10, 20, 30...) with named CSS variables.
+- **Fixed pixel values for everything.** Use rem for typography and spacing, em for component-internal sizing, px only for borders and shadows.
+- **console.log left in production.** Clean it up.
+
+---
+
+## Content Anti-Patterns
+
+- **"Lorem ipsum" in final deliverables.** Use real or realistic content. Design without content is decoration.
+- **Stock photo people smiling at laptops.** If using imagery, make it contextual.
+- **"Click here" link text.** Links should describe their destination: "View documentation" not "Click here".
+- **"Submit" button text.** Use the specific action: "Create account", "Send message", "Save changes".
+- **Walls of text without hierarchy.** Break content with headings, spacing, and visual rhythm.
+
+---
+
+## The Overall Pattern to Avoid
+
+The "AI slop" aesthetic is recognizable by its combination of: Inter/Roboto font, purple/blue gradient accents, evenly spaced centered layouts, uniform card grids with identical rounded corners, and generic stock imagery. Any single element might be fine in isolation. Together, they signal "an AI made this with zero human judgment."
+
+The antidote is intentionality. Every choice (font, color, spacing, layout, animation) should be a conscious decision tied to the specific context of what you are building.