picasso-skill 1.6.0 → 2.0.1

package/references/code-typography.md

@@ -0,0 +1,222 @@
+# Code Typography Reference
+
+## Table of Contents
+1. Monospace Font Selection
+2. Code Block Design
+3. Syntax Highlighting Accessibility
+4. Copy-to-Clipboard
+5. Responsive Code Blocks
+6. Inline Code Styling
+7. Diff Views
+8. Terminal Output
+9. Common Mistakes
+
+---
+
+## 1. Monospace Font Selection
+
+| Font | Ligatures | Style | Best For |
+|---|---|---|---|
+| JetBrains Mono | Yes | Clean, geometric | General purpose, IDEs |
+| Fira Code | Yes | Slightly rounded | Tutorials, docs |
+| Source Code Pro | No | Adobe, professional | Enterprise, clean look |
+| IBM Plex Mono | No | Corporate, legible | Documentation |
+| Geist Mono | No | Vercel, modern | Next.js projects |
+| Cascadia Code | Yes | Microsoft, playful | Terminals |
+
+```css
+code, pre, .mono {
+  font-family: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'Consolas', monospace;
+  font-feature-settings: 'liga' 1, 'calt' 1; /* enable ligatures */
+  font-variant-ligatures: common-ligatures;
+}
+```
+
+Ligatures: `=>` becomes ⇒, `!==` becomes ≢, `>=` becomes ≥. Enable for display, disable for editing if users copy code.
+
+---
+
+## 2. Code Block Design
+
+```css
+pre {
+  background: var(--surface-1);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 1rem 1.25rem;
+  font-size: 0.875rem;    /* 14px — slightly smaller than body */
+  line-height: 1.65;       /* Looser than body text for readability */
+  overflow-x: auto;
+  tab-size: 2;
+  -moz-tab-size: 2;
+}
+
+/* Dark mode code blocks on light sites */
+[data-theme="light"] pre {
+  background: oklch(0.14 0.02 230);
+  color: oklch(0.90 0.01 230);
+}
+```
+
+Line numbers (optional):
+```css
+pre.line-numbers {
+  counter-reset: line;
+  padding-left: 3.5rem;
+  position: relative;
+}
+pre.line-numbers .line::before {
+  counter-increment: line;
+  content: counter(line);
+  position: absolute;
+  left: 1rem;
+  color: var(--text-muted);
+  font-size: 0.75rem;
+  user-select: none; /* don't copy line numbers */
+}
+```
+
+---
+
+## 3. Syntax Highlighting Accessibility
+
+Every token color must have **minimum 3:1 contrast** against the code block background. Don't rely on color alone — use font-weight or font-style for emphasis.
+
+| Token Type | Suggested OKLCH (dark bg) | Purpose |
+|---|---|---|
+| Keywords | `oklch(0.75 0.15 300)` | purple-ish, bold |
+| Strings | `oklch(0.72 0.14 150)` | green |
+| Numbers | `oklch(0.75 0.12 60)` | amber |
+| Comments | `oklch(0.50 0.01 230)` | muted, italic |
+| Functions | `oklch(0.78 0.10 230)` | blue |
+| Variables | `oklch(0.85 0.01 230)` | near-white |
+
+```css
+.token-keyword { color: oklch(0.75 0.15 300); font-weight: 600; }
+.token-string { color: oklch(0.72 0.14 150); }
+.token-comment { color: oklch(0.50 0.01 230); font-style: italic; }
+```
+
+---
+
+## 4. Copy-to-Clipboard
+
+Position: top-right corner of the code block. Show on hover. Provide visual feedback.
+
+```jsx
+function CopyButton({ code }) {
+  const [copied, setCopied] = useState(false);
+
+  return (
+    <button
+      onClick={() => {
+        navigator.clipboard.writeText(code);
+        setCopied(true);
+        setTimeout(() => setCopied(false), 2000);
+      }}
+      className="absolute top-2 right-2 p-1.5 rounded-md bg-white/5 hover:bg-white/10 text-xs text-muted"
+      aria-label="Copy code"
+    >
+      {copied ? 'Copied' : 'Copy'}
+    </button>
+  );
+}
+```
+
+---
+
+## 5. Responsive Code Blocks
+
+Code blocks should **scroll horizontally** on mobile, never wrap. Terminal output CAN wrap.
+
+```css
+pre {
+  overflow-x: auto;
+  white-space: pre;         /* code: no wrap */
+  -webkit-overflow-scrolling: touch; /* smooth scroll on iOS */
+}
+
+pre.terminal {
+  white-space: pre-wrap;    /* terminal: wrap is OK */
+  word-break: break-all;
+}
+
+/* Hide scrollbar but keep functionality */
+pre::-webkit-scrollbar { height: 4px; }
+pre::-webkit-scrollbar-thumb { background: var(--border); border-radius: 4px; }
+```
+
+On very small screens (< 375px), consider reducing code font-size to 12px.
+
+---
+
+## 6. Inline Code Styling
+
+Inline code needs subtle visual distinction from body text:
+
+```css
+code:not(pre code) {
+  background: var(--surface-2);
+  padding: 0.15em 0.4em;
+  border-radius: 4px;
+  font-size: 0.9em;        /* slightly smaller than surrounding text */
+  font-weight: 500;
+  border: 1px solid var(--border);
+}
+```
+
+Never use inline code for emphasis. It's for code references (`useState`, `border-radius`, `GET /api/users`), not for highlighting words.
+
+---
+
+## 7. Diff Views
+
+Use color + icon, not color alone (colorblind users):
+
+```css
+.diff-add {
+  background: oklch(0.62 0.19 150 / 0.1);
+  border-left: 3px solid oklch(0.62 0.19 150);
+}
+.diff-add::before { content: '+'; color: oklch(0.62 0.19 150); }
+
+.diff-remove {
+  background: oklch(0.55 0.22 25 / 0.1);
+  border-left: 3px solid oklch(0.55 0.22 25);
+  text-decoration: line-through;
+  opacity: 0.7;
+}
+.diff-remove::before { content: '-'; color: oklch(0.55 0.22 25); }
+```
+
+---
+
+## 8. Terminal Output
+
+Terminal/console styling should feel distinct from code:
+
+```css
+.terminal {
+  background: oklch(0.08 0.01 230);
+  color: oklch(0.80 0.01 150); /* slight green tint for terminal feel */
+  font-family: 'JetBrains Mono', monospace;
+  padding: 1rem;
+  border-radius: 8px;
+}
+.terminal .prompt { color: oklch(0.65 0.10 230); } /* blue prompt */
+.terminal .output { color: oklch(0.75 0.01 230); } /* neutral output */
+.terminal .error { color: oklch(0.65 0.22 25); }   /* red errors */
+```
+
+---
+
+## 9. Common Mistakes
+
+- **Code font too large.** 14px for blocks, 0.9em for inline. Larger fights with body text.
+- **No horizontal scroll on code blocks.** Wrapping code breaks readability. Always `overflow-x: auto`.
+- **Syntax colors with < 3:1 contrast.** Comments especially — they tend to be too faint.
+- **Color-only diff indication.** Always add + / - markers or icons alongside color.
+- **Copying includes line numbers.** Use `user-select: none` on line number elements.
+- **Same styling for code blocks and terminal.** They serve different purposes. Terminal gets darker bg, green tint.
+- **`font-family: monospace` without named fonts.** Browsers default to Courier New which looks dated. Always specify a modern monospace font first.
+- **No copy button.** Users shouldn't have to triple-click and drag to copy code.

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