# Themes

The Orchard Suite supports multiple brand themes controlled by `ThemeProvider`. Themes override the `midnight-*` colour scale and the app-icon gradient, injecting brand-specific values as CSS custom properties at runtime.

## Available Themes

| Brand key | Theme name | `midnight-500` approx. | Used by |
|---|---|---|---|
| `'orchard'` | The Orchard (default) | `#3F93CF` (blue) | The Orchard apps |
| `'awal'` | AWAL | — | AWAL apps |
| `'sme'` | Sony Music Entertainment | — | SME apps |
| `'knr'` | KNR | — | KNR apps |

## How Theming Works

1. `ThemeProvider` reads `config.brand` and calls `applyTheme(brand)`.
2. `applyTheme` reads the matching theme object (`themeOrchard`, `themeAwal`, etc.) and sets each colour as a CSS custom property on `document.documentElement`.
3. All `--midnight-*` tokens across components update reactively without a page reload.

## Theme Object Shape

Each theme defines:

```ts
{
  colors: {
    'app-icon-gradient-color-0': string,  // gradient start
    'app-icon-gradient-color-1': string,  // gradient end
    'midnight-50' through 'midnight-1000': string,  // 20-step brand scale
    'dataviz-1' through 'dataviz-6': string,         // data visualisation palette
  }
}
```

## Available Theme Keys

The `themes` map exported from `@theorchard/suite-theming` contains all registered brands. Use it to get the list of valid keys without hardcoding them:

```tsx
import { themes } from '@theorchard/suite-theming';

const brandKeys = Object.keys(themes); // ['orchard', 'awal', 'sme', 'knr']
```

## Switching Themes at Runtime

Use `useTheme` (hook) or `useContext(ThemeContext)` directly:

```tsx
// Hook
import { useTheme } from '@theorchard/suite-theming';

const BrandSwitcher = () => {
  const { setTheme } = useTheme();
  return <button onClick={() => setTheme('awal')}>Switch to AWAL</button>;
};

// Direct context — useful outside hooks
import { useContext } from 'react';
import { ThemeContext } from '@theorchard/suite-theming';

const BrandSwitcher = () => {
  const { theme, setTheme } = useContext(ThemeContext);
  return <span>{theme}</span>;
};
```

## AppIcon Gradient

`AppIcon` and related components use `--app-icon-gradient-color-0` → `--app-icon-gradient-color-1`. These are set per-theme so brand icons automatically reflect the correct gradient.

## Rules

- MUST pass `config.brand` that matches one of: `'orchard'`, `'awal'`, `'sme'`, `'knr'`.
- MUST NOT hardcode `midnight-*` hex values — always reference the CSS token so themes apply correctly.
- Do NOT call `applyTheme` directly outside of `ThemeProvider` — use `setTheme` from `useTheme` hook instead.