<!-- source-hash: 67651d104f2d85ae6efdf60affb29813 -->
Runtime utilities for working with ODS (OpenFrame Design System) color tokens, providing platform-aware color resolution, CSS custom property management, and color math helpers for the `openmsp`, `openframe`, and `flamingo` platforms.

## Key Components

### Types

| Type | Values |
|---|---|
| `Platform` | `'openmsp'` \| `'openframe'` \| `'flamingo'` |
| `ColorCategory` | `'open'` \| `'flamingo'` \| `'system'` \| `'attention'` |
| `ColorVariant` | `'base'` \| `'hover'` \| `'active'` \| `'focus'` \| `'disabled'` |

### Token Lookup

- **`getODSToken(category, color, variant?)`** — Resolves a raw token value by composing the key as `{category}-{color}-{variant}`.
- **`getTokensByCategory(category)`** — Returns all tokens matching a category prefix.
- **`isValidODSToken(tokenKey)`** — Validates token existence in the ODS registry.

### Platform & Theme

- **`getCurrentPlatform()`** — Resolves the active platform from `data-app-type` DOM attribute or `NEXT_PUBLIC_APP_TYPE` env var (SSR-safe).
- **`getPlatformAccentColor(platform?)`** — Returns the CSS variable for the platform accent color.
- **`getPlatformConfig(platform?)`** — Returns a config object with accent color, theme mode, and brand name.
- **`switchPlatformTheme(platform)`** — Updates `data-app-type` on `<html>` and dispatches a `platformThemeChanged` custom event.
- **`generatePlatformCSS(platform)`** — Generates a CSS block with platform-scoped custom property overrides.

### Color Math

- **`hexToRgb(hex)`** / **`rgbToHex(r, g, b)`** — Hex ↔ RGB conversion with clamping. `hexToRgb` returns `null` on invalid input.
- **`rgbToHsl(r, g, b)`** / **`hslToRgb(h, s, l)`** — RGB ↔ HSL conversion.
- **`deriveHoverColor(hex)`** — Darkens each channel by 10.
- **`deriveActiveColor(hex)`** — Darkens each channel by 20.
- **`interpolateColors(startToken, endToken, progress)`** — Linear hex interpolation between two token values.
- **`getReadableTextColor(hex)`** — Returns `'#212121'` (dark) or `'#fafafa'` (light) based on WCAG luminance via `pickReadableTextColor`.

### Tailwind & DOM Helpers

- **`tokenToTailwindClass(tokenKey, type?)`** — Maps a semantic token name to a Tailwind class (e.g., `bg-ods-accent`).
- **`applyColorToken(element, property, tokenKey)`** — Sets a CSS custom property directly on an element.
- **`getSemanticColor(semanticName, platform?)`** — Reads a computed `--color-{name}` value from the live DOM.

### React Hook

- **`usePlatformColors(platform?)`** — Returns a platform config object plus convenience methods (`getToken`, `switchTheme`, `getSemanticColor`) suitable for use in React components.

## Usage Example

```typescript
import {
  getCurrentPlatform,
  getPlatformConfig,
  getODSToken,
  deriveHoverColor,
  getReadableTextColor,
  tokenToTailwindClass,
  hexToRgb,
  rgbToHex,
} from './ods-color-utils';

// Resolve active platform and config
const platform = getCurrentPlatform(); // 'openframe'
const config = getPlatformConfig(platform);
// {
//   platform: 'openframe',
//   accentColor: 'var(--ods-open-yellow-base)',
//   isDarkTheme: true,
//   isLightTheme: false,
//   brandName: 'OpenFrame'
// }

// Look up a raw ODS token
const yellowBase = getODSToken('open', 'yellow', 'base'); // '#f5c518'

// Derive interaction states from a custom hex color
const customBg = '#3a7bd5';
const hoverBg = deriveHoverColor(customBg);   // '#306bcb' (–10 per channel)
const activeBg = deriveActiveColor(customBg); // '#275bb5' (–20 per channel)

// Pick accessible text color over a background
const textColor = getReadableTextColor(customBg); // '#fafafa'

// Map a semantic token to a Tailwind utility class
const bgClass = tokenToTailwindClass('accent-primary', 'bg'); // 'bg-ods-accent'

// Low-level color math
const rgb = hexToRgb('#ff6600'); // { r: 255, g: 102, b: 0 }
const hex = rgbToHex(255, 102, 0); // '#ff6600'

// Switch platform theme at runtime (client-side only)
import { switchPlatformTheme } from './ods-color-utils';
switchPlatformTheme('flamingo'); // sets data-app-type="flamingo", dispatches event

// React usage
import { usePlatformColors } from './ods-color-utils';

function MyComponent() {
  const { accentColor, isDarkTheme, getToken, switchTheme } = usePlatformColors();
  return <div style={{ color: accentColor }}>{isDarkTheme ? 'Dark' : 'Light'}</div>;
}
```

## Notes

- **SSR-safe**: Functions that touch `window` or `document` guard with `typeof window === 'undefined'` checks.
- **`HEX_PATTERN`** (`/^#[0-9a-fA-F]{6}$/`) is exported for external validation.
- Hover/active darken steps (`10` / `20` per RGB channel) mirror the design system's preset interaction states, keeping custom colors consistent with system tokens.
- `getSemanticColor` temporarily switches the platform theme to read computed styles — avoid calling it in hot paths.

## Source

[`ods-color-utils.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ods-color-utils.ts)