raven-mcp 1.0.0

package/src/data/principles/accessibility.json

@@ -0,0 +1,151 @@
+[
+  {
+    "id": "color-contrast",
+    "name": "Color Contrast",
+    "category": "accessibility",
+    "summary": "Text and interactive elements must have sufficient contrast against their backgrounds.",
+    "description": "WCAG 2.1 requires minimum contrast ratios to ensure readability for users with low vision or color blindness. Normal text needs 4.5:1, large text (18px+ or 14px+ bold) needs 3:1, and UI components/graphics need 3:1. This is non-negotiable for any public-facing product. Test with tools like WebAIM's contrast checker.",
+    "implications": [
+      "Normal text: minimum 4.5:1 contrast ratio (WCAG AA)",
+      "Large text (18px+ regular or 14px+ bold): minimum 3:1",
+      "UI components and graphical objects: minimum 3:1",
+      "Enhanced accessibility (WCAG AAA): 7:1 for normal text, 4.5:1 for large",
+      "Don't rely on color alone to convey information — use icons, text, or patterns too",
+      "Test with grayscale to verify information is still clear without color",
+      "Check contrast on all background colors, not just the primary background"
+    ],
+    "violations": [
+      "Light gray text on white background (#999 on #fff = 2.85:1 — fails)",
+      "Colored text on colored background without checking contrast",
+      "Placeholder text with insufficient contrast (common: #aaa on #fff)",
+      "Status indicators using only color (red/green dots with no label)",
+      "Links that are only distinguished from body text by color"
+    ],
+    "applies_to": ["color", "typography", "buttons", "forms", "status-indicators", "links"],
+    "sources": ["https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html"]
+  },
+  {
+    "id": "keyboard-navigation",
+    "name": "Keyboard Navigation",
+    "category": "accessibility",
+    "summary": "All interactive content must be accessible and operable through keyboard alone.",
+    "description": "Many users navigate with keyboards — screen reader users, users with motor disabilities, and power users. All interactive elements must be reachable via Tab, operable via Enter/Space, and dismissible via Escape. Focus order should follow visual reading order. Custom interactive components need proper ARIA roles and keyboard event handlers.",
+    "implications": [
+      "All interactive elements must be focusable and have visible focus indicators",
+      "Tab order must follow the logical reading order of the page",
+      "Modals must trap focus and return focus to the trigger when closed",
+      "Custom dropdowns, tabs, and menus need arrow key navigation",
+      "Escape should close modals, dropdowns, and overlay elements",
+      "Skip navigation links for users to bypass repeated content",
+      "Never remove focus outlines without providing a visible alternative"
+    ],
+    "violations": [
+      "Click-only interactions with no keyboard equivalent",
+      "Invisible or removed focus indicators (outline: none without replacement)",
+      "Modal that doesn't trap focus — Tab goes to elements behind the overlay",
+      "Custom dropdown that doesn't respond to arrow keys or Escape",
+      "Focus order that doesn't match visual order (e.g., due to CSS order/flex)"
+    ],
+    "applies_to": ["navigation", "forms", "modals", "menus", "interactive-elements", "focus"],
+    "sources": ["https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html"]
+  },
+  {
+    "id": "screen-reader-support",
+    "name": "Screen Reader Support",
+    "category": "accessibility",
+    "summary": "Content must be perceivable and understandable when read by assistive technologies.",
+    "description": "Screen readers translate visual interfaces into speech or braille. This requires semantic HTML, proper ARIA labels, meaningful alt text, and logical document structure. The goal is equivalent access — a screen reader user should be able to accomplish the same tasks and access the same information as a sighted user.",
+    "implications": [
+      "Use semantic HTML elements (nav, main, header, footer, article, section)",
+      "Provide alt text for all meaningful images; empty alt for decorative images",
+      "Use ARIA labels for interactive elements without visible text labels",
+      "Heading hierarchy should be logical (h1 > h2 > h3, no skipping levels)",
+      "Form inputs must have associated labels (label element or aria-label)",
+      "Live regions (aria-live) for dynamic content updates",
+      "Announce state changes (loading, error, success) to screen readers"
+    ],
+    "violations": [
+      "Images without alt text or with unhelpful alt text ('image.png')",
+      "Div/span used for interactive elements instead of button/a",
+      "Form inputs without labels",
+      "Dynamic content updates that aren't announced to screen readers",
+      "Heading levels skipped or used for styling instead of structure"
+    ],
+    "applies_to": ["html", "images", "forms", "navigation", "dynamic-content", "headings"],
+    "sources": ["https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html"]
+  },
+  {
+    "id": "touch-target-size",
+    "name": "Touch Target Size",
+    "category": "accessibility",
+    "summary": "Interactive elements must be large enough to activate easily without accidental activation of adjacent targets.",
+    "description": "WCAG 2.5.5 (Enhanced, AAA) recommends 44x44 CSS pixels minimum. WCAG 2.5.8 (AA in WCAG 2.2) requires targets of at least 24x24px with adequate spacing. Apple HIG requires 44pt, Material Design requires 48dp. Small targets cause errors, frustration, and are inaccessible to users with motor impairments. This applies to buttons, links, checkboxes, and any tappable element.",
+    "implications": [
+      "Minimum 44x44px touch targets (Apple HIG) or 48x48dp (Material)",
+      "WCAG 2.2 minimum: 24x24px with adequate spacing",
+      "Adequate spacing between adjacent touch targets (at least 8px)",
+      "Inline links in text should have enough padding/line-height for tapping",
+      "Checkboxes and radio buttons need enlarged tap areas (label wrapping)",
+      "Small icons should have padding to extend the touch target beyond the visual"
+    ],
+    "violations": [
+      "Icon buttons smaller than 44px without extended tap target",
+      "Adjacent links in text with no spacing between them",
+      "Tiny checkboxes without clickable labels",
+      "Close buttons on modals that are 16x16px",
+      "Dense data tables with row-level click targets on mobile"
+    ],
+    "applies_to": ["buttons", "links", "mobile", "touch-targets", "forms", "icons"],
+    "sources": ["https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html"]
+  },
+  {
+    "id": "motion-sensitivity",
+    "name": "Motion and Animation Sensitivity",
+    "category": "accessibility",
+    "summary": "Provide mechanisms to pause, stop, or reduce motion for users who are sensitive to animation.",
+    "description": "Some users experience nausea, dizziness, or seizures from excessive motion, parallax effects, or flashing content. WCAG requires the ability to pause or disable motion, limits on flashing content, and respect for the prefers-reduced-motion media query. Auto-playing animations and videos must have pause controls.",
+    "implications": [
+      "Respect prefers-reduced-motion media query — reduce or eliminate animations",
+      "No content that flashes more than 3 times per second",
+      "Provide pause/stop controls for auto-playing content",
+      "Auto-playing videos must be muted and pausable",
+      "Parallax scrolling should be optional and smooth",
+      "Use subtle, purposeful animations — not gratuitous motion",
+      "Provide a motion preference toggle in app settings"
+    ],
+    "violations": [
+      "Ignoring prefers-reduced-motion — animations play regardless",
+      "Auto-playing video backgrounds with no pause control",
+      "Excessive parallax that causes motion sickness",
+      "Content that flashes rapidly (seizure risk)",
+      "Large, sweeping page transitions with no reduced-motion alternative"
+    ],
+    "applies_to": ["animation", "video", "transitions", "parallax", "auto-play", "motion"],
+    "sources": ["https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions.html"]
+  },
+  {
+    "id": "text-readability",
+    "name": "Text Readability",
+    "category": "accessibility",
+    "summary": "Text must be resizable, reflowable, and formatted for comfortable reading.",
+    "description": "WCAG requires text be resizable up to 200% without loss of content. Content should reflow on zoom without horizontal scrolling. Line length, line height, letter spacing, and paragraph spacing all affect readability. Minimum body text of 16px on web. Text should be readable with user-customized fonts and spacing.",
+    "implications": [
+      "Minimum 16px (1rem) body text on web",
+      "Line height of 1.5 for body text (WCAG recommendation)",
+      "Line length of 45-75 characters for optimal readability",
+      "Text must be resizable to 200% without content loss",
+      "Use responsive units (rem, em) not fixed px for font sizes",
+      "Ensure text reflows properly at all zoom levels",
+      "Support user-customized text spacing without breaking layout"
+    ],
+    "violations": [
+      "Body text smaller than 16px on web / 11pt on mobile",
+      "Line length exceeding 80 characters without a max-width",
+      "Fixed font sizes that don't scale with browser zoom",
+      "Text clipped or overflowing when zoomed to 200%",
+      "Single-line height (line-height: 1) on multi-line text"
+    ],
+    "applies_to": ["typography", "responsive", "zoom", "readability", "content"],
+    "sources": ["https://www.w3.org/WAI/WCAG21/Understanding/text-spacing.html"]
+  }
+]

