Home

DesignFoundation

A token-based SwiftUI design system that gives you 30+ production-ready components all wired to a single shared theme. Set the theme once at the app root — every button, input, card, and modal underneath inherits it automatically. Swap a color token and the entire UI updates. Works on iOS 18+, macOS 15+, and visionOS 2+, is Swift 6 strict concurrency safe, and ships Liquid Glass styles for iOS/macOS 26+.

The project exists because rebuilding the same primitives from scratch on every new SwiftUI project — and watching the design drift within months as teams use ad-hoc values — is a solved problem that shouldn't have to be solved again.

Why DesignFoundation?

Consistent Theming Without Manual Wiring

Every component reads from a single DFTheme value in SwiftUI's environment. Tokens cover color, typography, spacing, corner radius, shadow, animation, and per-component overrides. Change a token at any level of the view tree — the app root, a screen, a section — and everything downstream reacts. No style sheets to synchronize, no AppTheme.shared singletons, no hunting across files when a brand color changes.

// One line at the app root sets the palette for your entire UI
MyApp()
    .dfThemePreset(.aurora)

// Override a single token inside a sub-tree
VStack { ... }
    .dfTheme({ var t = DFTheme.auroraLight; t.colors.primary = .purple; return t }())

Four presets ship — .slate, .aurora, .copper, .sage — each pairing a light and dark theme that switches automatically on colorScheme changes. See Theme-Presets for the full palette comparison and Theming for building a custom theme from tokens.

Cross-Platform Without `#if os()` Guards

DFSidebar, DFTabBar, DFModal, and every other component handle platform differences internally via DFPlatformContext, which the .dfTheme() modifier injects automatically. You write the component once; it renders correctly on iPhone, iPad, Mac, and Apple Vision Pro.

The only place you need platform guards is in your own app-level scene declarations — WindowGroup with multiple IDs, .windowStyle(.titleBar), @Environment(\.openWindow) — APIs that DesignFoundation does not wrap. Everything DesignFoundation provides is guard-free by design.

// This single view works on iOS, macOS, and visionOS
struct ContentView: View {
    @State private var selection: String = "home"
    var body: some View {
        DFSidebar(selection: $selection, sections: sidebarSections)
    }
}

Swift 6 Strict Concurrency Safe

The package compiles under StrictConcurrency with no warnings. All style protocols carry explicit Sendable conformance. Environment values use safe static defaults. Components that need actor isolation use @MainActor; those that don't are pure value types. You get no concurrency warnings in your own Swift 6 targets. See Swift-6-Concurrency for the design rationale.

Liquid Glass Styles

Every component that can benefit from the iOS/macOS 26 material layer ships a .glass style variant. Enable it with a single style modifier. The package guards these internally — on older OS versions the component falls back to its .standard style silently, so you do not need availability checks at the call site.

// Liquid Glass across your entire shell in three lines
ContentView()
    .dfButtonStyle(.glass)
    .dfCardStyle(.glass)
    .dfSidebarStyle(.glass)

See Liquid-Glass for the full list of glass-capable components and the fallback behavior contract.

Quick Install

Xcode: File → Add Package Dependencies → paste the URL below → select Up to Next Major Version from 1.0.0.

https://github.com/NerdSnipe-Inc/design-foundation

Package.swift:

// swift-tools-version: 6.0
import PackageDescription

let package = Package(
    name: "YourApp",
    platforms: [
        .iOS(.v18),
        .macOS(.v15),
        .visionOS(.v2)
    ],
    dependencies: [
        .package(
            url: "https://github.com/NerdSnipe-Inc/design-foundation",
            from: "1.0.0"
        )
    ],
    targets: [
        .target(
            name: "YourApp",
            dependencies: ["DesignFoundation"]
        )
    ]
)

Then import at the top of any Swift file:

import DesignFoundation

Apply a theme preset at your app root and you're ready to use any component:

import SwiftUI
import DesignFoundation

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .dfThemePreset(.slate)
        }
    }
}

See Getting-Started for a complete walkthrough including first-run previews, theme switching, and your first custom component using tokens.

Component Map

All 33 components and form utilities organized by category. Style variant counts exclude the .glass variant where applicable — see the individual component page for the full list.

