DEV Community: Nerd Snipe

Part 5 — Deals, pricing, and a real board

Nerd Snipe — Wed, 22 Jul 2026 16:15:00 +0000

Part 5 — Deals, pricing, and a real board

Level: Intermediate/Advanced · Time: ~35 minutes · Builds on: Part 4 — Tags, ratings, and richer rows · Series 2, Part 2 of 3

Your contacts are tagged and scored. Now give them money attached — a deal value, a quote with real line items, and a board to see all of it at once. By the end of this tutorial your Contacts app will, without exaggeration, be doing the job of a lightweight sales pipeline.

Keep that thought. We'll come back to it in Part 6.

What we're adding

A Deal model attached to each contact, with a stage and a value.
DFPriceView and DFPriceSummaryView — a real quote screen with subtotal, discount, tax, and total.
DFQuantityStepper — editable line-item quantities on that quote.
A deals board — DFGrid of DFEntityCards, grouped by stage, filtered with the DFChip row from Part 4.
DFCarousel — a "hot leads" horizontal rail on the dashboard.

1. The Deal model

enum DealStage: String, CaseIterable, Identifiable, Hashable {
    case new, qualified, proposal, won
    var id: String { rawValue }
    var label: String {
        switch self {
        case .new:       "New"
        case .qualified: "Qualified"
        case .proposal:  "Proposal"
        case .won:       "Won"
        }
    }
}

struct LineItem: Identifiable, Hashable {
    let id = UUID()
    var name: String
    var unitPrice: Decimal
    var quantity: Int = 1
    var lineTotal: Decimal { unitPrice * Decimal(quantity) }
}

struct Deal: Identifiable, Hashable {
    let id = UUID()
    var contactID: Contact.ID
    var title: String
    var stage: DealStage = .new
    var lineItems: [LineItem]
    var value: Decimal { lineItems.reduce(0) { $0 + $1.lineTotal } }
}

2. A quote screen — `DFPriceView`, `DFQuantityStepper`, `DFPriceSummaryView`

Three components, one screen, in the order a user actually reads a quote: line items with editable quantities, then a summary breakdown at the bottom.

struct QuoteView: View {
    @State var deal: Deal
    private let taxRate: Decimal = 0.08

    private var subtotal: Decimal { deal.lineItems.reduce(0) { $0 + $1.lineTotal } }
    private var tax: Decimal { subtotal * taxRate }

    var body: some View {
        ScrollView {
            VStack(alignment: .leading, spacing: 16) {
                DFCard {
                    VStack(alignment: .leading, spacing: 12) {
                        DFText("Line items", scale: .headline)
                        ForEach($deal.lineItems) { $item in
                            HStack {
                                VStack(alignment: .leading, spacing: 2) {
                                    DFText(item.name, scale: .body)
                                    DFPriceView(amount: item.unitPrice).dfPriceViewStyle(.compact)
                                }
                                Spacer()
                                DFQuantityStepper(value: $item.quantity, range: 1...20)
                                    .dfQuantityStepperStyle(.compact)
                            }
                        }
                    }
                }

                DFCard {
                    DFPriceSummaryView(lineItems: [
                        DFPriceLineItem(label: "Subtotal", amount: subtotal),
                        DFPriceLineItem(label: "Tax (8%)", amount: tax),
                        DFPriceLineItem(label: "Total", amount: subtotal + tax, emphasis: .total),
                    ])
                }
            }
            .padding()
        }
        .dfNavigationBar(title: deal.title) { }
    }
}

Worth calling out:

DFPriceView(amount:) formats currency for you via Decimal.formatted(.currency(code:)) — locale-aware, no manual NumberFormatter. Pass compareAtAmount: and it renders a strikethrough automatically — handy for showing a discounted line item.
DFQuantityStepper is named that, not DFStepper, specifically to avoid colliding with SwiftUI's own Stepper. .compact style keeps it tight enough to live inline in a row like this.
DFPriceSummaryView takes an array of DFPriceLineItems — emphasis: .total on the last one renders a divider above it and bumps it to a headline weight automatically. You don't hand-roll the "is this the total row" styling logic.

Pro moment. Pro's E-commerce vertical ships this exact quote/checkout pattern already wired to real order data, plus a revenue dashboard built on the same DFPriceView primitive. If quotes and invoices are core to your product, that's a screen you don't write twice.

3. A deals board with `DFGrid`

Group deals by stage, reuse the segment-filter chip row's pattern for stage filtering, and lay the results out in a grid of DFEntityCards.

struct DealsBoardView: View {
    let deals: [Deal]
    @State private var selectedStage: DealStage?

    private var visible: [Deal] {
        guard let selectedStage else { return deals }
        return deals.filter { $0.stage == selectedStage }
    }

    var body: some View {
        VStack(spacing: 0) {
            HStack(spacing: 8) {
                DFChip(.selectable("All"), isSelected: selectedStage == nil)
                    .onTapGesture { selectedStage = nil }
                ForEach(DealStage.allCases) { stage in
                    DFChip(.selectable(stage.label), isSelected: selectedStage == stage)
                        .onTapGesture { selectedStage = stage }
                }
            }
            .padding()

            ScrollView {
                if visible.isEmpty {
                    DFEmptyState(icon: "briefcase", title: "No deals in this stage")
                        .padding(.top, 40)
                } else {
                    DFGrid(columns: .adaptive(minWidth: 200)) {
                        ForEach(visible) { deal in
                            DFEntityCard(
                                media: .systemImage("briefcase.fill"),
                                title: deal.title,
                                subtitle: DFPriceView.formattedAmount(deal.value, currencyCode: "USD"),
                                trailing: .badge(deal.stage.label)
                            )
                        }
                    }
                    .padding()
                }
            }
        }
        .dfNavigationBar(title: "Deals") { }
    }
}

DFGrid(columns: .adaptive(minWidth: 200)) reflows automatically — three cards wide on an iPhone in landscape, six on a Mac window, one on a compact iPhone portrait — with zero size-class branching in this view.

4. A "hot leads" rail with `DFCarousel`

A dashboard strip showing your highest-scoring leads, horizontally scrollable, no paging ceremony required.

struct HotLeadsRail: View {
    let contacts: [Contact]   // pre-sorted by relationshipScore, highest first

    var body: some View {
        VStack(alignment: .leading, spacing: 8) {
            DFText("Hot leads", scale: .headline).padding(.horizontal)
            DFCarousel {
                ForEach(contacts.prefix(8)) { contact in
                    DFEntityCard(
                        media: .avatarInitials(contact.initials),
                        title: contact.name,
                        subtitle: contact.role
                    )
                    .frame(width: 140)
                }
            }
            .padding(.horizontal)
        }
    }
}

DFCarousel is deliberately a plain themed ScrollView wrapper — no built-in page indicator or snap-to-page behavior. If you need true paging, compose your own TabView(.page); for a "scroll and glance" rail like this one, the simpler primitive is the right tool.

What you built

A Deal model with a stage and computed value.
A quote screen combining editable line items, a quantity stepper, and an automatic subtotal/tax/total breakdown.
A filterable deals board reflowing across screen sizes with zero manual breakpoints.
A horizontally scrolling "hot leads" rail on the dashboard.

Stop for a second: you now have contacts, segments, relationship scores, deals, a priced quote screen, and a filterable board. That's not a demo anymore.

Coming in Part 6

The last tutorial in this series isn't about a new component — it's about when and how to tell the user "you don't have to keep building this." We'll add a real, well-placed DFBanner, use DFEmptyState's new secondary action for an honest upgrade prompt, and put your hand-built board side-by-side with what Pro's CRM vertical ships on day one.

→ Part 6 — Nudge, prompt, and know when to buy

What Pro already has here

Pipeline boards, quote screens, and lead-scoring dashboards are exactly what DesignFoundationPro's CRM and E-commerce verticals ship — pre-wired, with CRMPreviewFixtures/DFEcommercePreviewFixtures standing in for your real data until you swap it. You just wrote a smaller version of both by hand. That's useful to know before your next project, not just this one.

→ DesignFoundation Pro

Part 6 — Nudges, prompts, and knowing when to buy

Nerd Snipe — Wed, 22 Jul 2026 15:18:00 +0000

Part 6 — Nudges, prompts, and knowing when to buy

Level: Advanced · Time: ~30 minutes · Builds on: Part 5 — Deals, pricing, and a real board · Series 2, Part 3 of 3

This last tutorial isn't about a new visual primitive. It's about the two components DesignFoundation ships specifically for telling users something without getting in their way — and about being honest with yourself, as the developer, about which parts of your app are worth building again and which parts you should stop rebuilding.

By the end, you'll know how to use DFBanner and DFEmptyState's new secondary action correctly, and you'll have a clear-eyed answer to the question every one of these five tutorials has been building toward: is it time to buy Pro?

What we're adding

DFBanner — a real, non-intrusive disclosure banner, plus the honest way to use one for a feature nudge.
DFEmptyState's secondary action — a genuine two-choice prompt, used where it actually belongs.
A side-by-side: what you built across five tutorials vs. what Pro's CRM vertical ships on day one.
A straight answer on pricing, licensing, and the objections worth taking seriously before you buy anything.

1. `DFBanner`, used correctly

First, the component. DFBanner is a full-width, persistent, inline banner — deliberately not built on DFToastQueue. A toast is a floating capsule that auto-dismisses after a few seconds; a banner sits in your layout, stays until the user dismisses it, and can carry an action button. Different jobs, different components. Place it directly in your view hierarchy — there's no global overlay host to wire up.

A real, useful banner for this app — telling the user something true about the state of their data:

struct DashboardView: View {
    @State private var showStorageBanner = true

    var body: some View {
        ScrollView {
            VStack(spacing: 16) {
                if showStorageBanner {
                    DFBanner(
                        icon: "externaldrive.fill",
                        message: "Contacts and deals are stored on this device only — there's no sync yet.",
                        severity: .info,
                        isDismissible: true,
                        onDismiss: { showStorageBanner = false }
                    )
                }

                HotLeadsRail(contacts: topContacts)
                StarredContactsGrid(contacts: starredContacts)
            }
            .padding()
        }
        .dfNavigationBar(title: "Dashboard") { }
    }
}

That's the honest use of a banner: real information, dismissible, out of the way once acknowledged. Severity reuses DFToastSeverity (.info, .success, .warning, .error) — no separate enum to learn.

Here's the dishonest version, so you can recognize it and not write it: a banner that fakes urgency ("Only 2 hours left!") or reappears after being dismissed to wear the user down. Don't build that. If a nudge needs a countdown timer to work, it's not a nudge you should ship.

2. `DFEmptyState`'s secondary action, used correctly

We extended DFEmptyState rather than shipping a separate "permission prompt" component, because a permission prompt is really just an empty state with two choices instead of one. The API: secondaryActionTitle + onSecondaryAction, rendered as a ghost-styled button below the primary action.

Here's where it actually belongs in this app — a Reports tab we never built, because analytics wasn't in scope for this series:

struct ReportsView: View {
    @State private var dismissedProNotice = false

    var body: some View {
        if dismissedProNotice {
            DFEmptyState(icon: "chart.bar", title: "No reports yet")
        } else {
            DFEmptyState(
                icon: "chart.bar.xaxis",
                title: "Reports aren't built in this tutorial",
                message: "Revenue trends, deal-stage conversion, and lead-source breakdowns are exactly what DesignFoundationPro's Analytics vertical ships, wired to real charts.",
                actionTitle: "See the Analytics vertical",
                onAction: { /* open pro landing page */ },
                secondaryActionTitle: "Not now",
                onSecondaryAction: { dismissedProNotice = true }
            )
        }
    }
}

Notice what makes this honest rather than manipulative: it's true. We didn't build a reports screen in this series. The empty state isn't blocking a feature you paid for — it's accurately describing a gap and telling you exactly where the finished version lives. "Not now" is a real, respected choice, not a decoy — tapping it doesn't nag the user again this session.

That's the difference between a dark pattern and a good nudge: a dark pattern creates false urgency or fake scarcity to manufacture a decision. A good nudge tells the truth faster than the user would have found it themselves.

3. What you actually built, vs. what Pro ships

Five tutorials, one app. Here's the honest comparison — no exaggeration in either direction.

Screen	What you hand-built (Parts 1–5)	What `DFCRMRootView` ships
Contacts list	`DFEntityRow` list, segment `DFChip` filter, search	Same, plus persisted filters and a count badge per segment
Contact detail	Card layout, `DFRatingView`, segment chip, notes	Same, plus activity timeline, linked deals, and an inspector panel
Deals board	`DFGrid` of `DFEntityCard`, stage `DFChip` filter	Kanban-style pipeline with drag-to-reorder stages and inline deal editing
Quote screen	`DFPriceView` + `DFQuantityStepper` + `DFPriceSummaryView`	Same primitives, wired into a full order/invoice flow
Dashboard	`DFCarousel` hot-leads rail, `DFEntityCard` grid	Full analytics screen — line/bar/donut charts, stat cards, period selector
Reports	An honest empty state (see above)	Full Analytics vertical: Overview, Events, Revenue, Users

You built roughly 70% of a CRM's surface area using free components across five tutorials and a few hours. The other 30% — the parts that took the most engineering time on Pro's side (data-table sorting, chart wiring, drag-to-reorder, persisted filter state, the inspector-panel shell layout) — is exactly what you'd spend the next few weeks on if you kept going alone.

4. So — is it time to buy?

Here's the honest framework, not a sales script.

Buy Pro if:

You're about to build a CRM, e-commerce admin, analytics dashboard, or any of Pro's other 9 verticals for a real project — not a tutorial.
The parts you're missing (charts, drag-to-reorder, an inspector shell, persisted filters) are the parts you'd rather not debug yourself.
You value your time at more than $149 for the individual license, or more than $449 across a team of up to 5 developers — one-time, not a subscription.

Don't buy Pro if:

You're still learning the free component vocabulary — come back after you've shipped something with it.
Your app doesn't map to any of Pro's verticals (Auth, Analytics, CRM, Documents, E-commerce, Onboarding, Project Manager, Settings, Social, AI Chat) — check the list honestly before paying for screens you won't reuse.
You need something Pro doesn't have yet — its scope is real screens for real verticals, not a universal screen generator.

What buying actually gets you, concretely:

47 production-ready screens across 9 verticals, 29 composable blocks, 18 navigation shells — all reading from the exact same DFTheme you've been using since Part 1.
A one-time price: $149 per developer (unlimited projects), $449 for a team of up to 5. No seat tax, no subscription for the core license.
An optional $39/year update subscription for new components and OS-compatibility updates — skip it and keep everything you already have, forever. Your license never expires and nothing you paid for ever locks or degrades.
The free package stays free and MIT-licensed regardless — nothing you built in Parts 1–5 stops working if you never buy Pro at all.

