picasso-skill 1.5.1 → 2.0.0

package/skills/picasso/references/dark-mode.md

@@ -0,0 +1,199 @@
+# Dark Mode Reference
+
+## Table of Contents
+1. Preference Hierarchy
+2. CSS Custom Properties Approach
+3. Mode Transition
+4. Surface Elevation in Dark Mode
+5. Color Adjustments
+6. Image and Media Handling
+7. Testing Dark Mode
+8. Forced Colors and High Contrast
+9. Common Mistakes
+
+---
+
+## 1. Preference Hierarchy
+
+System preference is the default. User override persists via localStorage. Never force dark mode without a toggle.
+
+```js
+// Check system preference, then user override
+const stored = localStorage.getItem('theme');
+const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+const isDark = stored ? stored === 'dark' : systemDark;
+document.documentElement.setAttribute('data-theme', isDark ? 'dark' : 'light');
+```
+
+```css
+/* System preference as base */
+:root { color-scheme: light dark; }
+
+/* Light (default) */
+:root, [data-theme="light"] {
+  --surface-0: oklch(0.99 0.005 var(--hue));
+  --text-primary: oklch(0.15 0.02 var(--hue));
+}
+
+/* Dark */
+[data-theme="dark"] {
+  --surface-0: oklch(0.11 0.02 var(--hue));
+  --text-primary: oklch(0.93 0.01 var(--hue));
+}
+```
+
+---
+
+## 2. CSS Custom Properties Approach
+
+Define all colors as CSS variables. Never hardcode hex in components. Dark mode is a variable swap, not a rewrite.
+
+```css
+[data-theme="dark"] {
+  --surface-0: oklch(0.11 0.02 230);   /* page bg */
+  --surface-1: oklch(0.14 0.02 230);   /* card bg */
+  --surface-2: oklch(0.17 0.022 230);  /* elevated bg */
+  --surface-3: oklch(0.20 0.024 230);  /* hover bg */
+  --border: oklch(0.22 0.015 230);
+  --text-primary: oklch(0.93 0.01 230);
+  --text-secondary: oklch(0.62 0.02 230);
+  --text-muted: oklch(0.42 0.015 230);
+}
+```
+
+---
+
+## 3. Mode Transition
+
+Never instant-swap. Use a 200ms opacity transition on the body. Disable transitions during the swap to prevent every element animating individually.
+
+```css
+/* Add this class during theme switch, remove after 200ms */
+.theme-transitioning * {
+  transition: none !important;
+}
+
+body {
+  transition: background-color 0.2s ease-out, color 0.2s ease-out;
+}
+```
+
+```js
+function toggleTheme() {
+  document.body.classList.add('theme-transitioning');
+  const next = document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark';
+  document.documentElement.dataset.theme = next;
+  localStorage.setItem('theme', next);
+  requestAnimationFrame(() => {
+    requestAnimationFrame(() => {
+      document.body.classList.remove('theme-transitioning');
+    });
+  });
+}
+```
+
+---
+
+## 4. Surface Elevation in Dark Mode
+
+In dark mode, elevated surfaces get LIGHTER, not darker. This is the opposite of light mode where shadows darken surfaces. Without this, dark mode looks flat.
+
+```
+Light mode elevation:  surface-0 (lightest) → surface-3 (slightly darker)
+Dark mode elevation:   surface-0 (darkest)  → surface-3 (slightly lighter)
+```
+
+Shadows are nearly invisible in dark mode. Replace with surface lightness differentiation and subtle border glow:
+
+```css
+[data-theme="dark"] .card {
+  background: var(--surface-1);
+  border: 1px solid oklch(1 0 0 / 0.06);
+  /* Shadow optional — use border + surface tint instead */
+  box-shadow: 0 0 0 1px oklch(1 0 0 / 0.03);
+}
+```
+
+---
+
+## 5. Color Adjustments
+
+Accent colors need lower chroma in dark mode. Full-saturation accents on dark backgrounds are harsh.
+
+```css
+:root { --accent: oklch(0.55 0.25 250); }         /* light: saturated */
+[data-theme="dark"] { --accent: oklch(0.65 0.18 250); } /* dark: lighter, less chroma */
+```
+
+Semantic colors also need adjustment:
+- Success green: lighter, less saturated
+- Error red: lighter to maintain contrast
+- Warning amber: reduce chroma to avoid glowing
+
+Text colors: minimum lightness 0.60 in OKLCH for body text on dark backgrounds. Below 0.55 looks washed out on cheap screens even if it passes WCAG.
+
+---
+
+## 6. Image and Media Handling
+
+Dim images slightly in dark mode to reduce glare. SVGs should use currentColor or CSS variables.
+
+```css
+[data-theme="dark"] img:not([data-no-dim]) {
+  filter: brightness(0.9) contrast(1.05);
+}
+
+[data-theme="dark"] svg { color: var(--text-primary); }
+```
+
+For decorative images, consider `mix-blend-mode: luminosity` to desaturate:
+```css
+[data-theme="dark"] .hero-image {
+  mix-blend-mode: luminosity;
+  opacity: 0.8;
+}
+```
+
+---
+
+## 7. Testing Dark Mode
+
+Dark mode is not "invert the colors." Test these specifically:
+
+1. **Contrast ratios** — recheck all text/background pairs. WCAG ratios change.
+2. **Shadows** — are they visible? If not, use border or surface tint instead.
+3. **Form inputs** — autofill styling overrides your dark background. Fix with `-webkit-box-shadow: 0 0 0 1000px var(--surface-1) inset`.
+4. **Selection color** — `::selection` background needs to contrast with dark text highlight.
+5. **Scrollbar** — custom scrollbar thumb must be visible on dark track.
+6. **Third-party embeds** — iframes, maps, payment forms may not respect your dark mode.
+7. **Screenshots** — take a screenshot and look at it on a non-retina screen. Subtle contrast often vanishes.
+
+---
+
+## 8. Forced Colors and High Contrast
+
+Windows High Contrast mode (`@media (forced-colors: active)`) overrides ALL custom colors. Your tinted neutrals, subtle borders, and custom focus rings will disappear.
+
+```css
+@media (forced-colors: active) {
+  .card { border: 1px solid CanvasText; }
+  :focus-visible { outline: 2px solid Highlight; }
+  .btn-primary { border: 2px solid ButtonText; }
+}
+```
+
+Never use `forced-color-adjust: none` globally. Only on specific elements where you've provided a system-color fallback.
+
+---
+
+## 9. Common Mistakes
+
+- **Instant theme swap without transition.** Jarring. Always fade (200ms).
+- **Shadows that work in light but vanish in dark.** Replace with borders + surface tint.
+- **Same accent chroma in both modes.** Reduce chroma for dark mode.
+- **Checking contrast only in light mode.** Dark mode ratios are different — recheck.
+- **`background: black` for dark mode.** Never pure black. Tint toward your hue.
+- **Not testing autofill.** Browsers apply white backgrounds to autofilled inputs.
+- **Not testing scrollbar.** Custom scrollbar may be invisible on dark backgrounds.
+- **Storing theme in state instead of localStorage.** Causes flash of wrong theme on reload.
+- **No `color-scheme: dark` declaration.** Browser UI elements (scrollbars, form controls) won't adapt without it.