Component	Category	Description	Style Variants
`DFButton`	Primitives	Tappable action button with loading state, leading icon, and role support	5 (`filled`, `outlined`, `ghost`, `tinted`, `glass`¹)
`DFText`	Primitives	Token-driven text with a semantic scale system for display through caption	6 scales, 3 built-in styles
`DFIcon`	Primitives	SF Symbol and custom image wrapper with token-driven size and color	3 built-in styles
`DFBadge`	Primitives	Inline label for counts, statuses, and tags; numeric and dot variants	4 (`default`, `subtle`, `outlined`, `glass`¹)
`DFAvatar`	Primitives	User representation from initials or image URL with presence ring support	4 (`circle`, `rounded`, `ring`, `glass`¹)
`DFDivider`	Primitives	Horizontal or vertical separator; labeled variant for section breaks	3 (`solid`, `dashed`, `gradient`)
`DFTextField`	Inputs	Single-line text input with optional leading and trailing icon slots	2 (`outlined`, `filled`)
`DFSecureField`	Inputs	Password input with built-in show/hide toggle; inherits `DFTextField` styles	2 (`outlined`, `filled`)
`DFValidatedTextField`	Inputs	`DFTextField` with `DFFormState` binding and themed inline error display	Inherits `DFTextField`
`DFToggle`	Inputs	Boolean switch or checkbox; both styles driven by the same binding	2 (`switch`, `checkbox`)
`DFSlider`	Inputs	Continuous value input with optional step and value label	2 (`standard`, `labeled`)
`DFPicker`	Inputs	Single-selection control in segmented, menu, or wheel presentation	3 (`segmented`, `menu`, `wheel`)
`DFDatePicker`	Inputs	Date and time selection with compact, calendar, or wheel display	3 (`compact`, `graphical`, `wheel`)
`DFCheckbox`	Inputs	Standalone checked state control, composable into forms and lists	1 (`default`)
`DFFieldValidator`	Forms	Protocol for field-level validation; built-ins: Required, Email, MinLength, MaxLength, Regex	Protocol
`DFFormState`	Forms	Observable form container tracking values, errors, and touched state per field key	Utility
`DFCard`	Layout	Generic content container with padding, background, and elevation options	4 (`elevated`, `outlined`, `filled`, `glass`¹)
`DFModal`	Overlays	Presented view covering the screen; dialog and fullscreen presentation modes	2 (`standard`, `glass`¹)
`DFSheet`	Overlays	Bottom / side sheet with configurable detents	3 (`standard`, `compact`, `glass`¹)
`DFPopover`	Overlays	Anchored floating panel for contextual content	3 (`arrow`, `compact`, `glass`¹)
`DFTooltip`	Overlays	On-hover or long-press hint bubble wrapping any trigger view	2 (`bubble`, `glass`¹)
`DFAlert`	Feedback	Convenience wrapper over native SwiftUI alert with typed action roles	Native system alert
`DFToast`	Feedback	Non-blocking notification with queue management and auto-dismiss	3 styles (`success`, `error`, `info`)
`DFSkeleton`	Loading	Shimmer placeholder for async content; rectangle and circle shapes	1 (shimmer)
`DFProgressBar`	Loading	Linear, circular, and indeterminate progress indicator	3 variants
`DFList`	Data	Themed list with swipe-to-delete, drag reorder, and multi-select	1 (`default`)
`DFListRow`	Data	Row for use inside `DFList`; leading/trailing slots and disclosure indicator	Accessory variants
`DFTable`	Data	Sortable columnar table for medium-density data display	1 (`default`)
`DFDataTable`	Data	Full-featured sortable, filterable, selectable table with empty state slot and keyboard navigation	1 (`default`)
`DFDataGrid`	Data	Power grid built on `DFDataTable` — inline cell edit, column visibility menu, bulk toolbar, client-side paging	2 (`.renderAll`, `.paged`)
`DFTabBar`	Navigation	Bottom tab bar for primary navigation; glass variant uses iOS/macOS 26 material	3 (`standard`, `minimal`, `glass`¹)
`DFNavigationBar`	Navigation	View modifier providing a themed navigation bar without UINavigationController	2 (`standard`, `transparent`)
`DFSidebar`	Navigation	macOS/iPadOS sidebar with sectioned items and collapsible groups	3 (`standard`, `plain`, `glass`¹)