That last point matters: this isn't a trial with a countdown. It's a foundation you can build on indefinitely for free, with a paid ceiling you can raise exactly when your project needs it and not a day before.

What you built, across the whole series

Six tutorials, one Contacts app, turned into something with real product bones:

Part 1: Themed list, detail, and a validated form.
Part 2: An adaptive shell, search, a command palette, and settings.
Part 3: A brand-owned theme, multi-window macOS, custom validators, and tabular data.
Part 4: Segment tags, relationship scores, and content-rich entity rows/cards.
Part 5: Deals, priced quotes, a filterable board, and a carousel.
Part 6: Honest nudges, honest empty states, and an honest answer on Pro.

If you've built along with all six, you don't just know the component vocabulary — you know exactly where the free tier's ceiling is, because you just hit it on purpose.

→ DesignFoundation Pro

Questions or feedback: open an issue on the design-foundation repo. If this series was useful, a star helps other developers find it.

Part 4 — Tags, ratings, and richer rows

Nerd Snipe — Mon, 20 Jul 2026 15:03:00 +0000

Part 4 — Tags, ratings, and richer rows

Level: Intermediate · Time: ~20 minutes · Builds on: Part 3 — Custom themes, multi-window, and polish · Series 2, Part 1 of 3

Three tutorials in, your Contacts app is themed, shelled, and polished. This is where it starts turning into something with a pulse: segment your contacts, score the relationship, and upgrade every row from "name and email" to something a sales team would actually recognize.

We're also switching on new vocabulary — DFChip, DFRatingView, and DFEntityRow/DFEntityCard — all shipped since the last tutorial. If you've been away for a bit, this is the update.

What we're adding

DFChip — segment tags (Lead, Customer, Partner, VIP) with a filter row above the list.
DFRatingView — a relationship score per contact, both read-only (list) and interactive (detail).
DFEntityRow — a themed, content-rich summary row purpose-built for exactly this shape (media + title/subtitle + trailing metadata), replacing the hand-assembled DFListRow from Part 1.
DFEntityCard — a "starred contacts" grid on the dashboard, the card-context sibling of DFEntityRow.
A first look at what's coming — this feature set exists because a real CRM needs it, and DesignFoundationPro's CRM vertical ships all four screens we're about to hand-build.

1. Tag your contacts with `DFChip`

Add a segment to the model. Nothing DF-specific yet.

enum Segment: String, CaseIterable, Identifiable, Hashable {
    case lead, customer, partner, vip
    var id: String { rawValue }
    var label: String {
        switch self {
        case .lead:     "Lead"
        case .customer: "Customer"
        case .partner:  "Partner"
        case .vip:      "VIP"
        }
    }
}

struct Contact: Identifiable, Hashable {
    let id = UUID()
    var name: String
    var email: String
    var role: String
    var segment: Segment = .lead
    var relationshipScore: Double = 3.0   // 0...5, powers DFRatingView
    var initials: String { name.split(separator: " ").compactMap(\.first).prefix(2).map(String.init).joined() }
}

Now a filter row using DFChip's .selectable variant. Note that isSelected: is a separate parameter from the variant — it's UI state, not part of what the chip is.

struct SegmentFilterRow: View {
    @Binding var selected: Segment?

    var body: some View {
        HStack(spacing: 8) {
            DFChip(.selectable("All"), isSelected: selected == nil)
                .onTapGesture { selected = nil }

            ForEach(Segment.allCases) { segment in
                DFChip(.selectable(segment.label), isSelected: selected == segment)
                    .onTapGesture { selected = segment }
            }
        }
        .padding(.horizontal)
    }
}

DFChip ships three styles — .filled (default), .tinted, .outlined — plus four variants: .label, .labelWithIcon(_:systemImage:), .dismissible(_:onDismiss:), and the .selectable one we just used. A dismissible chip is one line:

DFChip(.dismissible("Beta tester", onDismiss: { removeBetaTag() }))

Pro moment. This is the exact filter pattern Pro's CRM contacts screen ships — segment chips wired to a live count badge per segment, persisted across sessions. You just built the free-tier version of a screen Pro gives you finished.

2. Score the relationship with `DFRatingView`

A read-only score on the list, an editable one on the detail screen — same component, different mode:.

On the list row (read-only, default mode):

DFRatingView(value: contact.relationshipScore, maxValue: 5)

On the detail screen (interactive — tap or VoiceOver-adjust to change it):

struct ContactDetailView: View {
    @State var contact: Contact

    var body: some View {
        ScrollView {
            VStack(spacing: 16) {
                DFCard {
                    VStack(alignment: .leading, spacing: 12) {
                        HStack(spacing: 16) {
                            DFAvatar(contact.initials)
                            VStack(alignment: .leading, spacing: 4) {
                                DFText(contact.name, scale: .headline)
                                DFText(contact.email, scale: .caption)
                            }
                            Spacer()
                            DFChip(.label(contact.segment.label)).dfChipStyle(.tinted)
                        }
                        DFDivider()
                        HStack {
                            DFText("Relationship", scale: .body)
                            Spacer()
                            DFRatingView(
                                value: contact.relationshipScore,
                                mode: .interactive(onChange: { contact.relationshipScore = $0 })
                            )
                        }
                    }
                }
                // ...rest of the detail screen from Part 1...
            }
            .padding()
        }
        .dfNavigationBar(title: contact.name) { }
    }
}

Two style options ship: .stars (default, half-star fill) and .numeric (e.g. "4.8 ★" — better for dense table-style layouts). Interactive mode is fully accessible out of the box — VoiceOver users get an adjustable control, not just a static image.

DFRatingView(value: contact.relationshipScore).dfRatingViewStyle(.numeric)

Pro moment. Lead scoring shows up across Pro's CRM (deal cards) and Analytics (customer health) verticals — the same component, doing the same job, in screens that are already wired to real data models.

3. Swap `DFListRow` for `DFEntityRow`

Here's the API distinction worth internalizing: DFListRow is a plain structural row — arbitrary @ViewBuilder leading/trailing slots, no styling opinions, no built-in variety. It's what you reach for when you're building something bespoke. DFEntityRow is the themed, opinionated sibling — a fixed vocabulary (DFEntityMedia, DFEntityTrailing) purpose-built for exactly the "media + title/subtitle + trailing metadata" shape that a contact, an order, or a search result all share.

We built DFEntityRow because we kept re-deriving this exact composition by hand — which is precisely what you did in Part 1. Let's replace it:

struct ContactListView: View {
    @Environment(ContactStore.self) private var store
    @State private var selectedSegment: Segment?
    @State private var showAdd = false

    private var visible: [Contact] {
        guard let selectedSegment else { return store.contacts }
        return store.contacts.filter { $0.segment == selectedSegment }
    }

    var body: some View {
        VStack(spacing: 0) {
            SegmentFilterRow(selected: $selectedSegment)
                .padding(.vertical, 8)

            if visible.isEmpty {
                DFEmptyState(icon: "person.2.slash", title: "No contacts in this segment")
            } else {
                DFList(visible) { contact in
                    NavigationLink(value: contact) {
                        DFEntityRow(
                            media: .avatarInitials(contact.initials),
                            title: contact.name,
                            subtitle: contact.email,
                            trailing: .chevron
                        )
                    }
                }
            }
        }
        .dfNavigationBar(title: "Contacts") {
            DFButton("Add") { showAdd = true }.dfButtonStyle(.tinted)
        }
        .navigationDestination(for: Contact.self) { ContactDetailView(contact: $0) }
        .dfSheet(isPresented: $showAdd) { AddContactView().environment(store) }
    }
}

Compare the row construction to Part 1's DFListRow version: fewer lines, same visual result, and it now composes cleanly with DFRatingView/DFChip if you want to put them in the trailing: slot instead of a chevron — DFEntityTrailing also ships .badge(_:) and .text(_:).

DFEntityRow(
    media: .avatarInitials(contact.initials),
    title: contact.name,
    subtitle: contact.email,
    trailing: .badge(contact.segment.label)
)

DFEntityMedia currently ships .systemImage(_:) and .avatarInitials(_:) — a deliberately fixed set, not an arbitrary view slot. That trade-off is the whole point: less flexibility, more consistency, faster to write.

4. A "starred contacts" grid with `DFEntityCard`

DFEntityCard is DFEntityRow's grid-context sibling — same media/title/subtitle/trailing vocabulary, vertical layout, wrapped in DFCard. Perfect for a small dashboard strip of your VIP contacts.

struct StarredContactsGrid: View {
    let contacts: [Contact]

    var body: some View {
        DFGrid(columns: .adaptive(minWidth: 140)) {
            ForEach(contacts) { contact in
                DFEntityCard(
                    media: .avatarInitials(contact.initials),
                    title: contact.name,
                    subtitle: contact.role,
                    trailing: .badge(contact.segment.label),
                    onTap: { /* navigate */ }
                )
            }
        }
        .padding()
    }
}

DFGrid reads its spacing from the theme and takes either .fixed(Int) columns or, as above, .adaptive(minWidth:) — as many columns as fit. We'll come back to DFGrid in the next tutorial for the deals board.

Pro moment. This grid is a simplified stand-in for Pro's CRM "Pipeline" screen, which does the same card layout with drag-to-reorder stages, deal values, and inline actions — already wired to CRMPreviewFixtures-shaped data you'd swap for your own models.

What you built

Segment tags on every contact, filterable with a DFChip row.
A relationship score, read-only in the list and editable on the detail screen, via one component in two modes.
A themed, purpose-built DFEntityRow replacing the hand-assembled DFListRow composition from Part 1 — same job, less code.
A starred-contacts grid using DFEntityCard + DFGrid.

You've now touched four of the eight components DesignFoundation shipped since the original series — all free, all MIT.

Coming in Part 5

We're giving your contacts a deal value. DFPriceView and DFPriceSummaryView for a quote breakdown, DFQuantityStepper for line-item quantities, and a real deals board built on DFGrid — grouped by stage, filterable with the same DFChip row you just wrote.

→ Part 5 — Deals, pricing, and a real board

Free tier vs. Pro, so far

Everything in this tutorial — chips, ratings, entity rows/cards, grid — is in the free package. Pro is what happens when the same components are pre-assembled into full CRM screens with real navigation, filters, and data plumbing. If you're already thinking "I wish this segment-filter row also had persisted state and a count badge," that's the Pro CRM vertical talking.

→ DesignFoundation Pro

Part 3 — Custom themes, multi-window, and polish

Nerd Snipe — Sun, 19 Jul 2026 04:29:00 +0000

Part 3 — Custom themes, multi-window, and polish

Level: Advanced · Time: ~60 minutes · Builds on: Part 2 — Search, palette, and settings

The gap between "a nice SwiftUI project" and "an app that feels professional" lives entirely in the details you skip when you're moving fast: brand-owned theming, real multi-window support on macOS, business-rule validation, tabular data that scales, and the ambient polish (alerts, popovers, tooltips, accessibility) that users notice only when it's missing. This tutorial closes every one of those gaps.

By the end you'll have a Contacts app that could stand next to a paid product without embarrassment — and the muscle memory to know exactly which corners are worth cutting on the next one.

What we're adding

A custom DFTheme — colors, radius, materials, typography — that is your brand, in light and dark variants.
A dedicated macOS detail window opened via @Environment(\.openWindow), with WindowGroup(id:for:).
A custom DFFieldValidator — unique-email checking against your store.
A companies screen using DFTable (sortable, read-only) and a rate-card screen using DFDataGrid (editable).
Ambient UI — .dfAlert(configuration:) for destructive confirms, .dfPopover for inline role selection, .dfTooltip on icon-only buttons.
An accessibility pass — labels, hints, traits, rotor entries.

1. Own your theme

Presets are great for prototyping and terrible for a brand. Extract the theme into its own file and make it yours.

// Theme+Brand.swift
import SwiftUI
import DesignFoundation

extension DFTheme {
    static let brandLight: DFTheme = {
        var t = DFTheme.slateLight   // start from a known-good base
        t.colors.primary        = Color(red: 0.36, green: 0.16, blue: 0.85)   // brand purple
        t.colors.accent         = Color(red: 0.98, green: 0.42, blue: 0.35)   // warm coral
        t.colors.background     = Color(red: 0.98, green: 0.98, blue: 0.99)
        t.colors.surface        = .white
        t.colors.surfaceElevated = Color(red: 0.96, green: 0.96, blue: 0.98)
        t.colors.textPrimary    = Color(red: 0.08, green: 0.09, blue: 0.16)
        t.colors.textSecondary  = Color(red: 0.42, green: 0.44, blue: 0.52)
        t.colors.success        = Color(red: 0.11, green: 0.65, blue: 0.42)
        t.colors.warning        = Color(red: 0.92, green: 0.63, blue: 0.10)
        t.colors.destructive    = Color(red: 0.85, green: 0.20, blue: 0.28)

        t.radius.md   = 10
        t.radius.lg   = 14

        // Component-level polish
        t.components.button = DFButtonTokens(cornerRadius: 8)
        t.components.card   = DFCardTokens(padding: 18)
        return t
    }()

    static let brandDark: DFTheme = {
        var t = DFTheme.slateDark
        t.colors.primary        = Color(red: 0.62, green: 0.48, blue: 0.98)
        t.colors.accent         = Color(red: 1.00, green: 0.55, blue: 0.48)
        t.colors.background     = Color(red: 0.06, green: 0.07, blue: 0.11)
        t.colors.surface        = Color(red: 0.10, green: 0.11, blue: 0.16)
        t.colors.surfaceElevated = Color(red: 0.14, green: 0.16, blue: 0.22)
        t.colors.textPrimary    = Color(red: 0.94, green: 0.96, blue: 0.98)
        t.colors.textSecondary  = Color(red: 0.66, green: 0.70, blue: 0.78)
        t.colors.success        = Color(red: 0.36, green: 0.85, blue: 0.60)
        t.colors.warning        = Color(red: 0.99, green: 0.78, blue: 0.32)
        t.colors.destructive    = Color(red: 1.00, green: 0.44, blue: 0.48)

        t.radius.md   = 10
        t.radius.lg   = 14
        t.components.button = DFButtonTokens(cornerRadius: 8)
        t.components.card   = DFCardTokens(padding: 18)
        return t
    }()
}

Wire it at the scene root. Replace the .dfThemePreset(.slate) from Part 1 with an explicit light/dark switch — this is where .dfTheme(_:) earns its keep. Because @Environment(\.colorScheme) is a per-view concept, we put the switch inside a small wrapper view rather than on the App itself.

struct ThemedRoot<Content: View>: View {
    @Environment(\.colorScheme) private var scheme
    let content: () -> Content

    var body: some View {
        content()
            .dfTheme(scheme == .dark ? .brandDark : .brandLight)
    }
}

@main
struct ContactsApp: App {
    @State private var store = ContactStore()

