picasso-skill 1.5.1 → 2.0.0

package/references/conversion-design.md

@@ -0,0 +1,193 @@
+# Conversion Design & Landing Page Reference
+
+## 1. Landing Page Anatomy
+
+### Hero Section Variations
+
+| Pattern | Best For | Key Spec |
+|---------|----------|----------|
+| **Split** (text left, visual right) | SaaS, B2B | 50/50 or 60/40 split; text column gets primary CTA |
+| **Centered** (text stacked over image) | Brand launches, simple products | Max 600-700px text width; single focal CTA below headline |
+| **Full-bleed media** (text overlay) | Lifestyle, hospitality, portfolios | 4.5:1 contrast on overlay text; darken overlay at 40-60% opacity |
+| **Video background** | High-engagement storytelling | Auto-mute; < 5s to first frame; fallback static image required |
+
+**Above-the-fold priorities (in order):** Value proposition headline, supporting subhead (1-2 sentences), primary CTA, trust signal (logo bar or stat).
+
+Users form an opinion in **50 milliseconds**. Every extra 100KB in hero media increases bounce by ~1.8%.
+
+### CTA Design
+
+- **Minimum size:** 44x44px (Apple/WCAG), 48x48px (Material).
+- **Color:** 3:1+ contrast ratio against background; prominence matters more than specific color.
+- **Placement:** Above fold in hero; repeat after mid-page value build; repeat near final content.
+- **Copy:** First-person ("Start my free trial") outperforms second-person by 10-90%.
+- **Repetition:** Single consistent CTA repeated 2-3 times, not multiple competing actions.
+
+### Social Proof Patterns
+
+| Type | Effectiveness | Placement |
+|------|--------------|-----------|
+| Star ratings + reviews | 82% influence | Near pricing/CTA |
+| Customer testimonials | 78% influence | After feature sections |
+| Video testimonials | +34% conversion lift | Mid-page or dedicated section |
+| Client logos | Trust signal | Directly below hero |
+| User count / stats | Up to +43% conversion | Hero section or sub-hero |
+| Security badges | Reduces abandonment | Near forms and payment |
+
+### Pricing Page Design
+
+**3 tiers optimal** (center-stage effect). Structure per card:
+1. Tier name + "best for" one-liner
+2. Price with billing toggle (default annual; show savings as % AND dollar)
+3. Primary CTA button (below price, above features)
+4. 8-12 core features with checkmarks/values
+
+**Highlight recommended tier:** Distinct background, "Most Popular" badge, border emphasis, or elevation. Produces 12-15% lift in mid-tier selection.
+
+---
+
+## 2. Conversion Psychology
+
+### Visual Hierarchy for Conversion
+
+Follow the **F-pattern**: headline, key benefit, and CTA along the top-left-to-bottom path. **Z-pattern** for simpler pages: logo top-left, nav CTA top-right, content center diagonal, conversion CTA bottom-right.
+
+### Scarcity & Urgency (Ethical Only)
+- Real-time inventory counts -- only truthful data.
+- Time-limited offers with visible countdown -- only genuine deadlines.
+- Social proof urgency ("42 people viewing") -- must reflect real data.
+
+### Trust Signals Hierarchy
+1. Security badges (SSL, payment logos) -- near checkout/forms.
+2. Money-back guarantees -- near CTA.
+3. Third-party reviews (G2, Trustpilot) -- 82% influence.
+4. Customer logos -- below hero.
+5. Certifications (SOC 2, GDPR, HIPAA) -- footer or trust section.
+
+### Friction Reduction
+- Each additional form field reduces completion by 3-5%.
+- Multi-step forms: 300% higher conversion on mobile vs single long form.
+- Progress bars: +20-30% form completion when visible.
+- Smart defaults: pre-fill known data; appropriate input types.
+- Single-column layout mandatory on mobile.
+- Inline validation on blur, not on submit.
+
+---
+
+## 3. Mobile Conversion Patterns
+
+### Sticky CTAs
+- Position 100-150px from bottom viewport, above gesture areas.
+- 10-20% conversion improvement on long pages.
+- Must not cover critical content; include dismiss option.
+- Pair with micro trust note: "No credit card required."
+
+### Thumb Zone Design
+- **Primary actions:** Lower-center of screen (natural thumb reach).
+- **Navigation:** Bottom bar with 3-5 destinations.
+- **Avoid:** Top corners for frequent actions.
+- **Tap targets:** Minimum 48px square with spacing.
+
+### Bottom Sheets & Swipe
+- Bottom sheets for secondary actions, filters, confirmations.
+- Swipe-to-dismiss for non-critical modals.
+- Swipe actions on list items for quick operations.
+
+### One-Tap Actions
+- Apple Pay / Google Pay for instant checkout.
+- Social login to reduce signup friction.
+- Quick-reply chips in notifications and chat.
+
+---
+
+## 4. Navigation & Information Architecture
+
+### Navigation by App Type
+
+| App Type | Primary Pattern | Key Feature |
+|----------|----------------|-------------|
+| **SaaS** | Left sidebar + top bar | Collapsible sidebar; breadcrumbs for depth |
+| **E-commerce** | Mega menu + category nav | Faceted filtering; persistent cart with count |
+| **Content** | Top nav + hamburger (mobile) | Search-forward; reading progress indicator |
+| **Social** | Bottom tab bar (mobile) | 3-5 tabs; notification badges; create center |
+
+### Search UX
+- Autocomplete after 2-3 characters; limit to 5-7 results.
+- Display recent searches on focus before typing.
+- Surface top 3-5 filters inline; bottom sheet for advanced.
+- No results: offer spelling corrections, related terms, category browsing.
+
+### Infinite Scroll vs Pagination
+
+| Criterion | Pagination | Infinite Scroll | Load More |
+|-----------|-----------|----------------|-----------|
+| Content type | Structured data, tables | Discovery feeds, social | Catalogs, search |
+| User intent | Find specific item | Browse/explore | Mixed |
+| SEO need | High (unique URLs) | Low | Medium |
+| Accessibility | Best | Worst | Good |
+| Mobile performance | Good | Memory risk | Good |
+
+### Breadcrumbs
+Use for hierarchies 3+ levels deep. Place below top nav, above page title. Truncate middle items on mobile with ellipsis.
+
+---
+
+## 5. Onboarding UX
+
+### Progressive Onboarding Framework
+
+**Phase 1 -- Signup:** Ask only email + password (or social login). Defer profile details until after first value moment.
+
+**Phase 2 -- First-run experience:** Welcome screen with 1-2 sentence value prop. 3-5 step setup wizard for essential configuration. Pre-populated sample data so the product feels alive.
+
+**Phase 3 -- Feature discovery (ongoing):** Contextual tooltips triggered by user behavior, not on first load. Checklist widget showing setup progress (drives 70%+ completion). Celebrate milestones.
+
+### Tooltips vs Modals vs Coachmarks
+
+| Pattern | Use When | Avoid When |
+|---------|----------|------------|
+| **Tooltips** | Explaining a single element | More than 1-2 on screen |
+| **Modals** | Critical announcements, required input | Interrupting flow; never on first load for tours |
+| **Coachmarks** | Introducing 3-5 key features in sequence | Users are mid-task; keep under 5 steps |
+| **Hotspots** | Passive discovery of new features | Overuse trains users to ignore them |
+
+### Empty States
+Every empty state needs: (1) Illustration/icon, (2) Brief explanation, (3) Primary action CTA, (4) Optional link to docs/help.
+
+---
+
+## 6. Email & Notification Design
+
+### Transactional Email Structure
+Brand header, clear subject line, single-column body at 600px max width, primary action button (min 44px height, full-width mobile), minimal footer with unsubscribe.
+
+### Notification Hierarchy
+
+| Level | Channel | Timing |
+|-------|---------|--------|
+| **Urgent** | Push + in-app + email | Immediate |
+| **Informational** | In-app + email | Batched or near-real-time |
+| **Promotional** | Email only | Scheduled; respect quiet hours |
+
+### Push Notification UX
+- 40-50 character headline max.
+- Deep-link to relevant screen, not app home.
+- Limit to 3-5 per day.
+- Implement quiet hours (default 10 PM - 8 AM local time).
+
+---
+
+## Quick Reference: Conversion Numbers
+
+| Metric | Value |
+|--------|-------|
+| First impression time | 50ms |
+| Mobile bounce if load > 3s | 53% |
+| First-person CTA copy lift | 10-90% |
+| Drop per extra form field | 3-5% |
+| Progress bar completion boost | 20-30% |
+| Multi-step form mobile lift | up to 300% |
+| Video testimonial lift | +34% |
+| Sticky mobile CTA lift | 10-20% |
+| "Most Popular" badge lift | 12-15% |
+| Per extra second load time | 7-10% drop |

