User Settings Component
Relevant source files
The following files were used as context for generating this wiki page:
The User Settings Component manages user preferences for the website's appearance, specifically theme modes and font pairings. It provides a vanilla TypeScript implementation for interactive pickers that update the document state and persist choices in local storage. Sources: src/components/Settings/picker.ts, src/components/Settings/ThemeMode/utils.ts
Core Picker Architecture
The settings system utilizes a generic picker pattern for managing selections. This pattern uses native HTML elements, such as buttons and popovers, combined with vanilla TypeScript to handle interactions and state synchronization. Sources: src/components/Settings/picker.ts:1-10
Interaction Flow
The picker handles keyboard navigation, focus management, and selection updates. When a user interacts with a picker, the following flow occurs:
The diagram shows the logic flow for user interactions with a settings picker. Sources: src/components/Settings/picker.ts:40-100
Key Picker Functions
| Function | Purpose |
|---|---|
bindPreferencePicker | Attaches event listeners for clicks and keydown events to a picker element. |
syncPreferencePicker | Updates the UI attributes (aria-labels, hidden states) to match the current value. |
onPickerKeydown | Handles ArrowUp, ArrowDown, Home, and End keys for accessible navigation. |
closeSettingsPickers | Programmatically closes any open setting popovers. |
Sources: src/components/Settings/picker.ts:104-165
Theme Management
The theme system allows users to switch between light, dark, and system-defined modes. It applies classes to the document root and monitors system preference changes. Sources: src/components/Settings/ThemeMode/utils.ts:1-10
Theme Selection Logic
When a theme mode is selected, the system determines the "Effective Mode" based on the input. If "system" is chosen, the component queries the browser's prefers-color-scheme media query. Sources: src/components/Settings/ThemeMode/utils.ts:11-30
The sequence diagram illustrates how a theme selection propagates from the UI to storage and the DOM. Sources: src/components/Settings/ThemeMode/utils.ts:40-65, src/components/Settings/ThemeMode/theme-mode.ts
Theme Utilities
getEffectiveThemeMode(): Returns either the stored mode or the current system preference if the mode is set to 'system'. Sources: src/components/Settings/ThemeMode/utils.ts:47-49watchSystemPreference(): Attaches a listener to the(prefers-color-scheme: dark)media query to update the UI automatically when the user is in 'system' mode. Sources: src/components/Settings/ThemeMode/utils.ts:55-75
Font Pairings
The system supports predefined font pairings that change the typography of the entire site. Each pairing defines specific font families for headings, body text, and navigation. Sources: src/components/Settings/Font/pairings.ts:1-30
Configuration Structure
Font pairings are defined in FONT_PAIRING_CONFIGS. Each entry specifies CSS variables and metadata for the fonts.
| Pairing ID | Label | Heading Font | Body/Nav Font |
|---|---|---|---|
work | Work | Space Grotesk | IBM Plex Sans |
play | Play | Fredoka | Nunito |
live | Live | Lora | Source Sans 3 |
Sources: src/components/Settings/Font/pairings.ts:77-105
CSS Integration
The component generates dynamic CSS to apply these pairings. It maps generic font variables (e.g., --font-sans, --font-heading) to the specific font variables of the active pairing. Sources: src/components/Settings/Font/pairings.ts:149-165
/* Example of generated rules */
[data-font='work'] {
--default-font-family: var(--font-ibm-plex-sans);
--font-heading: var(--font-space-grotesk);
--font-ui: var(--font-ibm-plex-sans);
}
Sources: src/components/Settings/Font/pairings.ts:153-155
Styles and Layout
Settings panels are positioned using CSS Anchor Positioning (where supported) or absolute positioning. The global styles define the appearance of the popovers and the transitions between states. Sources: src/assets/styles/global.css:57-75
- Popovers: The
[data-preference-options]attribute identifies the settings panel, which is positioned relative to its anchor trigger. Sources: src/assets/styles/global.css:70-76 - Typography: The
[data-font]selector at the document level ensures that font pairings correctly inherit styles down to buttons, inputs, and other UI elements. Sources: src/assets/styles/typography.css:67-75
Conclusion
The User Settings Component provides a low-overhead, accessible way for users to customize their experience. By relying on native browser features like popovers and media queries, it ensures high performance while maintaining state consistency through local storage. Sources: src/components/Settings/picker.ts, src/components/Settings/ThemeMode/utils.ts