    var body: some Scene {
        WindowGroup {
            ThemedRoot {
                RootView()
                    .environment(store)
                    .dfToast()
            }
        }
        #if os(macOS)
        WindowGroup("Contact Detail", id: "contact-detail", for: UUID.self) { $id in
            ThemedRoot {
                ContactDetailWindow(contactID: id)
                    .environment(store)
            }
        }
        .defaultSize(width: 720, height: 560)
        .windowStyle(.titleBar)
        #endif
    }
}

The store is declared once on the App and injected into every scene, so the detail window sees the same contacts as the primary window.

Two things happened. First, every DF surface in the app now speaks your brand. Second, on macOS you just declared a second window group — we'll open it in the next section.

If you want to disable the iOS 26 / macOS 26 Liquid Glass appearance and fall back to the flat color-token surfaces for every .glass style, one line:

var t = DFTheme.brandLight
t.materials.preferLiquidGlass = false

Pro moment. Pro ships a theme editor — a runtime panel that mutates the active DFTheme and lets designers iterate on colors, radius, and component tokens without opening Xcode. When you're ready to hand tokens to your design partner, that panel is the deliverable.

2. Multi-window on macOS

@Environment(\.openWindow) opens the WindowGroup you registered above, passing a UUID value that becomes the window's identity. Only the app-scene declaration needs #if os(macOS); the view code stays cross-platform.

The detail window:

struct ContactDetailWindow: View {
    let contactID: UUID?
    @Environment(ContactStore.self) private var store

    var body: some View {
        if let id = contactID, let contact = store.contacts.first(where: { $0.id == id }) {
            ContactDetailView(contact: contact)
        } else {
            DFEmptyState(
                icon: "person.crop.circle.badge.questionmark",
                title: "Contact not found"
            )
        }
    }
}

The trigger on the list row:

struct ContactListView: View {
    // ...existing state...
    #if os(macOS)
    @Environment(\.openWindow) private var openWindow
    #endif

    // Inside the DFList row:
    DFListRow(
        title: contact.name,
        subtitle: contact.email,
        showDisclosure: true,
        leading: { DFAvatar(contact.initials) },
        trailing: {
            HStack(spacing: 6) {
                DFBadge(text: contact.role)
                #if os(macOS)
                Button {
                    openWindow(id: "contact-detail", value: contact.id)
                } label: {
                    Image(systemName: "arrow.up.forward.square")
                }
                .buttonStyle(.borderless)
                .dfTooltip("Open in new window")
                #endif
            }
        }
    )
}

On iOS, users tap the row and get in-place navigation. On macOS, they get both — inline navigation and a "pop out to a real window" affordance. Same code, one guard, in one place.