package/skills/picasso/references/depth-and-elevation.md

@@ -0,0 +1,211 @@
+# Depth and Elevation Reference
+
+## Table of Contents
+1. The Layering Technique
+2. Dual Shadow System
+3. Inset Shadows
+4. Gradient + Inner Shadow Combo
+5. Semantic Z-Index Scale
+6. Shadow Usage Guide
+7. Dark Mode Shadow Adjustments
+8. The "Remove Borders" Rule
+9. Hover Elevation Pattern
+10. Common Mistakes
+
+---
+
+## 1. The Layering Technique
+
+The single highest-ROI technique for transforming flat UIs into ones that feel crafted. Three steps:
+
+1. **Create color layers.** Generate 3-4 shades of your base color by incrementing lightness in OKLCH:
+```css
+--bg-deep:    oklch(0.18 0.01 var(--hue));   /* page background (deepest) */
+--bg-base:    oklch(0.22 0.01 var(--hue));   /* card/section background */
+--bg-raised:  oklch(0.26 0.012 var(--hue));  /* elevated interactive elements */
+--bg-highest: oklch(0.30 0.015 var(--hue));  /* selected/active states */
+```
+In light mode, reverse the direction: the page is lightest, and elevated elements are slightly darker or lighter depending on the effect.
+
+2. **Layer elements.** Darker backgrounds feel recessed. Lighter surfaces feel elevated. Stack your components accordingly: page → section → card → interactive element.
+
+3. **Add dual shadows.** A light inset shadow on top combined with a dark shadow at the bottom creates realistic depth. See section 2 below.
+
+---
+
+## 2. Dual Shadow System
+
+Combine a light inset highlight on the top edge with a dark drop shadow at the bottom. This simulates overhead light hitting a raised surface.
+
+```css
+/* Small: subtle, most use cases (cards at rest, navbar, buttons) */
+--shadow-sm:
+  inset 0 1px 0 0 oklch(1 0 0 / 0.05),
+  0 1px 2px 0 oklch(0 0 0 / 0.15);
+
+/* Medium: emphasis and hover states */
+--shadow-md:
+  inset 0 1px 0 0 oklch(1 0 0 / 0.08),
+  0 2px 8px -2px oklch(0 0 0 / 0.2);
+
+/* Large: modals, popovers, focused cards */
+--shadow-lg:
+  inset 0 1px 0 0 oklch(1 0 0 / 0.1),
+  0 8px 24px -4px oklch(0 0 0 / 0.25);
+
+/* Extra large: hero overlays, dramatic emphasis */
+--shadow-xl:
+  0 16px 48px -8px oklch(0 0 0 / 0.3),
+  0 4px 12px -2px oklch(0 0 0 / 0.15);
+```
+
+These values use OKLCH alpha for consistency with your color tokens. Adapt the hue to match your palette if desired (e.g., `oklch(0 0 0 / 0.15)` could become `oklch(0 0.01 var(--hue) / 0.15)` for tinted shadows).
+
+---
+
+## 3. Inset Shadows
+
+For elements that should feel *recessed* into the surface (input fields, progress bars, table cells, code blocks):
+
+```css
+.recessed {
+  box-shadow:
+    inset 0 2px 4px 0 oklch(0 0 0 / 0.15),   /* dark shadow at top */
+    inset 0 -1px 0 0 oklch(1 0 0 / 0.05);     /* subtle light at bottom */
+}
+```
+
+Inset shadows reverse the mental model: instead of floating above the surface, the element sits below it. Use this for:
+- Text inputs (the field feels carved into the form)
+- Progress bar tracks (the bar sits inside a groove)
+- Recessed stat cards (metrics feel embedded, not floating)
+
+---
+
+## 4. Gradient + Inner Shadow Combo
+
+Simulates directional light hitting a raised surface from above. Powerful for selected cards, active states, and CTAs:
+
+```css
+.elevated-card {
+  background: linear-gradient(
+    to bottom,
+    oklch(0.28 0.015 var(--hue)),  /* lighter at top (light source) */
+    oklch(0.24 0.01 var(--hue))    /* darker at bottom */
+  );
+  box-shadow:
+    inset 0 1px 0 0 oklch(1 0 0 / 0.08),  /* highlight at top edge */
+    0 2px 8px -2px oklch(0 0 0 / 0.2);     /* shadow beneath */
+}
+```
+
+This combination makes elements feel physically present. Reserve it for the most important interactive elements on the page -- overuse dilutes the effect.
+
+---
+
+## 5. Semantic Z-Index Scale
+
+Use named z-index values instead of magic numbers. This prevents z-index wars and makes the stacking context explicit:
+
+```css
+--z-dropdown: 100;
+--z-sticky:   200;
+--z-fixed:    300;
+--z-modal:    400;
+--z-toast:    500;
+--z-tooltip:  600;
+```
+
+Rules:
+- Never use bare numbers. Always reference the variable.
+- Never go above 600 unless you have a documented reason.
+- Modals need a backdrop at `--z-modal - 1` (399).
+- Toasts should float above modals so errors are visible during dialogs.
+
+---
+
+## 6. Shadow Usage Guide
+
+| Element | Shadow Level | Additional Treatment |
+|---------|-------------|---------------------|
+| Cards (default) | sm | -- |
+| Cards (hover) | md | transition 150ms |
+| Selected card | md + gradient | light inset top |
+| Modal / dialog | xl | overlay backdrop |
+| Dropdown menu | lg | -- |
+| Navbar (sticky) | sm | only when scrolled |
+| Input (focus) | -- | accent ring instead |
+| Recessed element | inset | dark top + light bottom |
+| Progress bar | inset sm | inside container |
+| Buttons (default) | sm | -- |
+| Buttons (active) | inset sm | press-in effect |
+| Tooltip | md | -- |
+
+Not every element needs a shadow. Use shadows to communicate interactive hierarchy: elements the user can act on float above static content.
+
+---
+
+## 7. Dark Mode Shadow Adjustments
+
+Shadows are far less visible against dark backgrounds. Compensate with these techniques:
+
+1. **Increase shadow opacity** by 0.05-0.10 compared to light mode values
+2. **Add a subtle border** (1px `oklch(1 0 0 / 0.05)`) for edge definition where shadows alone are too faint
+3. **Use inner glow** instead of drop shadows for the "elevated" feeling on small elements
+4. **Higher surface = lighter background** -- in dark mode this is the primary depth cue, more important than shadows
+
+```css
+[data-theme="dark"] {
+  --shadow-sm:
+    inset 0 1px 0 0 oklch(1 0 0 / 0.03),
+    0 1px 3px 0 oklch(0 0 0 / 0.25);
+  --shadow-md:
+    inset 0 1px 0 0 oklch(1 0 0 / 0.05),
+    0 3px 12px -3px oklch(0 0 0 / 0.35);
+}
+```
+
+---
+
+## 8. The "Remove Borders" Rule
+
+When you have established a clear color layering system (darker background → lighter card → lightest interactive element), borders on the lighter elements become redundant. The color contrast already creates visual separation. Remove them.
+
+Keep borders only where:
+- Color layering alone does not provide enough contrast (e.g., two surfaces with very similar lightness)
+- You need to indicate a semantic boundary (form fields, table cells)
+- The element is interactive and the border communicates state (focus, error)
+
+This rule significantly reduces visual noise and makes the layering technique more effective.
+
+---
+
+## 9. Hover Elevation Pattern
+
+```css
+.card {
+  box-shadow: var(--shadow-sm);
+  transition: box-shadow 150ms ease-out, transform 150ms ease-out;
+}
+.card:hover {
+  box-shadow: var(--shadow-md);
+  transform: translateY(-2px);
+}
+```
+
+Key constraints:
+- Keep the translateY subtle: 1-3px maximum. Exaggerated lifts (5px+) feel cheap and dated.
+- Always transition both shadow and transform together for a cohesive effect.
+- On touch devices, this hover state should not apply (use `@media (hover: hover)`).
+
+---
+
+## 10. Common Mistakes
+
+- Using the same `box-shadow` on every element (no hierarchy, everything looks the same)
+- Shadow blur radius too large (20px+ on cards creates a fuzzy, unfocused look)
+- Forgetting to adjust shadows for dark mode (invisible shadows destroy the depth system)
+- Overusing shadows on flat, decorative elements that do not need elevation
+- Using `filter: drop-shadow()` when `box-shadow` would suffice (drop-shadow does not support inset and renders differently)
+- Relying solely on shadows for depth without the color layering foundation (shadows alone look stuck-on)
+- Hard-coded z-index values like `z-index: 9999` (always use the semantic scale)

