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

---

License

MIT © 2026 NerdSnipe Inc.