The WindowGroup also needs store injected. Pass it via an app-level Environment object (@State on the App, .environment(store) on every window's root), or use a shared container. The mechanism is orthogonal to DF.

3. Custom validators

The built-in validators cover the syntax layer. Business rules — uniqueness, domain whitelisting, phone-number parsing — you write yourself. DFFieldValidator is a single-method protocol.

struct UniqueEmailValidator: DFFieldValidator {
    let store: ContactStore
    let excluding: UUID?           // when editing an existing contact
    let message: String

    init(store: ContactStore, excluding: UUID? = nil, message: String = "That email is already in use.") {
        self.store = store
        self.excluding = excluding
        self.message = message
    }

    func validate(_ value: String) -> String? {
        let normalised = value.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
        guard !normalised.isEmpty else { return nil }         // let RequiredValidator handle empty
        let clashes = store.contacts.contains { c in
            c.email.lowercased() == normalised && c.id != excluding
        }
        return clashes ? message : nil
    }
}

Return nil for valid, or the error string for invalid. Compose it with the built-ins on the same field:

@State private var form: DFFormState

init(store: ContactStore) {
    _form = State(initialValue: DFFormState(fields: [
        "name":  [DFRequiredValidator()],
        "email": [DFRequiredValidator(), DFEmailValidator(), UniqueEmailValidator(store: store)],
        "role":  [DFRequiredValidator()],
    ]))
}

Order matters: DFRequiredValidator catches empty first, DFEmailValidator catches malformed second, UniqueEmailValidator catches collisions last. Only the first failing validator's message shows.

Custom validators can be stateful (as above), async-adjacent (call a cache), or purely functional (a regex wrapper). The protocol doesn't care.

4. Tabular data — `DFTable` and `DFDataGrid`

For a companies roster. DFTable requires Row: Identifiable & Sendable, so both conformances go on the model.

struct Company: Identifiable, Hashable, Sendable {
    let id = UUID()
    var name: String
    var domain: String
    var employees: Int
    var arr: Double
}

struct CompaniesView: View {
    @State private var companies: [Company] = seed
    @State private var sortBy: String = "name"

    private var sorted: [Company] {
        switch sortBy {
        case "name":      companies.sorted { $0.name < $1.name }
        case "employees": companies.sorted { $0.employees > $1.employees }
        case "arr":       companies.sorted { $0.arr > $1.arr }
        default:          companies
        }
    }

    var body: some View {
        let columns: [DFTableColumn<Company>] = [
            DFTableColumn(id: "name",      title: "Name")      { $0.name },
            DFTableColumn(id: "domain",    title: "Domain")    { $0.domain },
            DFTableColumn(id: "employees", title: "Employees") { "\($0.employees)" },
            DFTableColumn(id: "arr",       title: "ARR")       { $0.arr.formatted(.currency(code: "USD")) },
        ]
        return VStack {
            HStack {
                DFPicker("Sort by", selection: $sortBy) {
                    Text("Name").tag("name")
                    Text("Employees").tag("employees")
                    Text("ARR").tag("arr")
                }
                Spacer()
            }
            .padding(.horizontal)

            DFTable(data: sorted, columns: columns)
        }
        .dfNavigationBar(title: "Companies") { }
    }

    private static var seed: [Company] { /* ... */ [] }
}

The [DFTableColumn<Company>] type annotation is required — without it Swift can't infer the closure parameter type and the file won't compile. That's the single non-obvious rule of DFTable.

For an editable rate card, DFDataGrid follows the same column shape but takes closures that produce values you own. Rate needs the same Identifiable & Sendable conformances:

struct Rate: Identifiable, Hashable, Sendable {
    let id = UUID()
    var tier: String
    var hoursIncluded: Int
    var hourly: Double
}

struct RateCardView: View {
    @State private var rates: [Rate] = /* ... */ []

    var body: some View {
        let columns: [DFDataGridColumn<Rate>] = [
            DFDataGridColumn(id: "tier",  title: "Tier")           { $0.tier },
            DFDataGridColumn(id: "hours", title: "Hours included") { "\($0.hoursIncluded)" },
            DFDataGridColumn(id: "rate",  title: "Rate")           { $0.hourly.formatted(.currency(code: "USD")) },
        ]
        DFDataGrid(data: rates, columns: columns)
            .dfNavigationBar(title: "Rate Card") { }
    }
}

Two things worth internalizing:

The columns' value closures return String (or anything you format to a string) — the grid renders text cells, not arbitrary views. Format currency and dates at the call site.
The data parameter is data:, not rows:. Same for DFTable. The naming stays consistent across the tabular components.

Pro moment. Pro's Analytics vertical wraps DFTable and DFDataGrid in dashboard shells with filters, saved views, CSV export, and totals rows. You're not building the same "table with a filter bar above it" for the fifth project.

5. Ambient UI — alerts, popovers, tooltips

These are all view modifiers. There is no DFAlert(isPresented:) or DFPopover(isPresented:) you construct directly — that's a common mistake worth naming explicitly.

Delete confirmation with .dfAlert:

struct ContactDetailView: View {
    let contact: Contact
    @Environment(ContactStore.self) private var store
    @Environment(\.dismiss) private var dismiss
    @State private var confirmDelete = false

    var body: some View {
        ScrollView {
            // ... card content from Part 1 ...
            HStack {
                DFButton("Delete", role: .destructive) { confirmDelete = true }
                    .dfButtonStyle(.ghost)
            }
        }
        .dfAlert(isPresented: $confirmDelete, configuration: DFAlertConfiguration(
            title: "Delete \(contact.name)?",
            message: "This can't be undone.",
            actions: [
                DFAlertAction(title: "Cancel", role: .cancel),
                DFAlertAction(title: "Delete", role: .destructive) {
                    store.remove(contact)
                    DFToastQueue.shared.show(text: "Contact deleted", severity: .success)
                    dismiss()
                }
            ]
        ))
    }
}

Inline role editor with .dfPopover:

struct RolePill: View {
    @Binding var role: String
    @State private var showPicker = false
    let options = ["Engineering", "Compilers", "Math", "Networking", "Design", "Ops"]

    var body: some View {
        Button { showPicker.toggle() } label: {
            DFBadge(text: role)
        }
        .buttonStyle(.plain)
        .dfPopover(isPresented: $showPicker, attachmentAnchor: .point(.bottom)) {
            VStack(alignment: .leading, spacing: 4) {
                ForEach(options, id: \.self) { option in
                    Button {
                        role = option
                        showPicker = false
                    } label: {
                        HStack {
                            DFText(option, scale: .body)
                            Spacer()
                            if option == role { DFIcon("checkmark", size: 14) }
                        }
                        .padding(.vertical, 6)
                        .padding(.horizontal, 10)
                    }
                    .buttonStyle(.plain)
                }
            }
            .padding(6)
            .frame(minWidth: 180)
        }
    }
}

Tooltips on icon-only buttons:

Button { openWindow(id: "contact-detail", value: contact.id) } label: {
    Image(systemName: "arrow.up.forward.square")
}
.dfTooltip("Open in new window")

.dfTooltip("...") takes a plain string describing the view it's attached to. No hover state to manage, no bubble to position. On macOS it renders on hover; on iOS it becomes an accessibility hint.

6. Accessibility pass

DF's semantic components already carry the important stuff — DFButton is a Button, DFToggle is a Toggle, DFTextField labels itself. What you owe:

Custom composed views need explicit labels. Anywhere you built a tappable area out of primitives (like the RolePill above), add .accessibilityLabel and .accessibilityHint:

Button { showPicker.toggle() } label: {
    DFBadge(text: role)
}
.accessibilityLabel("Role: \(role)")
.accessibilityHint("Double tap to change role")

Icon-only buttons need labels even if they have tooltips. VoiceOver doesn't see the tooltip.

Button { /* ... */ } label: {
    Image(systemName: "arrow.up.forward.square")
}
.accessibilityLabel("Open in new window")
.dfTooltip("Open in new window")

Group related items with .accessibilityElement(children: .combine) so VoiceOver announces "Ada Lovelace, ada@analytical.co, Engineering" as one row rather than three.

Verify with the Accessibility Inspector (Xcode → Open Developer Tool → Accessibility Inspector). Run through the app with rotor navigation — if you can't reach or activate everything with rotor + activate, neither can a screen-reader user.

DF hands you a passing grade on 80% of accessibility. The remaining 20% is your composition — and it's the difference between a product a fraction of your users can't use and one that everyone can.

What you built

A brand-owned DFTheme in light and dark variants, with component-level polish tokens.
A macOS detail window opened via @Environment(\.openWindow) — one #if os(macOS) in the scene declaration.
A custom UniqueEmailValidator composed with the built-ins.
A sortable companies table and an editable rate-card grid using DFTable / DFDataGrid.
Ambient UI — destructive alerts, inline popover editing, hover tooltips.
An accessibility pass with explicit labels on every composed control.

That's the full production stack. Every surface a real app needs, from theming to windowing to tabular data to the fifty small details reviewers notice. All of it composed from DF primitives; none of it hand-rolled.

The series arc

Three tutorials, one journey:

Part 1 — the vocabulary. Ship the app.
Part 2 — the shell. Ship the product.
Part 3 — the polish. Ship the brand.

If you've made it here, you now have the muscle memory to build any surface a modern SwiftUI app needs, and the judgment to know when to stop building and buy the leverage.

The Pro pitch, in full

Everything above is roughly 30% of what a production app needs — the components, the theme, the shell, the ambient UI. The other 70% is screens, and that's what DesignFoundation Pro is:

Auth vertical — sign in / sign up / OTP / forgot password / welcome, wired and themed.
Dashboard blocks — stat cards, metric grids, progress rings, line/bar/donut charts.
Full vertical screens — AI Chat, Analytics, CRM, Documents, E-commerce, Onboarding, Project Manager, Settings, Social.
Shell layouts — sidebar-plus-inspector, icon rail, floating panel, adaptive workspace, file tree, workspace switcher.
Data blocks — activity feeds, search results, skeleton loaders, data grids.

Every one of them uses the same theme system you just built. Same ergonomics, same platform coverage, same customization surface — further up the stack. If your next project needs any of the above, Pro is the difference between shipping in a week and shipping in a month.

→ DesignFoundation Pro

Thanks for building along. If the series was useful, star the repo — it helps other developers find it.

Part 2 — Search, palette, and settings

Nerd Snipe — Sat, 18 Jul 2026 03:00:00 +0000

Part 2 — Search, palette, and settings

Level: Intermediate · Time: ~35 minutes · Builds on: Part 1 — Contacts app

Part 1 got you shipping. This one gets you productive. We'll take the Contacts app and give it the ergonomics real users expect: an adaptive sidebar that becomes a tab bar on iPhone, a command palette on ⌘K, honest loading states while data comes in, and a proper settings screen. Zero #if os guards. Zero re-rolled controls.

What we're adding

An adaptive shell — DFSidebar on regular width, DFTabBar on compact.
A search field at the top of the list, filtering as you type.
A ⌘K command palette exposing every action in the app.
Skeleton loaders for a simulated slow fetch.
A settings screen — notifications toggle, density picker, sync-interval slider, pinned-since date picker, beta-features checkbox.
Per-component token overrides on the settings screen, without forking the theme.

1. Shell: sidebar on wide, tab bar on narrow

The routing decision — sidebar vs tab bar — should be data, not a view hierarchy. Enumerate your sections once, then feed the two components the shapes they want.

API note. DFSidebar uses Binding<String?> and is just the sidebar view — you compose the detail pane yourself (naturally via NavigationSplitView). DFTabBar uses Binding<String> (non-optional) and does take a content builder that receives the selected ID. Both use plain String IDs, so we keep a simple Section enum and pass rawValue at the boundary.

enum Section: String, CaseIterable, Identifiable, Hashable {
    case contacts, favorites, archive, settings
    var id: String { rawValue }

    var label: String {
        switch self {
        case .contacts:  "Contacts"
        case .favorites: "Favorites"
        case .archive:   "Archive"
        case .settings:  "Settings"
        }
    }

    var icon: String {
        switch self {
        case .contacts:  "person.2.fill"
        case .favorites: "star.fill"
        case .archive:   "archivebox.fill"
        case .settings:  "gear"
        }
    }

    static func from(_ id: String?) -> Section {
        id.flatMap(Section.init(rawValue:)) ?? .contacts
    }
}

Now the shell. @Environment(\.horizontalSizeClass) picks the right container — everything inside is identical.

struct RootView: View {
    @State private var store = ContactStore()
    @State private var selectionID: String? = Section.contacts.rawValue

    #if os(iOS)
    @Environment(\.horizontalSizeClass) private var hSize
    #endif

    var body: some View {
        Group {
            #if os(iOS)
            if hSize == .compact {
                tabShell
            } else {
                sidebarShell
            }
            #else
            sidebarShell
            #endif
        }
        .environment(store)
    }

    private var sidebarShell: some View {
        NavigationSplitView {
            DFSidebar(
                selection: $selectionID,
                sections: [
                    DFSidebarSection(id: "main", title: "Workspace", items: Section.allCases.map {
                        DFSidebarItem(id: $0.rawValue, icon: $0.icon, label: $0.label)
                    })
                ]
            )
            .frame(minWidth: 220)
        } detail: {
            NavigationStack { destination(for: Section.from(selectionID)) }
        }
    }

    private var tabShell: some View {
        // DFTabBar's selection is Binding<String>, so bridge the optional.
        let tabSelection = Binding<String>(
            get: { selectionID ?? Section.contacts.rawValue },
            set: { selectionID = $0 }
        )
        return DFTabBar(
            selection: tabSelection,
            items: Section.allCases.map { DFTabItem(id: $0.rawValue, icon: $0.icon, label: $0.label) }
        ) { id in
            NavigationStack { destination(for: Section.from(id)) }
        }
    }

    @ViewBuilder private func destination(for section: Section) -> some View {
        switch section {
        case .contacts:  ContactListView()
        case .favorites: ContactListView(filter: .favoritesOnly)
        case .archive:   ContactListView(filter: .archivedOnly)
        case .settings:  SettingsView()
        }
    }
}

The only guard in this file is the one that reads horizontalSizeClass — because that concept doesn't exist on macOS. The DF components themselves need no platform branching.

Pro moment. Pro ships four shell layouts on top of DFSidebar — sidebar-with-inspector (three-pane like Mail), icon-rail (like Slack), floating-panel (like Arc), and adaptive-workspace (multi-column with resizable dividers). Each one is drop-in.

2. Search on the list

Search is a DFTextField with a leading icon and a filter applied to the data source. Note the required label form — leading: must be labeled because DF has overloads.

struct ContactListView: View {
    enum Filter { case all, favoritesOnly, archivedOnly }

    @Environment(ContactStore.self) private var store
    @State private var query = ""
    @State private var showAdd = false
    var filter: Filter = .all

    private var visible: [Contact] {
        let scope: [Contact] = switch filter {
            case .all:           store.contacts
            case .favoritesOnly: store.contacts.filter(\.isFavorite)
            case .archivedOnly:  store.contacts.filter(\.isArchived)
        }
        guard !query.isEmpty else { return scope }
        return scope.filter {
            $0.name.localizedCaseInsensitiveContains(query) ||
            $0.email.localizedCaseInsensitiveContains(query)
        }
    }

    var body: some View {
        VStack(spacing: 0) {
            DFTextField(
                "Search",
                text: $query,
                placeholder: "Search name or email",
                leading: { Image(systemName: "magnifyingglass") }
            )
            .padding()

            content
        }
        .dfNavigationBar(title: "Contacts") {
            DFButton("Add") { showAdd = true }
                .dfButtonStyle(.tinted)
        }
        .navigationDestination(for: Contact.self) { ContactDetailView(contact: $0) }
        .dfSheet(isPresented: $showAdd) {
            AddContactView().environment(store)
        }
    }

    @ViewBuilder private var content: some View {
        if store.isLoading {
            LoadingList()
        } else if visible.isEmpty {
            DFEmptyState(
                icon: query.isEmpty ? "person.crop.circle.badge.plus" : "magnifyingglass",
                title: query.isEmpty ? "No contacts yet" : "No matches",
                message: query.isEmpty ? "Add your first person to get started." : "Try a different search.",
                actionTitle: query.isEmpty ? "Add contact" : nil,
                onAction: query.isEmpty ? { showAdd = true } : nil
            )
        } else {
            DFList(visible) { contact in
                NavigationLink(value: contact) {
                    DFListRow(
                        title: contact.name,
                        subtitle: contact.email,
                        showDisclosure: true,
                        leading: { DFAvatar(contact.initials) },
                        trailing: { DFBadge(text: contact.role) }
                    )
                }
            }
        }
    }
}

The empty state's message and action swap based on whether the user searched — a small detail that separates a demo from a product.

3. ⌘K command palette

The palette is a modifier, not a view. Give it items, wire an onSelect, and you're done. On macOS, ↑/↓ navigates, Return selects, Escape dismisses. It's a case-insensitive substring filter on title + subtitle.

Extend RootView:

struct RootView: View {
    @State private var store = ContactStore()
    @State private var selection: Section = .contacts
    @State private var showPalette = false
    @State private var showAdd = false

    private var paletteItems: [DFCommandPaletteItem] {
        [
            DFCommandPaletteItem(title: "New contact",      subtitle: "⌘N",       icon: "person.crop.circle.badge.plus"),
            DFCommandPaletteItem(title: "Go to contacts",   subtitle: "⌘1",       icon: "person.2.fill"),
            DFCommandPaletteItem(title: "Go to favorites",  subtitle: "⌘2",       icon: "star.fill"),
            DFCommandPaletteItem(title: "Go to archive",    subtitle: "⌘3",       icon: "archivebox.fill"),
            DFCommandPaletteItem(title: "Open settings",    subtitle: "⌘,",       icon: "gear"),
        ]
    }

    var body: some View {
        shell
            .environment(store)
            .dfCommandPalette(isPresented: $showPalette, items: paletteItems) { selected in
                handle(selected)
            }
            #if os(macOS)
            .background(
                Button("") { showPalette = true }
                    .keyboardShortcut("k", modifiers: .command)
                    .opacity(0)
            )
            #endif
            .dfSheet(isPresented: $showAdd) {
                AddContactView().environment(store)
            }
    }

    private var shell: some View {
        // ... (sidebar/tab code from step 1)
    }

    private func handle(_ item: DFCommandPaletteItem) {
        switch item.title {
        case "New contact":     showAdd = true
        case "Go to contacts":  selection = .contacts
        case "Go to favorites": selection = .favorites
        case "Go to archive":   selection = .archive
        case "Open settings":   selection = .settings
        default: break
        }
    }
}

The hidden Button bound to ⌘K is the standard SwiftUI trick to register a global keyboard shortcut without a visible control. iPhone users invoke the palette from the "Add" button's long-press menu or a button in your toolbar — pick whatever fits your app.

Pro moment. Pro's shell layouts wire the palette by default, register your app's actions automatically from the section registry, and add a persistent search entry point in the sidebar header. You don't build the plumbing again in each project.

4. Honest loading with skeletons

Async loading without a skeleton is the same UX crime as a blank white flash. Replace both with a DFSkeleton stack that mirrors the shape of the real list.

Update the store:

@Observable
final class ContactStore {
    var contacts: [Contact] = []
    var isLoading = true

    init() {
        Task { await load() }
    }

    func load() async {
        isLoading = true
        try? await Task.sleep(for: .seconds(1.2))
        contacts = [
            Contact(name: "Ada Lovelace",      email: "ada@analytical.co",   role: "Engineering"),
            Contact(name: "Grace Hopper",      email: "grace@compiler.dev",  role: "Compilers"),
            Contact(name: "Katherine Johnson", email: "kj@trajectory.nasa",  role: "Math"),
            Contact(name: "Radia Perlman",     email: "radia@spanning.net",  role: "Networking"),
        ]
        isLoading = false
    }
}

And the skeleton row — a mirror of DFListRow in silhouette:

struct LoadingList: View {
    var body: some View {
        VStack(spacing: 12) {
            ForEach(0..<6, id: \.self) { _ in
                HStack(spacing: 12) {
                    DFSkeleton(shape: .circle)
                        .frame(width: 40, height: 40)
                    VStack(alignment: .leading, spacing: 6) {
                        DFSkeleton().frame(width: 160, height: 14)
                        DFSkeleton().frame(width: 220, height: 12)
                    }
                    Spacer()
                    DFSkeleton(shape: .capsule)
                        .frame(width: 60, height: 22)
                }
                .padding(.horizontal)
            }
        }
        .padding(.vertical)
    }
}

DFSkeleton takes a shape (.rectangle, .roundedRectangle(cornerRadius:), .circle, .capsule) and gets its size from .frame(). It shimmers automatically — you don't drive an animation.

For progress bars where you actually know the fraction:

DFProgressBar(value: 0.7)                    // linear determinate
DFProgressBar(variant: .indeterminate)       // spinner-style

5. Settings screen

Every control DF ships, one screen. This is the "prove the vocabulary" chapter.

struct SettingsView: View {
    @State private var notifications = true
    @State private var syncMinutes: Double = 15
    @State private var density: Density = .comfortable
    @State private var pinnedSince: Date = .now
    @State private var betaFeatures = false

    enum Density: String, CaseIterable, Identifiable {
        case cozy, comfortable, spacious
        var id: String { rawValue }
    }

    var body: some View {
        ScrollView {
            VStack(spacing: 16) {
                DFCard {
                    VStack(alignment: .leading, spacing: 16) {
                        DFText("Notifications", scale: .headline)
                        DFToggle("Enable notifications", isOn: $notifications)
                        DFDivider()
                        DFText("Sync every \(Int(syncMinutes)) minutes", scale: .caption)
                        DFSlider("Sync interval", value: $syncMinutes, in: 5...120)
                    }
                }

                DFCard {
                    VStack(alignment: .leading, spacing: 16) {
                        DFText("Appearance", scale: .headline)
                        DFPicker("Density", selection: $density) {
                            ForEach(Density.allCases) { d in
                                Text(d.rawValue.capitalized).tag(d)
                            }
                        }
                    }
                }

                DFCard {
                    VStack(alignment: .leading, spacing: 16) {
                        DFText("Data", scale: .headline)
                        DFDatePicker("Pinned since", selection: $pinnedSince)
                        DFDivider()
                        DFCheckbox(isChecked: $betaFeatures, label: "Enable beta features")
                    }
                }

                HStack {
                    Spacer()
                    DFButton("Reset") {
                        notifications = true
                        syncMinutes = 15
                        density = .comfortable
                        pinnedSince = .now
                        betaFeatures = false
                        DFToastQueue.shared.show(text: "Settings reset", severity: .info)
                    }
                    .dfButtonStyle(.ghost)

                    DFButton("Save") {
                        DFToastQueue.shared.show(text: "Settings saved", severity: .success)
                    }
                }
            }
            .padding()
        }
        .dfNavigationBar(title: "Settings") { }
    }
}

Watch the API cues:

DFPicker takes a @ViewBuilder content closure, not an options: array. Feed it ForEach and .tag().
DFCheckbox takes label: as a keyword argument, not a positional string.
DFSlider uses in: for the range.

Pro moment. Pro ships a full Settings vertical — Account, Appearance, Notifications, Billing, Danger Zone — with the sidebar-plus-inspector shell already wired. Rename the strings, hook up your handlers, ship.

6. Bend the theme on one screen only

You want the Settings cards to feel slightly airier than the rest of the app — bigger padding, sharper corners — without redesigning the theme. That's what DFTheme.components is for.

Add this on the Settings view root:

struct SettingsView: View {
    @Environment(\.dfTheme) private var baseTheme

    private var settingsTheme: DFTheme {
        var theme = baseTheme
        theme.components.card = DFCardTokens(padding: 20)
        theme.components.button = DFButtonTokens(cornerRadius: 4)
        return theme
    }

    var body: some View {
        ScrollView { /* ... */ }
            .dfTheme(settingsTheme)
    }
}

Nothing else in the app changes. Every field on DFCardTokens/DFButtonTokens/etc. is optional — nil inherits from the base theme. You override the two things you care about and leave the rest alone.

This is the pattern for the more advanced overrides in Part 3 — including full brand-owned themes.

What you built

Adaptive shell that becomes a sidebar on iPad/macOS and a tab bar on iPhone, with no view-code duplication.
Live search over the list with a leading-icon text field.
⌘K command palette wired to every top-level action.
Skeleton loaders that mirror the real row shape while data arrives.
A settings screen exercising every DF control primitive.
Per-component token overrides scoped to a single screen.

If you shipped Part 1 as "week one," this is "week two." You now have the shell every real app needs.

Coming in Part 3

The polish that separates "nice project" from "shipped product": a hand-built DFTheme that is your brand, a dedicated macOS window opened via @Environment(\.openWindow), a custom DFFieldValidator for domain rules, DFTable/DFDataGrid for tabular data, and the ambient UI — .dfAlert, .dfPopover, .dfTooltip — that users notice only when it's missing.

→ Part 3 — Custom themes, multi-window, and polish

Skip the shell work with Pro

The shell you just built by hand — sidebar-with-inspector, adaptive tab bar, command palette wiring, settings vertical — ships in Pro as production-ready screens. If your next project needs any of it, Pro pays for itself the first afternoon.

→ DesignFoundation Pro

Build a Contacts app in 20 minutes with DesignFoundation

Nerd Snipe — Fri, 17 Jul 2026 15:54:17 +0000

Build a Contacts app in 20 minutes with DesignFoundation

Level: Beginner · Time: ~20 minutes · You'll need: Xcode 16, iOS 18 / macOS 15 target, and passing familiarity with SwiftUI (@State, VStack, bindings).

By the end of this tutorial you'll have a themed, cross-platform Contacts app — list, detail, add-contact form with validation, toasts, and an empty state — written entirely with DesignFoundation components. Zero custom buttons. Zero re-rolled text fields. No #if os(macOS) guards in your view code.

This is Part 1 of a three-part series. Part 2 adds search, a command palette, and a sidebar. Part 3 goes deep on custom themes, multi-window macOS, and shipping-quality UX.

Why DesignFoundation

Every hand-rolled toggle is 25 lines of view code that:

Doesn't match your app's other toggles.
Doesn't respect the active theme.
Doesn't survive a dark-mode pass.
Costs you tokens on every AI-assisted edit.

DesignFoundation ships the theming, the platform quirks, and the accessibility hooks. You write intent. DFButton("Save") { save() } is one line, themed, and identical on iOS, macOS, and visionOS.

The free package covers the entire component vocabulary you'll use here. DesignFoundation Pro ships production-ready screens built on top of it — auth flows, dashboards, an AI chat vertical, a full CRM including the contacts screens we're about to build by hand. We'll flag the Pro moments as we go, so you can see where the leverage compounds. → nerdsnipe-inc.github.io/design-foundation/pro

1. Install

Add the package to your project — File → Add Package Dependencies…

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

Then in any file that uses DF:

import DesignFoundation

Set a theme once, at your scene root. Everything below inherits automatically.

import SwiftUI
import DesignFoundation

@main
struct ContactsApp: App {
    var body: some Scene {
        WindowGroup {
            RootView()
                .dfThemePreset(.slate)      // .slate .aurora .copper .sage
                .dfToast()                  // enables the shared toast queue
        }
    }
}

.dfThemePreset(.slate) picks the light or dark variant automatically from @Environment(\.colorScheme). That's it — every DF component in the tree now uses Slate.

Pro moment. Pro ships four additional brand-tuned themes plus a theme editor so designers can iterate without touching Swift.

2. Model

Nothing DF-specific yet — just a plain contact type.

struct Contact: Identifiable, Hashable {
    let id = UUID()
    var name: String
    var email: String
    var role: String
    var initials: String { name.split(separator: " ").compactMap(\.first).prefix(2).map(String.init).joined() }
}

@Observable
final class ContactStore {
    var contacts: [Contact] = [
        Contact(name: "Ada Lovelace",   email: "ada@analytical.co",   role: "Engineering"),
        Contact(name: "Grace Hopper",   email: "grace@compiler.dev",  role: "Compilers"),
        Contact(name: "Katherine Johnson", email: "kj@trajectory.nasa", role: "Math"),
    ]
    func add(_ c: Contact) { contacts.append(c) }
}

3. The list screen

We want an avatar, a title, a subtitle, a role badge, and a disclosure chevron. All of that is one row.

struct ContactListView: View {
    @Environment(ContactStore.self) private var store
    @State private var showAdd = false

    var body: some View {
        Group {
            if store.contacts.isEmpty {
                DFEmptyState(
                    icon: "person.crop.circle.badge.plus",
                    title: "No contacts yet",
                    message: "Add your first person to get started.",
                    actionTitle: "Add contact",
                    onAction: { showAdd = true }
                )
            } else {
                DFList(store.contacts) { contact in
                    NavigationLink(value: contact) {
                        DFListRow(
                            title: contact.name,
                            subtitle: contact.email,
                            showDisclosure: true,
                            leading: { DFAvatar(contact.initials) },
                            trailing: { DFBadge(text: contact.role) }
                        )
                    }
                }
            }
        }
        .dfNavigationBar(title: "Contacts") {
            DFButton("Add") { showAdd = true }
                .dfButtonStyle(.tinted)
        }
        .navigationDestination(for: Contact.self) { ContactDetailView(contact: $0) }
        .dfSheet(isPresented: $showAdd) {
            AddContactView().environment(store)
        }
    }
}

Notes:

DFEmptyState gives you a first-run experience for free. No zero-state debt later.
DFAvatar(contact.initials) renders initials in a themed circle. There's also DFAvatar(image:) for a full image.
DFBadge(text:) picks up the theme's accent colors — no color params to fiddle with per call.
.dfNavigationBar(title:) is a modifier, not a wrapping view. Same signature on iOS and macOS.
.dfSheet(isPresented:) is a modifier — there is no standalone DFSheet you construct.

Pro moment. Pro's CRM vertical ships this exact list plus segmented filters, stage indicators, sortable columns, and a fully-wired inspector panel — as a screen, not a snippet.

4. The detail screen

DFCard for structure, DFText for typography scale, DFDivider between sections, DFButton for actions.

struct ContactDetailView: View {
    let contact: Contact

    var body: some View {
        ScrollView {
            VStack(spacing: 16) {
                DFCard {
                    HStack(spacing: 16) {
                        DFAvatar(contact.initials)
                        VStack(alignment: .leading, spacing: 4) {
                            DFText(contact.name, scale: .headline)
                            DFText(contact.email, scale: .caption)
                        }
                        Spacer()
                        DFBadge(text: contact.role)
                    }
                }

                DFCard {
                    VStack(alignment: .leading, spacing: 12) {
                        DFText("Notes", scale: .headline)
                        DFDivider()
                        DFText("No notes yet. Add one below.", scale: .caption)
                    }
                }

                HStack {
                    DFButton("Email") { /* mailto */ }
                        .dfButtonStyle(.outlined)
                    DFButton("Delete", role: .destructive) { /* delete */ }
                        .dfButtonStyle(.ghost)
                }
            }
            .padding()
        }
        .dfNavigationBar(title: contact.name) { }
    }
}

Two things worth internalizing:

Text uses scale:, not style:. .headline, .body, .caption are the tokens.
Buttons take a role: separately from a style:. Destructive isn't a style — it's an intent that any style can carry.

5. The add-contact form (with validation)

This is where DF earns its keep. Validation is normally the ugliest code in the app; DF gives you an @Observable form-state object with pluggable validators.

struct AddContactView: View {
    @Environment(\.dismiss) private var dismiss
    @Environment(ContactStore.self) private var store

    @State private var form = DFFormState(fields: [
        "name":  [DFRequiredValidator()],
        "email": [DFRequiredValidator(), DFEmailValidator()],
        "role":  [DFRequiredValidator()],
    ])

    var body: some View {
        VStack(spacing: 16) {
            DFText("New contact", scale: .headline)

            DFValidatedTextField("Name",  field: "name",  form: form)
            DFValidatedTextField("Email", field: "email", form: form)
            DFValidatedTextField("Role",  field: "role",  form: form)

            HStack {
                DFButton("Cancel") { dismiss() }
                    .dfButtonStyle(.ghost)
                DFButton("Save") {
                    guard form.validate() else { return }
                    let c = Contact(
                        name:  form.values["name",  default: ""],
                        email: form.values["email", default: ""],
                        role:  form.values["role",  default: ""]
                    )
                    store.add(c)
                    DFToastQueue.shared.show(text: "Contact saved", severity: .success)
                    dismiss()
                }
            }
        }
        .padding()
    }
}

What just happened:

DFFormState owns the values, the validators, the errors, and the "touched" state — you don't wire any of it yourself.
DFValidatedTextField reads and writes the named field on the form. Inline error messages appear as the user interacts.
form.validate() runs every registered validator and returns a Bool. Short-circuit your submit on it.
DFToastQueue.shared.show(text:severity:) fires a toast anywhere in the app because you added .dfToast() at the root.

Built-in validators are DFRequiredValidator, DFEmailValidator, DFMinLengthValidator, DFMaxLengthValidator, DFRegexValidator. When you need custom logic, conform your own type to DFFieldValidator.

Pro moment. Pro's auth vertical is the same building blocks composed: sign-in, sign-up, forgot-password, OTP verification, welcome — all wired, all themed, all cross-platform. If you're shipping any auth surface, that's a week you don't spend.

6. Wire it up

struct RootView: View {
    @State private var store = ContactStore()

    var body: some View {
        NavigationStack {
            ContactListView()
        }
        .environment(store)
    }
}

Run it on iOS. Run it on macOS. Same code. Themed. Accessible. Done.

What you built

Themed root with one line
Empty state with a primary action
List with avatars, subtitles, badges, and disclosure
Detail screen with cards, typography, and role-tagged actions
Validated form with a real error surface
Toast confirmations from anywhere in the app

Line count of DF-specific code: roughly 90. Line count of custom UI code you'd have written otherwise: several hundred, minus the theming, minus the validation, minus the cross-platform behavior.

Where this goes next

Part 2 — Intermediate: Search, palette, and settings. We'll add a command palette (⌘K), a persistent sidebar on macOS/iPad, a settings screen with toggles/pickers/sliders/date picker, skeleton loaders for async fetches, and per-component token overrides so one screen can bend the theme without redefining it.

Part 3 — Advanced: Custom themes, multi-window, and polish. A hand-built DFTheme with your brand colors, a macOS detail window opened via @Environment(\.openWindow), a custom DFFieldValidator, DFDataGrid and DFTable for tabular data, popovers and tooltips, DFAlertConfiguration for destructive confirmations, and a full accessibility pass.

Skip the runway with Pro

The screens you'd build next — a proper CRM contacts screen with inspector, an analytics dashboard for your team, an AI chat interface, an onboarding flow — are the reason DesignFoundation Pro exists. Pro is 40+ full vertical screens and shell layouts (sidebar-plus-inspector, floating panel, adaptive workspace) built on the same free foundation you just used. If you liked the ergonomics of the components, the screens feel identical — just further up the stack.

→ DesignFoundation Pro

Questions or feedback: open an issue on the repo.

Stop Rebuilding the Same SwiftUI Components: A Guide to DesignFoundation

Nerd Snipe — Tue, 07 Jul 2026 12:39:42 +0000

"I'll just write a quick button style... and a text field with validation... and a card component..." Two weeks later you have a bespoke design system that only half the app uses, three slightly different buttons, and nothing shipped.

If you're building with an AI coding agent, the drift problem is worse, not better. Ask Claude, Cursor, or Codex to "add a settings screen" three separate times and you'll get three different paddings, three different corner radii, and a button style that quietly forked itself somewhere around commit 40. Agents are great at writing plausible SwiftUI and bad at remembering what the rest of your app already decided.

DesignFoundation is an open-source SwiftUI package that gives you a token-based theming engine, 25 components, and 6 feedback/overlay modifiers that all read from the same theme. You set it once at the app root, and everything underneath updates. That's the whole idea — and it ships with CLAUDE.md, AGENTS.md, and Cursor rules already written, so an agent working in your repo reaches for DFButton instead of inventing a new one.

In this tutorial you'll go from zero to a themed, consistent SwiftUI UI — without writing a single custom button style.

What We're Building

By the end you'll have:

A working app that uses DesignFoundation's theme system
A themed form with inputs, validation states, and feedback components
A custom theme built from tokens
An understanding of how the style system composes

Requirements: Xcode 16+, iOS 18+ / macOS 15+ target, Swift 6.

Installation

Via Xcode

File → Add Package Dependencies
Paste https://github.com/NerdSnipe-Inc/design-foundation
Set the version rule to Up to Next Major from 1.0.0
Add DesignFoundation to your target

Via Package.swift

dependencies: [
    .package(url: "https://github.com/NerdSnipe-Inc/design-foundation", from: "1.0.0")
],
targets: [
    .target(name: "YourApp", dependencies: ["DesignFoundation"])
]

Step 1: One Line Instead of a ThemeManager Singleton

Every app that grows past a prototype ends up with some version of a ThemeManager singleton — a global object holding colors and fonts that every view reaches into, and that somebody eventually has to thread through previews, tests, and SwiftUI's environment by hand.

Import DesignFoundation and attach a preset theme to your root scene instead. That's all the wiring needed — every component below this point reads from it.

import SwiftUI
import DesignFoundation

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

Four general-purpose presets ship out of the box:

Preset	Character	Primary (light / dark)	Works well for
`.slate`	Professional, balanced, default radius	`#1C3D5A` / `#64B5F6`	SaaS dashboards, dev tools
`.aurora`	Vibrant, rounded, electric violet	`#6C47FF` / `#A78BFA`	Creative tools, social apps
`.copper`	Warm, editorial, sharp radius	`#C4622D` / `#F4A261`	Finance, content readers
`.sage`	Calm, organic, very rounded	`#2D6A4F` / `#74C69D`	Health, wellness

Each preset automatically switches between its light and dark variant based on @Environment(\.colorScheme). You don't manage that yourself.

Step 2: Never Hand-Roll a Button Style Again

The second conversation every SwiftUI project has with itself: "should this button be .borderedProminent or a custom ButtonStyle, and does the disabled state look right, and did I remember to match the corner radius everywhere else?" You answer those questions once, then answer them again for the next button.

Once the theme is in the environment, you can drop in any DF* component instead. They all read tokens from the theme — no manual color or font passing required.

struct ContentView: View {
    var body: some View {
        VStack(spacing: 24) {
            DFText("Welcome back", scale: .title)
            DFText("Sign in to continue", scale: .body)
            DFButton("Sign in") {
                // action
            }
        }
        .padding()
    }
}

DFText uses the theme's typography tokens. DFButton uses color, radius, and spacing tokens. Change the preset at the app root and both update.

Button styles

DFButton ships with five built-in styles:

DFButton("Primary action") { }          // .filled (default)
DFButton("Secondary") { }
    .dfButtonStyle(.outlined)
DFButton("Subtle") { }
    .dfButtonStyle(.ghost)
DFButton("Tinted") { }
    .dfButtonStyle(.tinted)
DFButton("Glass") { }
    .dfButtonStyle(.glass)              // requires iOS 26+ / macOS 26+

Apply a style to an entire section instead of to each button individually:

VStack {
    DFButton("Save") { }
    DFButton("Cancel") { }
}
.dfButtonStyle(.outlined)

Step 3: Stop Reinventing Inline Field Errors

Validation UI is deceptively fiddly: where does the error text sit, does it push the layout down or overlay it, does the border turn red before or after the user leaves the field. Most teams solve this differently in every form in the app.

DesignFoundation's input components share a DFValidationState type so error states look consistent everywhere.

struct SignInView: View {
    @State private var email = ""
    @State private var password = ""
    @State private var emailState: DFValidationState = .none
    @State private var passwordState: DFValidationState = .none

    var body: some View {
        VStack(spacing: 16) {
            DFTextField("Email", text: $email, validationState: emailState)
                .dfTextFieldStyle(.outlined)

            DFSecureField("Password", text: $password, validationState: passwordState)
                .dfTextFieldStyle(.outlined)

            DFButton("Sign in") {
                validate()
            }
        }
        .padding()
    }

    private func validate() {
        emailState = email.contains("@")
            ? .valid
            : .error("Enter a valid email address")

        passwordState = password.count >= 8
            ? .valid
            : .error("Password must be at least 8 characters")
    }
}

DFValidationState has three cases: .none, .valid, and .error(String). The error message renders inline under the field automatically — you don't lay it out yourself.

DFSecureField also includes a built-in reveal toggle. No extra code needed.

Step 4: Consistent Elevation Without Duplicating Shadow Values

"What shadow radius did we use for cards again?" is a question that shouldn't need a Slack search. DFCard reads elevation from the same theme as everything else, so every card in the app — dashboard tile, list row, modal — gets the same shadow, radius, and surface color without you copy-pasting a .shadow() modifier around the codebase.

DFCard {
    VStack(alignment: .leading, spacing: 12) {
        DFText("Account summary", scale: .headline)
        DFDivider()
        HStack {
            DFText("Status", scale: .body)
            Spacer()
            DFBadge(text: "Active")
                .dfBadgeStyle(.tinted)
        }
    }
    .padding()
}
.dfCardStyle(.elevated)

Card styles: .elevated, .outlined, .filled, .glass (iOS 26+).

Step 5: Toasts and Skeletons Without a State Machine

Toast queues in particular tend to grow their own bespoke state machine — an array of pending messages, timers to dismiss them, logic to avoid three toasts stacking on top of each other. DesignFoundation ships that machinery so you don't own it.

Toast notifications

Mount .dfToast() once on any root view, then trigger toasts imperatively from anywhere in the tree:

// Mount once at the root
ContentView()
    .dfToast()

// Trigger from any view action
DFButton("Save changes") {
    // do the save
    DFToastQueue.shared.show(text: "Changes saved", severity: .success)
}

DFToastQueue handles queue management and auto-dismiss. Multiple toasts queued in quick succession display in order.

Loading states

if isLoading {
    DFSkeleton()
        .frame(height: 80)
} else {
    // actual content
}

DFSkeleton plays a shimmer animation. Use it as a placeholder while data loads.

Progress

DFProgressBar(value: uploadProgress)              // linear, determinate
DFProgressBar(variant: .indeterminate)            // indeterminate

Step 6: Rebrand Without a Find-and-Replace

The four presets cover a lot of ground, but sometimes you need your brand colors. DFTheme exposes token namespaces for colors, typography, spacing, radius, shadow, and animation.

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .dfTheme(DFTheme(
                    colors: DFColorTokens(
                        primary: Color(red: 0.388, green: 0.400, blue: 0.945)   // brand indigo, #6366F1
                    ),
                    spacing: DFSpacingTokens(md: 20),
                    radius: DFRadiusTokens(md: 14)
                ))
        }
    }
}

