# How to Customize UI Elements in FluidVoice: A Complete SwiftUI Theming Guide

> Customize UI elements in FluidVoice by editing ThemePalette for global changes or individual SwiftUI views for component overrides. Follow this comprehensive theming guide.

- Repository: [ALTIC/FluidVoice](https://github.com/altic-dev/FluidVoice)
- Tags: tutorial
- Published: 2026-07-08

---

**You can customize UI elements in FluidVoice by modifying the centralized `ThemePalette` in [`ThemeEnvironment.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ThemeEnvironment.swift) for global changes, or by editing individual SwiftUI view structs in `Sources/Fluid/UI/` for component-specific overrides.**

FluidVoice is built entirely on SwiftUI and implements a centralized theming system that manages colors, typography, and spacing across the application. Because the UI is declarative and modular, you can tailor the appearance of any screen by adjusting theme values or modifying view code directly without touching lower-level AppKit APIs.

## Understanding the Theming Architecture

The theming system centers on [`Sources/Fluid/Theme/ThemeEnvironment.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Theme/ThemeEnvironment.swift), which defines the `ThemePalette` and typography structs used throughout the app. This theme is injected into the view hierarchy via `@Environment(\.theme)`, allowing every UI component to access consistent styling values.

When you open any view file in `Sources/Fluid/UI/`, you will see references like `self.theme.palette.accent` for colors or `self.theme.typography.title` for fonts. This pattern ensures that changing a single value in the theme environment propagates automatically to every view that references it.

## Global Customization via Theme Palette

To change the appearance of FluidVoice across the entire application, modify the `ThemePalette` struct in [`ThemeEnvironment.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ThemeEnvironment.swift). This struct contains color definitions for window backgrounds, accent colors, and text.

For example, the default accent color is defined as a blue hex value:

```swift
// Sources/Fluid/Theme/ThemeEnvironment.swift
public struct ThemePalette {
    public var accent = Color(hex: "#0A84FF")          // ← default blue
    // ...
}

```

To apply a custom teal accent globally, update the value:

```swift
public var accent = Color(hex: "#00BFA5")

```

All views referencing `self.theme.palette.accent`—such as the "Quick Setup" icon in [`WelcomeView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/WelcomeView.swift) (lines 61-68)—will immediately adopt the new color when you rebuild the app.

## Modifying Typography System-Wide

Font families and sizes are stored in `theme.typography`. By editing these values in [`ThemeEnvironment.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ThemeEnvironment.swift), you can adjust the weight and size of titles, captions, and body text without touching individual view files.

The typography system follows the same environment pattern as the color palette, ensuring that text styling remains consistent across `WelcomeView`, `CommandModeView`, and `MeetingTranscriptionView`.

## Component-Level Customization

For targeted changes to specific screens, edit the individual SwiftUI view structs in `Sources/Fluid/UI/`. Each component is self-contained, allowing you to add new visual elements, replace existing ones, or apply custom modifiers.

### Adding Elements to Existing Views

You can insert new UI elements into existing stacks. For example, to add a settings button to the Welcome screen:

```swift
// Sources/Fluid/UI/WelcomeView.swift
private var commandModeGuide: some View {
    VStack(alignment: .leading, spacing: 12) {
        // Existing content …
        HStack {
            // New button that opens the Settings window
            Button("Open Settings") {
                NSWorkspace.shared.open(URL(string: "x-apple.systempreferences:")!)
            }
            .buttonStyle(.bordered)
            .controlSize(.small)
        }
    }
}

```

Because `Button` inherits the environment automatically, it respects the current theme colors without additional configuration.

### Overriding Styles for Specific Views

When you need a one-off customization that shouldn't affect the global theme, apply modifiers directly to the view. For example, to use a custom font in `MeetingTranscriptionView` while keeping the theme's color:

```swift
// Sources/Fluid/UI/MeetingTranscriptionView.swift
var body: some View {
    VStack(spacing: 0) {
        // Header
        VStack(spacing: 8) {
            Image(systemName: "waveform.circle.fill")
                .font(.system(size: 48))
                .foregroundStyle(Color.fluidGreen.gradient)

            Text("Meeting Transcription")
                .font(.custom("HelveticaNeue-Bold", size: 28))      // ← custom font
                .foregroundStyle(self.theme.palette.primaryText)   // keep theme color
        }
        // …
    }
}

```

## Creating Custom Reusable Components

You can build new UI components that automatically respect the FluidVoice theme by accessing the environment. Create a new file in `Sources/Fluid/UI/` and inject the theme:

```swift
// Sources/Fluid/UI/CustomBadge.swift
import SwiftUI

struct CustomBadge: View {
    let label: String
    @Environment(\.theme) private var theme

    var body: some View {
        Text(label)
            .font(self.theme.typography.badge)
            .foregroundStyle(.white)
            .padding(.horizontal, 6)
            .padding(.vertical, 2)
            .background(self.theme.palette.accent, in: RoundedRectangle(cornerRadius: 4))
    }
}

```

Drop `CustomBadge(label: "Beta")` into any view, and it will update automatically if you modify the theme palette.

## Key Files for UI Customization

- **[`Sources/Fluid/Theme/ThemeEnvironment.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Theme/ThemeEnvironment.swift)** — Defines `ThemePalette` and typography; the entry point for global color and font changes.
- **[`Sources/Fluid/Theme/NativeButtonStyles.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Theme/NativeButtonStyles.swift)** — Contains custom button styling for `.fluidButton` instances; edit to change button appearance globally.
- **[`Sources/Fluid/UI/WelcomeView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/UI/WelcomeView.swift)** — Main onboarding screen; demonstrates theme usage for icons, text, and buttons (see lines 61-68 for accent color usage).
- **[`Sources/Fluid/UI/CommandModeView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/UI/CommandModeView.swift)** — UI for the command-mode hot-key overlay; useful for styling command-mode specific elements.
- **[`Sources/Fluid/UI/MeetingTranscriptionView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/UI/MeetingTranscriptionView.swift)** — Complex UI with file pickers and result cards; reference for custom view composition.

## Summary

- **Global changes** are made in [`ThemeEnvironment.swift`](https://github.com/altic-dev/FluidVoice/blob/main/ThemeEnvironment.swift) by modifying `ThemePalette` and typography values, which propagate via `@Environment(\.theme)`.
- **Component-specific changes** involve editing individual SwiftUI view files in `Sources/Fluid/UI/` to add elements, apply modifiers, or rearrange layouts.
- **Custom components** should use `@Environment(\.theme)` to ensure they remain consistent with the app's visual language.
- All changes are compile-time safe and immediately visible at runtime thanks to SwiftUI's declarative architecture.

## Frequently Asked Questions

### How do I change the accent color in FluidVoice?

Edit the `accent` property in [`Sources/Fluid/Theme/ThemeEnvironment.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Theme/ThemeEnvironment.swift). Update the `Color(hex:)` value to your desired hex code, and all views referencing `theme.palette.accent`—including icons in [`WelcomeView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/WelcomeView.swift)—will update automatically.

### Can I add custom buttons to existing screens like the Welcome view?

Yes. Open [`Sources/Fluid/UI/WelcomeView.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/UI/WelcomeView.swift), locate the relevant `VStack` or `HStack`, and insert a standard SwiftUI `Button`. The button will inherit the environment's theme automatically, or you can apply specific styles using `.buttonStyle()` and `.controlSize()` modifiers.

### How do I create a new UI component that matches FluidVoice's theme?

Create a new Swift file in `Sources/Fluid/UI/` and define a `View` struct that accesses the theme via `@Environment(\.theme) private var theme`. Use `self.theme.palette` for colors and `self.theme.typography` for fonts to ensure your component stays synchronized with global theme changes.

### Where are the font styles defined in FluidVoice?

Font families and sizes are defined in [`Sources/Fluid/Theme/ThemeEnvironment.swift`](https://github.com/altic-dev/FluidVoice/blob/main/Sources/Fluid/Theme/ThemeEnvironment.swift) within the typography struct. Views access these via `self.theme.typography` to ensure consistent text styling across the application.