particles

frontend/src/components/GlowParticleEffect.tsx

@@ -0,0 +1,275 @@
+/**
+ * GlowParticleEffect Component
+ *
+ * A wrapper component that adds soft glowing particle effects to its children.
+ * Particles spawn at click locations and float upward while fading.
+ *
+ * VISUAL ARCHITECTURE:
+ * ┌──────────────────────────────────────────────────────────┐
+ * │  Wrapper Container (position: relative)                  │
+ * │  ┌────────────────────────────────────────────────────┐  │
+ * │  │ Children (note content, wikilinks, etc.)           │  │
+ * │  │                                                    │  │
+ * │  │  Some text with [[wikilink]] that you can click    │  │
+ * │  │                      ↑                             │  │
+ * │  │                  Click here                        │  │
+ * │  └────────────────────────────────────────────────────┘  │
+ * │  ┌────────────────────────────────────────────────────┐  │
+ * │  │ Canvas Overlay (position: absolute, pointer-events:│  │
+ * │  │ none)                                              │  │
+ * │  │                 ░░▒▓██▓▒░░                         │  │
+ * │  │              ░░▒▓██▓▒░░                            │  │
+ * │  │           ░░▒▓██▓▒░░   <- Particles float up       │  │
+ * │  │                                                    │  │
+ * │  └────────────────────────────────────────────────────┘  │
+ * └──────────────────────────────────────────────────────────┘
+ *
+ * VISUAL FLOW:
+ * 1. User clicks on wikilink (or any child element)
+ * 2. Click event bubbles up to wrapper
+ * 3. Particles spawn at click coordinates
+ * 4. Particles animate independently on canvas
+ * 5. Canvas has pointer-events: none, so clicks pass through
+ *
+ * ACCESSIBILITY:
+ * - Respects prefers-reduced-motion
+ * - Canvas is purely decorative (no interaction)
+ * - Does not interfere with screen readers
+ */
+
+import React, { useRef, useCallback, useEffect, useState } from 'react';
+import { useGlowParticles } from '@/hooks/useGlowParticles';
+import { useReducedMotion } from '@/hooks/useReducedMotion';
+import type { ParticleConfig, ParticlePreset } from '@/types/particles';
+import { DEFAULT_PARTICLE_CONFIG, PARTICLE_PRESETS } from '@/types/particles';
+
+export interface GlowParticleEffectProps {
+  /**
+   * Content to wrap with particle effect
+   */
+  children: React.ReactNode;
+
+  /**
+   * Particle configuration (colors, sizes, speeds, etc.)
+   * Can be a preset name or custom config object
+   */
+  config?: Partial<ParticleConfig> | ParticlePreset;
+
+  /**
+   * CSS class for the wrapper container
+   */
+  className?: string;
+
+  /**
+   * Whether particles are enabled
+   * Automatically disabled when prefers-reduced-motion is set
+   */
+  enabled?: boolean;
+
+  /**
+   * Optional callback when particles are spawned
+   * Useful for analytics or sound effects
+   */
+  onParticleBurst?: (x: number, y: number) => void;
+
+  /**
+   * Selector for elements that should trigger particles
+   * If not provided, ANY click in the container triggers particles
+   * Example: '.wikilink' to only trigger on wikilink clicks
+   */
+  triggerSelector?: string;
+}
+
+/**
+ * Resolve config from preset name or partial config
+ */
+function resolveConfig(
+  configProp?: Partial<ParticleConfig> | ParticlePreset
+): ParticleConfig {
+  if (!configProp) {
+    return DEFAULT_PARTICLE_CONFIG;
+  }
+
+  // If it's a string, look up the preset
+  if (typeof configProp === 'string') {
+    return PARTICLE_PRESETS[configProp] || DEFAULT_PARTICLE_CONFIG;
+  }
+
+  // Merge with defaults
+  return { ...DEFAULT_PARTICLE_CONFIG, ...configProp };
+}
+
+/**
+ * GlowParticleEffect Component
+ *
+ * Wraps children with an invisible canvas overlay that renders particles.
+ *
+ * USAGE:
+ * ```tsx
+ * <GlowParticleEffect config="elegant" triggerSelector=".wikilink">
+ *   <div>Content with [[wikilinks]]</div>
+ * </GlowParticleEffect>
+ * ```
+ */
+export function GlowParticleEffect({
+  children,
+  config: configProp,
+  className = '',
+  enabled = true,
+  onParticleBurst,
+  triggerSelector,
+}: GlowParticleEffectProps) {
+  // Check accessibility preference
+  const prefersReducedMotion = useReducedMotion();
+
+  // Resolve final configuration
+  const config = resolveConfig(configProp);
+
+  // Determine if particles should be active
+  const isDisabled = prefersReducedMotion || !enabled;
+
+  // Reference to wrapper for coordinate calculation
+  const wrapperRef = useRef<HTMLDivElement>(null);
+
+  // Canvas dimensions state
+  const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
+
+  // Initialize particle system
+  const { canvasRef, createParticleBurst } = useGlowParticles(config, isDisabled);
+
+  /**
+   * UPDATE CANVAS DIMENSIONS
+   *
+   * VISUAL PURPOSE: Canvas must match container size for correct positioning.
+   * If canvas is smaller than container, particles would be clipped.
+   * If larger, particles could render in invisible area.
+   *
+   * We use ResizeObserver to handle:
+   * - Initial mount
+   * - Window resize
+   * - Layout changes
+   */
+  useEffect(() => {
+    const wrapper = wrapperRef.current;
+    if (!wrapper) return;
+
+    const updateDimensions = () => {
+      const rect = wrapper.getBoundingClientRect();
+      setDimensions({
+        width: rect.width,
+        height: rect.height,
+      });
+    };
+
+    // Initial measurement
+    updateDimensions();
+
+    // Watch for size changes
+    const resizeObserver = new ResizeObserver(updateDimensions);
+    resizeObserver.observe(wrapper);
+
+    return () => {
+      resizeObserver.disconnect();
+    };
+  }, []);
+
+  /**
+   * HANDLE CLICK FOR PARTICLE SPAWN
+   *
+   * VISUAL FLOW:
+   * 1. User clicks somewhere in the wrapper
+   * 2. We check if click target matches triggerSelector (if provided)
+   * 3. We calculate click position relative to canvas
+   * 4. We spawn particles at that position
+   *
+   * The particles appear exactly where the user clicked,
+   * creating a direct visual response to the interaction.
+   */
+  const handleClick = useCallback(
+    (event: React.MouseEvent<HTMLDivElement>) => {
+      // Skip if disabled
+      if (isDisabled) return;
+
+      // Check if trigger selector is specified
+      if (triggerSelector) {
+        // Find if click target matches selector (or is inside matching element)
+        const target = event.target as HTMLElement;
+        const matchingElement = target.closest(triggerSelector);
+        if (!matchingElement) {
+          // Click was not on a triggering element
+          return;
+        }
+      }
+
+      const wrapper = wrapperRef.current;
+      if (!wrapper) return;
+
+      /**
+       * CALCULATE RELATIVE COORDINATES
+       *
+       * VISUAL: event.clientX/Y are viewport-relative
+       * We need coordinates relative to the canvas origin (top-left of wrapper)
+       *
+       * rect.left/top give us the wrapper's position in the viewport
+       * Subtracting gives us the click position within the wrapper
+       */
+      const rect = wrapper.getBoundingClientRect();
+      const x = event.clientX - rect.left;
+      const y = event.clientY - rect.top;
+
+      // Spawn particles at click location
+      createParticleBurst(x, y);
+
+      // Notify callback if provided
+      onParticleBurst?.(x, y);
+    },
+    [isDisabled, triggerSelector, createParticleBurst, onParticleBurst]
+  );
+
+  return (
+    <div
+      ref={wrapperRef}
+      className={`relative ${className}`}
+      onClick={handleClick}
+    >
+      {/* Children (the actual content) */}
+      {children}
+
+      {/*
+        CANVAS OVERLAY
+
+        VISUAL ARCHITECTURE:
+        - Positioned absolutely to cover the entire wrapper
+        - pointer-events: none allows clicks to pass through to children
+        - z-index ensures particles render above content
+
+        VISUAL: The canvas is invisible until particles are drawn on it.
+        It acts as a transparent layer floating above the content.
+      */}
+      {!isDisabled && (
+        <canvas
+          ref={canvasRef}
+          width={dimensions.width}
+          height={dimensions.height}
+          className="absolute inset-0 pointer-events-none z-10"
+          style={{
+            // Ensure canvas covers entire container
+            width: '100%',
+            height: '100%',
+          }}
+          // Accessibility: Mark as decorative/presentation
+          role="presentation"
+          aria-hidden="true"
+        />
+      )}
+    </div>
+  );
+}
+
+/**
+ * Re-export presets for convenience
+ */
+export { PARTICLE_PRESETS } from '@/types/particles';
+export type { ParticleConfig, ParticlePreset } from '@/types/particles';
+
+export default GlowParticleEffect;

