How to Customize the Frontend UI in Palmier Pro: Complete Guide to AppTheme

Customize the frontend UI in Palmier Pro by modifying the AppTheme type in Sources/PalmierPro/UI/AppTheme.swift, which serves as the single source of truth for all design tokens including colors, spacing, fonts, radii, and shadows.

Palmier Pro is a SwiftUI-based macOS application that centralizes all visual styling within a dedicated design system. To customize the frontend UI in Palmier Pro, you work directly with the AppTheme type, where every color, spacing value, corner radius, and animation duration is defined as a static constant. This architecture ensures consistent styling across the application while allowing you to rebrand or adjust the interface by editing files in the Sources/PalmierPro/UI/ directory.

Understanding the AppTheme Architecture

The Single Source of Truth Design

The AppTheme type in Sources/PalmierPro/UI/AppTheme.swift functions as the central design system for the application. Unlike hard-coded values scattered throughout views, all visual constants reside as static members within nested enums like AppTheme.Accent, AppTheme.Spacing, and AppTheme.Radius. This approach means that when you modify a value in AppTheme.swift, the change propagates automatically to every SwiftUI view and AppKit helper that references that token.

Key Files and Their Roles

Several critical files consume these design tokens:

• Sources/PalmierPro/UI/AppTheme.swift: Defines all design tokens including colors, spacing, fonts, radii, shadows, and opacity values.
• Sources/PalmierPro/UI/SidebarRowButton.swift: Demonstrates how UI components import AppTheme and apply tokens via modifiers like .padding() and .foregroundStyle().
• Sources/PalmierPro/UI/HoverHighlight.swift: Uses AppTheme.Radius, AppTheme.Anim.hover, and AppTheme.Opacity for consistent interaction styling.
• Sources/PalmierPro/Toolbar/ToolbarView.swift: Applies spacing and accent colors to the top-level toolbar.
• Sources/PalmierPro/Timeline/TimelineView.swift: Shows how lower-level AppKit drawing code reads the same token values via AppTheme properties.

How to Customize the Frontend UI in Palmier Pro

Method 1: Extend the Design System with New Tokens

When you need to add new brand colors or custom spacing values, extend the existing enums in AppTheme.swift. For example, to add a corporate brand accent color:

// Add to Sources/PalmierPro/UI/AppTheme.swift
enum Accent {
    // Existing accents…
    static let brand = Color(red: 0.12, green: 0.34, blue: 0.78)   // ← new brand color
}

You can then reference this token in any view:

Text("Powered by MyCo")
    .foregroundStyle(AppTheme.Accent.brand)

Method 2: Modify Existing Global Tokens

To change existing UI dimensions globally, update the static constants directly. If you want larger spacing between toolbar items, modify the value in AppTheme.swift:

// In AppTheme.swift, inside enum Spacing
static let md = CGFloat(12)   // default was 10

All components using AppTheme.Spacing.md (such as ToolbarView.swift) automatically adopt the new spacing without requiring individual view modifications.

Method 3: Override Tokens Locally for Specific Views

For screen-specific customizations, create a view-specific extension that supplies custom values without altering the global theme:

extension AppTheme {
    enum Custom {
        static let buttonBackground = Color.orange
    }
}

Then apply it in your specific view:

struct SpecialPanel: View {
    var body: some View {
        Button("Tap me") { /* action */ }
            .padding(AppTheme.Spacing.lg)
            .background(AppTheme.Custom.buttonBackground)   // uses the panel-specific token
    }
}

Practical Code Examples

Adding a Custom Icon Size

To introduce a new size for large toolbar icons, add a constant to AppTheme.IconSize:

// AppTheme.swift – add a new size for large toolbar icons
enum IconSize {
    // Existing sizes…
    static let xl = CGFloat(30)
    static let xl2 = CGFloat(36)   // ← new size
}

Consume it in your view:

Image(systemName: "camera")
    .font(.system(size: AppTheme.IconSize.xl2))
    .foregroundStyle(AppTheme.Text.primaryColor)

Re-styling Sidebar Buttons

The SidebarRowButton component in Sources/PalmierPro/UI/SidebarRowButton.swift demonstrates standard token consumption. To customize the button background when selected, first add a new token:

// In AppTheme.swift
enum Background {
    static let selected = NSColor(red: 0.15, green: 0.15, blue: 0.20, alpha: 1)
}

Then modify the view implementation:

struct SidebarRowButton: View {
    // existing definition...
    var body: some View {
        Button(action: action) {
            HStack(spacing: AppTheme.Spacing.smMd) {
                Image(systemName: systemImage)
                    .font(.system(size: AppTheme.FontSize.smMd))
                    .frame(width: AppTheme.Spacing.lgXl)
                Text(label)
                    .font(.system(size: AppTheme.FontSize.md))
                Spacer()
            }
            .padding(.horizontal, AppTheme.Spacing.smMd)
            .padding(.vertical, AppTheme.Spacing.sm)
            .foregroundStyle(AppTheme.Text.primaryColor)
            .hoverHighlight(cornerRadius: AppTheme.Radius.sm, isActive: isSelected)
        }
        .buttonStyle(.plain)
        .background(isSelected ? AppTheme.Background.selected : .clear)  // custom background
    }
}

Creating Custom Shadow Styles

Define reusable shadow configurations in AppTheme.swift for card-like interfaces:

// AppTheme.swift – add a subtle shadow for cards
struct ShadowStyle {
    // existing properties...
}
enum Shadow {
    static let card = ShadowStyle(color: .black.opacity(0.1),
                                 radius: 3, x: 0, y: 1)
}

Apply the shadow to any container:

VStack {
    // content
}
.shadow(AppTheme.Shadow.card)

Summary

• All UI customization in Palmier Pro centers on the AppTheme type in Sources/PalmierPro/UI/AppTheme.swift.
• Extend the design system by adding new static constants to existing enums like Accent or Spacing.
• Modify global tokens to change appearance across the entire application automatically.
• Override values locally using view-specific extensions when you need isolated customizations.
• SwiftUI views in Sources/PalmierPro/UI/ and AppKit code in Sources/PalmierPro/Timeline/ both consume the same AppTheme constants.

Frequently Asked Questions

Where are all the UI colors defined in Palmier Pro?

All colors, including accent colors, text colors, and background colors, are defined as static constants within the AppTheme enum in Sources/PalmierPro/UI/AppTheme.swift. No hard-coded color values exist elsewhere in the codebase, ensuring that the AppTheme file serves as the definitive source for the color palette.

Can I customize the UI without modifying the core source files?

While the current architecture requires editing AppTheme.swift for global changes, you can create view-specific customizations by extending AppTheme with nested enums in your own Swift files. This approach keeps your custom tokens organized while avoiding modifications to the original theme definitions, though you will still need to recompile the application.

How do AppKit components access the theme values?

Lower-level AppKit drawing code, such as the timeline rendering in Sources/PalmierPro/Timeline/TimelineView.swift, accesses the same design tokens through AppTheme properties that expose NSColor and CGColor values. This ensures visual consistency between SwiftUI and AppKit layers throughout the application.

Will my changes to AppTheme affect the entire application automatically?

Yes. Because every view references AppTheme constants rather than hard-coded values, modifying a token in AppTheme.swift immediately updates all components that use that token. Changes propagate to sidebar buttons in SidebarRowButton.swift, hover effects in HoverHighlight.swift, and toolbar layouts in ToolbarView.swift without requiring additional code changes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}