package/src/data/principles/color-theory.json

@@ -0,0 +1,100 @@
+[
+  {
+    "id": "color-60-30-10",
+    "name": "60-30-10 Color Rule",
+    "category": "color-theory",
+    "summary": "Use a 60% dominant color, 30% secondary color, and 10% accent color for balanced compositions.",
+    "description": "Borrowed from interior design, this ratio creates visual balance and hierarchy. 60% is the dominant/background color, 30% is the secondary/surface color, and 10% is the accent used for CTAs, highlights, and emphasis. This prevents the common mistake of overusing brand colors, which creates visual fatigue. The accent color's power comes from its scarcity.",
+    "implications": [
+      "60% dominant: background, large surfaces (white, off-white, or dark bg)",
+      "30% secondary: cards, sidebar, secondary surfaces",
+      "10% accent: CTAs, links, active states, key highlights",
+      "The accent color should be used sparingly — overuse destroys its impact",
+      "Neutral colors (gray spectrum) should make up most of the 60% and 30%",
+      "Test by blurring the page — the accent should pop against the dominant"
+    ],
+    "violations": [
+      "Brand color used as background — creates visual fatigue",
+      "Accent color used on 30%+ of the page — loses emphasis power",
+      "No accent color — everything is gray and nothing stands out",
+      "Three equally competing bright colors with no clear hierarchy"
+    ],
+    "applies_to": ["color", "visual-design", "branding", "layout", "cta", "hierarchy"],
+    "sources": ["https://www.interaction-design.org/literature/article/the-60-30-10-rule"]
+  },
+  {
+    "id": "dark-ui-design",
+    "name": "Dark UI Design",
+    "category": "color-theory",
+    "summary": "Dark interfaces require different approaches to elevation, contrast, and color usage.",
+    "description": "Dark mode isn't just inverting colors. Material Design's dark theme guide establishes that lighter surfaces are 'elevated' (opposite of light mode). Use desaturated colors to reduce eye strain. Don't use pure black (#000) — it creates excessive contrast and halation. Background surfaces should use dark grays (#121212 to #1e1e1e). Color accents need more saturation to be visible on dark backgrounds.",
+    "implications": [
+      "Don't use pure black (#000000) — use dark grays (#121212, #1a1a1a, #1e1e1e)",
+      "Express elevation with lighter surfaces (dp0: #121212, dp1: #1e1e1e, dp2: #222222)",
+      "Use desaturated colors on dark backgrounds to reduce eye strain",
+      "Increase text opacity levels: primary 87%, secondary 60%, disabled 38%",
+      "Accent colors may need higher saturation to maintain visibility",
+      "Avoid pure white text on dark backgrounds — use off-white (rgba(255,255,255,0.87))",
+      "Shadows are less effective in dark mode — use borders or surface elevation instead",
+      "Test for dark mode contrast issues — WCAG ratios still apply"
+    ],
+    "violations": [
+      "Pure black background with pure white text — harsh, causes halation",
+      "Inverted light mode colors without adjustment — saturated colors cause eye strain",
+      "Shadows as the primary elevation cue — invisible on dark backgrounds",
+      "Low-saturation accent colors that disappear on dark surfaces",
+      "Same opacity for text that works in light mode — appears washed out"
+    ],
+    "applies_to": ["color", "dark-mode", "elevation", "contrast", "visual-design"],
+    "sources": ["https://m3.material.io/styles/color/dark-theme"]
+  },
+  {
+    "id": "semantic-color",
+    "name": "Semantic Color Usage",
+    "category": "color-theory",
+    "summary": "Assign meaning to colors consistently — success is green, error is red, warning is amber.",
+    "description": "Colors carry meaning. Red signals error/danger, green signals success, amber/yellow signals warning, blue signals information. These mappings are deeply cultural (in Western markets) and should be consistent across the entire product. Always pair color with another signal (icon, text, pattern) for accessibility. Define semantic color tokens in your design system.",
+    "implications": [
+      "Red/destructive: errors, delete actions, critical alerts",
+      "Green/success: confirmations, completion, positive status",
+      "Amber/warning: caution states, approaching limits, non-critical issues",
+      "Blue/info: informational messages, links, primary actions",
+      "Gray/neutral: disabled states, secondary information, borders",
+      "Always pair color with text or icon — never color alone",
+      "Define semantic tokens: color-error, color-success, color-warning, color-info"
+    ],
+    "violations": [
+      "Red used for a non-error primary CTA (confusing meaning)",
+      "Green and red used interchangeably for different UI elements",
+      "Inconsistent status colors across different pages",
+      "Color as the only indicator of state — fails for colorblind users"
+    ],
+    "applies_to": ["color", "status", "error-states", "success", "warnings", "design-system"],
+    "sources": ["https://m3.material.io/styles/color/roles"]
+  },
+  {
+    "id": "color-accessibility",
+    "name": "Color and Accessibility",
+    "category": "color-theory",
+    "summary": "8% of men and 0.5% of women have some form of color vision deficiency — design for it.",
+    "description": "Color blindness affects 1 in 12 men and 1 in 200 women. The most common type (deuteranopia/protanopia) makes red and green difficult to distinguish. Design should never rely on color alone. Use redundant coding: color + shape, color + text, color + pattern. Test designs with color blindness simulators. Ensure sufficient contrast between all color pairs that need to be distinguished.",
+    "implications": [
+      "Never use color as the sole indicator of meaning or state",
+      "Add icons or text labels alongside color-coded status indicators",
+      "Use patterns or hatching in charts/graphs in addition to color",
+      "Test with color blindness simulators (deuteranopia, protanopia, tritanopia)",
+      "Red-green combinations are the most problematic — use additional cues",
+      "Ensure adjacent colors in charts have sufficient contrast from each other",
+      "Consider colorblind-safe palettes (blue-orange instead of red-green)"
+    ],
+    "violations": [
+      "Red/green only indicators for success/error states",
+      "Pie chart with color-only legend — indistinguishable segments",
+      "Form validation using only red outlines with no icon or text",
+      "Traffic light status indicators without labels",
+      "Data visualization using only color to distinguish series"
+    ],
+    "applies_to": ["color", "accessibility", "charts", "status", "forms", "data-visualization"],
+    "sources": ["https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html"]
+  }
+]

