Skip to main content
AcornKit — the agent-ready SwiftUI starter kit. The only kit your AI coding agent already understands: it ships CLAUDE.md, AGENTS.md, TOKENS.md, and a scaffold skill, so you can tell Claude Code or Cursor “add a settings screen” and it follows the kit’s conventions instead of guessing.

​
What’s in the box

  • AcornCore — the dependency-free engine: design system (AcornTheme + tokens), StoreKit 2 subscriptions, onboarding→paywall→home gate, analytics protocol, account/data-deletion, an auth seam, an AI-chat seam, and composable UI.
  • acorn-ios-template — a runnable app shell that composes AcornCore: 2 onboarding styles, 2 paywall styles, a tabbed home + settings, and an example AI Assistant tab.
  • Optional modules — swap a vendor in one line: AcornCoreRevenueCat, AcornCoreSupabase (auth), AcornCorePostHog (analytics), AcornCoreAI (OpenAI/Claude), AcornCoreFirebase.
  • Agent files + scaffold skill — CLAUDE.md / AGENTS.md / CONTEXT.md / TOKENS.md, a Makefile, SwiftLint + token-lint, and scaffold-ios-app.
  • Real proof — built by the studio behind shipped apps (Focus0, Habit0, OnePushMan, …).

​
Requirements

  • macOS + Xcode 16+, iOS 17+ target. Swift 6.
  • A paid Apple Developer account (to ship; not needed to build/run locally).
  • Optional, only if you use them: a Supabase project (auth), RevenueCat account, an LLM key.

​
1. Scaffold your app

The template ships with {{PLACEHOLDER}} tokens ({{APP_DISPLAY_NAME}}, {{APP_TAGLINE}}, {{APP_SLUG}}, {{BUNDLE_ID}}, {{SIMULATOR_ID}}). Use the scaffold-ios-app skill to stamp a fresh app from the template — it replaces the placeholders and lays out the workspace + feature package. Keep AcornCore beside your app (the package references it at ../../AcornCore).
Prefer your agent? Open the kit in Claude Code / Cursor and ask it to scaffold a new app — the agent files tell it exactly how.

​
2. Make it yours

Everything app-specific lives in one file — AppConfig.swift (the composition root):
  • Brand: override only the colors that differ from the premium-dark default in BrandConfig / BrandColors; set the app name. Read TOKENS.md before touching UI — raw colors/fonts/padding fail make lint.
  • Pick screen styles: AppConfig.onboardingStyle (.valueStack / .story) and paywallStyle (.planList / .singleCTA).
  • Product IDs: set productIDPrefix → <prefix>.{weekly,monthly,yearly,lifetime}.

​
3. Run it

From the app directory (never call xcodebuild directly — use the Makefile):
TaskCommand
Build & run on the simulatormake build
Unit testsmake test
Token + SwiftLintmake lint
Full verification (build/test/screens/a11y)make verify
Print the design-token referencemake tokens
You now have a working onboarding → paywall → home → settings flow with a hard paywall, the design system, and the example Assistant tab — all running.

​
The architecture in 60 seconds

AcornKit’s rule: your app talks to protocols, never to vendors. Each capability is a swappable seam with a dependency-free default and an optional vendor module:
CapabilitySeam (protocol)Default (no deps)Optional swap
SubscriptionsSubscriptionProvidingStoreKitSubscriptionProviderRevenueCatSubscriptionProvider → RevenueCat setup
AuthAuthProvidingAnonymousAuthProvider (guest)SupabaseAuthProvider → Auth setup
AnalyticsAnalyticsProvidingConsoleAnalyticsPostHogAnalytics
AI chatChatProvidingEchoChatProvider / ProxyChatProviderOpenAIChatProvider / AnthropicChatProvider → AI chat setup
Data deletionDataResettingLocalDataResetterFirebaseDataResetter / Composite
Swapping any of them is a one-line change in AppConfig — the screens never change.

​
Add features the agent-ready way

This is the kit’s edge. In Claude Code / Cursor, ask for a feature in plain English — “add a journal feature with a list and a detail screen” — and the agent reads CLAUDE.md / AGENTS.md / TOKENS.md and produces code that uses your tokens, your @Observable pattern, and your folder structure. No re-teaching conventions every time.

​
Ship checklist

1

Brand + product IDs

Set in AppConfig; make lint clean.
2

Subscriptions

StoreKit products in App Store Connect (or swap to RevenueCat — see RevenueCat setup).
3

Auth (if used)

Supabase + Sign in with Apple configured — see Auth setup.
4

AI (if used)

Proxy deployed, key server-side — see AI chat setup.
5

App Store compliance

Privacy policy + Terms in legalLinks; “Delete all data” wired (it’s built in).
6

Verify

make verify passes (build + tests + a11y).

​
Next

Auth setup

Add accounts in 3 steps with Supabase + Sign in with Apple.

RevenueCat in one line

Swap StoreKit for RevenueCat without touching a screen.

Add an AI chat

Stream completions with the key kept server-side.
Design tokens live in TOKENS.md; architecture & conventions in AGENTS.md / CLAUDE.md (shipped in the kit).