Layouts and preferences

Totems has horizontal and vertical application layouts. The preferences provider selects the layout and resolves light, dark, and system theme choices.

Where layout is selected

AppShell in src/App.tsx reads layoutSelected through useUserPreferences(). It chooses HorizontalLayout or VerticalLayout from src/components/layout/ and changes the main content container accordingly.

The default layout in src/application/UserPreferences.tsx is horizontal. The main theme defaults to system. Existing browser preferences override those defaults.

Use the preferences API

Inside a component rendered beneath UserPreferencesProvider, import the hook from src/application/UserPreferencesContext.ts. For a component placed directly in src/components/, a small control can look like this:

import { Button } from "react-bootstrap";
import { useUserPreferences } from "../application/UserPreferencesContext";

export function DarkThemeButton() {
  const { setSelectedTheme } = useUserPreferences();
  return (
    <Button onClick={() => setSelectedTheme("dark")}>Use dark theme</Button>
  );
}

The hook throws outside its provider. Preserve the provider when extracting a starter shell from the demo.

Understand theme choices

The main theme accepts light, dark, or system. Menu and header surfaces accept light, dark, or match.

Desktop menu and header match follow the main theme. Mobile menu match follows the resolved desktop menu; mobile header match follows the resolved desktop header. This matters when the main content is light but the navigation is deliberately dark.

The provider applies data-bs-theme, data-menu-theme, data-header-theme, data-mobile-header-theme, and data-mobile-menu-theme to the document root. Use those existing attributes rather than creating a separate body class or competing theme state.

Saved preferences and defaults

src/application/themePreferences.ts defines the storage keys, including totem-theme and totem-layout. Preferences use browser local storage; when storage is unavailable, controls still work for the current session.

If you change a default and see no difference, inspect the saved preference for your development origin. Remove only the relevant preference key or test in a fresh browser profile. Clearing all site storage can remove unrelated application data.

UI preferences are distinct from app records. A saved theme does not mean edits to Projects, Calendar, or Chat persist.

Check layout changes

Test long titles, action groups, collapsed navigation, and narrow widths. Page headers stack below the small breakpoint. Keep keyboard focus visible and verify menus close and reopen correctly in each layout.

Use Styling and themes for color and typography changes; keep preferences responsible for selecting values, rather than duplicating the SCSS system in JavaScript.