# Themes & appearance — handoff

## Summary

Theming covers light/dark/system themes, custom CSS variables, font choices, page zoom, message spacing, and view transitions. Themes can be extended by plugins.

## User-facing behavior

- Theme toggle in settings (light / dark / system)
- Page zoom slider (General settings)
- Message spacing density
- View transitions on navigation (where supported)
- Plugin-registered custom themes

## Architecture

```
ThemeManager.tsx — auth vs client theme application
settings.ts — theme, zoom, spacing in settingsAtom
useTheme.ts — read/apply theme
ClientNonUIFeatures — PageZoomFeature, EmojiStyleFeature
vanilla-extract / folds tokens in colors.css.ts
```

## Key files

| Path | Role |
|------|------|
| `cinny/src/app/pages/ThemeManager.tsx` | Route-level theme |
| `cinny/src/app/state/settings.ts` | Settings including theme |
| `cinny/src/app/hooks/useTheme.ts` | Theme hook |
| `cinny/src/colors.css.ts` | Color tokens |
| `cinny/src/app/pages/client/ClientNonUIFeatures.tsx` | Page zoom CSS |
| `cinny/src/app/hooks/useViewTransitions.ts` | View transitions |
| `cinny/src/app/hooks/useMessageSpacing.ts` | Message density |
| `cinny/public/themes/` | Bundled theme files (if present) |

## Data model

| Key | Storage |
|-----|---------|
| `settingsAtom` | theme, pageZoom, messageSpacing, emojiStyle |

## Dependencies

- `folds` design system
- `@vanilla-extract/css` for component styles
- CSS `prefers-color-scheme` for system theme

## Integration points

- **plugins**: `registerTheme` API
- **user-settings**: General tab controls
- **forum**: `forumTheme.css.ts` forum-specific styling

## Testing

### Manual

1. Switch dark/light; all pages consistent.
2. System theme follows OS.
3. Page zoom 80–150%; layout usable.
4. Plugin theme applies without breaking contrast.

### Automated

- None

## Known issues & gotchas

- Separate `AuthRouteThemeManager` and client theme — auth pages may differ
- Zoom uses `font-size` on `documentElement` — may affect rem layout globally
- Forum theme partially separate from global tokens

## Future work

- High contrast accessibility theme
- Per-room wallpaper from avatar metadata banner

## Related docs

- [user-settings HANDOFF](../user-settings/HANDOFF.md)
- [plugins HANDOFF](../plugins/HANDOFF.md)
- [avatar-metadata HANDOFF](../avatar-metadata/HANDOFF.md)

## Add your extra things here

- `EmojiStyle` enum affects `--font-emoji` CSS variable
- `useViewTransitions` tied to browser View Transitions API support