Skip to main content

ADR-0001: Target macOS 26 + Apple Silicon, SwiftUI-First with Liquid Glass

Context and Problem Statement​

Stet is a native macOS application whose entire value proposition rests on being beautiful and unmistakably native — a code viewing and direction surface that feels like it shipped from Cupertino. It also needs to run sandboxed Linux containers locally to dispatch AI agents (see ADR-0003).

We must decide the minimum OS and hardware target and the UI framework. These choices are effectively irreversible: they define the aesthetic ceiling, the available system frameworks, and the addressable market from day one.

Decision Drivers​

  • No-compromise native aesthetics. Liquid Glass (macOS 26 Tahoe) is the current Apple design language; it looks right only in apps built SwiftUI-native from day one, using adaptive materials rather than fixed frosted panels.
  • Local container execution. Apple's container / Containerization framework runs Linux containers as lightweight per-container VMs, but requires macOS 26 and Apple silicon.
  • Small team, high iteration speed. Declarative SwiftUI removes large amounts of AppKit delegate/boilerplate; faster iteration matters more than supporting legacy hardware for a greenfield product.
  • Addressable market vs. focus. Supporting Intel and older macOS multiplies testing surface and forces fallbacks that dilute the native story.

Considered Options​

  • Option A: macOS 26 + Apple silicon only; SwiftUI-first.
  • Option B: macOS 26+ but keep Intel alive (mandatory Docker fallback, no in-process Apple containers).
  • Option C: macOS 15 + 26 support; SwiftUI with materials fallbacks.
  • Option D: AppKit-first for maximum control.

Decision Outcome​

Chosen option: Option A — macOS 26 (Tahoe)+ and Apple silicon only, SwiftUI-first with native Liquid Glass, dropping to AppKit via NSViewRepresentable only where a specific surface (the code canvas, ADR-0002) requires it.

This is a deliberate, opinionated floor. It unlocks the two things the product cannot compromise on — Liquid Glass fidelity and in-process local containers — and keeps the team focused on one modern stack.

Consequences​

  • Good, because the app can adopt Liquid Glass natively without fallback code paths, achieving the intended aesthetic ceiling.
  • Good, because Apple's Containerization Swift package (ADR-0003) becomes available, giving license-free, per-container-VM isolation with sub-second starts.
  • Good, because a single Swift 6 / Xcode 26 / SwiftUI target minimizes testing surface and maximizes iteration speed.
  • Bad, because Intel Macs and macOS 15-and-earlier users are excluded entirely.
  • Bad, because betting on a one-year-old design language and a 1.0 container framework carries platform-maturity risk.
  • Neutral, because AppKit remains reachable via representables for the few surfaces (large scrolling code documents) where it is warranted.

Confirmation​

  • Package.swift / project declares macOS(.v26) as the minimum platform and builds only for arm64.
  • The app shell renders with adaptive Liquid Glass materials (verified visually on macOS 26).
  • No code path targets Intel or macOS < 26.

Pros and Cons of the Options​

Option A: macOS 26 + Apple silicon only, SwiftUI-first​

  • Good, native Liquid Glass and in-process Apple containers both available.
  • Good, single modern toolchain; fastest iteration.
  • Bad, narrowest hardware/OS reach.

Option B: macOS 26+ but keep Intel alive​

  • Good, larger addressable market.
  • Bad, Apple silicon-only Containerization forces Docker as a mandatory dependency; loses the native container story on a whole class of machines.
  • Bad, dual container code paths from day one.

Option C: macOS 15 + 26​

  • Good, one more OS version of reach.
  • Bad, no full Liquid Glass; materials fallbacks dilute the aesthetic.
  • Bad, complicates the container story and the design system.

Option D: AppKit-first​

  • Good, maximum control and mature controls.
  • Bad, far more boilerplate; Liquid Glass adoption is awkward; slower iteration.

More Information​

Apple container shipped 1.0 on 2026-06-09 (requires macOS 26 + Apple silicon). SwiftUI is Apple's positioned default for new macOS apps. See ADR-0002 (viewer posture and the AppKit-interop boundary) and ADR-0003 (container runtime).