<!-- source-hash: a1cf673720fb7e195d055604da5c8efd -->
Storybook stories for the ODS (OpenFrame Design System) theme system, demonstrating light/dark theme switching, design token visualization, and component behavior across themes.

## Key Components

| Export | Type | Description |
|--------|------|-------------|
| `Showcase` | Story | Full-page demo with theme toggle, color token grid, and all UI components |
| `ToggleOnly` | Story | Minimal copy-paste reference showing `ThemeProvider` + `useThemeToggle()` integration |
| `SideBySide` | Story | Forced side-by-side light/dark panels using `.theme-light`/`.theme-dark` class escapes |
| `ThemeToggleButton` | Helper | Toggle button built on `useThemeToggle()` with Sun/Moon icons |
| `ThemeStatusBar` | Helper | Status bar showing current theme with explicit `setTheme('light' | 'dark')` controls |
| `TokenGrid` | Helper | Visual swatches for all `--ods-*` surface, text, accent, status, and border tokens |
| `ComponentsShowcase` | Helper | Renders Buttons, Inputs, Badges, Cards, and Alerts against the active theme |
| `Swatch` | Helper | Single color swatch rendering a Tailwind token class with its label |

## Usage Example

```typescript
// Wrap once with ThemeProvider; consume useThemeToggle() anywhere inside
import { ThemeProvider, useThemeToggle } from '../components/providers/theme-provider'

function MyToggle() {
  const { isDark, toggle, mounted } = useThemeToggle()
  return (
    <button onClick={toggle}>
      {mounted ? (isDark ? 'Switch to light' : 'Switch to dark') : 'Toggle theme'}
    </button>
  )
}

export default function App() {
  return (
    <ThemeProvider>
      <MyToggle />
    </ThemeProvider>
  )
}
```

> **How it works:** `ThemeProvider` (wrapping `next-themes`) sets `data-theme="light|dark"` on `<html>`. The `src/styles/ods-colors.css` file swaps all `--ods-*` primitive values accordingly — components only read tokens and are theme-unaware.