UI Design Styling

ryOS UI Design & Styling

Canonical References

• Implementation spec: docs/3.3.1-theme-architecture.md
• User-facing overview: docs/3.3-theme-system.md
• Token source of truth: src/styles/themes/tokens.css
• Theme CSS import order: src/styles/themes.css
• Tailwind mappings and variants: tailwind.config.js
• Theme metadata/state: src/themes/, src/stores/useThemeStore.ts, src/hooks/useThemeFlags.ts

Visual values belong in CSS --os-* tokens. TypeScript theme files hold metadata, platform behavior, dark-mode support flags, and wallpaper defaults; do not duplicate palettes in TS or component code.

Supported Themes

Default theme is macosx; default Aqua material is glass.

Root Attributes

useThemeStore applies attributes to <html>. Prefer targeting these through tokens and Tailwind variants.

CSS Layers

src/styles/themes.css imports theme CSS in this order:

1. tokens.css - defaults, per-theme token blocks, [data-selected="true"], z-index scale.
2. platform.css - rules shared by mac or windows platform buckets.
3. containment.css - reduced motion and third-party/app isolation.
4. aqua.css - Aqua structural chrome, .aqua-button, brushed metal, typography.
5. windows.css - Windows structural landing rules.
6. dark-aqua.css - Aqua dark tokens and structural overrides.
7. aqua-glass.css - Aqua Glass overrides, imported after dark Aqua.
8. control-panels-mac.css / control-panels-themed.css - Control Panels skins.

Windows themes also load /css/xp-custom.css or /css/98-custom.css dynamically. When a rule applies to both XP and Win98, use data-os-platform="windows" instead of duplicated exact-theme selectors.

Tokens and Utilities

Use token-backed Tailwind utilities first:

className="bg-os-window-bg border-os-window rounded-os shadow-os-window"
className="font-os-ui text-os-text-primary"
className="bg-os-panel-bg border-[length:var(--os-metrics-border-width)]"
className="bg-os-input-bg border-os-input-border focus:border-os-input-focusBorder"
className="text-os-link bg-os-selection-bg text-os-selection-text"
className="h-os-titlebar h-os-menubar z-menubar"

Core token groups:

• Fonts: --os-font-ui, --os-font-mono
• Surfaces: --os-color-window-bg, --os-color-panel-bg, --os-color-input-bg
• Borders/separators: --os-color-window-border, --os-color-separator, --os-color-input-border
• Text: --os-color-text-primary, --os-color-text-secondary, --os-color-text-disabled, --os-color-link
• Chrome: --os-color-menubar-*, --os-color-titlebar-*, --os-color-button-*
• Selection/accent: --os-color-selection-*, --os-color-selection-glow, --os-color-selection-ring-gap
• Metrics/shadows: --os-metrics-*, --os-window-shadow
• Aqua extras: --os-color-traffic-light-*, --os-pinstripe-*, --os-texture-*, --os-typography-*
• Layering: --z-base, --z-dialog, --z-menubar, --z-dropdown, --z-spotlight

Shadcn HSL variables (--background, --primary, etc.) still exist for generic UI primitives. For OS chrome and app surfaces, prefer --os-* tokens and bg-os-* / text-os-* utilities.

Tailwind Variants

Use root-attribute variants for small static visual differences:

className={cn(
  "bg-os-window-bg text-os-text-primary",
  "os-windows:border-os os-mac-aqua:rounded-os",
  "os-mac-system7:rounded-none os-theme-win98:shadow-none",
  "os-dark:bg-os-window-bg os-mac-aqua-dark:text-os-text-primary"
)}

Available variants:

• os-mac:, os-windows:
• os-mac-aqua:, os-mac-system7:
• os-theme-system7:, os-theme-macosx:, os-theme-xp:, os-theme-win98:
• os-dark:, os-mac-aqua-dark:, os-theme-<id>-dark:

Prefer CSS variants and tokens over React theme branches when the DOM and behavior do not change.

Theme State and Flags

Use useThemeFlags() for component decisions:

const {
  currentTheme,
  osPlatform,
  macChrome,
  metadata,
  isWindowsTheme,
  isMacTheme,
  isMacOSTheme,
  isSystem7Theme,
  isWinXp,
  isWin98,
  isClassicTheme,
  isAquaMenuChrome,
  isMacAquaChrome,
  supportsDarkMode,
  isDarkMode,
  darkModePreference,
  supportsAccent,
  accent,
  aquaMaterial,
  isAquaGlass,
} = useThemeFlags();

Use React branches only when structure, behavior, assets, layout math, or app logic differs. For non-React code, use useThemeStore.getState() or helpers from @/themes such as getOsPlatform, getOsMacChrome, isWindowsTheme, isMacTheme, isThemeWinXp, and isThemeWin98.

Shared Surface Primitives

Prefer shared primitives before adding new four-way class branches:

import {
  osCardClassName,
  osDrawerSurfaceClassName,
  osToolbarSurfaceClassName,
  osAppSidebarSurfaceClassName,
  osSeparatorBorderClassName,
  osSubtleIconButtonClassName,
  windowsBevelClassName,
} from "@/components/shared/osThemePrimitives";

Pass isAquaGlass when a primitive supports it. Use windowsBevelClassName("raised" | "sunken") instead of hand-writing Win98 bevel borders.

Icon and Asset Sourcing

When choosing app icons, toolbar glyphs, file-type art, dialog icons, devices, folders, or other OS-flavored imagery, search the repo icon libraries before drawing new assets or using external sources.

Active theme icons live under public/icons/<theme>/... and are resolved through public/icons/manifest.json by helpers such as pickIconPath, resolveIconLegacyAware, and useIconPath. Historical source libraries live outside active theme resolution:

• Mac OS X Panther/Tiger catalogs: public/resources/macos-icon-catalogs/{panther,tiger}/catalog.md
• Windows 98/XP catalogs: public/resources/windows-icon-catalogs/{win98,xp}/catalog.md

Use this order:

1. Prefer an existing logical icon in public/icons/default, then matching theme variants in public/icons/macosx, public/icons/win98, or public/icons/xp.
2. If no active icon fits, search the resource catalogs by concept and source era-appropriate art from categories such as applications, system-preferences, control-panels, dialog-ui-assets, folders, devices, and file-types.
3. Copy/adapt the chosen catalog asset into public/icons/<theme>/... only when it should participate in active UI rendering; keep public/resources/... as the source catalog, not as runtime app metadata.
4. Run bun run generate:icons after changing active public/icons files.
5. Preserve cross-theme fallback behavior: add default assets first, then theme-specific variants where they materially improve the UI.

Useful searches:

rg -i "calculator|paint|printer|warning|folder" public/resources/*-icon-catalogs
rg -i "\"themes\"|\"macosx\"|\"win98\"|\"xp\"" public/icons/manifest.json