frontend/src/components/NoteViewer.tsx

@@ -3,6 +3,7 @@
  * T081-T082: Wikilink click handling and broken link styling
  * T009: Font size buttons (A-, A, A+) for content adjustment
  * T037-T052: Table of Contents panel integration
+ * PARTICLE EFFECT: Soft glowing particles on wikilink clicks
  */
 import { useMemo, useEffect } from 'react';
 import ReactMarkdown from 'react-markdown';
@@ -26,6 +27,7 @@ import { createWikilinkComponent, resetSlugCache } from '@/lib/markdown.tsx';
 import { markdownToPlainText } from '@/lib/markdownToText';
 import { useTableOfContents } from '@/hooks/useTableOfContents';
 import { TableOfContents } from '@/components/TableOfContents';
+import { GlowParticleEffect } from '@/components/GlowParticleEffect';
 
 type FontSizePreset = 'small' | 'medium' | 'large';
 
@@ -238,7 +240,24 @@ export function NoteViewer({
         {/* Main content panel */}
         <ResizablePanel defaultSize={isTocOpen ? 75 : 100}>
           <ScrollArea className="h-full p-6">
-            <div className="prose prose-slate dark:prose-invert max-w-none animate-fade-in-smooth">
+            {/*
+              PARTICLE EFFECT INTEGRATION
+
+              VISUAL: Wraps the markdown content with a canvas overlay.
+              When users click on wikilinks (.wikilink elements), soft
+              glowing particles spawn at the click location.
+
+              TRIGGER: Only wikilink clicks spawn particles (triggerSelector)
+              STYLE: "elegant" preset - balanced size, moderate glow, ~1 second fade
+
+              The particles float upward and fade out, creating a subtle
+              visual acknowledgment of the navigation action.
+            */}
+            <GlowParticleEffect
+              config="elegant"
+              triggerSelector=".wikilink"
+              className="prose prose-slate dark:prose-invert max-w-none animate-fade-in-smooth"
+            >
               <ReactMarkdown
                 remarkPlugins={[remarkGfm]}
                 components={markdownComponents}
@@ -246,7 +265,7 @@ export function NoteViewer({
               >
                 {processedBody}
               </ReactMarkdown>
-            </div>
+            </GlowParticleEffect>
 
             <Separator className="my-8" />
 

frontend/src/hooks/useGlowParticles.ts

@@ -0,0 +1,515 @@
+/**
+ * useGlowParticles Hook
+ *
+ * Core particle system hook that manages creation, animation, and rendering
+ * of soft glowing particles on a canvas element.
+ *
+ * VISUAL ARCHITECTURE:
+ * ┌─────────────────────────────────────────────────────┐
+ * │  Canvas (positioned absolutely over content)        │
+ * │                                                     │
+ * │     ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    │
+ * │     ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    │
+ * │     ░░░░░░░░░░░▓▓▓░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    │  <- Particles float
+ * │     ░░░░░░░░░░▓███▓░░░░░░░░░░▒▒▒░░░░░░░░░░░░░░░    │     upward and fade
+ * │     ░░░░░░░░░░░▓▓▓░░░░░░░░░░▒███▒░░░░░░░░░░░░░░    │
+ * │     ░░░░░░░░░░░░░░░░░░░░░░░░░▒▒▒░░░░░░░░░░░░░░░    │
+ * │     ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    │
+ * │                      ↑                             │
+ * │                  Click here                        │
+ * │               [Wikilink Text]                      │
+ * └─────────────────────────────────────────────────────┘
+ *
+ * Each particle (▓██▓ above) consists of:
+ * - Bright center (█) - solid color
+ * - Gradient falloff (▓) - fading to transparent
+ * - Soft glow halo (▒) - shadowBlur effect
+ */
+
+import { useRef, useCallback, useEffect } from 'react';
+import type { Particle, ParticleConfig } from '@/types/particles';
+import { DEFAULT_PARTICLE_CONFIG } from '@/types/particles';
+
+/**
+ * Parse hex color to RGB components
+ *
+ * VISUAL PURPOSE: We need RGB values to create gradient stops with
+ * varying alpha (transparency) values. Hex colors don't support alpha
+ * in the same way, so we convert to rgba() format.
+ *
+ * Example: '#6366f1' -> { r: 99, g: 102, b: 241 }
+ */
+function hexToRgb(hex: string): { r: number; g: number; b: number } {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  return result
+    ? {
+        r: parseInt(result[1], 16),
+        g: parseInt(result[2], 16),
+        b: parseInt(result[3], 16),
+      }
+    : { r: 99, g: 102, b: 241 }; // Fallback to indigo
+}
+
+/**
+ * Generate a random number within a range
+ */
+function randomBetween(min: number, max: number): number {
+  return Math.random() * (max - min) + min;
+}
+
+/**
+ * Unique ID generator for particles
+ */
+let particleIdCounter = 0;
+
+export interface UseGlowParticlesReturn {
+  /**
+   * Ref to attach to the canvas element
+   * The canvas should be positioned absolutely over the content area
+   */
+  canvasRef: React.RefObject<HTMLCanvasElement | null>;
+
+  /**
+   * Trigger a particle burst at specific coordinates
+   * @param x - X coordinate relative to canvas
+   * @param y - Y coordinate relative to canvas
+   *
+   * VISUAL: Creates particleCount particles at (x,y) that burst outward
+   * in random directions
+   */
+  createParticleBurst: (x: number, y: number) => void;
+
+  /**
+   * Check if animation loop is currently running
+   */
+  isAnimating: boolean;
+}
+
+/**
+ * Main particle system hook
+ *
+ * @param config - Particle visual configuration (colors, sizes, speeds, etc.)
+ * @param disabled - If true, particles won't be created (accessibility)
+ * @returns Canvas ref and burst trigger function
+ *
+ * VISUAL LIFECYCLE OVERVIEW:
+ * 1. User clicks -> createParticleBurst(x, y) called
+ * 2. Particles spawn at click point with random velocities
+ * 3. Animation loop runs at 60 FPS:
+ *    a. Clear previous frame
+ *    b. Update each particle (position, life, size)
+ *    c. Draw each particle (gradient + glow)
+ *    d. Remove dead particles (life <= 0)
+ * 4. Loop stops when all particles are gone (performance optimization)
+ */
+export function useGlowParticles(
+  config: ParticleConfig = DEFAULT_PARTICLE_CONFIG,
+  disabled: boolean = false
+): UseGlowParticlesReturn {
+  // Mutable refs that persist across renders without causing re-renders
+  const particlesRef = useRef<Particle[]>([]);
+  const animationFrameRef = useRef<number | null>(null);
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const isAnimatingRef = useRef<boolean>(false);
+
+  /**
+   * CREATE PARTICLE BURST
+   *
+   * VISUAL EFFECT: When called, spawns N particles at the click location.
+   * Each particle:
+   * - Starts at (x, y)
+   * - Gets a random velocity in a random direction
+   * - Gets a random size and color from config
+   * - Has full life (1.0) at spawn
+   *
+   * The "burst" pattern comes from random angles - particles explode
+   * outward in all directions like a tiny firework.
+   *
+   * Visual analogy: Like tapping a dandelion and seeds flying off
+   */
+  const createParticleBurst = useCallback(
+    (x: number, y: number) => {
+      // Skip if disabled (accessibility) or no canvas
+      if (disabled) return;
+
+      const newParticles: Particle[] = [];
+
+      for (let i = 0; i < config.particleCount; i++) {
+        /**
+         * RANDOM ANGLE for burst direction
+         *
+         * VISUAL: Math.random() * Math.PI * 2 gives angle from 0 to 2π
+         * This means particles fly in ALL directions (360 degrees)
+         *
+         * Alternative patterns:
+         * - Math.PI * 1.5 to Math.PI * 2.5 = upward-biased cone
+         * - Fixed angle = particles move in same direction
+         */
+        const angle = Math.random() * Math.PI * 2;
+
+        /**
+         * RANDOM SPEED within configured range
+         *
+         * VISUAL: Variation in speed creates depth - some particles
+         * appear to move faster/closer while others drift slowly
+         */
+        const speed = randomBetween(config.minSpeed, config.maxSpeed);
+
+        /**
+         * VELOCITY COMPONENTS from angle and speed
+         *
+         * VISUAL:
+         * - vx = speed * cos(angle): horizontal component
+         * - vy = speed * sin(angle): vertical component
+         *
+         * Together, these create the direction of movement
+         */
+        const vx = Math.cos(angle) * speed;
+        const vy = Math.sin(angle) * speed;
+
+        /**
+         * RANDOM SIZE for visual variety
+         *
+         * VISUAL: Mix of sizes creates depth and interest.
+         * Smaller particles appear more distant/delicate.
+         */
+        const size = randomBetween(config.minSize, config.maxSize);
+
+        /**
+         * RANDOM COLOR from palette
+         *
+         * VISUAL: Each particle gets one of the configured colors.
+         * The gradient will fade from this color (center) to transparent (edge).
+         */
+        const color = config.colors[Math.floor(Math.random() * config.colors.length)];
+
+        newParticles.push({
+          x,
+          y,
+          vx,
+          vy,
+          size,
+          life: 1.0, // Full life at spawn (completely visible)
+          color,
+          id: particleIdCounter++,
+        });
+      }
+
+      // Add new particles to existing ones
+      particlesRef.current = [...particlesRef.current, ...newParticles];
+
+      // Start animation if not already running
+      if (!isAnimatingRef.current) {
+        isAnimatingRef.current = true;
+        animationFrameRef.current = requestAnimationFrame(animate);
+      }
+    },
+    [config, disabled]
+  );
+
+  /**
+   * DRAW SINGLE PARTICLE
+   *
+   * This is where the visual magic happens. Each particle is rendered as:
+   * 1. A radial gradient (bright center -> transparent edge)
+   * 2. With a soft glow effect (shadowBlur)
+   *
+   * VISUAL BREAKDOWN:
+   *
+   *        ░░░░░░░░░░░░░░░  <- Glow halo (shadowBlur)
+   *       ░░░░░░░░░░░░░░░░░
+   *      ░░░░░▒▒▒▒▒▒▒░░░░░░  <- Outer gradient (50% opacity, fading)
+   *     ░░░░▒▒▒▒▒▒▒▒▒▒░░░░░
+   *    ░░░░▒▒▒▓▓▓▓▓▒▒▒░░░░░  <- Mid gradient (70% opacity)
+   *    ░░░░▒▒▓▓███▓▓▒▒░░░░░  <- Inner core (100% opacity)
+   *    ░░░░▒▒▒▓▓▓▓▓▒▒▒░░░░░
+   *     ░░░░▒▒▒▒▒▒▒▒▒░░░░░░
+   *      ░░░░░▒▒▒▒▒▒▒░░░░░░
+   *       ░░░░░░░░░░░░░░░░░
+   *        ░░░░░░░░░░░░░░░
+   */
+  const drawParticle = useCallback(
+    (ctx: CanvasRenderingContext2D, particle: Particle) => {
+      // Calculate current visual properties based on life
+      // As life decreases, particle becomes smaller and more transparent
+      const currentSize = particle.size * particle.life;
+      const currentOpacity = particle.life;
+
+      // Skip if too small to see
+      if (currentSize < 0.5) return;
+
+      // Parse the base color to RGB for gradient creation
+      const rgb = hexToRgb(particle.color);
+
+      /**
+       * CREATE RADIAL GRADIENT
+       *
+       * ctx.createRadialGradient(x0, y0, r0, x1, y1, r1)
+       *
+       * PARAMETERS EXPLAINED:
+       * - (x0, y0, r0): Inner circle - center of particle, radius 0
+       * - (x1, y1, r1): Outer circle - center of particle, radius = currentSize/2
+       *
+       * VISUAL: The gradient will interpolate colors from the inner circle
+       * to the outer circle. Since both circles share the same center,
+       * this creates a circular gradient radiating outward.
+       *
+       *   Inner (r0=0)    Outer (r1=radius)
+       *        █          ░░░░░░░░░░
+       *        ↓          ↓
+       *      [solid] -> [transparent]
+       */
+      const radius = currentSize / 2;
+      const gradient = ctx.createRadialGradient(
+        particle.x,
+        particle.y,
+        0, // Inner circle: center point, radius 0 (a dot)
+        particle.x,
+        particle.y,
+        radius // Outer circle: same center, radius = particle size
+      );
+
+      /**
+       * ADD COLOR STOPS
+       *
+       * Color stops define how the gradient transitions from center to edge.
+       *
+       * VISUAL EFFECT OF EACH STOP:
+       *
+       * Stop 0.0 (center): Full color, full opacity
+       *   - This is the "hot spot" - brightest point
+       *   - Like the white center of a candle flame
+       *
+       * Stop 0.4 (40% radius): Full color, 70% opacity
+       *   - Still bright but starting to fade
+       *   - Creates a solid-looking core
+       *
+       * Stop 0.7 (70% radius): Full color, 30% opacity
+       *   - Clearly fading now
+       *   - The "warm glow" zone
+       *
+       * Stop 1.0 (edge): Full color, 0% opacity
+       *   - Completely transparent
+       *   - No hard edge - particle "melts" into background
+       *
+       * The currentOpacity multiplier makes the whole particle
+       * more transparent as it ages (life decreases from 1 to 0)
+       */
+      gradient.addColorStop(
+        0,
+        `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${1.0 * currentOpacity})`
+      );
+      gradient.addColorStop(
+        0.4,
+        `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${0.7 * currentOpacity})`
+      );
+      gradient.addColorStop(
+        0.7,
+        `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${0.3 * currentOpacity})`
+      );
+      gradient.addColorStop(
+        1,
+        `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, 0)`
+      );
+
+      /**
+       * APPLY GLOW EFFECT (shadowBlur)
+       *
+       * VISUAL: shadowBlur creates a soft halo around whatever we draw.
+       * Unlike the radial gradient (which IS the particle shape),
+       * the shadow extends BEYOND the particle boundary.
+       *
+       * Think of it like:
+       * - Radial gradient = the physical LED light bulb
+       * - shadowBlur = the glow you see around the bulb
+       *
+       * shadowBlur = 15 means:
+       * - A 15-pixel soft blur extends beyond the particle
+       * - Color matches shadowColor (the particle's color)
+       * - Intensity determined by currentOpacity
+       *
+       * As particle life decreases:
+       * - Glow intensity decreases proportionally
+       * - Creates the effect of "cooling down" or "fading away"
+       */
+      ctx.shadowBlur = config.glowIntensity * currentOpacity;
+      ctx.shadowColor = `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${0.6 * currentOpacity})`;
+
+      /**
+       * DRAW THE PARTICLE
+       *
+       * ctx.arc(x, y, radius, startAngle, endAngle)
+       * - Draws a circle (full arc = 0 to 2π)
+       * - Fill with our radial gradient
+       *
+       * VISUAL: The combination of radial gradient + shadowBlur creates:
+       * - Bright core (gradient center)
+       * - Soft falloff (gradient edge)
+       * - Extended glow (shadow blur)
+       *
+       * Together: a soft, glowing orb that looks like a tiny light source
+       */
+      ctx.beginPath();
+      ctx.arc(particle.x, particle.y, radius, 0, Math.PI * 2);
+      ctx.fillStyle = gradient;
+      ctx.fill();
+
+      // Reset shadow to avoid affecting other drawings
+      ctx.shadowBlur = 0;
+      ctx.shadowColor = 'transparent';
+    },
+    [config.glowIntensity]
+  );
+
+  /**
+   * ANIMATION LOOP
+   *
+   * This runs at approximately 60 frames per second (synced with display).
+   * Each frame:
+   * 1. Clear the previous frame (canvas becomes transparent)
+   * 2. Update each particle's physics (position, life, size)
+   * 3. Draw each particle in its new state
+   * 4. Remove particles that have "died" (life <= 0)
+   * 5. Continue loop if particles remain, else stop
+   *
+   * VISUAL FLOW:
+   * Frame 0: Particles at spawn position, full brightness
+   * Frame 30: Particles have moved, 50% life remaining
+   * Frame 60: Particles nearly gone, very faint
+   * Frame 67: All particles dead, loop stops
+   *
+   * Performance note: Loop only runs when particles exist.
+   * When no particles remain, we stop to save CPU.
+   */
+  const animate = useCallback(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) {
+      isAnimatingRef.current = false;
+      return;
+    }
+
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+      isAnimatingRef.current = false;
+      return;
+    }
+
+    /**
+     * CLEAR PREVIOUS FRAME
+     *
+     * VISUAL: Wipes the canvas completely transparent.
+     * Without this, particles would leave "trails" as they move.
+     *
+     * Alternative: Use ctx.fillRect with semi-transparent color
+     * for intentional trail/afterimage effects (not desired here).
+     */
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+    /**
+     * UPDATE AND DRAW EACH PARTICLE
+     */
+    particlesRef.current = particlesRef.current.filter((particle) => {
+      /**
+       * UPDATE POSITION
+       *
+       * VISUAL: Move particle by its velocity
+       * - x += vx: horizontal movement
+       * - y += vy: vertical movement
+       *
+       * Result: Particle drifts in its assigned direction
+       */
+      particle.x += particle.vx;
+      particle.y += particle.vy;
+
+      /**
+       * APPLY UPWARD DRIFT
+       *
+       * VISUAL: Adds small upward acceleration each frame
+       * Negative vy = moving up (canvas y increases downward)
+       *
+       * Effect: Particles gradually curve upward like:
+       * - Sparks rising from a fire
+       * - Bubbles floating in liquid
+       * - Heat shimmer rising
+       */
+      particle.vy += config.upwardDrift;
+
+      /**
+       * UPDATE LIFE (opacity)
+       *
+       * VISUAL: Decrease life each frame
+       * life goes from 1.0 -> 0.0 over fadeRate * frames
+       *
+       * At 60 FPS with fadeRate 0.016:
+       * 1.0 / 0.016 = 62.5 frames = ~1 second to fade out
+       */
+      particle.life -= config.fadeRate;
+
+      /**
+       * UPDATE SIZE (shrinking)
+       *
+       * VISUAL: Multiply size by shrinkRate each frame
+       * shrinkRate 0.985 means particle is 98.5% of previous size
+       *
+       * After 60 frames: 0.985^60 = 0.40 = 40% of original size
+       *
+       * Combined with fade, creates "dissipating" effect
+       */
+      particle.size *= config.shrinkRate;
+
+      /**
+       * DRAW THE PARTICLE
+       *
+       * Only if still alive (visible)
+       */
+      if (particle.life > 0) {
+        drawParticle(ctx, particle);
+      }
+
+      /**
+       * KEEP OR REMOVE
+       *
+       * Return true to keep particle in array, false to remove
+       * Remove when life <= 0 (completely faded out)
+       */
+      return particle.life > 0;
+    });
+
+    /**
+     * CONTINUE OR STOP LOOP
+     *
+     * VISUAL: If particles remain, schedule next frame
+     * If no particles, stop the animation loop
+     *
+     * Performance: Prevents unnecessary CPU usage when idle
+     */
+    if (particlesRef.current.length > 0) {
+      animationFrameRef.current = requestAnimationFrame(animate);
+    } else {
+      isAnimatingRef.current = false;
+      animationFrameRef.current = null;
+    }
+  }, [config.fadeRate, config.shrinkRate, config.upwardDrift, drawParticle]);
+
+  /**
+   * CLEANUP ON UNMOUNT
+   *
+   * Cancel any pending animation frame to prevent memory leaks
+   * and errors from drawing on unmounted canvas
+   */
+  useEffect(() => {
+    return () => {
+      if (animationFrameRef.current !== null) {
+        cancelAnimationFrame(animationFrameRef.current);
+      }
+    };
+  }, []);
+
+  return {
+    canvasRef,
+    createParticleBurst,
+    isAnimating: isAnimatingRef.current,
+  };
+}
+
+export default useGlowParticles;

frontend/src/hooks/useReducedMotion.ts

@@ -0,0 +1,67 @@
+/**
+ * useReducedMotion Hook
+ *
+ * Accessibility hook that detects user's motion preference.
+ * When enabled, particle effects should be disabled or minimized.
+ *
+ * VISUAL ACCESSIBILITY CONTEXT:
+ * Some users experience motion sickness, vestibular disorders, or simply
+ * prefer reduced animation. The "prefers-reduced-motion" media query
+ * indicates this preference.
+ *
+ * When this hook returns true:
+ * - Particle effects should NOT be rendered
+ * - OR particles should appear statically (no animation)
+ * - This respects user autonomy and WCAG guidelines
+ */
+import { useState, useEffect } from 'react';
+
+/**
+ * Detects if the user prefers reduced motion
+ *
+ * @returns true if user prefers reduced motion, false otherwise
+ *
+ * USAGE:
+ * ```tsx
+ * const prefersReducedMotion = useReducedMotion();
+ *
+ * if (prefersReducedMotion) {
+ *   // Skip particle animation entirely
+ *   return null;
+ * }
+ * ```
+ */
+export function useReducedMotion(): boolean {
+  // Server-side rendering safety: default to false
+  const [prefersReducedMotion, setPrefersReducedMotion] = useState(false);
+
+  useEffect(() => {
+    // Check if matchMedia is available (browser environment)
+    if (typeof window === 'undefined' || !window.matchMedia) {
+      return;
+    }
+
+    // Create media query matcher
+    const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+
+    // Set initial value
+    setPrefersReducedMotion(mediaQuery.matches);
+
+    // Listen for changes (user might toggle system preference)
+    const handleChange = (event: MediaQueryListEvent) => {
+      setPrefersReducedMotion(event.matches);
+    };
+
+    // Modern browsers use addEventListener
+    mediaQuery.addEventListener('change', handleChange);
+
+    // Cleanup listener on unmount
+    return () => {
+      mediaQuery.removeEventListener('change', handleChange);
+    };
+  }, []);
+
+  return prefersReducedMotion;
+}
+
+export default useReducedMotion;

frontend/src/types/particles.ts

@@ -0,0 +1,296 @@
+/**
+ * Particle System Types
+ *
+ * VISUAL OVERVIEW:
+ * These types define the data structures for creating soft, glowing particles
+ * that appear when users interact with elements (like wikilinks).
+ *
+ * Each particle is a small glowing orb (6-12px) with:
+ * - A radial gradient from bright center to transparent edge
+ * - A soft blur halo that extends beyond the particle boundary
+ * - Smooth animation: floating outward, shrinking, and fading
+ *
+ * Visual Analogy: Think of particles as tiny floating embers or LED lights
+ * viewed through frosted glass - soft, warm, and gradually fading.
+ */
+
+/**
+ * Individual Particle State
+ *
+ * Each particle is an autonomous visual element with its own position,
+ * velocity, appearance, and lifecycle state.
+ */
+export interface Particle {
+  /**
+   * Horizontal position in canvas coordinates (pixels from left edge)
+   * VISUAL: Determines where the glowing orb appears on screen
+   */
+  x: number;
+
+  /**
+   * Vertical position in canvas coordinates (pixels from top edge)
+   * VISUAL: Combined with x, places the particle's center point
+   */
+  y: number;
+
+  /**
+   * Horizontal velocity (pixels per animation frame)
+   * VISUAL: Positive = moving right, Negative = moving left
+   * Typical range: -3 to +3 for gentle floating movement
+   */
+  vx: number;
+
+  /**
+   * Vertical velocity (pixels per animation frame)
+   * VISUAL: Positive = moving down, Negative = moving up
+   * Typically starts negative with small positive bias for upward drift
+   */
+  vy: number;
+
+  /**
+   * Particle diameter in pixels
+   * VISUAL: Determines the size of the glowing orb
+   * The radial gradient spans from center (0) to this radius (size/2)
+   * Typical range: 4-14 pixels for subtle effect
+   */
+  size: number;
+
+  /**
+   * Lifecycle progress from 1.0 (birth) to 0.0 (death)
+   * VISUAL EFFECTS:
+   * - Multiplied with opacity: particle becomes more transparent as life decreases
+   * - Multiplied with glow intensity: halo shrinks as particle dies
+   * - When life <= 0, particle is removed from the system
+   *
+   * Visual analogy: Like a candle burning down - starts bright, gradually dims
+   */
+  life: number;
+
+  /**
+   * Base color for the particle gradient (hex format: '#RRGGBB')
+   * VISUAL: This is the CENTER color of the radial gradient
+   * The edge fades to transparent using the same hue
+   *
+   * Palette typically includes:
+   * - '#6366f1' (indigo/blue) - cool, professional
+   * - '#a855f7' (purple) - rich, balanced
+   * - '#ec4899' (pink) - warm accent
+   */
+  color: string;
+
+  /**
+   * Unique identifier for React reconciliation
+   * Not visually relevant, but necessary for efficient DOM updates
+   */
+  id: number;
+}
+
+/**
+ * Particle System Configuration
+ *
+ * These settings control the overall visual behavior of the particle system.
+ * Adjusting these values changes the "feel" of the effect.
+ */
+export interface ParticleConfig {
+  /**
+   * Number of particles spawned per trigger (click/interaction)
+   * VISUAL IMPACT:
+   * - Low (5-10): Subtle, minimal effect - professional/elegant
+   * - Medium (12-20): Noticeable but not overwhelming
+   * - High (25+): Dense, celebratory - can feel tacky if overdone
+   *
+   * Recommendation: 12-15 for subtle elegance
+   */
+  particleCount: number;
+
+  /**
+   * Minimum particle diameter in pixels
+   * VISUAL: Sets the lower bound for particle size variation
+   * Smaller particles appear more distant/delicate
+   * Typical value: 4-6 pixels
+   */
+  minSize: number;
+
+  /**
+   * Maximum particle diameter in pixels
+   * VISUAL: Sets the upper bound for particle size variation
+   * Larger particles appear closer/more prominent
+   * Typical value: 8-12 pixels
+   */
+  maxSize: number;
+
+  /**
+   * Minimum initial velocity magnitude (pixels per frame)
+   * VISUAL: How slow the slowest particles move
+   * Lower = more leisurely floating
+   * Typical value: 1.5-2.0
+   */
+  minSpeed: number;
+
+  /**
+   * Maximum initial velocity magnitude (pixels per frame)
+   * VISUAL: How fast the fastest particles move
+   * Higher = more energetic burst
+   * Typical value: 3.0-4.5
+   */
+  maxSpeed: number;
+
+  /**
+   * Glow halo intensity (shadowBlur value in pixels)
+   * VISUAL IMPACT:
+   * - 5-10: Subtle glow, barely perceptible halo
+   * - 12-18: Moderate glow, clearly visible soft halo
+   * - 20+: Strong glow, dramatic ethereal effect
+   *
+   * This creates the "frosted glass" effect around particles.
+   * The glow color matches the particle color.
+   *
+   * Visual analogy: Like the halo around a streetlight on a foggy night
+   */
+  glowIntensity: number;
+
+  /**
+   * Life decrement per animation frame (typically at 60 FPS)
+   * VISUAL IMPACT:
+   * - 0.010: Slow fade (~1.7 seconds to disappear)
+   * - 0.015: Medium fade (~1.1 seconds) - RECOMMENDED
+   * - 0.025: Fast fade (~0.7 seconds)
+   *
+   * Controls how quickly particles become transparent and die.
+   * Lower values = longer-lasting particles
+   */
+  fadeRate: number;
+
+  /**
+   * Size multiplier per animation frame (0 < shrinkRate < 1)
+   * VISUAL IMPACT:
+   * - 0.995: Very slow shrink, particles stay nearly same size
+   * - 0.985: Moderate shrink - RECOMMENDED (40% original size after 60 frames)
+   * - 0.970: Fast shrink, particles quickly become tiny
+   *
+   * Combined with fadeRate, creates the "dissipating" visual effect.
+   */
+  shrinkRate: number;
+
+  /**
+   * Upward drift acceleration per frame (added to vy each frame)
+   * VISUAL: Negative values make particles float upward over time
+   * Creates the "rising heat" or "bubbles ascending" effect
+   *
+   * Typical value: -0.02 to -0.05
+   * 0 = no drift, particles move in straight lines
+   */
+  upwardDrift: number;
+
+  /**
+   * Available colors for random selection
+   * VISUAL: Each spawned particle gets a random color from this array
+   * Colors should be harmonious for a cohesive effect.
+   *
+   * Default palette: blue (#6366f1), purple (#a855f7), pink (#ec4899)
+   * Matches Tailwind indigo-500, violet-500, pink-500
+   */
+  colors: string[];
+}
+
+/**
+ * Default configuration for subtle, elegant particles
+ *
+ * VISUAL RESULT:
+ * - 12 small particles (6-10px) spawn per click
+ * - Move outward at moderate speed (2-3.5 px/frame)
+ * - Have a visible but not overwhelming glow (15px blur)
+ * - Fade and shrink over approximately 1 second
+ * - Float gently upward as they age
+ * - Colors: cool blue/purple/pink palette
+ */
+export const DEFAULT_PARTICLE_CONFIG: ParticleConfig = {
+  particleCount: 12,
+  minSize: 6,
+  maxSize: 10,
+  minSpeed: 2.0,
+  maxSpeed: 3.5,
+  glowIntensity: 15,
+  fadeRate: 0.016,    // ~60 frames = 1 second to fade out
+  shrinkRate: 0.985,  // ~40% original size after 60 frames
+  upwardDrift: -0.03, // Gentle upward float
+  colors: [
+    '#6366f1', // Indigo (blue-ish)
+    '#a855f7', // Violet (purple)
+    '#ec4899', // Pink
+  ],
+};
+
+/**
+ * Pre-configured visual presets for different use cases
+ *
+ * Each preset creates a distinct visual "mood"
+ */
+export const PARTICLE_PRESETS = {
+  /**
+   * SUBTLE preset
+   * VISUAL: Small, quick, minimal particles
+   * USE CASE: Professional applications, frequent interactions
+   * IMPRESSION: Polished, refined, not distracting
+   */
+  subtle: {
+    particleCount: 8,
+    minSize: 4,
+    maxSize: 7,
+    minSpeed: 2.0,
+    maxSpeed: 3.0,
+    glowIntensity: 10,
+    fadeRate: 0.020,    // Faster fade (~0.8 seconds)
+    shrinkRate: 0.980,
+    upwardDrift: -0.02,
+    colors: ['#6366f1', '#a855f7', '#ec4899'],
+  } satisfies ParticleConfig,
+
+  /**
+   * ELEGANT preset (default)
+   * VISUAL: Balanced size and count, moderate glow
+   * USE CASE: Standard interactions, wikilink clicks
+   * IMPRESSION: Premium UI polish, noticeable but tasteful
+   */
+  elegant: DEFAULT_PARTICLE_CONFIG,
+
+  /**
+   * VIBRANT preset
+   * VISUAL: More particles, larger, longer-lasting
+   * USE CASE: Celebrations, achievements, special actions
+   * IMPRESSION: Playful, energetic, celebratory
+   */
+  vibrant: {
+    particleCount: 20,
+    minSize: 8,
+    maxSize: 14,
+    minSpeed: 2.5,
+    maxSpeed: 4.5,
+    glowIntensity: 20,
+    fadeRate: 0.012,    // Slower fade (~1.4 seconds)
+    shrinkRate: 0.990,
+    upwardDrift: -0.04,
+    colors: ['#6366f1', '#a855f7', '#ec4899', '#f472b6'],
+  } satisfies ParticleConfig,
+
+  /**
+   * MINIMAL preset
+   * VISUAL: Very few, very small, very quick particles
+   * USE CASE: High-frequency interactions, accessibility considerations
+   * IMPRESSION: Almost imperceptible polish
+   */
+  minimal: {
+    particleCount: 5,
+    minSize: 3,
+    maxSize: 5,
+    minSpeed: 2.5,
+    maxSpeed: 3.5,
+    glowIntensity: 8,
+    fadeRate: 0.025,    // Fast fade (~0.7 seconds)
+    shrinkRate: 0.975,
+    upwardDrift: -0.01,
+    colors: ['#6366f1', '#a855f7'],
+  } satisfies ParticleConfig,
+} as const;
+
+export type ParticlePreset = keyof typeof PARTICLE_PRESETS;