¹ .glass requires iOS 26+ / macOS 26+. Falls back to .standard silently on earlier OS versions.

Components by Category

Primitives

The building blocks every other component is composed from.

DFButton — Action button with filled, outlined, ghost, tinted, and Liquid Glass styles. Supports a leading SF Symbol icon, loading spinner state, and role: .destructive. Style propagates through the environment so one modifier styles an entire section. → Buttons
DFText — Token-driven text rendering with a semantic scale system (display, title, headline, body, caption, label). Adapts point sizes per platform using SwiftUI semantic text styles. → Text-and-Typography
DFIcon — SF Symbol and custom image wrapper. Token-driven size (xs through xl) and color. Resolves size in priority order: explicit → style → theme token. → Icons
DFBadge — Inline label for notification counts, statuses, role tags, and binary dot indicators. Numeric overflow clips at a configurable max with a + suffix. → Badges
DFAvatar — User image or initials-generated placeholder with configurable size, shape, presence ring color, and online/busy/offline indicator. → Avatars
DFDivider — Horizontal or vertical separator with solid, dashed, or gradient fill. The labeled variant centers a DFText within the rule, useful for section breaks in lists. → Dividers

Inputs

All input components share DFValidationState (.idle, .valid, .error(String)) so inline error presentation is consistent across the UI.

DFTextField — Single-line text input with outlined and filled backgrounds, optional leading/trailing icon, and character count. Respects .disabled() and DFValidationState. → Text-Fields
DFSecureField — Password input that wraps DFTextField with a built-in reveal toggle. The toggle icon and animation are themed. → Text-Fields
DFValidatedTextField — DFTextField bound to a DFFormState field key. Displays DFValidationState error text below the field automatically. → Forms-and-Validation
DFToggle — Boolean switch (native Toggle appearance) or checkbox square, both driven by the same Binding<Bool>. Style is set via .dfToggleStyle(). → Controls
DFSlider — Continuous range input with optional step value, formatted value label, and leading/trailing range labels. → Controls
DFPicker — Single-value selection in segmented pill, dropdown menu, or scroll wheel presentation. Drives any Hashable & CaseIterable type. → Controls
DFDatePicker — Date/time picker in compact text, full calendar, or scroll wheel layout. Respects in: range and displayedComponents. → Controls
DFCheckbox — Standalone checked-state control. Composable into form rows and list cells. Themed check mark color and border follow the active DFTheme. → Controls

Forms and Validation

DFFieldValidator — Protocol for field validation logic. Built-ins cover the most common cases; conform your own for custom rules. Built-ins: Required, Email, MinLength(n), MaxLength(n), Regex(pattern:message:). → Forms-and-Validation
DFFormState — @Observable container holding string values, DFValidationState per field, and a touched set. Call validate() to run all validators or validate(field:) for a single field. → Forms-and-Validation

Layout

DFCard — General-purpose content container. Elevated (drop shadow), outlined (border), filled (flat surface color), and Liquid Glass variants. Configurable padding via the theme spacing token or explicit override. → Cards

Overlays

DFModal — Full-cover presentation for task flows and confirmations. Standard (dialog size) and fullscreen modes. Applied as a view modifier: .dfModal(isPresented:) { }. → Overlays
DFSheet — Bottom or trailing sheet. Standard detents or compact (half-height). Applied as .dfSheet(isPresented:) { }. → Overlays
DFPopover — Anchored floating panel positioned relative to a source view. Arrow variant shows a callout pointer; compact omits it for tighter contexts. → Overlays
DFTooltip — On-hover (macOS) or long-press (iOS) hint bubble wrapping any trigger view. Placement is explicit (top, bottom, leading, trailing) or automatic. → Overlays

Feedback

DFAlert — Typed convenience wrapper over the native SwiftUI alert system. Define actions with DFAlertAction carrying role: .cancel or role: .destructive. Applied as .dfAlert(isPresented:alert:). → Alerts-and-Toasts
DFToast — Non-blocking notification with success, error, and info styles. DFToastQueue.shared manages FIFO display and auto-dismiss timing. Apply .dfToast(queue:) once at the scene root. → Alerts-and-Toasts