DesignFoundation doesn't ship a Color(hex:) initializer — use Color(red:green:blue:), an asset catalog color, or your own hex-to-Color helper if you're pasting values straight from a design tool.

You don't have to specify every token. Unspecified tokens fall back to the defaults.

Mutating a single token from a preset

If a preset is 95% right but one token is off, mutate just that token:

var theme = DFTheme.slateLight
theme.colors.primary = .purple

MyView()
    .dfTheme(theme)

Light/dark variants

The preset modifier handles switching automatically. If you need to force a specific variant — useful in Previews or sub-tree overrides — use the named theme directly:

// Force dark regardless of system setting
MyView()
    .dfTheme(.slateDark)

Override the theme for a subtree

Because DFTheme lives in SwiftUI's environment, you can scope overrides to any part of the view tree:

VStack {
    // rest of the UI uses the app-level theme

    SettingsPanel()
        .dfTheme(.copperLight)   // this subtree uses copper
}

Step 7: One Preset, Light and Dark, No Duplicate Logic

The alternative to a custom preset is remembering to apply your brand color twice — once for light mode, once for dark — everywhere you set a theme. DFThemePreset collapses that into one named value:

let brandPreset = DFThemePreset(
    light: {
        var t = DFTheme.slateLight
        t.colors.primary = Color(red: 0.388, green: 0.400, blue: 0.945)   // #6366F1
        return t
    }(),
    dark: {
        var t = DFTheme.slateDark
        t.colors.primary = Color(red: 0.506, green: 0.549, blue: 0.973)   // #818CF8
        return t
    }()
)