package/skills/picasso/references/i18n-visual-patterns.md

@@ -0,0 +1,177 @@
+# Internationalization Visual Patterns Reference
+
+## Table of Contents
+1. Logical Properties
+2. RTL Layout Mirroring
+3. Text Expansion by Language
+4. CJK Text Rendering
+5. Number and Currency Formatting
+6. Font Stacks for Multi-Language
+7. Icon Mirroring in RTL
+8. Common Mistakes
+
+---
+
+## 1. Logical Properties
+
+Replace physical properties with logical ones. This makes RTL support automatic.
+
+| Physical (avoid) | Logical (use) |
+|---|---|
+| `margin-left` | `margin-inline-start` |
+| `margin-right` | `margin-inline-end` |
+| `padding-left` | `padding-inline-start` |
+| `text-align: left` | `text-align: start` |
+| `float: left` | `float: inline-start` |
+| `border-left` | `border-inline-start` |
+| `left: 0` | `inset-inline-start: 0` |
+
+```css
+/* Good: works in both LTR and RTL */
+.sidebar { margin-inline-end: 2rem; padding-inline-start: 1rem; }
+
+/* Bad: breaks in RTL */
+.sidebar { margin-right: 2rem; padding-left: 1rem; }
+```
+
+---
+
+## 2. RTL Layout Mirroring
+
+Set `dir="auto"` on user-generated content. Set `dir="rtl"` on the `<html>` element for RTL languages.
+
+```html
+<html lang="ar" dir="rtl">
+```
+
+Flexbox and Grid automatically reverse in RTL when using logical properties. No extra CSS needed.
+
+```css
+/* This works in both directions automatically */
+.nav { display: flex; gap: 1rem; }
+.card { display: grid; grid-template-columns: auto 1fr; }
+```
+
+---
+
+## 3. Text Expansion by Language
+
+English text expands significantly when translated. Design for the longest likely translation.
+
+| Language | Expansion from English |
+|---|---|
+| German | +30-35% |
+| French | +15-20% |
+| Finnish | +30-40% |
+| Russian | +15-25% |
+| Chinese | -30-50% (shorter) |
+| Japanese | -20-40% (shorter) |
+| Arabic | +20-25% |
+
+Rules:
+- Never use fixed-width containers for translatable text.
+- Buttons: use `min-width` not `width`. Allow text to wrap or grow.
+- Navigation: test with German translations (longest common language).
+- Truncate with `text-overflow: ellipsis` as a last resort, never as the design.
+
+```css
+/* Good: grows with content */
+.btn { min-width: 120px; padding-inline: 1.5rem; white-space: nowrap; }
+
+/* Bad: text overflows in German */
+.btn { width: 120px; }
+```
+
+---
+
+## 4. CJK Text Rendering
+
+Chinese, Japanese, and Korean text has different line-breaking and spacing rules.
+
+```css
+/* Allow CJK text to break at any character */
+.cjk-text {
+  line-break: auto;
+  word-break: keep-all; /* Korean: don't break within words */
+  overflow-wrap: break-word;
+}
+
+/* CJK doesn't need letter-spacing for readability */
+:lang(zh), :lang(ja), :lang(ko) {
+  letter-spacing: 0;
+}
+```
+
+CJK text is denser — reduce line-height slightly:
+```css
+:lang(zh), :lang(ja) { line-height: 1.7; } /* vs 1.5 for Latin */
+```
+
+---
+
+## 5. Number and Currency Formatting
+
+Never hardcode currency symbols or number formats. Use `Intl.NumberFormat`.
+
+```js
+// Automatic locale-aware formatting
+new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(1234.56)
+// → "$1,234.56"
+
+new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(1234.56)
+// → "1.234,56 €"
+
+new Intl.NumberFormat('ja-JP', { style: 'currency', currency: 'JPY' }).format(1234)
+// → "￥1,234"
+```
+
+For dates: use `Intl.DateTimeFormat`, never manual formatting.
+
+---
+
+## 6. Font Stacks for Multi-Language
+
+Include system fonts per script as fallbacks:
+
+```css
+body {
+  font-family:
+    'Your Custom Font',        /* Latin */
+    'Noto Sans SC',            /* Simplified Chinese */
+    'Noto Sans JP',            /* Japanese */
+    'Noto Sans KR',            /* Korean */
+    'Noto Sans Arabic',        /* Arabic */
+    system-ui, sans-serif;     /* Fallback */
+}
+```
+
+Google's Noto family covers every Unicode script. Use it as the universal fallback.
+
+---
+
+## 7. Icon Mirroring in RTL
+
+Icons that imply direction MUST mirror in RTL. Icons that don't imply direction must NOT.
+
+**Mirror in RTL:** arrows, back/forward, reply, undo/redo, text indent, send, search (if it implies reading direction), progress bars.
+
+**Do NOT mirror:** play/pause, checkmarks, plus/minus, clock, globe, user, settings gear, download, external link.
+
+```css
+[dir="rtl"] .icon-directional {
+  transform: scaleX(-1);
+}
+```
+
+---
+
+## 8. Common Mistakes
+
+- **Hardcoding `left`/`right` in CSS.** Use logical properties.
+- **Fixed-width buttons.** They overflow in German/Finnish. Use `min-width`.
+- **Testing only in English.** Design breaks with 35% longer strings.
+- **`text-align: left` instead of `text-align: start`.** Breaks RTL.
+- **Mirroring ALL icons in RTL.** Only directional icons should flip.
+- **Hardcoding date formats.** `01/02/2026` means different dates in US vs UK. Use `Intl.DateTimeFormat`.
+- **Not loading CJK fonts.** System fonts for CJK vary wildly. Include Noto Sans.
+- **Ignoring `dir="auto"` on user content.** A Hebrew comment in an English page needs auto-detection.