package/src/data/principles/d4d.json

@@ -0,0 +1,113 @@
+[
+  {
+    "id": "d4d-framework",
+    "name": "Design for Delight (D4D)",
+    "category": "d4d",
+    "summary": "A customer empathy framework for validating product decisions through structured hypothesis testing.",
+    "description": "Design for Delight is a framework that starts with deep customer empathy, generates multiple solution options, narrows through evidence-based evaluation, and validates through scrappy experiments. It prevents teams from jumping to solutions before understanding the problem, and ensures hypotheses are testable and measurable. Every step produces an artifact that feeds the next step.",
+    "implications": [
+      "Always start with a Customer Problem Statement before proposing solutions",
+      "Frame problems from the customer's perspective using first-person voice",
+      "Generate 3-5 solution options before committing to one",
+      "Every hypothesis must include a measurable signal and target timeframe",
+      "LOFAs (Leap of Faith Assumptions) must be falsifiable and ordered by risk",
+      "Experiments should be the smallest possible test that produces learning"
+    ],
+    "violations": [
+      "Jumping to a solution without articulating the customer problem",
+      "Only considering one solution option",
+      "Hypotheses without measurable success criteria or timeframes",
+      "LOFAs that aren't falsifiable ('Users will like it')",
+      "Running experiments without clear decision rules (advance vs pivot)"
+    ],
+    "applies_to": ["product-strategy", "research", "validation", "prioritization", "experimentation"],
+    "sources": ["Internal framework"],
+    "templates": {
+      "customer_problem_statement": {
+        "format": "- I am [narrow description of the customer/persona]\n- I am trying to [desired outcome]\n- But [problem/barrier]\n- Because [root cause]\n- Which makes me feel [emotion]",
+        "guidance": [
+          "First person, customer voice",
+          "'I am' must be narrow — not 'a user' but a specific persona with context",
+          "The barrier should be observable, not assumed",
+          "Root cause should be specific enough to act on",
+          "Emotion reveals the true impact and urgency"
+        ]
+      },
+      "ideal_state": {
+        "format": "In the ideal state, [customer/segment] can [job/outcome] so that [benefit/emotion/impact], measurable by [customer benefit metric / outcome metric].",
+        "guidance": [
+          "Describes the end state without prescribing a solution",
+          "Includes a measurable indicator of success",
+          "Focuses on customer benefit, not feature delivery"
+        ]
+      },
+      "hypothesis_statement": {
+        "format": "We believe that [solution/approach] for [customer/segment] will [customer benefit/outcome]. We'll know this is true when [signal/metric] moves to [target] by [timeframe].",
+        "guidance": [
+          "'Moves to [target] by [timeframe]' is mandatory — never leave it vague",
+          "The signal should be something you can actually measure",
+          "The timeframe forces urgency and prevents infinite experiments",
+          "If you can't fill in the target, you don't understand the problem well enough"
+        ]
+      },
+      "lofa": {
+        "format": "Assumption: [Statement that must be true for the solution to work]\nRisk level: [High/Medium/Low]\nHow to test: [Cheapest way to validate or invalidate]\nFalsification criteria: [What would prove this wrong]",
+        "guidance": [
+          "2-4 assumptions, ordered by risk (highest first)",
+          "Each must be falsifiable",
+          "Test the riskiest assumption first",
+          "If the highest-risk LOFA fails, the solution fails — don't proceed"
+        ]
+      },
+      "scrappy_experiment": {
+        "format": "Test: [smallest test to learn fast]\nOwners: [who]\nStart date: [when]\nDecision rule: [advance if X, pivot if Y]",
+        "guidance": [
+          "The test should take days, not weeks",
+          "Decision rules must be specific and agreed upon before starting",
+          "The experiment tests the riskiest LOFA, not the full solution",
+          "If the decision rule is met, advance to the next LOFA or build"
+        ]
+      },
+      "operating_loop": {
+        "stages": [
+          {
+            "stage": "frame",
+            "name": "Frame",
+            "description": "Define the customer, problem, desired benefit, and constraints.",
+            "outputs": ["Customer Problem Statement", "Ideal State"]
+          },
+          {
+            "stage": "empathy",
+            "name": "Empathy",
+            "description": "Key observations about the customer. What have you seen? What are you assuming?",
+            "outputs": ["Observation list", "Assumption list"]
+          },
+          {
+            "stage": "broad",
+            "name": "Go Broad",
+            "description": "Generate 3-5 distinct solution options. Keep each to 1-2 lines. No evaluation yet.",
+            "outputs": ["3-5 solution options"]
+          },
+          {
+            "stage": "narrow",
+            "name": "Go Narrow",
+            "description": "Compare options on customer benefit and feasibility. Pick 1-2 to pursue.",
+            "outputs": ["Comparison matrix", "Selected option(s)"]
+          },
+          {
+            "stage": "experiment",
+            "name": "Experiment",
+            "description": "Write hypothesis, identify LOFAs, define signals, and design the smallest test.",
+            "outputs": ["Hypothesis Statement", "LOFAs", "Scrappy Experiment"]
+          },
+          {
+            "stage": "recommendation",
+            "name": "Recommendation",
+            "description": "Clear call: build, pivot, or kill. Include risks, dependencies, and now vs. later.",
+            "outputs": ["Recommendation", "Risk assessment", "Timeline"]
+          }
+        ]
+      }
+    }
+  }
+]

