Apple platformsSwiftUI package

Lumen for Apple platforms

Share a Lumen design language across iPhone, iPad, Mac, Apple TV, and Apple Watch while keeping SwiftUI behavior native.

Start building Browse components

PackageLumenUI

LumenUI installs through Swift Package Manager; no npm package, CocoaPod, or copied source is required. Add the repository URL, pin exact version 2.1.0 for reproducible builds, and attach the LumenUI product to your application target.

Get started

Install and configure

Before you begin

What you need

macOS with Xcode 16 or newer and the SDK for the Apple platform you target
An existing SwiftUI application targeting a supported Apple platform
An Apple Developer account only for physical-device or TestFlight distribution

Add the Swift package
In Xcode, choose File → Add Package Dependencies, paste the repository URL, and pin exact version 2.1.0 for reproducible builds. Use a compatible-version rule only when the application accepts compatible updates.
Link LumenUI to the target
Select the LumenUI library product and attach it to the application target that renders your SwiftUI views.
Import, theme, and run
Import LumenUI, wrap the root surface in lumenTheme, select a simulator, and press Run.

# Xcode → File → Add Package Dependencies…
https://github.com/santi020k/lumen

# Dependency Rule
Exact Version: 2.1.0

# Add this product to your application target
LumenUI

// Package.swift
dependencies: [
    .package(
        url: "https://github.com/santi020k/lumen",
        exact: "2.1.0"
    )
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "LumenUI", package: "lumen")
        ]
    )
]

import LumenUI

@main
struct ExampleApp: App {
    var body: some Scene {
        WindowGroup {
            LumenSurface {
                LumenText("Welcome", variant: .title)
                LumenButton("Continue", action: continueFlow)
            }
            .lumenTheme(.light)
        }
    }
}

Try every component

Run the Apple playground

The Apple gallery runs as an iOS app from Xcode and as a macOS Swift Package executable. Choose an iPhone simulator and press Run; signing is not required for the simulator.

Available on the App Store

Take the Lumen Playground with you

Version 1.0 is available for iPhone, iPad, and Mac. The same listing installs the native gallery for the Apple device you are using.

View on the App Store

git clone https://github.com/santi020k/lumen.git
cd lumen
open apps/playground-apple/LumenApplePlayground.xcodeproj

pnpm playground:apple:build
swift run --package-path apps/playground-apple LumenApplePlayground

Installing locally versus publishing

You can run the gallery locally before configuring any store account.

Simulator builds do not require an Apple Developer account or signing.
For a physical device or TestFlight, select your team under Signing & Capabilities.
Archive the playground in Xcode only after choosing the final bundle identifier and signing team.

Appearance

Choose and change the theme

Apply one built-in Lumen theme to the root content view. The modifier shares semantic colors through the SwiftUI environment and sets the matching preferred color scheme for native controls, sheets, and system surfaces.

WindowGroup {
    AppRoot()
        .lumenTheme(.light)
}

@AppStorage("useDarkAppearance") private var useDarkAppearance = false

var body: some Scene {
    WindowGroup {
        AppRoot()
            .lumenTheme(useDarkAppearance ? .dark : .light)
    }
}

Style with semantic roles

Use Lumen semantic colors through public components instead of styling each control independently. The selected theme also keeps SF Symbols, native controls, and presented views aligned with the same appearance.

Verify both appearances

Preview every supported device family in light and dark appearances.
Check sheets, menus, focus rings, and system controls as well as the main view.
Test Dynamic Type, Increase Contrast, and VoiceOver in both themes.

Continue with AI

Give your coding tool the Lumen workflow

Install the portable skill once, open your application in a compatible coding tool, and name the target platform in the request. The skill reads the native package and documentation before selecting components.

1 · Install the skill

npx skills add santi020k/lumen --skill lumen-ui

npx skills add santi020k/lumen --skill lumen-ui

Follow the installer prompts and select the AI coding tools available on your machine.

2 · Ask for the native target

Use $lumen-ui to build this screen in SwiftUI.
Use the LumenUI Swift package and public SwiftUI components.
Preserve native navigation and state, and include loading, empty, error, Dynamic Type, and VoiceOver behavior.

Use $lumen-ui to build this screen in SwiftUI.
Use the LumenUI Swift package and public SwiftUI components.
Preserve native navigation and state, and include loading, empty, error, Dynamic Type, and VoiceOver behavior.

Review the generated package imports, component states, and platform accessibility behavior.

The Agent Skill and optional MCP server cover web and native adapters. MCP can list the components available for this platform and return installation, setup, API examples, accessibility guidance, and reference source for each documented native component.

Open the complete AI setup guide

Real platform output

Rendered by Apple / SwiftUI

This verified capture comes from the native preview host using the package in this repository. The controls are rendered by Apple, not by HTML.

Lumen component gallery rendered directly by the LumenUI SwiftUI package

Supported surface

Components and capabilities

The shared native tier is complemented by SwiftUI and macOS-specific controls that preserve native navigation, focus, and window behavior.

Sparkline

Line chart

Bar chart

Pie chart

Scatter chart

Heatmap

Range chart

Combo chart

Theme

Text

Surface

Icon

Icon button

Button

Text field

Badge

Divider

Spinner

Card

Alert

Progress

Skeleton

Disclosure

Avatar

Textarea

Field group

Chip

Button group

Toast

Toggle

Settings row

Picker

Slider

Search field

Phone input

Checkbox

Radio group

Segmented control

Tabs

Navigation bar

Empty state

Error state

List row

Banner

Stat

Gauge

Section header

Status bar

Date field

Date range field

Widget text

Widget icon

Widget badge

Widget compact stat

Link

Tab bar minimization

Tab accessory

Shortcut recorder

Symbol picker

Graphic

Backdrop

Illustration

Image

Alert dialog

Sheet

Share button

Wearable action

Wearable progress

Wearable status

Wearable metric

Wearable list row

Open the full component reference

Platform contract

Designed for Apple / SwiftUI

Apple platform coverage

The package supports iOS 16, macOS 13, tvOS 16, visionOS 1, and watchOS 9 or newer.

Adaptive density

Controls automatically use touch-friendly mobile density and compact pointer-friendly Mac density.

SwiftUI conventions

Dynamic Type, SF Symbols, environment values, VoiceOver, and native controls remain first-class.

Move between platform guidance without losing the shared Lumen design language.