SwiftUI
packages/ui-swiftui is the native SwiftUI implementation of KinetixUI — the
iOS counterpart to the Jetpack Compose library.
Kinetix* views for 90 of the
109 React catalogue entries — the full React component
surface bar the 19 deliberate non-ports, built in batches on a macOS swift build CI path;
each is a native SwiftUI implementation of the same component contract as its
packages/ui/src/components/*.tsx counterpart, with a doc comment stating
anything not carried over.
It's a standalone SwiftPM package inside this monorepo, not a
pnpm/npm workspace package — there's no package.json, so it's invisible
to pnpm install / Turborepo. It lives here for proximity to the token
source it's built from.
Not on the SwiftPM registry. Consume it from a repo checkout with
.package(path: "…/packages/ui-swiftui") — the same "own the code"
model as the web CLI and the Compose library. A publication workflow
(publish-swiftui.yml, which mirrors the package to its own repository for
tagged releases) exists but has not been used for a real release.
- Package
KinetixUI· stable package- Distribution
- Not on Swift Package Manager yet: build it from a repository checkout pinned to a commit.
- Catalogue
- 90 of 109 catalogue entries. Browse components
- Not implemented
- 19 entries, each with its reason on platform coverage.
- Verification
- Catalogue verified to experimental (the weakest component sets it). Components with test evidence: Interaction not yet verified · Accessibility not yet verified · RTL not yet verified · Large text not yet verified. CI:
native-swiftui.yml. - Tokens
- Swift enums: colors (light + dark), type styles, spacing, radius, motion How tokens reach SwiftUI
- Start
- Set up SwiftUI
What differs from the React library#
- SwiftUI views, written natively. State is caller-owned through bindings, and overlays such as dialogs,
sheets and toasts are placed in an
.overlayor a top-levelZStackand driven by anisPresentedbinding, rather than managed by a provider the way Radix does on the web. - System controls where they are strong. Slider, date picker, calendar, scroll area, carousel and chart wrap the SwiftUI control or the Charts framework, so they keep the system look. The calendar picks one date; there is no range selection.
- Its own token set. The library reads a SwiftUI
Colorset generated for it, with real dark values, not the UIKitUIColoroutput (see Tokens below). - SF Symbols replace the web's icon set.
- Distribution and evidence. It is source you add from a pinned checkout, and the only compiler feedback
in CI is
swift buildon macOS. The evidence counts in the summary above say how much of the catalogue has tests beyond that.
A first adoption path#
- Pin a commit and add the package from a checkout.
- Build the first screen inside
KinetixTheme. - Apply your own colours with a custom theme.
- Read Not ported and Known gaps for the components your screens need before you plan around them.
Setup#
Package.swift declares one library target, KinetixUI, for
.iOS(.v16) / .macOS(.v13) (the floor is 16 / 13 because
KinetixButton uses the View-level .tracking text modifier). It uses
swift-tools-version: 6.0, so it needs Swift 6, which means Xcode 16 or newer.
Add the package from a pinned checkout#
There is no released version to depend on, so pin a commit instead. SwiftPM reads
Package.swift from the root of a git repository and this one keeps it in
packages/ui-swiftui, so .package(url:) pointed at this repository does not
resolve. Add the repository as a submodule and check out the commit you want:
git submodule add https://github.com/zedalleys/kinetixui.git Vendor/kinetixui
git -C Vendor/kinetixui checkout <commit-sha>
git add .gitmodules Vendor/kinetixui
git commit -m "Add KinetixUI at <commit-sha>"The commit records .gitmodules and the pinned commit (the submodule's gitlink) in
your repository. Anyone who clones it, CI included, gets exactly that commit with
git submodule update --init.
In an Xcode app project, choose File › Add Package Dependencies… › Add Local…,
select Vendor/kinetixui/packages/ui-swiftui, and add the KinetixUI library to
your app target. In a Swift package, depend on the local path:
// Package.swift
dependencies: [
.package(path: "Vendor/kinetixui/packages/ui-swiftui"),
],
targets: [
.target(name: "App", dependencies: [
.product(name: "KinetixUI", package: "ui-swiftui"),
]),
]Your repository now records exactly which commit you build against. To update, read what changed for this package, then move the pin:
git -C Vendor/kinetixui fetch
git -C Vendor/kinetixui log --oneline <commit-sha>..origin/main -- packages/ui-swiftui
git -C Vendor/kinetixui checkout <newer-commit-sha>
git add Vendor/kinetixui
git commit -m "Update KinetixUI to <newer-commit-sha>"The last two lines record the new pin in your repository; without them a fresh clone still builds the old commit.
First screen#
Wrap a screen — or a #Preview — in KinetixTheme so every Kinetix*
view resolves to the right light/dark token set:
import KinetixUI
import SwiftUI
struct ContentView: View {
@State private var enabled = true
var body: some View {
KinetixTheme {
// KinetixTheme picks light/dark off the system colorScheme,
// the same as the web "system" mode.
VStack(spacing: 12) {
KinetixButton(action: {}) { Text("Get started") }
KinetixButton(variant: .outline, size: .sm, action: {}) { Text("Cancel") }
KinetixButton(variant: .destructive, action: {}) { Text("Delete") }
.disabled(!enabled)
}
.padding(16)
}
}
}Show ContentView from your app's WindowGroup and run it. You should see a
Get started button, a smaller outlined Cancel button and a destructive
Delete button, in light or dark to match the system appearance.
CI compiles this sample as written: node scripts/adoption/swiftui-consumer.mjs puts the Package.swift lines
above and ContentView into a fresh Swift package that depends on this one by path, shows it from a WindowGroup,
and runs swift build on macOS. That proves it compiles, not how it looks; nothing runs it on a device or simulator.
Once that works
- Apply your own colours without forking components.
- Browse the components that ship on SwiftUI; each page shows its SwiftUI code and how it is verified.
- Assemble a screen from blocks with their SwiftUI code.
- Before you plan around a component, read Known gaps.
@Environment(\.kinetixColors) exposes the active KinetixColors set if
you need a token directly.
A custom theme#
KinetixTheme takes your own colour sets and still switches on
colorScheme:
KinetixTheme(light: AcmeTheme.light, dark: AcmeTheme.dark) {
KinetixButton(action: {}) { Text("Save") }
}You can write that pair by hand, or export one from a Create design:
npx @kinetixui/cli preset swiftui <KX1_…> -n AcmeTheme -o Sources/AcmeTheme.swiftReplace the value in angle brackets before running this.
That writes a public enum with a light and a dark KinetixColors,
built from the same resolved theme the workspace exports —
see the CLI reference.
Or skip the terminal: Create's Export panel has a SwiftUI target that generates the same file in the browser, and shows the command above beside it. The preview there is web — it renders the React components — so what changes when you select SwiftUI is the generated file, not the picture.
Colours, and now corners and shadows too. KinetixColors used to be the
whole themeable surface: corner radius and elevation were literals inside each
view (RoundedRectangle(cornerRadius: 16)), so a design could not move them.
The package ships two more sets beside it, and the components read them:
KinetixTheme(
light: AcmeTheme.light,
dark: AcmeTheme.dark,
radii: KinetixRadii(field: 2, control: 6, container: 10, surface: 14),
elevations: .flat
) {
ContentView()
}KinetixRadii is four corners named for what the corner does — field (inputs,
tags), control (buttons, tabs), container (alerts, panels), surface (cards,
dialogs, sheets) — plus none and full. KinetixElevations is the sm / md
/ lg / xl ladder, each step an ordered list of shadow layers, the same shape
Flutter's KinetixShadow uses. Both default to the shipped tokens, so
KinetixTheme { … } looks exactly as it did.
preset swiftui exports all three. A Create design arrives as colours, radii
and elevation together:
KinetixTheme(
light: AcmeTheme.light,
dark: AcmeTheme.dark,
radii: AcmeTheme.radii,
elevations: AcmeTheme.elevations
) {
ContentView()
}A value the design did not change — a colour, or a whole ladder — is written as a reference to the shipped token rather than a copy of today's number, so it keeps following the library. A design that changes nothing exports a file of pure references.
Two limits worth knowing. SwiftUI's .shadow has no spread, and the shared
token ladder uses it on lg, so a SwiftUI lg renders slightly larger than the
web's — the built-in ladder is mapped the same way, so a generated theme and the
default differ from the web identically. And eight corners across five components
(AppBar, ColorPicker, FileUpload, InputOtp, Sidebar) sit at 6, which is not a
step on the 4 / 8 / 12 / 16 ladder; they stay literal rather than being moved
silently.
Tokens: SwiftUI Color, not UIColor#
The pre-existing iOS token output
(packages/tokens/dist/ios/KinetixColors.swift, Theme.swift) is
UIColor-based. UIColor is UIKit-only — it doesn't compile on macOS,
so a package that must swift build on a macOS CI runner can't consume
it. The token engine emits a parallel SwiftUI-Color semantic set
for this library (KinetixColorsSwiftUI light /
KinetixColorsSwiftUIDark dark), from the ios-swiftui-theme platform
block in style-dictionary/sd.config.mjs. The UIColor output is
untouched — this is purely additive, the same way Android has Color.kt
alongside Theme.kt / Theme.dark.kt.
Unlike every other native platform, this set runs on both Style
Dictionary passes — a KinetixTheme needs real light and dark values.
The vendored copies under Sources/KinetixUI/ are generated. After any
token change:
pnpm build:tokens && pnpm vendor:swiftuiWhat's covered#
KinetixTheme plus Kinetix* views for everything in
packages/ui/src/components except the 19 non-ports below.
- Controls —
KinetixButton(buttonVariantsCVA 1:1: variant × size × corners),KinetixCheckbox,KinetixSwitch,KinetixToggle/KinetixToggleGroup,KinetixSlider,KinetixRadioGroup/KinetixRadioButton,KinetixRating,KinetixFab,KinetixStepper. - Inputs —
KinetixInput(corners enum, trailing slot),KinetixTextarea,KinetixNumberInput,KinetixPasswordInput,KinetixInputOtp,KinetixInputGroupfamily,KinetixSelect,KinetixDatePicker,KinetixCalendar,KinetixFileUpload,KinetixField(+Label/Description/Message). - Display —
KinetixBadge,KinetixTag,KinetixLabel,KinetixKbd(+KbdGroup),KinetixSeparator,KinetixSkeleton,KinetixSpinner,KinetixProgress,KinetixCircularProgress,KinetixAvatar(+Fallback),KinetixImage,KinetixCardfamily,KinetixAlertfamily,KinetixInform,KinetixQuote,KinetixMetric,KinetixCodeBlock,KinetixChart,KinetixAudioPlayer,KinetixAspectRatio,KinetixEmptyfamily. - Data —
KinetixTablefamily,KinetixDataTable(sort + pagination),KinetixCarousel. - Navigation & disclosure —
KinetixAccordionfamily,KinetixCollapsible,KinetixTabsList/Trigger/Content,KinetixList/KinetixListItem,KinetixScrollArea,KinetixResizablePanels,KinetixSidebar/Item,KinetixBreadcrumbfamily,KinetixPaginationfamily,KinetixTableOfContents,KinetixNavigationBar,KinetixAppBar/Link,KinetixTabBar/Item,KinetixFooterfamily. - Overlays & menus —
KinetixDialogfamily,KinetixAlertDialog,KinetixModal,KinetixSheet,KinetixDrawer,KinetixPopover,KinetixHoverCard,KinetixTooltip,KinetixDropdownMenu(+ sharedKinetixMenuItem/Separator/Label),KinetixContextMenu,KinetixMenubar/Menu,KinetixCommandDialogfamily,KinetixToaster.
Selection / expansion / presentation state is caller-owned throughout (a
@Binding or a plain isExpanded / isSelected + action) — the same
division the Compose port uses, since there's no SwiftUI context to
thread a shared value through the way Radix does. Overlay views
(KinetixDialog, KinetixSheet, KinetixSidebar, KinetixToaster, …)
are placed in an .overlay { } or a top-level ZStack and driven by an
isPresented / isOpen binding.
Not ported (deliberate)#
Form—KinetixField(+Label/Description/Message) is the equivalent; there's noreact-hook-form-shaped context to wrap. Same call as the Compose port.NavigationMenu— a hover-triggered desktop mega-menu with no touch idiom.Combobox— a recipe (Popover + Command) on the web, not a standalone component; composeKinetixPopover+ a filtered list, or reach forKinetixSelect.DirectionProvider— the web needs a provider to thread direction through Radix; this platform already carries layout direction in the framework itself, so there is nothing to wrap.NativeSelect— wraps the browser's own<select>, a web-only escape hatch fromSelect's custom popover;KinetixSelectalready wraps SwiftUI's ownMenu.AvatarGroup— re-wraps its children (React.Children.toArray), not an idiomatic SwiftUI pattern; compose anHStackofKinetixAvatars with negative spacing (spacing: -8).Tour— targets an arbitrary already-rendered element by CSS selector; SwiftUI has no equivalent live-tree query. Compose a sequence ofKinetixPopoversteps, each anchored to the view it explains.KanbanBoard— built on@dnd-kit's accessible multi-container drag-and-drop; hand-rolling that from scratch is a much bigger lift than porting the component. Use.draggable/.dropDestinationdirectly for the specific board.ResultState— a React-first beta (business capability roadmap, Phase 1); a native port is an open roadmap decision, not a refusal. ComposeKinetixEmptywith a status icon, title and actions.ReferenceCode— React-first beta, same decision. ComposeText(…).textSelection(.enabled)with aKinetixButtonthat copies.PriceBreakdown— React-first beta, same decision. ComposeKinetixDescriptionListrows with the total after aKinetixSeparator.PassCard— React-first beta, same decision. ComposeKinetixCard,KinetixDescriptionListand the supplied code as anImage.AmountDisplay— a React-first beta (business capability roadmap, Phase 2); same open decision. Compose a tabular-figureTextwith the sign in the string and a full accessibility label.GuestPicker— React-first beta, same decision. Compose oneKinetixNumberInputper category, named after it, in aKinetixPopover.CountrySelect— React-first beta, same decision. ComposeKinetixSelectover your own country list.PhoneInput— React-first beta, same decision. Compose a calling-codeKinetixSelectand aKinetixInputwith.keyboardType(.phonePad)in a left-to-right row.DateRangeInput— React-first beta, same decision. Compose two date-onlyDatePickers, the end bounded by the start.TimeSlotPicker— React-first beta, same decision. ComposeKinetixToggletiles in an adaptiveLazyVGrid.AddressFields— React-first beta, same decision. Compose aKinetixFieldper address field with the platform's autofill hints.
Known gaps#
- Not published yet. The publication workflow has never run for real.
swift buildonmacos-latest(against the.macOS(.v13)target, no simulator) is the sole compiler feedback on every push that touchespackages/ui-swiftui,tokens/, orstyle-dictionary/. - Platform controls are reused where they're strong —
KinetixSlider/KinetixDatePicker/KinetixCalendar/KinetixScrollArea/KinetixCarousel/KinetixChartwrap the SwiftUI control (or theChartsframework), so those use the system look, not a hand-built one (a documented gap, same call as the Compose Material3 wraps).KinetixCalendaris single-date only, no range select. - Type scale is wired.
Font.kinetixBody/.kinetixLabelMd/.kinetixTitleMd… (TypeScale.swift, from the vendoredKinetixType.swift) back the components'.font(…);KinetixTextStyleKinetixType.<style>are public for your own text. Letter-spacing is still a sibling.tracking(…); a single style-and-tracking modifier is a possible follow-up.
- Icons use SF Symbols (
checkmark,chevron.down,star.fill, …) rather than the web's lucide set — the closest system equivalent.