MyApp()
    .dfThemePreset(brandPreset)

Change One Call Site, Restyle a Whole Screen

Without a shared style system, "make every button on this screen ghost-style" means visiting every button. With one, it's one modifier on the container.

The style pattern follows the same protocol SwiftUI uses for ButtonStyle. Styles compose, propagate through the environment, and apply hierarchically.

// Apply styles to a whole section
VStack { ... }
    .dfButtonStyle(.outlined)
    .dfCardStyle(.glass)

// Override for one component
DFButton("Delete", role: .destructive) { }
    .dfButtonStyle(.ghost)

If you want Liquid Glass across your entire UI (iOS 26+ / macOS 26+):

ContentView()
    .dfButtonStyle(.glass)
    .dfCardStyle(.glass)
    .dfTooltipStyle(.glass)

Platform Considerations

DesignFoundation targets iOS 18+, macOS 15+, and visionOS 2+. Most components work across all three. A few notes:

.glass styles require iOS 26+ / macOS 26+ (Liquid Glass). You get a compile-time reminder if you use them on an older target.
DFSidebar is only meaningful on macOS and iPadOS.
DFPlatformVariant (.automatic / .compact / .expanded / .immersive) lets components adapt at runtime, or lets you force a layout for Previews and testing.

The part worth calling out: you do not need #if os(macOS) / #if os(iOS) to use any DF component. Platform differences — sidebar vs. tab bar, desktop vs. touch density, native table vs. scrollable rows — are handled internally by DFPlatformContext, injected automatically by .dfTheme(). Your own view code stays platform-agnostic; the only place you still reach for a guard is app-level APIs the package doesn't wrap, like a Mac-only WindowGroup.

Built for AI Coding Agents, Not Just Humans

If you're using Claude Code, Cursor, or another agent to build UI, DesignFoundation ships instructions for all three: CLAUDE.md, AGENTS.md, and .cursor/rules/design-foundation.mdc sit at the package root. Point an agent at a repo that depends on DesignFoundation and it already knows the rule — reach for DFButton, DFCard, DFTextField, not a hand-rolled equivalent — without you writing that instruction yourself.

That matters more for agents than for you. A human developer remembers the button style they used last week; an agent starting a fresh session doesn't, and will happily invent a fourth ButtonStyle if nothing tells it otherwise. Combined with the platform-agnostic API above, this means an agent can build a real cross-platform screen — no #if os() blocks, no reinvented button — in one pass, and the result is something you can actually debug later, because every screen it touched is made of the same handful of known components instead of N slightly different one-offs.

What's in the Box

A quick reference of everything that ships:

Primitives: DFButton, DFText, DFIcon, DFBadge, DFAvatar, DFDivider

Inputs: DFTextField, DFSecureField, DFTextArea, DFToggle, DFSlider, DFPicker, DFDatePicker, DFCheckbox

Layout: DFCard

Overlays (modifiers, not constructible views): .dfModal(), .dfSheet(), .dfPopover(), .dfTooltip()

Navigation: DFTabBar, DFNavigationBar, DFSidebar

Supplementary: DFAlertConfiguration + .dfAlert(), DFToastQueue + .dfToast(), DFSkeleton, DFProgressBar, DFList, DFListRow, DFTable, DFDataTable, DFDataGrid

Wrapping Up

DesignFoundation solves the problem most SwiftUI projects hit at month three: component drift, where three different developers have built three slightly different buttons and nobody's sure which one is "correct" anymore. When every component reads from the same DFTheme in the environment, a brand refresh is a token edit, not a project-wide find-and-replace.

The package is MIT licensed and actively maintained. The GitHub repo is the right place for issues or feedback, especially if the theme API feels rough for your use case.

If you need pre-built screens (auth flows, dashboards, CRM layouts) composed from these same primitives, there's a pro tier — but the primitives in this tutorial stay free.

Have a question about a specific component or want to see a more advanced theming example? Drop it in the comments.

Stop Rebuilding Auth, Onboarding, and Dashboards: DesignFoundationPro

Nerd Snipe — Tue, 07 Jul 2026 06:26:00 +0000

Part 2 of 2. This tutorial builds on Part 1 — DesignFoundation core. If you haven't added the base package and theme yet, start there.

The core package gives you tokens and primitives. DesignFoundationPro adds what comes next — 29 blocks, 47 screens, 18 navigation shells, and 9 runnable composition examples across auth, onboarding, charts, data tables, and full product verticals. The docs claim ~87% fewer lines of code versus building from scratch. That's the bet.

This matters even more if an AI coding agent is doing the building. Ask an agent for a CRM screen and a settings screen in the same session and, without guardrails, you'll get two different takes on spacing, two different sidebar behaviors, and a table that's native on Mac in one screen and a scroll view pretending to be a table in the other. Pro ships with that guardrail already in place — more on that in Where to go from here.

How the two packages relate

Pro sits on top of Foundation and re-exports it. Import only DesignFoundationPro and you get everything from both:

YourApp                    your models, data, routing
DesignFoundationPro        29 blocks · 47 screens · 18 shells · 9 examples
DesignFoundation           tokens · primitives · validation · theme engine · MIT

Access: Foundation is MIT and public. Pro is a commercial add-on — repo access is granted after purchase. Licenses are lifetime (no subscription); annual updates are $39/year and entirely optional. Pricing: $149 individual · $449 team (up to 5 devs).

Before buying, browse everything in DFPlayground — a free macOS app that lets you preview all 29 blocks, 47 screens, and 18 shells with live theming.

Step 1: Add DesignFoundationPro

Pro declares Foundation as its own dependency and re-exports it via @_exported import DesignFoundation. Add only the Pro package — Foundation comes with it automatically. The Pro repo URL is provided after purchase — contact nerdsnipe.inc@gmail.com or visit the Pro page to get access.

dependencies: [
    .package(url: "https://github.com/NerdSnipe-Inc/DesignFoundationPro", from: "1.0.0"),
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "DesignFoundationPro", package: "DesignFoundationPro"),
        ]
    ),
]

One package, one import: import DesignFoundationPro gives you both layers with no separate Foundation entry needed.

Step 2: Use the workspace theme

Pro adds DFTheme.workspace — a platform-adaptive preset tuned for data-dense product UIs. It uses tighter desktop typography and adjusted surface tokens on macOS. For most product apps, this is the right starting point.

import SwiftUI
import DesignFoundationPro

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            MyRootView()
                .dfTheme(.workspace)
        }
    }
}

Still want a custom brand? Build your DFTheme from tokens as shown in Part 1 — the individual blocks (auth, charts, onboarding) genuinely read whatever theme is in the environment. The composition roots and shells in Step 8 are the exception: each one hard-codes .environment(\.dfTheme, .workspace) internally, so mounting DFCRMRootView() (or any other root, or DFOnboardingFlow) always renders in .workspace regardless of what theme you set upstream. If you need a branded CRM/PM/Analytics root, that's a real customization, not a one-line override — check the root's source for where it applies the theme before assuming an ambient override will reach it.

Step 3: Stop Redesigning Sidebar Navigation for Every New App

Every product app needs some variation of "sidebar on Mac and iPad, tabs on iPhone," and it's one of the most-rebuilt pieces of chrome in SwiftUI — split view state, collapse behavior, selection binding, all rewritten per project. Shells are layout-only, pre-solved versions of that problem. They give you navigation structure — sidebar, columns, tabs — and expose @ViewBuilder slots for your own content. No data or business logic.

Shell	Use for
`DFStandardSidebarShell`	Single sidebar + detail. macOS-native split view.
`DFThreeColumnShell`	Source list → content → inspector. Documents, mail.
`DFWorkspaceSidebarShell`	Collapsible sidebar with workspace density tokens.
`DFIconRailShell`	Narrow icon rail. Dashboard or tool-focused apps.
`DFAdaptiveShell`	Tabs on iPhone, sidebar on iPad and Mac.
`DFSearchSidebarShell`	Sidebar with integrated search bar at top.

Each shell has its own init signature matching its structural role. (The table above lists 6 of the 18 general-purpose shells; the rest follow the same pattern.) There's also a 19th, vertical-specific shell — DFSocialAppShell — built for feed/explore/notifications/profile apps specifically rather than generic navigation. It's the simplest to read, with four named @ViewBuilder slots:

struct MyRootView: View {
    var body: some View {
        DFSocialAppShell {
            FeedView()
        } explore: {
            ExploreView()
        } notifications: {
            NotificationsView()
        } profile: {
            ProfileView()
        }
        .dfToastHost()
    }
}

The sidebar shells take typed nav data alongside a selection binding and a content @ViewBuilder: DFStandardSidebarShell takes sections: [DFNavSection] (each section holds [DFNavItem]), DFAdaptiveShell takes [DFAdaptiveTab], DFWorkspaceSidebarShell takes [DFWorkspace] plus an icon rail and account switcher. The composition roots (Step 8) wire all of this for you when you're building a known vertical.

Mount .dfToastHost() once on any root view. After that, trigger toasts from anywhere in the tree with DFToastQueue.shared.show(text: "Saved", severity: .success).

Step 4: Ship a Real Sign-In Flow Before Lunch, Not After a Sprint

Auth screens feel simple until you're deep into forgot-password states, social provider buttons, OTP resend timers, and inline validation — a week of work for something that isn't your product's differentiator.

The four Pro auth blocks — DFWelcomeBlock, DFSignInBlock, DFSignUpBlock, DFOTPBlock — each take a Configuration struct with callbacks. Form validation is wired by default using DFFormState from Foundation; set usesFormValidation: false only when you own it yourself.

DFSignInBlock(configuration: .init(
    title: "Sign in to Acme",
    subtitle: "Welcome back",
    socialProviders: [
        .apple  { Task { await AuthService.signInWithApple()  } },
        .google { Task { await AuthService.signInWithGoogle() } },
    ],
    onSubmit: { email, password in
        // onSubmit is not async — wrap async work in a Task
        Task { await AuthService.signIn(email: email, password: password) }
    },
    onForgotPassword: { showForgotPassword() },
    onSignUp: { showSignUp() }
))

The block handles layout, field spacing, validation error display, and social auth button presentation across iOS, macOS, and visionOS. Desktop density is applied automatically from @Environment(\.dfUseDesktopDensity).

OTP verification

Pair DFSignUpBlock with DFOTPBlock for email verification. Each block is independent — you control navigation between them:

DFOTPBlock(configuration: .init(
    title: "Check your email",
    subtitle: registeredEmail,   // shown under the title
    onSubmit: { code in
        // onSubmit is not async — wrap async work in a Task
        Task { await AuthService.verify(otp: code) }
    },
    onResend: {
        Task { await AuthService.resendOTP() }
    }
))

Step 5: One Config Object Instead of a Seven-Screen State Machine You Own

Onboarding flows are where a lot of hand-rolled apps quietly go wrong — the "what screen comes next" logic ends up spread across seven view files with their own local state, and resuming mid-flow after the app is backgrounded is an afterthought nobody tests.

DFOnboardingFlow is the highest-level Pro component: a multi-step flow that covers welcome, sign-up or sign-in, OTP verification, profile setup, permission requests, plan selection, personalisation, and a success screen. It manages its own step state (persisted across launches via UserDefaults) and handles back navigation.

You configure the whole flow via DFOnboardingConfiguration — one struct, no subclassing:

