picasso-skill 2.0.0 → 2.0.2

package/references/brand-and-identity.md

@@ -0,0 +1,136 @@
+# Brand and Identity Reference
+
+## Table of Contents
+1. Logo Sizing Rules
+2. Logo Placement
+3. Logo Lockup Variants
+4. Brand Color Usage
+5. Brand Typography
+6. Consistency Across Pages
+7. When to Bend Brand Rules
+8. Common Mistakes
+
+---
+
+## 1. Logo Sizing Rules
+
+- **Minimum size:** 24px height for icon-only, 32px height for full logo. Below this it's illegible.
+- **Clear space:** Minimum clear space around logo = the height of the logo's icon element. No text or elements may intrude.
+- **Typical sizes by context:**
+
+| Context | Height |
+|---|---|
+| Favicon | 32px |
+| Mobile header | 28-32px |
+| Desktop header | 32-40px |
+| Footer | 24-28px |
+| Hero/marketing | 48-64px |
+| App splash | 80-120px |
+
+```css
+.logo { height: 32px; width: auto; } /* maintain aspect ratio */
+.logo-icon { height: 28px; width: 28px; }
+```
+
+---
+
+## 2. Logo Placement
+
+- **Header:** top-left for LTR, top-right for RTL. Always links to homepage.
+- **Footer:** bottom-left or bottom-center. Smaller than header.
+- **Marketing pages:** centered for hero sections, left-aligned for navigation.
+- **Loading/splash:** centered vertically and horizontally.
+
+The header logo is the most important. It should be the first visual element the user sees, but not dominate the page. Keep it slim.
+
+---
+
+## 3. Logo Lockup Variants
+
+Every brand needs at least 3 logo variants:
+
+1. **Full lockup:** icon + wordmark (for headers, marketing)
+2. **Icon only:** for favicons, app icons, small spaces, mobile headers
+3. **Wordmark only:** for editorial/text-heavy contexts
+
+```jsx
+// Responsive logo: icon on mobile, full on desktop
+<Link href="/" className="flex items-center gap-2">
+  <img src="/logo-icon.svg" alt="" className="h-7 w-7" />
+  <span className="hidden sm:inline text-sm font-bold tracking-tight">Brand Name</span>
+</Link>
+```
+
+---
+
+## 4. Brand Color Usage
+
+Follow the 60-30-10 rule with brand colors:
+- **60%** — neutral surfaces (backgrounds, cards). Brand color should NOT be the 60%.
+- **30%** — supporting colors (borders, secondary text, section backgrounds).
+- **10%** — brand/accent color (CTAs, active states, highlights). This is where brand color goes.
+
+```css
+:root {
+  --brand: oklch(0.55 0.25 250);       /* Primary brand color — use at 10% */
+  --brand-subtle: oklch(0.95 0.03 250); /* Tinted background — use sparingly */
+  --brand-on-dark: oklch(0.70 0.18 250); /* Lighter variant for dark backgrounds */
+}
+```
+
+Never use brand color as background for large areas (hero sections, full-width bars) unless the brand is specifically known for it (like Spotify's green). Large saturated surfaces are fatiguing.
+
+---
+
+## 5. Brand Typography
+
+If the brand has a custom/licensed font, use it for headings only. Body text should be a readable, web-optimized font.
+
+```css
+/* Brand font for headings */
+h1, h2, h3 { font-family: 'Brand Display', var(--font-body); }
+
+/* Readable font for body */
+body { font-family: 'DM Sans', system-ui, sans-serif; }
+```
+
+If the brand font isn't available for web, find the closest web-safe alternative:
+- Futura → use Outfit or Jost
+- Helvetica Neue → use Inter (only acceptable here) or Geist
+- Garamond → use EB Garamond or Cormorant
+
+---
+
+## 6. Consistency Across Pages
+
+Every page should share:
+- Same header and footer (identical, not "similar")
+- Same color palette (no page-specific colors)
+- Same typography scale
+- Same border-radius philosophy
+- Same spacing scale
+
+Variation should come from layout and content, not from inconsistent styling. A dashboard page and a marketing page can look different through layout while sharing the same design tokens.
+
+---
+
+## 7. When to Bend Brand Rules
+
+Strict brand adherence isn't always right:
+- **Data-dense dashboards:** Brand color as accent only. Don't fight with data colors.
+- **Error states:** Use standard red for errors, not brand color. Users need instant recognition.
+- **Third-party embeds:** Payment forms, maps, chat widgets have their own styling. Don't fight it.
+- **Dark mode:** Brand color may need lightness/chroma adjustment to maintain contrast.
+- **Accessibility:** If brand colors don't meet WCAG contrast, accessibility wins.
+
+---
+
+## 8. Common Mistakes
+
+- **Logo too small in the header.** Minimum 28px height. Users need to identify the brand instantly.
+- **Brand color as full-width background.** Fatiguing. Use at 10% ratio maximum.
+- **Different fonts on every page.** Pick 2 fonts and use them everywhere.
+- **Logo without clear space.** Crowded logos look unprofessional. Enforce minimum padding.
+- **No icon-only variant.** Mobile needs a compact logo. Don't just shrink the full lockup.
+- **Brand color unchanged in dark mode.** Adjust lightness and chroma for dark backgrounds.
+- **Inconsistent border radius between pages.** One sharp page and one rounded page = two brands.

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.