picasso-skill 1.0.0

package/skills/picasso/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/skills/picasso/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