DFOnboardingFlow(configuration: .init(
    appName:         "Acme",
    welcomeTagline:  "Welcome to Acme",
    welcomeHeadline: "The best tool for your team.",
    enableAppleSignIn:  true,
    enableGoogleSignIn: true,

    featureHighlights: [
        .init(icon: "sparkles", title: "AI-Powered",
              description: "Smart suggestions across every workflow."),
        .init(icon: "person.3", title: "Built for Teams",
              description: "Real-time collaboration, no friction."),
    ],

    requestedPermissions: [.notifications],

    showPlanSelection: true,
    planTiers: [
        .init(name: "Free",  price: "$0",   period: "forever",
              features: ["3 projects", "1,000 API calls"], isPopular: false),
        .init(name: "Pro",   price: "$49",  period: "/ month",
              features: ["Unlimited projects", "Priority support"],
              isPopular: true, badge: "Most Popular"),
    ],

    personalisationTags: [
        .init(id: "startup",    label: "Startup"),
        .init(id: "enterprise", label: "Enterprise"),
        .init(id: "freelance",  label: "Freelance"),
    ],

    onSignUp:  { name, email, password in
        // Return Bool: true = success, false = failure (e.g. email taken)
        return await AuthService.signUp(name: name, email: email, password: password)
    },
    onSignIn:  { email, password in
        return await AuthService.signIn(email: email, password: password)
    },
    onOTPVerify:             { code in return await AuthService.verify(otp: code) },
    onOTPResend:             {           await AuthService.resendOTP()         },
    onProfileSave:           { name, avatar in await ProfileService.save(name, avatar) },
    onPermissionRequest:     { perm in  await PermissionService.request(perm) },
    onPlanSelected:          { tier in   BillingService.select(tier)          },
    onPersonalisationComplete: { tags in ProfileService.saveTags(tags)        },
    onComplete:              {           AppState.shared.isOnboarded = true   }
))

That one initialiser configures every step. If the user backgrounds the app mid-onboarding, they resume where they left off.

Step 6: Swift Charts Without the Axis-and-Legend Boilerplate

Swift Charts gives you the primitives, but every dashboard still needs the same surrounding scaffolding — a period picker, a legend, loading and empty states, consistent theme colors per series. That's the part that gets rebuilt per project.

Chart blocks are composables, not screen-locked. Drop them into your own views, not just the Analytics root. They use Swift Charts under the hood and inherit theme colors automatically.

Block	Use for
`DFLineChartBlock`	Trends, time series, cumulative metrics
`DFBarChartBlock`	Category comparison, period-over-period
`DFDonutChartBlock`	Part-to-whole breakdown, proportions
`DFStatCardBlock`	Single metric with delta and trend sparkline

Don't use DFChartPlaceholderBlock in shipping UI. It's a loading/skeleton state only. For loading chart data, pass isLoading: true to the real chart block instead.

// Keyword arguments must appear in the same order as the initializer declares them —
// isLoading: comes right after title:, before data:.
DFLineChartBlock(configuration: .init(
    title: "Active Users",
    isLoading: isFetchingData,
    data: [
        ("Mon", 182), ("Tue", 195), ("Wed", 188),
        ("Thu", 212), ("Fri", 240), ("Sat", 198),
    ],
    periods: DFChartPeriodPreset.allCases,
    selectedPeriod: .sevenDays,
    onPeriodChange: { period in
        // onPeriodChange is not async — wrap async work in a Task
        Task { await loadTrend(for: period) }
    },
    height: isDesktop ? 140 : 220
))

The period toolbar is built in. Your domain period enum conforms to DFChartPeriodRepresentable if you need custom ranges beyond the preset.

Step 7: The Mac-Native-Table-vs-iPhone-Fallback Problem, Solved Once

A data table that feels native on macOS (keyboard navigation, Return to activate a row) and still works on a phone-width screen is two different UIs wearing the same data. Building both, and deciding which one renders where, is a recurring cross-platform tax.

DFDataTable ships in Foundation but it's most useful in Pro-scale apps. On macOS it renders a native Table with keyboard navigation and Return-to-activate. On iPhone it falls back to scrollable header + rows. Use it on regular-width layouts; keep DFList with swipe actions on compact phone screens where that fits better.

@State private var selectedIDs: Set<Contact.ID> = []

private var columns: [DFDataTableColumn<Contact>] {
    [
        DFDataTableColumn(id: "name",    title: "Name")    { $0.name            },
        DFDataTableColumn(id: "company", title: "Company") { $0.company         },
        DFDataTableColumn(id: "status",  title: "Status")  { $0.status.rawValue },
    ]
}

DFDataTable(
    data:          filteredContacts,
    columns:       columns,
    selection:     $selectedIDs,
    selectionMode: .multiple,
    filterQuery:   searchText,
    onRowActivate: { openDetail($0) },
    emptyContent: {
        DFEmptyStateBlock(configuration: .init(
            icon:    "person.crop.circle.badge.questionmark",
            title:   "No contacts found",
            message: "Try a different search or filter."
        ))
    }
)

Step 8: A CRM/PM/Analytics Shell You Delete Code From, Not Build Up To

Starting a new product vertical from a blank ContentView means weeks before it looks like a real app. If you're building a known vertical, Pro ships full composition roots instead: pre-wired screens, navigation, and blocks. Mount the root, replace the fixture data with your models, and you have something that looks like a real product immediately.

Root	What it includes
`DFCRMRootView`	Home, pipeline, contacts table, analytics
`DFPMRootView`	Project board, list, timeline, team roster
`DFAnalyticsRootView`	Overview, events, revenue, users — all with charts
`DFAIChatRootView`	New chat, thread, compare view, settings sheet
`DFEcommerceRootView`	Store home, orders table, products, revenue
`DFSettingsRootView`	Account, security, billing, team, danger zone
`DFSocialAppShell`	Feed, explore, notifications, profile

struct MyRootView: View {
    var body: some View {
        DFCRMRootView()
            .dfToastHost()
    }
}

The .environment(\.dfTheme, .workspace) line from Step 2 isn't needed here — every composition root applies .workspace internally, so it renders themed correctly with no setup at all. The root ships with preview fixtures (CRMPreviewFixtures, etc.) so it renders immediately with realistic data. Replace those fixtures with your own domain types as you go. Keep the layout, the density helpers, and the theme wiring — those are the parts you don't want to rebuild.

Quality gate. Before shipping a screen built on Pro, QUALITY-GATE.md in the repo has 15 review items including platform-native layout, non-happy-path previews, and correct root wiring. The bar is: would this hold up as a standalone app?

Advanced: Validation Wiring You Write Once, Not Per Screen

Every form in an app tends to reinvent its own field-to-validator plumbing — a slightly different isValid computed property each time. Pro auth and settings screens wire DFFormState by default so that plumbing exists once. If you need the same pattern in your own views:

private enum Field {
    static let email    = "email"
    static let password = "password"
}

@State private var form = DFFormState()

// Register fields and validators — e.g. in .task or a setup method:
form.register(field: Field.email,    validators: [DFRequiredValidator(), DFEmailValidator()])
form.register(field: Field.password, validators: [DFRequiredValidator(), DFMinLengthValidator(minLength: 8)])

// In your view body:
DFValidatedTextField("Email", field: Field.email, form: form)

DFSecureField(
    "Password",
    text: form.binding(for: Field.password),
    validationState: form.validationState(for: Field.password)
)

DFButton("Sign in") {
    guard form.validate() else { return }
    // DFButton action is () -> Void — wrap async work in a Task
    Task {
        await submit(
            form.values[Field.email,    default: ""],
            form.values[Field.password, default: ""]
        )
    }
}

Built-in validators: DFRequiredValidator, DFEmailValidator, DFMinLengthValidator, DFMaxLengthValidator, DFRegexValidator. Conform to DFFieldValidator to add your own.

Built for AI Coding Agents

Pro ships the same CLAUDE.md / AGENTS.md / .cursor rule file as Foundation, plus more: a .cursor/skills and .cursor/references library covering Apple's Human Interface Guidelines platform-by-platform, Liquid Glass, Swift Charts patterns, accessibility, and desktop-app archetypes. Point Claude Code, Cursor, or Codex at a repo that depends on DesignFoundationPro and it isn't just told "use DFButton" — it has design-pattern reference material to draw on when it's deciding how a screen should actually look.

That's the difference between an agent that produces a working screen and one that produces a correct-looking, cross-platform screen without a single #if os(macOS) block — because the platform branching already happened inside the shell, the block, or the root it reached for. The practical result: when three different agent sessions build three different features of the same app, they come out looking like one product instead of three.

Where to go from here

DesignFoundationPro is designed to be adopted incrementally — a single block takes about 5 minutes to drop in, a full screen 10 minutes, a composition root 15. You don't need the full vertical to get value from it.

DFPlayground — free macOS app, browse all 29 blocks, 47 screens, and 18 shells with live theming before committing to anything
Official docs — integration guide, theme reference, the Foundation Way philosophy

Issues and feedback on the GitHub repo. If you missed the foundation layer, start with Part 1.

Why I'm Building a Native Mac Command Center for Developers (And Why You Should Care)

Nerd Snipe — Wed, 25 Mar 2026 15:25:41 +0000

Why I'm Building a Native Mac Command Center for Developers (And Why You Should Care)

I've been shipping SaaS products as a solo founder for the past few years. My daily workflow looked like this:

Tab 1: GitHub — check PRs, review code, merge conflicts
Tab 2: Stripe — did anyone pay today? Any chargebacks?
Tab 3: Vercel — is the site down? Why is the build failing?
Tab 4: Sentry — what broke overnight?
Tab 5: Linear — what am I supposed to be working on?
Tab 6–15: Slack, Notion, PostHog, Railway, Firebase, Supabase, Render... you get the idea.

Every morning, I'd open 15+ browser tabs just to answer three questions:

What's broken?
What needs my attention right now?
Is the business still running?

Context-switching hell. And I got tired of it.

So I built Navique — a native macOS command center for developers who are sick of managing their entire stack across 15 browser tabs.

What Is Navique?

It's a native Mac app (SwiftUI, not Electron, not a web wrapper) that consolidates everything you need to run your dev projects:

GitHub: PRs, code reviews, branch status, multi-repo view
Revenue: Stripe MRR, new customers, churn
Deployments: Vercel, Railway, Render, Netlify — all in one place
Errors: Sentry alerts and trends
Analytics: PostHog, Firebase
Project management: Kanban board synced with GitHub issues
AI agents: Local orchestration via bundled Eggspert engine (supports Ollama + 20 cloud LLM providers)

52+ customizable dashboard cards. 14+ integrations. One app.

And here's the kicker: it runs 100% locally. Your GitHub tokens, Stripe keys, and project data never leave your Mac unless you choose a cloud LLM for the AI features.

