<!-- source-hash: 320c7ab088203622f31bd929824e3767 -->
Provides color analysis utilities for extracting dominant colors from images and selecting accessible contrast colors from the Flamingo design palette, primarily used for dynamic badge and card styling.

## Key Components

| Export | Type | Description |
|--------|------|-------------|
| `ColorPalette` | Interface | Color descriptor with `name`, `hex`, and `rgb` tuple |
| `DESIGN_PALETTE` | Constant | Three-color palette: yellow `#FFC008`, black `#161616`, gray `#888888` |
| `hexToRgb` | Function | Converts a hex string to an RGB tuple |
| `getContrastRatio` | Function | Returns WCAG contrast ratio between two RGB colors |
| `extractDominantColor` | Function | Samples a canvas to find the most frequent bucketed color |
| `getBestContrastColor` | Function | Picks the palette color with highest contrast (≥ 3:1 minimum) |
| `analyzeImageColor` | Function | Loads an image URL, extracts dominant color, returns best palette match |
| `extractImageEdgeColorAsync` | Function | Samples edge pixels of an image and returns the dominant hex color for background fills |

## Usage Example

```typescript
import { analyzeImageColor, extractImageEdgeColorAsync, getContrastRatio, hexToRgb } from './color-analysis';

// Get the best badge text color for a logo image
const badgeColor = await analyzeImageColor('https://example.com/logo.png');
console.log(badgeColor.hex); // '#161616'

// Extract edge color for email/card background fill
const bgColor = await extractImageEdgeColorAsync('https://example.com/hero.jpg');
console.log(bgColor); // '#1a2b3c'

// Manual contrast check between two hex colors
const ratio = getContrastRatio(hexToRgb('#FFC008'), hexToRgb('#161616'));
console.log(ratio); // ~11.5 (passes WCAG AA and AAA)
```

> **Note:** `extractDominantColor` and `analyzeImageColor` are client-side only and require `document`/`canvas` APIs. `extractImageEdgeColorAsync` also guards against SSR with a `typeof window` check, resolving to `#000000` on the server.