package/src/data/principles/gestalt.json

@@ -0,0 +1,129 @@
+[
+  {
+    "id": "gestalt-proximity",
+    "name": "Proximity",
+    "category": "gestalt",
+    "summary": "Elements placed close together are perceived as a group.",
+    "description": "The most fundamental spatial grouping principle. Objects near each other are automatically perceived as related. The space between groups must be significantly larger than the space within groups for grouping to be clear. This applies to form layouts, navigation, card grids, and any multi-element composition.",
+    "implications": [
+      "Keep related form fields close together with more space between groups",
+      "Use consistent spacing within groups and larger gaps between groups",
+      "Place labels immediately adjacent to their corresponding inputs",
+      "Group navigation items by section with visual separators",
+      "Use spacing ratios (inner spacing = base, outer spacing = 2-3x base)"
+    ],
+    "violations": [
+      "Labels equidistant between two inputs — ambiguous association",
+      "Uniform spacing throughout — no grouping communicated",
+      "Action buttons far from the content they affect"
+    ],
+    "applies_to": ["layout", "forms", "spacing", "grouping", "navigation", "cards"],
+    "sources": ["https://www.interaction-design.org/literature/topics/gestalt-principles"]
+  },
+  {
+    "id": "gestalt-similarity",
+    "name": "Similarity",
+    "category": "gestalt",
+    "summary": "Elements that share visual characteristics (color, shape, size) are perceived as related.",
+    "description": "When elements look alike, we assume they serve the same function or belong to the same category. This principle is the foundation of consistent component design — all buttons, all cards, all links should share visual characteristics within their type. Breaking similarity intentionally draws attention to the different element (see Von Restorff Effect).",
+    "implications": [
+      "Style all elements of the same type consistently",
+      "Use color coding consistently to represent categories or states",
+      "Differentiate interactive from non-interactive elements clearly",
+      "Use consistent icon styles throughout the product",
+      "Break similarity intentionally for emphasis (highlighted CTA, featured plan)"
+    ],
+    "violations": [
+      "Same color used for links and static text",
+      "Interactive elements that look like non-interactive ones",
+      "Inconsistent icon styles (some outlined, some filled) without meaning"
+    ],
+    "applies_to": ["consistency", "color", "icons", "buttons", "visual-design", "cards"],
+    "sources": ["https://www.interaction-design.org/literature/topics/gestalt-principles"]
+  },
+  {
+    "id": "gestalt-closure",
+    "name": "Closure",
+    "category": "gestalt",
+    "summary": "The brain completes incomplete shapes, perceiving them as whole forms.",
+    "description": "People perceive incomplete shapes as complete when enough visual information is provided. In UI, this means you don't need to fully enclose every element — partial borders, implied containers, and cropped images all work because the brain fills in the gaps. This enables cleaner, less cluttered designs that still communicate structure.",
+    "implications": [
+      "Use partial borders or open containers for a lighter visual feel",
+      "Cropped images at screen edges suggest more content beyond the viewport",
+      "Horizontal scroll indicators can show partial next items to imply scrollability",
+      "Progress indicators work because the brain completes the circle/bar",
+      "Card carousels showing partial next card encourage swiping"
+    ],
+    "violations": [
+      "Fully enclosed sections with heavy borders creating visual clutter",
+      "Cropped content that looks broken rather than intentionally suggesting more",
+      "Hidden scrollable content with no partial element visible to indicate scrollability"
+    ],
+    "applies_to": ["layout", "cards", "carousel", "progress", "visual-design", "scroll"],
+    "sources": ["https://www.interaction-design.org/literature/topics/gestalt-principles"]
+  },
+  {
+    "id": "gestalt-continuity",
+    "name": "Continuity",
+    "category": "gestalt",
+    "summary": "The eye follows smooth lines and curves, preferring continuous paths over abrupt changes.",
+    "description": "Elements arranged along a line or curve are perceived as related and following a direction. The eye follows the smoothest path. In UI, this applies to reading patterns (F-pattern, Z-pattern), timeline designs, step progressions, and flow visualizations. Alignment creates continuity — misalignment breaks it and creates friction.",
+    "implications": [
+      "Align elements to create clear reading paths (left-aligned text, grid alignment)",
+      "Design timelines and step indicators as continuous flows",
+      "Use consistent alignment across pages to create predictable scan patterns",
+      "Guide the eye through intentional visual flow (size, color, position)",
+      "Ensure data visualizations follow smooth, readable paths"
+    ],
+    "violations": [
+      "Misaligned elements that break the reading flow",
+      "Step indicators that jump between different visual positions",
+      "Inconsistent alignment across different sections"
+    ],
+    "applies_to": ["alignment", "timelines", "reading-patterns", "visual-flow", "layout"],
+    "sources": ["https://www.interaction-design.org/literature/topics/gestalt-principles"]
+  },
+  {
+    "id": "gestalt-figure-ground",
+    "name": "Figure-Ground",
+    "category": "gestalt",
+    "summary": "The brain separates visual input into foreground (figure) and background (ground).",
+    "description": "Users instantly perceive which elements are the focus (figure) and which are the background (ground). Modals with overlays, cards on backgrounds, and highlighted elements all leverage figure-ground separation. Ambiguity in figure-ground creates confusion. Strong contrast between figure and ground creates clarity.",
+    "implications": [
+      "Use overlays/scrims behind modals to establish clear figure-ground",
+      "Elevate cards above the background with subtle shadows or border contrast",
+      "Use background color to push non-essential content to the 'ground'",
+      "Create depth hierarchy: background → surface → elevated → overlay",
+      "Ensure sufficient contrast between foreground content and background"
+    ],
+    "violations": [
+      "Modal without overlay — unclear what's foreground vs background",
+      "Cards that don't visually separate from the page background",
+      "Elements with ambiguous depth — unclear if they're clickable or decorative",
+      "Text on patterned backgrounds with insufficient contrast"
+    ],
+    "applies_to": ["modals", "cards", "elevation", "depth", "contrast", "overlays"],
+    "sources": ["https://www.interaction-design.org/literature/topics/gestalt-principles"]
+  },
+  {
+    "id": "gestalt-common-fate",
+    "name": "Common Fate",
+    "category": "gestalt",
+    "summary": "Elements moving in the same direction are perceived as a group.",
+    "description": "Motion creates grouping. When multiple elements animate or move together, they're perceived as a unit. In UI, this applies to drag-and-drop selections, coordinated animations, parallax scrolling layers, and accordion expansions. Elements that move differently from the group are perceived as separate or special.",
+    "implications": [
+      "Animate related elements together (multi-select drag, group transitions)",
+      "Use coordinated animations for elements that belong together",
+      "Different scroll speeds (parallax) create distinct visual layers",
+      "Accordion animations should move all child content together",
+      "Loading sequences can animate related elements simultaneously"
+    ],
+    "violations": [
+      "Elements in the same group animating at different speeds or directions",
+      "Unrelated elements animating together, creating false grouping",
+      "Drag-and-drop where selected items don't move together"
+    ],
+    "applies_to": ["animation", "motion", "drag-and-drop", "transitions", "grouping"],
+    "sources": ["https://www.interaction-design.org/literature/topics/gestalt-principles"]
+  }
+]