Why Native Mac? (And Why I Didn't Just Build a Web Dashboard)

I tried every web dashboard. They all felt... off.

Slow to load
Janky animations
No offline mode
Generic design (Bootstrap vibes)
Took 3 seconds just to check if the site was down

I wanted something that felt like a real Mac app:

Glass morphism UI that matches macOS 15
Keyboard shortcuts everywhere (Cmd+K command palette, obviously)
Menubar integration
Offline-capable (local SQLite database)
Fast — opens in under 1 second, dashboard renders instantly

Plus, I like building with Swift. SwiftUI is genuinely great once you get past the learning curve.

The AI agent engine (Eggspert) is built in Rust because I needed async actors and didn't want to deal with Swift concurrency for that part. Rust + tokio gave me a 30 MB binary that handles parallel agent dispatch, tool calling, and streaming responses without breaking a sweat.

The Tech Stack

Main app:

Swift 6.0 + SwiftUI
macOS 15.0+ (Apple Silicon + Intel)
SQLite for local data
WebSocket connections to integrations

Eggspert engine (bundled):

Rust (tokio async runtime)
14-module actor architecture
REST/SSE/WebSocket API on localhost:4200
Supports Ollama (local) + Anthropic, OpenAI, Gemini, Groq, DeepSeek, and 15 more cloud providers

Why this matters: You can run the entire stack offline if you use Ollama. No cloud dependency except for the integrations you choose to connect.

Who Is This For?

Navique is for:

✅ Indie developers shipping SaaS products
✅ Solo founders managing GitHub + Stripe + deployments
✅ Small engineering teams (2–8 people)
✅ Freelance devs juggling multiple client projects
✅ Anyone who knows what an MCP server is and gets excited about it

Navique is NOT for:

❌ Non-technical users looking for a pretty todo list
❌ Enterprise teams with 50+ developers (it's built for small, fast-moving teams)
❌ Windows or Linux users (macOS only, no cross-platform plans)

Why I'm Building This in Public

I'm bootstrapped. No VC funding. No co-founder. Just me, a MacBook Pro, and a lot of coffee.

I'm documenting the entire journey — the technical decisions, the design choices, what worked, what failed, and what I'm learning along the way.

Over the next month, I'll be posting every other day about:

How I built specific features (GitHub integration, AI code review, dashboard cards)
Design decisions (why glass morphism, why keyboard-first)
Integration challenges (dealing with GitHub's API, Stripe webhooks, deployment APIs)
Beta feedback (what testers love, what they hate)
Pricing psychology (why perpetual license instead of subscription)
Launch prep (influencer outreach, Product Hunt strategy)

Why? Because I learn by teaching. And if I'm being honest, I need the accountability. Building solo is lonely — posting publicly keeps me shipping.

Current Status: Beta Recruiting

The core is working. I use it daily for my own projects. Still shipping features and iterating based on feedback. Now I need validation that it's useful to someone other than me.

I'm looking for 10–15 beta testers who:

Actively ship software (SaaS, mobile apps, web apps)
Use macOS as their daily driver
Manage GitHub repos + at least 2–3 other tools (Stripe, deployments, analytics, etc.)
Are willing to share honest feedback (good and bad)

What you get:

Free beta access (no credit card)
Founding user pricing when we launch ($99 instead of $149)
Early access to all features before public launch
Direct line to me via Discord for feedback/bugs

If you're interested: DM me on Twitter @HatchingEggbert or comment below with what tools you currently juggle daily.

What's Next

Over the next 4 weeks:

Week 1: Beta recruitment, onboarding first testers
Week 2: Ship features based on beta feedback
Week 3: Influencer outreach (Founding Creator program)
Week 4: Launch prep (Product Hunt, press kit, landing page)

I'll be posting updates every other day. Follow along if you're curious about building native macOS apps, shipping solo, or just want to see if I can actually pull this off.

Next post: How I built the GitHub integration (and why GitHub's API is both amazing and frustrating).

Follow the journey:

Twitter/X: @HatchingEggbert
Dev.to: @nerd_snipe_dev

Join the beta:
DM me or comment below with what tools you currently use daily. I'll send the download link within 24 hours.

Building in public, one post at a time. 🚀

When Your AI Agent Needs to Phone a Friend: Patterns for Tool Calling

Nerd Snipe — Wed, 18 Mar 2026 21:57:09 +0000

When Your AI Agent Needs to Phone a Friend: Patterns for Tool Calling

You know what's funny about building AI agents? The hardest part isn't the AI. It's figuring out when to let them use tools.

I've been working on a client project where we're building an agent that manages infrastructure deployments. Simple enough, right? The agent needs to check server status, restart services, maybe trigger a build. Standard DevOps stuff.

But here's the thing — giving an AI unrestricted access to production infrastructure is... well, let's just say my client wasn't thrilled when I suggested it. And honestly? They were right.

The Problem Nobody Talks About

Most tutorials show you how to connect tools to your LLM. They don't show you how to prevent your agent from becoming a very expensive chaos machine.

I learned this one the hard way last year. We built an agent that could manage GitHub repositories — create issues, close PRs, comment on discussions. Standard stuff. We deployed it, and within an hour it had commented on 47 issues with variations of "I'll look into this" and then... did nothing. Because we hadn't taught it when NOT to use tools.

The client was understanding. Mostly. After we fixed it.

Pattern One: The Permission Model

Here's what actually works — treat tool access like you'd treat database permissions in a multi-tenant app.

Your agent shouldn't get a binary yes/no on tool access. It needs gradations. Can it READ from this API? Sure. Can it WRITE? Maybe. Can it DELETE? Better ask a human first.

I build this with three tiers:

Green tier: Read-only, low-risk operations. Check status, list resources, fetch data.
Yellow tier: Writes that are reversible. Create a draft, update metadata, add a comment.
Red tier: Destructive operations. Deploy to production, delete resources, send emails to customers.

Green tier? The agent can use these freely. Yellow tier? It needs to explain why first (I actually make it justify the call in its reasoning). Red tier? Always requires human approval.

Pattern Two: The Dry-Run Dance

Something about this approach clicked when I tried it on that infrastructure project...

Before any write operation, we make the agent run a dry-run first. It calls the tool with a flag that says "show me what you WOULD do, but don't actually do it." Then it presents the results to the user: "If I run this command, here's what will happen..."

You'd be surprised how often the agent catches its own mistakes at this stage.

And honestly, users love it. It feels collaborative instead of scary. The agent isn't just doing things TO your infrastructure — it's working WITH you.

Pattern Three: Tool Chains, Not Tool Calls

This pattern showed up on three different projects last month, so I know it's real.

Instead of giving your agent direct access to tools, give it access to tool chains — predefined sequences that include validation steps.

Example: Instead of a "deploy" tool that just... deploys, we created a "safe_deploy" chain:

Run tests
Check current production status
Verify no other deployments in progress
Create a backup
Deploy
Run smoke tests
Rollback if smoke tests fail

The agent calls one tool. But that tool enforces a safe workflow. It can't skip steps. It can't override the safety checks.

This saved us twice already. Once when the agent tried to deploy during another team's maintenance window. Once when it tried to deploy code that hadn't passed CI yet.

Pattern Four: The Audit Trail

Make everything loggable. Not just "the agent called this tool" — log WHY it called it.

We modified our tool-calling interface to require a reasoning parameter. The agent has to explain its logic before it can use the tool. This gets logged.

Why? Because when something goes wrong (and it will), you need to understand the agent's decision-making process. Was it following instructions correctly but with bad data? Was it misunderstanding the task? Did it hallucinate a reason to use the tool?

You can't debug what you can't see.

Here's what I keep telling my team — the reasoning log is more valuable than the action log. Actions tell you what happened. Reasoning tells you why. And "why" is what you need to fix the agent's behavior.

What Actually Matters

Tool calling isn't about connecting APIs to LLMs. That's the easy part. The hard part is building the guardrails, the safety nets, the "are you SURE?" moments.

Your agent should be powerful but not reckless. Capable but not autonomous in the scary sense.

I think the best agent systems feel less like automation and more like collaboration. The agent can do things... but it checks in. It explains. It asks permission when it should.

And yeah — sometimes that means sacrificing pure automation for safety. But after watching an agent try to delete a production database because it "thought it was a test environment"? I'm okay with that trade-off.

Where to Start

If you're building agents with tool access:

Start with read-only tools. Get comfortable with those first.
Add writes slowly, one at a time.
Log everything, especially the reasoning.
Build dry-run modes into your tools from day one.
Don't give destructive access without human approval. Just don't.

The goal isn't to make your agent fully autonomous. The goal is to make it a reliable collaborator.

Building AI agents that actually work in production? That's what we do at NerdSnipe. If you're wrestling with tool-calling patterns or just want to talk through your agent architecture, reach out.

The 'AI Can't Do That' Conversation I Keep Having

Nerd Snipe — Mon, 09 Mar 2026 15:08:45 +0000

I had this conversation again last week.

Client calls. Excited. They've seen what ChatGPT can do, read about AI replacing developers, watched their nephew generate a landing page in thirty seconds. They want an AI that can "just handle all the customer support tickets."

Here's the thing — I've been building software for over three decades now, and the gap between what people think AI can do and what it actually delivers in production is... well, it's a problem.

The Demo Effect

Demos are magic. I get it. You type a question, the AI responds perfectly, everyone claps. But production systems don't run on demos. They run on edge cases and angry customers and that one weird data format from 2009 that nobody documented.

I've built a lot of AI systems for clients at this point. Custom agents, tool-using workflows, the whole deal. And honestly? The technology is incredible. But it's not magic. It's software. Which means it breaks in software ways.

What I Actually Tell Clients

When someone comes to me wanting AI to "just do the thing," I ask three questions:

What happens when it's wrong?

Not if. When. Because LLMs hallucinate. They make stuff up. They sound confident while being completely incorrect. If your use case can't tolerate that — and most can't — you need guardrails. Human review. Fallback systems. Which means it's not "just AI" anymore.

Can you describe the edge cases?

Here's what I keep telling my team: the easy stuff works out of the box now. It's the weird stuff that kills you. The customer who types in emoji. The support ticket that's actually three questions disguised as one. The edge case nobody thought about until 3am on a Saturday.

After 30 years of writing code, I still get surprised by how users actually use software. AI doesn't make that go away. It just moves the complexity around.

What's your ground truth?

AI works best when you can verify the output. Search queries? Great — you can show sources. Code generation? Amazing — you can run tests. Customer support? Trickier. How do you know if the response was actually helpful? If it solved the real problem? If it didn't make the customer angrier?

You need measurement. Logging. Feedback loops. The boring infrastructure stuff that makes everything actually work.

The Real Win

But here's where it gets interesting.

When you scope it right — when you accept what AI actually is instead of what the hype says it should be — you can build some genuinely useful stuff. I've got clients running AI systems that work. Really work. In production. Making money.

The trick? They're not trying to replace humans entirely. They're augmenting workflows. Handling the repetitive stuff. Surfacing insights. Doing the first pass so humans can focus on the complex cases.

Something about this approach clicked when I tried it on a client project last month. They wanted AI to "write all the documentation." What we actually built: an AI that drafts documentation based on code changes, which then gets reviewed and edited by their team. 80% time savings. Zero hallucinated API endpoints in the final docs.

That's the pattern. AI does the grunt work. Humans do the judgment calls.

The Uncomfortable Truth

Most of what people want AI to do... we could already do with traditional software. We just didn't want to write all the rules by hand. AI lets us skip that part — the model learns the patterns instead of us coding them.

Which is incredible! I'm not downplaying it. But it's also why the same engineering principles still apply. You still need error handling. Monitoring. Testing. Graceful degradation. All the stuff that makes software reliable.

The AI part might be new. The rest? Same problems. Different tools.

So What Do I Actually Build?

These days, most of my AI work falls into a few categories:

Classification and routing — AI reads the input, figures out what kind of request it is, routes it to the right place. Super reliable because the output space is constrained.
Draft generation — AI creates the first version, human refines it. Works for emails, reports, code, documentation.
Structured extraction — Pull specific fields from messy input. Way better than regex. Still needs validation.
Search and retrieval — Semantic search is genuinely game-changing. Actually finds relevant stuff even when the keywords don't match.

Notice a pattern? Limited scope. Clear success criteria. Human in the loop when it matters.

The Conversation I Want to Have

Instead of "Can AI do this?" I'd rather talk about:

What are you doing manually that's driving you crazy?
Where are you spending time on repetitive work?
What would get 10x easier with better search or better summarization?

Then we can figure out if AI is the right tool. Sometimes it is. Sometimes a spreadsheet and a Python script would work better.

After all these years, I still believe in using the right tool for the job. AI is a powerful tool. It's not the only tool.

Want to talk about what AI could actually do for your project? Not the hype version — the real version that ships and works and makes your life easier. Hit me up at NerdSnipe.cc and let's figure it out together.

The AI Feature Nobody Asked For (And Why I Built It Anyway)

Nerd Snipe — Sat, 07 Mar 2026 23:23:44 +0000

The AI Feature Nobody Asked For (And Why I Built It Anyway)

Here's a thing I've learned after three decades writing code: clients don't always know what they need until they see it working.

Last month, I shipped an AI feature for a client that wasn't in the original spec. Not even close. They wanted a basic chat interface for their support docs — pretty straightforward, right? Feed the LLM their documentation, let customers ask questions, call it a day. Standard RAG pattern. We've all built a dozen of these by now.

But something about this one bugged me.

The Problem They Didn't Mention

Their docs were... fine. Technically accurate. But they'd been written over five years by different people, and you could feel it. Tone shifted. Examples got stale. Some sections were way too detailed while others basically said "figure it out yourself."

I'm watching the LLM try to answer questions, and it's pulling from three different docs that contradict each other. The AI's doing its best to synthesize, but honestly? Garbage in, garbage out.

After 30 years of writing code, I still get surprised by how often the real problem isn't the one you're paid to solve.

What I Built Instead

So I added a layer they didn't ask for — a documentation health monitor. Every time the RAG system pulls a chunk to answer a question, it also tracks:

How often that chunk gets used
Whether users ask follow-up questions (sign of confusion)
If multiple contradicting chunks get pulled together
Gaps where users ask questions but no good docs exist

Then I built a simple dashboard showing them where their docs were actually failing. Heat maps. Conflict reports. The works.

Took me maybe two extra days. Didn't charge for it.

The Client's Reaction

You know that moment when someone sees something they didn't know they needed? That happened.

They've now got a backlog of doc improvements driven by actual user behavior, not guesses. Their support chat works better because they're fixing the source material. And honestly — this is the part that clicked for me — the AI stopped being a band-aid over bad docs and started being a lens that showed them where to improve.

Here's what I keep telling my team: AI features shouldn't just answer questions. They should surface the questions you should've been asking.

The Engineering Part

Technically, this wasn't rocket science. I'm tracking:

# Simplified version
def track_retrieval(query, chunks, user_satisfaction):
    for chunk in chunks:
        analytics.log({
            'doc_id': chunk.source_id,
            'query': query,
            'rank': chunk.rank,
            'follow_up_needed': user_satisfaction < 0.7,
            'timestamp': now()
        })

    # Check for conflicts
    if has_contradicting_chunks(chunks):
        alert_doc_team(chunks)

Basic analytics. The magic isn't in the code — it's in what you choose to measure.

I've been building with LLMs for a few years now, and the pattern I keep seeing: the most valuable features aren't the AI outputs. They're the insights you get from watching the AI work.

What This Means for Your Projects

If you're integrating AI into an existing workflow, ask yourself: what could the AI tell you about the system it's plugging into?

RAG over messy data? Track where the conflicts are.
Code generation? Log what patterns devs accept vs. reject.
Content recommendations? Watch what people skip.

The AI's already doing the work. You're just not capturing the metadata.

And here's the thing — clients love this stuff. They hired you to build a chat interface, but you're delivering strategic insights about their business. That's the kind of value that turns one-off projects into long-term relationships.

One Last Thing

You might be thinking: "But won't this add scope creep? Extra maintenance? Technical debt?"

Maybe. Sort of. But I'd rather ship something that actually solves the underlying problem than just tick off the requirements. After three decades, I'm done building exactly what was asked for if I can see it won't work.

Your mileage may vary. But I sleep better knowing I built something useful.

Have you ever shipped an AI feature that solved a problem the client didn't know they had? I'd love to hear about it in the comments.

DEV Community: Nerd Snipe

Part 5 — Deals, pricing, and a real board

Part 5 — Deals, pricing, and a real board

What we're adding

1. The Deal model

2. A quote screen — DFPriceView, DFQuantityStepper, DFPriceSummaryView

3. A deals board with DFGrid

4. A "hot leads" rail with DFCarousel

What you built

Coming in Part 6

What Pro already has here

Part 6 — Nudges, prompts, and knowing when to buy

Part 6 — Nudges, prompts, and knowing when to buy

What we're adding

1. DFBanner, used correctly

2. DFEmptyState's secondary action, used correctly

3. What you actually built, vs. what Pro ships

4. So — is it time to buy?

What you built, across the whole series

Part 4 — Tags, ratings, and richer rows

Part 4 — Tags, ratings, and richer rows

What we're adding

1. Tag your contacts with DFChip

2. Score the relationship with DFRatingView

3. Swap DFListRow for DFEntityRow

4. A "starred contacts" grid with DFEntityCard

What you built

Coming in Part 5

Free tier vs. Pro, so far

Part 3 — Custom themes, multi-window, and polish

Part 3 — Custom themes, multi-window, and polish

What we're adding

1. Own your theme

2. Multi-window on macOS

3. Custom validators

4. Tabular data — DFTable and DFDataGrid

5. Ambient UI — alerts, popovers, tooltips

6. Accessibility pass

What you built

The series arc

The Pro pitch, in full

Part 2 — Search, palette, and settings

Part 2 — Search, palette, and settings

What we're adding

1. Shell: sidebar on wide, tab bar on narrow

2. Search on the list

3. ⌘K command palette

4. Honest loading with skeletons

5. Settings screen

6. Bend the theme on one screen only

What you built

Coming in Part 3

Skip the shell work with Pro

Build a Contacts app in 20 minutes with DesignFoundation

Build a Contacts app in 20 minutes with DesignFoundation

Why DesignFoundation

1. Install

2. Model

3. The list screen

4. The detail screen

5. The add-contact form (with validation)

6. Wire it up

What you built

Where this goes next

Skip the runway with Pro

Stop Rebuilding the Same SwiftUI Components: A Guide to DesignFoundation

What We're Building

Installation

Via Xcode

Via Package.swift

Step 1: One Line Instead of a ThemeManager Singleton

Step 2: Never Hand-Roll a Button Style Again

Button styles

Step 3: Stop Reinventing Inline Field Errors

Step 4: Consistent Elevation Without Duplicating Shadow Values

Step 5: Toasts and Skeletons Without a State Machine

Toast notifications

Loading states

Progress

Step 6: Rebrand Without a Find-and-Replace

2. A quote screen — `DFPriceView`, `DFQuantityStepper`, `DFPriceSummaryView`

3. A deals board with `DFGrid`

4. A "hot leads" rail with `DFCarousel`

1. `DFBanner`, used correctly

2. `DFEmptyState`'s secondary action, used correctly

1. Tag your contacts with `DFChip`

2. Score the relationship with `DFRatingView`

3. Swap `DFListRow` for `DFEntityRow`

4. A "starred contacts" grid with `DFEntityCard`

4. Tabular data — `DFTable` and `DFDataGrid`