Loading States

DFSkeleton — Shimmer placeholder for content that has not loaded. Rectangle and circle shapes match the geometry of the real content. Compose multiples to sketch a full skeleton screen. → Loading-States
DFProgressBar — Determinate linear bar, determinate circular ring, and indeterminate spinner. Token-driven track and fill colors. → Loading-States

Data Display

DFList — Themed list view with swipe-to-delete, drag reorder, and multi-select managed internally. Accepts any Identifiable collection and a @ViewBuilder row factory. → Lists-and-Tables
DFListRow — Composable row for use inside DFList or a plain List. Slots for a leading icon, primary title, subtitle, trailing content, and a disclosure indicator. Accessory options: .navigation, .checkmark(isOn:), .custom(AnyView). → Lists-and-Tables
DFTable — Columnar table with sortable headers. Column definitions carry key path, label, and optional width. → Lists-and-Tables
DFDataTable — Full-featured table with single and multi-row selection (Set<ID>), shared DFDataTableColumn API, @ViewBuilder empty state, filterQuery for client-side row search, onRowActivate closure (Return/double-click on macOS, tap on iOS), and arrow-key navigation on macOS. Native SwiftUI Table on macOS; scrollable row layout on iOS. → Data-Tables
DFDataGrid — Power-user grid built on DFDataTable — inline cell editing backed by DFFormState and DFFieldValidator, column visibility menu, bulk action toolbar slot, and two large-dataset strategies: .renderAll (lazy stack) and .paged (client-side windowing). → Data-Tables

Navigation

DFTabBar — Primary tab navigation bar. Standard style mirrors the platform tab bar; minimal style floats icons without a background surface; glass style applies the iOS/macOS 26 material. → Navigation
DFNavigationBar — View modifier that attaches a themed navigation bar with title, display mode, and trailing action slots, without requiring NavigationStack or UINavigationController. → Navigation
DFSidebar — Sectioned sidebar for macOS and iPadOS regular width. Item selection drives a Binding<String>. Sections and items defined with DFSidebarSection and DFSidebarItem. Standard, plain, and glass styles. → Navigation

Theme System Summary

The DFTheme struct is a value type that sits in SwiftUI's environment under the \.dfTheme key. It is organized into seven token namespaces:

Namespace	What it controls
`colors`	Semantic color roles: primary, surface, surfaceElevated, textPrimary, textSecondary, border, accent, success, warning, error, interactive states
`typography`	SwiftUI semantic text styles mapped per scale; adapts automatically to platform and Dynamic Type
`spacing`	Named steps: `xs` (4 pt), `sm` (8 pt), `md` (12 pt), `lg` (16 pt), `xl` (24 pt), `xxl` (32 pt)
`radius`	Corner radius steps: `sm`, `md`, `lg`, `full` (pill)
`shadow`	Per-elevation shadow definitions
`animation`	Timing curves and durations used in state transitions
`components`	Per-component overrides (e.g. button minimum height, sidebar width) that layer on top of the base tokens

Apply a preset using the convenience modifier:

MyApp().dfThemePreset(.copper)

Build a fully custom theme:

MyApp()
    .dfTheme(DFTheme(
        colors: DFColorTokens(primary: .indigo, surface: Color(.systemBackground)),
        spacing: DFSpacingTokens(md: 20),
        radius: DFRadiusTokens(md: 14)
    ))

Mutate a single token from an existing preset:

var theme = DFTheme.slateLight
theme.colors.primary = .teal
SomeView().dfTheme(theme)

See Theming for the complete DFTheme API, every token with its default value, and a guide to building a custom preset. See Theme-Presets for the four built-in presets with light/dark palette swatches.

Style System Summary

Every component exposes a style protocol following the same makeBody(configuration:) pattern as native SwiftUI ButtonStyle. Styles compose, propagate through the environment, and apply hierarchically — set a style on a container and every eligible descendant inherits it.

// Style an entire section — all DFButtons inside become outlined
VStack {
    DFButton("Cancel") { }
    DFButton("Save") { }
}
.dfButtonStyle(.outlined)

