Skip to main content

Theming System Documentation

Overview​

The FishingLog theming system allows users, events, and charter businesses to fully customize their app experience using TamaGUI's powerful theming capabilities. This creates a personalized, branded experience that makes users feel like the app is truly theirs.

Features​

  • User Personalization: Users can create and apply custom themes to personalize their app
  • Event Branding: Events can have custom themes for their event pages
  • Charter Branding: Charter businesses can brand their business pages with custom themes
  • TamaGUI Integration: Full support for TamaGUI theme tokens (colors, spacing, typography, etc.)
  • Theme Sharing: Users can share their themes publicly for others to use
  • Theme Inheritance: Themes can extend from base themes for easy customization
  • Theme Marketplace: Public themes can be discovered and used by all users

Architecture​

Theme Entity​

The Theme entity stores theme configurations with:

  • Basic Info: Name, description, type (User/Event/Charter/System/Shared)
  • TamaGUI Tokens: Full JSON theme configuration for TamaGUI compatibility
  • Quick Access Properties: Common theme properties (colors, fonts, spacing) for easy access
  • Branding: Logo, favicon, background images for events/charters
  • Metadata: Additional JSON for custom properties

Relationships​

  • User → Theme: Users can have one active theme
  • FishingEvent → Theme: Events can have custom themes
  • CharterCaptain → Theme: Charter businesses can have branded themes
  • Theme → Theme: Themes can extend from base themes (inheritance)

API Endpoints​

Theme Management​

  • GET /api/theme - Get all available themes (public + user's own)
  • GET /api/theme/{id} - Get a specific theme
  • GET /api/theme/me - Get current user's active theme
  • POST /api/theme - Create a new theme
  • PUT /api/theme/{id} - Update a theme (owner only)
  • DELETE /api/theme/{id} - Delete a theme (owner only, soft delete)
  • POST /api/theme/{id}/apply - Apply theme to current user
  • DELETE /api/theme/me - Remove theme from current user (revert to default)
  • POST /api/theme/{id}/duplicate - Duplicate a theme

Authorization​

  • View: Users can view public themes and their own themes
  • Create: Any authenticated user can create themes
  • Update/Delete: Only theme owner or admin can modify themes
  • System Themes: Default system themes cannot be modified/deleted (admin override)

TamaGUI Integration​

Theme Tokens Structure​

The ThemeTokens field stores a JSON object compatible with TamaGUI's theme system:

{
  "colors": {
    "background": "#ffffff",
    "foreground": "#000000",
    "accent": "#007AFF",
    "secondary": "#5856D6",
    "border": "#E5E5EA",
    "error": "#FF3B30",
    "warning": "#FF9500",
    "success": "#34C759",
    "info": "#5AC8FA"
  },
  "spacing": {
    "xs": 4,
    "sm": 8,
    "md": 16,
    "lg": 24,
    "xl": 32
  },
  "typography": {
    "fontFamily": "System",
    "headingFontFamily": "System",
    "fontSize": 16,
    "lineHeight": 1.5
  },
  "borderRadius": {
    "sm": 4,
    "md": 8,
    "lg": 12,
    "full": 9999
  }
}

Quick Access Properties​

For convenience, common theme properties are also stored as individual fields:

  • BackgroundColor, ForegroundColor, AccentColor, etc.
  • FontFamily, HeadingFontFamily, BaseFontSize, LineHeight
  • BaseSpacing, BorderRadius
  • LogoUrl, FaviconUrl, BackgroundImageUrl

These allow quick access without parsing JSON, while ThemeTokens provides full TamaGUI compatibility.

Usage Examples​

Creating a User Theme​

POST /api/theme
Content-Type: application/json

{
  "name": "Ocean Blue",
  "description": "A calming ocean-inspired theme",
  "themeType": "User",
  "accentColor": "#007AFF",
  "backgroundColor": "#F0F8FF",
  "foregroundColor": "#1E3A5F",
  "fontFamily": "System",
  "isPublic": false
}

Applying Theme to User​

POST /api/theme/{themeId}/apply

Creating Event Theme​

POST /api/theme
Content-Type: application/json

{
  "name": "Summer Fishing Tournament 2025",
  "description": "Official theme for the tournament",
  "themeType": "Event",
  "accentColor": "#FF6B35",
  "logoUrl": "https://example.com/event-logo.png",
  "backgroundImageUrl": "https://example.com/event-bg.jpg",
  "isPublic": true
}

Creating Charter Business Theme​

POST /api/theme
Content-Type: application/json

{
  "name": "Deep Sea Adventures Branding",
  "description": "Charter business theme",
  "themeType": "Charter",
  "accentColor": "#0066CC",
  "logoUrl": "https://example.com/charter-logo.png",
  "isPublic": false
}

Frontend Integration​

React Native (TamaGUI)​

import { useTheme } from '@tamagui/core';

// Fetch user's theme
const theme = await fetch('/api/theme/me').then(r => r.json());

// Apply TamaGUI theme
const tamaguiTheme = {
  ...theme.themeTokens, // Full TamaGUI tokens
  // Or use quick access properties
  background: theme.backgroundColor,
  color: theme.foregroundColor,
  // etc.
};

// Use in TamaGUI provider
<TamaguiProvider config={config} defaultTheme={tamaguiTheme}>
  {/* App content */}
</TamaguiProvider>

Web App (TamaGUI)​

Similar integration for web, using TamaGUI's web components with the theme tokens.

Theme Types​

  • User: Personal themes for individual users
  • Event: Themes for fishing events (expos, tournaments, etc.)
  • Charter: Themes for charter business pages
  • System: Default system themes (cannot be deleted)
  • Shared: Public themes available to all users

Best Practices​

  1. Theme Inheritance: Create base themes and extend them for variations
  2. Public Themes: Share well-designed themes publicly for community use
  3. Branding: Use logos and background images for events/charters
  4. Accessibility: Ensure sufficient color contrast in custom themes
  5. Performance: Keep theme tokens JSON reasonably sized
  6. Testing: Test themes on both light and dark mode (if supported)

Future Enhancements​

  • Theme marketplace/gallery
  • Theme templates for quick setup
  • Dark mode support
  • Theme preview before applying
  • Theme analytics (most popular themes)
  • Theme versioning
  • Import/export themes

Security Considerations​

  • Users can only modify their own themes (unless admin)
  • System themes are protected from deletion
  • Themes in use cannot be deleted (must remove from users/events/charters first)
  • Public themes are visible to all authenticated users
  • Private themes are only visible to the creator