Openfoodjournal UI

OpenFoodJournal UI/UX Design System

Living reference for every visual and interaction pattern in the app. Consult before creating or modifying any SwiftUI view. Update whenever a new pattern is established or an existing one changes.

Quick Reference

Color System

Macro Colors (Canonical)

Progress Status Colors

Opacity Conventions

Typography

Convention: All numeric displays use .system(design: .rounded). Precise alignment uses .monospacedDigit().

Glassmorphism (iOS 26+)

The app targets iOS 26+ exclusively — no #available guards needed.

Standard Patterns

// Card surface
.glassEffect(in: .rect(cornerRadius: 20))

// Circular element (macro rings)
.glassEffect(in: .circle)

// Tinted interactive element
.glassEffect(
    .regular.tint(color.opacity(0.35)),
    in: .circle
)

// Multiple glass elements in proximity
GlassEffectContainer(spacing: 20) {
    HStack { /* glass children */ }
}

// Buttons
.buttonStyle(.glass)           // Standard
.buttonStyle(.glassProminent)  // Primary action

Glass Rules

1. Apply .glassEffect() after layout and appearance modifiers
2. Wrap multiple glass siblings in GlassEffectContainer
3. Use .interactive() only on tappable/focusable elements
4. Use .glassEffectID(_:in:) + @Namespace for morphing transitions
5. Prefer .glassEffect() over .background(.ultraThinMaterial) for new UI

See the swiftui-liquid-glass skill for the complete Liquid Glass API reference.

Navigation Architecture

Tab Structure

4-tab TabView at root with .tabBarMinimizeBehavior(.never):

Each tab wraps its content in NavigationStack.

Sheet Management (Enum-Driven)

Always use a single enum for all sheets within a page:

enum DailyLogSheet: Identifiable {
    case scan, manualEntry, editEntry(NutritionEntry)
    case foodBank, containers
    
    var id: String { /* unique per case */ }
}

@State private var presentedSheet: DailyLogSheet?

// In body:
.sheet(item: $presentedSheet) { sheet in
    switch sheet {
    case .scan: ScanCaptureView(logDate: selectedDate)
    case .manualEntry: ManualEntryView(defaultDate: selectedDate)
    // ...
    }
}

Never use multiple @State booleans for sheet presentation.

Sheet Configuration

Every sheet must include:

• NavigationStack wrapper for internal nav
• .navigationTitle() + .navigationBarTitleDisplayMode(.inline)
• Cancel button: ToolbarItem(placement: .cancellationAction)
• Save button: ToolbarItem(placement: .confirmationAction) with .fontWeight(.semibold) and .disabled() guard
• @Environment(\.dismiss) private var dismiss

Component Catalog

Shared Components (Views/Shared/)

Row Components

Inline Component Pattern

Extract reusable card builders as private @ViewBuilder functions:

@ViewBuilder
private func macroCard(_ macro: NutrientKind.MacroType, value: Double, 
                       goal: Double, color: Color) -> some View {
    Button { selectedMacro = macro } label: {
        VStack(spacing: 4) { /* content */ }
    }
    .buttonStyle(.plain)
}

Layout Patterns

List (Preferred for Swipeable Content)

List {
    MealSectionView(...)  // Returns Section{}
}
.listStyle(.plain)
.scrollContentBackground(.hidden)

Gotcha: .swipeActions is silently ignored outside List. Never use ScrollView + LazyVStack for rows that need swipe actions.

LazyVGrid (2-Column Cards)

LazyVGrid(columns: [GridItem(.flexible()), GridItem(.flexible())], spacing: 10) {
    macroCard(...)  // 4 cards in 2×2
}

List Row Customization

.listRowSeparator(.hidden)
.listRowBackground(Color.clear)
.listRowInsets(EdgeInsets(top: 8, leading: 16, bottom: 8, trailing: 16))

Empty States

ContentUnavailableView {
    Label("No Saved Foods", systemImage: "refrigerator")
} description: {
    Text("Save a food from a scan first...")
}

Animation Conventions

Convention: Use withAnimation(.spring(...)) for user-initiated actions. Use .animation(.easeInOut, value:) for data-driven transitions.

Form/Input Patterns

Numeric Text Fields

// Always use text-backed fields to avoid cursor-jump artifacts
@State private var quantityText: String
let quantity = Double(quantityText) ?? 0

TextField("Weight", text: $quantityText)
    .keyboardType(.decimalPad)

Focus Chain

fileprivate enum FormField: Hashable {
    case name, calories, protein, carbs, fat
    case micronutrient(String)
}
@FocusState private var focusedField: FormField?

// Chain fields:
TextField("Calories", text: $caloriesText)
    .focused($focusedField, equals: .calories)
    .submitLabel(.next)
    .onSubmit { focusedField = .protein }

Picker Styles

Confirmation Dialogs

.confirmationDialog(
    "Delete \(food.name)?",
    isPresented: $showDeleteConfirm,
    titleVisibility: .visible
) {
    Button("Delete", role: .destructive) { /* action */ }
}

State Management Patterns

Service Injection

// App creates @Observable services, injects via .environment()
@Environment(NutritionStore.self) private var store
@Environment(UserGoals.self) private var goals

SwiftData Bindings

@Bindable var entry: NutritionEntry  // Two-way binding to @Model
TextField("Name", text: $entry.name)  // Auto-persists

Derived State

// Compute from primary sources — never duplicate as @State
private var filteredFoods: [SavedFood] {
    searchText.isEmpty ? allFoods : allFoods.filter { ... }
}

Persistence

// UserGoals uses AppStorage with @ObservationIgnored to avoid conflicts
@ObservationIgnored @AppStorage("goals.calories")
var dailyCalories: Double = 2000

SF Symbols Reference

Checklist for New Views

Before merging any new view:

• Uses glass effects (not .background(.ultraThinMaterial))
• Card corners use 20 pt radius
• Colors match macro color table above
• Sheets use enum-driven presentation
• Sheets have Cancel/Save toolbar + dismiss
• List rows use standard insets (8, 16, 8, 16)
• Animations use spring for user actions, easeInOut for data
• Numeric inputs use text-backed fields
• Tappable elements have 44+ pt hit targets
• Empty states use ContentUnavailableView
• Progress indicators use the status color thresholds

UI Roadmap

Food Bank Improvements

• Remove source icons (barcode/fork/pencil) from SavedFoodRowView — they add visual noise without value
• Shift calorie count from right edge to where source icons were (left-center area)
• Add macro chips (P/C/F) to the right of each food row — same MacroChip pattern as EntryRowView
• Add "Last Used" sort option and make it the default — newly added foods count as "last used" even before being logged, so recently saved foods surface to the top for better glanceability
• Search should match brand field in addition to name

Keyboard UX

• Every keyboard popup must have a "Done" button to dismiss — use .toolbar { ToolbarItemGroup(placement: .keyboard) { Spacer(); Button("Done") { focusedField = nil } } }

Calendar Strip → Continuous Scrollable Calendar

• Replace fixed Sun–Sat WeeklyCalendarStrip with a continuously scrollable calendar
• Interaction design modeled after iOS Calendar monthly view: vertical continuous scroll with smooth momentum snapping to month boundaries
• Sticky month/year header that transitions smoothly as user scrolls between months
• Days show the same progress ring colors as current day cells
• Tapping a day selects it and scrolls the journal to that date