// Override a single component within that section
DFButton("Delete", role: .destructive) { }
    .dfButtonStyle(.destructive)

// Liquid Glass shell in three lines
ContentView()
    .dfButtonStyle(.glass)
    .dfCardStyle(.glass)
    .dfSidebarStyle(.glass)

Writing a custom style means conforming to the component's style protocol and implementing one function. Built-in styles are concrete public structs — copy any of them as a starting point. See Style-System for the protocol definitions, the environment propagation rules, and a walkthrough of writing and composing custom styles.

Complex Screens

If your app needs production-ready auth flows (sign in, sign up, OTP, forgot password), dashboard metric blocks (stat cards, line/bar/donut charts), or full vertical screens (CRM, Analytics, Chat, Onboarding, Project Manager, Settings), DesignFoundation Pro ships these composed from the same primitives. See nerdsnipe-inc.github.io/design-foundation/pro for the full block inventory.

Platforms

Platform	Minimum	Liquid Glass `.glass` styles
iOS	18.0	Requires iOS 26+
macOS	15.0	Requires macOS 26+
visionOS	2.0	Not applicable

DFPlatformVariant (automatic, compact, expanded, immersive) lets components select an appropriate form factor at runtime, or lets you force a specific layout in Previews and tests. See Cross-Platform for the platform adaptation model and the complete list of components that change behavior between compact and expanded layouts.

Navigation

Wiki Page	What it covers
Getting-Started	Installation, first app, Previews setup, theme switching walkthrough
Theming	`DFTheme` API, all token namespaces with default values, custom theme construction
Theme-Presets	Slate, Aurora, Copper, Sage — palette swatches, use-case guidance, per-preset customization
Style-System	Style protocol pattern, environment propagation, writing and composing custom styles
Liquid-Glass	`.glass` style variants, OS availability, fallback behavior contract
Cross-Platform	`DFPlatformContext`, `DFPlatformVariant`, when platform guards are and are not needed
Swift-6-Concurrency	Strict concurrency design, `Sendable` conformances, `@MainActor` usage
Buttons	`DFButton` — initializers, all style variants, icon, loading state, role, accessibility
Text-and-Typography	`DFText` — scale system, semantic text styles, custom scale, accessibility sizing
Icons	`DFIcon` — SF Symbol and custom image, size tokens, color, rendering modes
Badges	`DFBadge` — text, numeric, dot variants, overflow, accessibility
Avatars	`DFAvatar` — image and initials sources, presence rings, sizes and shapes
Dividers	`DFDivider` — orientation, labeled variant, gradient fill
Text-Fields	`DFTextField`, `DFSecureField` — all initializers, icon slots, validation state display
Controls	`DFToggle`, `DFSlider`, `DFPicker`, `DFDatePicker`, `DFCheckbox`
Forms-and-Validation	`DFFieldValidator`, `DFFormState`, `DFValidatedTextField`, built-in validators
Cards	`DFCard` — padding, styles, composing with other components
Overlays	`DFModal`, `DFSheet`, `DFPopover`, `DFTooltip` — presentation patterns, glass variants
Alerts-and-Toasts	`DFAlert`, `DFToast`, `DFToastQueue` — queue management, styles, dismiss timing
Loading-States	`DFSkeleton`, `DFProgressBar` — shapes, variants, skeleton screen composition
Lists-and-Tables	`DFList`, `DFListRow`, `DFTable` — delete, reorder, multi-select, sort
Data-Tables	`DFDataTable`, `DFDataGrid` — column API, selection, filtering, inline edit, paging
Navigation	`DFTabBar`, `DFNavigationBar`, `DFSidebar` — data types, styles, selection binding
Changelog	Release history and migration notes

Uh oh!

Home

DesignFoundation

Why DesignFoundation?

Consistent Theming Without Manual Wiring

Cross-Platform Without #if os() Guards

Swift 6 Strict Concurrency Safe

Liquid Glass Styles

Quick Install

Component Map

Components by Category

Primitives

Inputs

Forms and Validation

Layout

Overlays

Feedback

Loading States

Data Display

Navigation

Theme System Summary

Style System Summary

Complex Screens

Platforms

Navigation

License

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Cross-Platform Without `#if os()` Guards