package/references/data-visualization.md

@@ -0,0 +1,226 @@
+# Data Visualization & Dashboard Design Reference
+
+## 1. Chart Selection Decision Matrix
+
+Select charts by the **question your data answers**, not by what looks interesting.
+
+| Purpose | Recommended Charts | Avoid |
+|---|---|---|
+| **Comparison** (categories vs values) | Bar (vertical/horizontal), Grouped bar, Lollipop | Pie (hard to compare slices) |
+| **Trend over time** (time-series) | Line, Area, Sparkline | Bar (unless discrete intervals) |
+| **Composition** (parts of a whole) | Stacked bar, Pie/Donut (<=6 slices), Treemap | Line chart |
+| **Distribution** (spread/frequency) | Histogram, Box plot, Violin, Scatter | Pie chart |
+| **Relationship** (two+ numeric vars) | Scatter, Bubble (3rd variable as size) | Bar chart |
+| **Ranking** (ordered comparison) | Horizontal bar (sorted), Lollipop | Pie/Donut |
+| **Flow/Conversion** (sequential stages) | Funnel, Sankey | Bar chart |
+| **Performance vs target** (single KPI) | Gauge, Bullet chart | Pie chart |
+| **Inline trend indicator** (compact) | Sparkline (word-sized) | Full chart |
+| **Intensity/correlation** (two categorical axes) | Heatmap | 3D bar charts |
+
+### Quick Decision Flow
+
+```
+What are you showing?
+  -> Change over time?  -> Line (continuous) / Bar (discrete intervals)
+  -> Comparison?        -> Bar (horizontal if labels are long)
+  -> Part of whole?     -> Donut (<=6 cats) / Treemap (many) / Stacked bar (over time)
+  -> Relationship?      -> Scatter / Bubble
+  -> Distribution?      -> Histogram / Box plot
+  -> Single KPI?        -> Big number card with sparkline
+```
+
+---
+
+## 2. Dashboard Design Patterns
+
+### Layout Patterns
+
+**Overview + Detail (most common):** Top row = KPI summary cards. Middle = primary charts. Bottom = detailed tables or drill-down views.
+
+**Drill-Down:** Start with high-level aggregates; clicking reveals progressively granular data. Use breadcrumbs for navigation context.
+
+**Contextual/Filtered:** Global filter bar at top. All panels respond to the same filter state.
+
+### Grid System
+
+Use a **12-column grid** with 16-24px gutters.
+
+```
+| KPI | KPI | KPI | KPI |       <- 3-col each (4 cards)
+|   Primary Chart   | Secondary |  <- 8-col + 4-col
+|      Data Table              |  <- 12-col full width
+```
+
+### KPI Card Anatomy
+
+```
++----------------------------------+
+|  Revenue            +12.3% ^    |  <- Label + trend indicator
+|  $1,234,567                     |  <- Primary metric (large)
+|  vs $1,098,000 target           |  <- Comparison context
+|  ________ sparkline             |  <- Trend line (last 30 days)
++----------------------------------+
+```
+
+**Rules:**
+- Always pair KPIs with context (target, prior period, benchmark).
+- Semantic color only for status: green = on track, amber = warning, red = critical.
+- Show "Last updated" timestamp on every dashboard.
+- Limit to 4-8 KPI cards maximum per view.
+
+### Real-Time Data Display
+
+- Visible "live" indicator or timestamp for data freshness.
+- CSS transitions for value changes (fade or count-up animation).
+- Avoid polling faster than ~5s minimum.
+
+---
+
+## 3. Color for Data
+
+### Sequential (low-to-high, single variable)
+```
+Blues:    #f7fbff -> #9ecae1 -> #08519c -> #08306b
+Viridis: #fde725 -> #35b779 -> #31688e -> #440154
+```
+Light = low, dark = high.
+
+### Diverging (two extremes with neutral midpoint)
+```
+RdBu:  #b2182b -> #f4a582 -> #f7f7f7 -> #92c5de -> #2166ac
+PRGn:  #762a83 -> #c2a5cf -> #f7f7f7 -> #a6dba0 -> #1b7837
+```
+Use for deviation from center (profit/loss, above/below average).
+
+### Qualitative / Categorical (distinct groups)
+```
+Tableau 10:  #4e79a7  #f28e2c  #e15759  #76b7b2  #59a14f  #edc949  #af7aa1  #ff9da7  #9c755f  #bab0ab
+Okabe-Ito:   #E69F00  #56B4E9  #009E73  #F0E442  #0072B2  #D55E00  #CC79A7  #000000
+```
+
+### OKLCH Programmatic Palettes
+
+```css
+/* Sequential: same hue, vary lightness */
+--color-1: oklch(0.95 0.03 250);  /* lightest */
+--color-2: oklch(0.75 0.08 250);
+--color-3: oklch(0.55 0.13 250);
+--color-4: oklch(0.35 0.15 250);  /* darkest */
+
+/* Qualitative: same lightness+chroma, rotate hue */
+--cat-1: oklch(0.7 0.12 30);   /* orange */
+--cat-2: oklch(0.7 0.12 230);  /* blue */
+--cat-3: oklch(0.7 0.12 150);  /* green */
+--cat-4: oklch(0.7 0.12 330);  /* pink */
+```
+
+### Colorblind-Safe Rules
+
+1. **Default to Okabe-Ito** for categorical data.
+2. **Never use red/green as the only differentiator.**
+3. **Use Viridis** for sequential scales.
+4. **Blue is the safest single hue.**
+5. **Supplement color with shape, pattern, or label** (WCAG 1.4.1).
+6. **Limit categorical colors to 6-8 max.**
+
+---
+
+## 4. Chart Accessibility
+
+### Text Alternatives (WCAG 1.1.1)
+
+```jsx
+<figure>
+  <svg role="img" aria-labelledby="chart-title" aria-describedby="chart-desc">
+    <title id="chart-title">Quarterly Revenue</title>
+    <desc id="chart-desc">Bar chart showing revenue growth from $1.2M in Q1 to $1.5M in Q4.</desc>
+  </svg>
+  <details>
+    <summary>View data table</summary>
+    <table><!-- structured data as accessible fallback --></table>
+  </details>
+</figure>
+```
+
+### Keyboard Navigation
+- All interactive chart elements must be focusable.
+- Arrow keys move between data points within a series.
+- Enter/Space to activate (drill-down, tooltip).
+- Escape to dismiss tooltips.
+
+### Visual Patterns for Colorblindness
+Use SVG fill patterns alongside color so colorblind users and grayscale remain readable.
+
+---
+
+## 5. React Charting Libraries
+
+| Library | Best For | Bundle Size | Learning Curve |
+|---|---|---|---|
+| **Recharts** | Standard dashboards, rapid prototyping | Light | Low |
+| **Nivo** | Rich chart variety, theming, SSR | ~371KB/module | Moderate |
+| **Victory** | Cross-platform (React + React Native) | ~1.16MB | Low |
+| **visx** | Custom/brand-specific visualizations | ~12.3KB | High |
+| **Chart.js** | Large datasets (up to 1M points) | 14-48KB | Low |
+| **D3** | Full control, custom viz libraries | Varies | Very High |
+
+```
+Need it fast with standard charts?         -> Recharts
+Need rich chart types + theming?           -> Nivo
+Need web + React Native?                   -> Victory
+Need pixel-perfect custom viz?             -> visx
+Need to render 100K+ data points?          -> Chart.js (Canvas)
+Need full control?                         -> D3 directly
+```
+
+### Recharts Example
+
+```tsx
+import { BarChart, Bar, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from 'recharts';
+
+function RevenueChart({ data }) {
+  return (
+    <ResponsiveContainer width="100%" height={300}>
+      <BarChart data={data}>
+        <CartesianGrid strokeDasharray="3 3" stroke="#e0e0e0" />
+        <XAxis dataKey="month" />
+        <YAxis tickFormatter={(v) => `$${v / 1000}k`} />
+        <Tooltip formatter={(v) => [`$${v.toLocaleString()}`, 'Revenue']} />
+        <Bar dataKey="revenue" fill="#4e79a7" radius={[4, 4, 0, 0]} />
+      </BarChart>
+    </ResponsiveContainer>
+  );
+}
+```
+
+---
+
+## 6. Data-Ink Ratio (Tufte Principles)
+
+### Core Rules
+1. **Above all else, show the data.**
+2. **Maximize data-ink ratio** = (ink used for data) / (total ink).
+3. **Erase non-data-ink** -- gridlines, borders, backgrounds that carry no information.
+4. **Erase redundant data-ink** -- if a label says "42%", you don't also need a gridline at 42.
+
+### Remove (Chartjunk)
+3D effects, gradient fills, heavy gridlines, decorative icons, redundant legends, box borders around charts, background colors (unless encoding data).
+
+### Add
+Direct labels on bars/lines, annotations on key events, reference lines (target, average, benchmark).
+
+### Small Multiples
+Instead of one cluttered multi-series chart, repeat the same simple chart for each category. Same axes, same scale, side by side.
+
+### Sparklines
+Word-sized graphics embedded inline. No axes, no labels -- pure trend.
+
+```tsx
+<ResponsiveContainer width={80} height={20}>
+  <LineChart data={trend}>
+    <Line type="monotone" dataKey="value" stroke="#4e79a7" dot={false} strokeWidth={1.5} />
+  </LineChart>
+</ResponsiveContainer>
+```
+
+Use in: KPI cards, table cells, inline with text.

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