<!-- source-hash: 8d0a4e249109b10a270ca0755176abc6 -->
Runtime utility library for working with ODS (OpenFrame Design System) color tokens, providing platform-aware theming, token lookup, CSS generation, and React integration helpers.

## Key Components

| Export | Type | Description |
|--------|------|-------------|
| `Platform` | Type | Union of `'openmsp' \| 'openframe' \| 'flamingo'` |
| `ColorCategory` | Type | Union of `'open' \| 'flamingo' \| 'system' \| 'attention'` |
| `ColorVariant` | Type | Union of `'base' \| 'hover' \| 'active' \| 'focus' \| 'disabled'` |
| `getODSToken` | Function | Looks up a raw token value by category, color name, and variant |
| `getPlatformAccentColor` | Function | Returns the CSS variable for the current or specified platform's accent color |
| `getCurrentPlatform` | Function | Resolves platform from DOM attribute or `NEXT_PUBLIC_APP_TYPE` env var |
| `switchPlatformTheme` | Function | Updates `data-app-type` on `<html>` and dispatches `platformThemeChanged` event |
| `getSemanticColor` | Function | Reads a computed `--color-*` CSS property for a given platform |
| `tokenToTailwindClass` | Function | Maps a semantic token key to its corresponding Tailwind utility class |
| `getTokensByCategory` | Function | Returns all tokens matching a given `ColorCategory` prefix |
| `isValidODSToken` | Function | Checks whether a token key exists in the ODS token map |
| `getPlatformConfig` | Function | Returns a config object with accent color, theme type, and brand name |
| `generatePlatformCSS` | Function | Builds a CSS block of custom property overrides for a platform |
| `applyColorToken` | Function | Directly sets a CSS custom property on an `HTMLElement` |
| `interpolateColors` | Function | Linearly interpolates between two hex ODS tokens by progress (0–1) |
| `usePlatformColors` | Function | React-friendly helper returning platform config and token accessors |
| `getReadableTextColor` | Function | Returns `#212121` or `#fafafa` based on Rec. 601 luminance of a hex color |

## Usage Example

```typescript
import {
  getCurrentPlatform,
  getPlatformConfig,
  getODSToken,
  tokenToTailwindClass,
  interpolateColors,
  getReadableTextColor,
  usePlatformColors,
  switchPlatformTheme
} from './ods-color-utils';

// Resolve the active platform (SSR + CSR safe)
const platform = getCurrentPlatform(); // 'openframe'

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

// Look up a raw design token
const tokenValue = getODSToken('system', 'greys-background', 'base');

// Map a semantic token to a Tailwind class
const twClass = tokenToTailwindClass('text-primary', 'text');
// → 'text-ods-text-primary'

// Interpolate between two hex tokens (e.g. for animations)
const midColor = interpolateColors('open-yellow-base', 'flamingo-pink-base', 0.5);

// Ensure readable text on a dynamic background
const textColor = getReadableTextColor('#FFC008'); // → '#212121'

// Switch platform at runtime (updates <html data-app-type> + fires event)
switchPlatformTheme('flamingo');

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

> **Note:** `getSemanticColor` and `applyColorToken` are browser-only — they return `undefined` or no-op on the server. `switchPlatformTheme` cannot persist `process.env` changes in production; use it for UI-layer toggling only.