cinny/docs/handoff/features/themes-and-appearance/HANDOFF.md

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
• plugins HANDOFF
• avatar-metadata HANDOFF

Add your extra things here

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