Skip to content

About

Native design system for SwiftUI & UIKit via Swift Package Manager: tokens, typography, components, assets and runtime multi-tenant theming.

Topics

Resources

Accessibility

Stars

3 stars

Watchers

1 watching

Forks

Repository files navigation

DesignSystemKit

A native design system for SwiftUI and UIKit, distributed with Swift Package Manager. It gives your apps one set of tokens, typography, components and icons. Themes can be switched at runtime for white-label apps, tenant branding and seasonal skins.

No third-party dependencies.

Module What it gives you
DesignSystemCore Semantic colour tokens (light + dark), spacing, radius, border, elevation and motion scales, typography scale, DSTheme, ThemeStore (Combine + NotificationCenter, persistence), tenant ThemeRegistry, ThemeValidator (WCAG contrast), field validation. No UI framework imports.
DesignSystemAssets Bundled Poppins fonts (SIL OFL) with explicit FontRegistry, semantic icon catalog with SF Symbol fallback, localized component strings (English, Spanish, German, Arabic, Hindi) with plurals, locale-aware formatting.
DesignSystemSwiftUI .appTheme(...), @ThemeTokens, Dynamic Type text styles, buttons, text fields, checkbox, radio, toggle, picker, date field, card, badge, chip, divider, banner, progress, dialog, empty state, sheet style, skeleton/shimmer, state modifiers, illustrations, DSHostingController.
DesignSystemUIKit Dynamic UIColors, Dynamic Type UIFonts, theme observation for view controllers, window appearance binding, DSUIButton, DSUITextField, DSUICardView, DSUIBadge, DSUILabel.
DesignSystemPreview A browsable catalog of every token and component, with a live theme switcher. For demo apps; production apps don't need it.

Requirements: iOS 16+, iPadOS 16+, Mac Catalyst 16+, macOS 13+ (Core, Assets and SwiftUI). Xcode 16 or later, Swift 6 toolchain.

Installation

In Xcode, choose File ▸ Add Package Dependencies…, enter the repository URL, and add the products you need. Or in Package.swift:

.package(url: "https://github.com/eeshuu/DesignSystemKit.git", from: "1.0.0"),
// …
.target(name: "App", dependencies: [
    .product(name: "DesignSystemSwiftUI", package: "DesignSystemKit"),
    .product(name: "DesignSystemUIKit", package: "DesignSystemKit"),   // only if you use UIKit
]),

Resources (fonts, icons, translations) come with the package. Nothing has to be copied into your app.

Quick start: SwiftUI

import DesignSystemAssets
import DesignSystemCore
import DesignSystemSwiftUI
import SwiftUI

@main
struct MyApp: App {
    @StateObject private var store = ThemeStore(persistence: UserDefaultsThemePersistence())

    init() {
        FontRegistry.registerBundledFonts()   // explicit: importing a module runs no code
    }

    var body: some Scene {
        WindowGroup {
            ContentView().appTheme(store: store)   // once, at the root
        }
    }
}

struct ContentView: View {
    @ThemeTokens private var ds
    @State private var email = ""

    var body: some View {
        VStack(alignment: .leading, spacing: ds.spacing.lg) {
            DSText("Welcome back", style: .title)
            DSTextField("Email", text: $email, kind: .email,
                        validation: FieldValidator([.email("Enter a valid email")], isOptional: true).validate(email),
                        isRequired: true)
            DSButton("Continue", trailingIcon: .arrowRight, fullWidth: true) { }
        }
        .padding(ds.spacing.xl)
        .background(ds.colors.background)
    }
}

Switch at runtime from anywhere:

store.selectTheme(id: "forest")          // brand theme
store.setAppearance(.dark)               // .system, .light or .dark
store.selectTheme(forTenant: "acme")     // tenant mapping you registered

Quick start: UIKit

import DesignSystemCore
import DesignSystemUIKit

final class ProfileViewController: UIViewController, DSThemeable {
    private let store: ThemeStore
    private var subscription: DSThemeSubscription?
    private let titleLabel = DSUILabel(style: .heading1, text: "Profile")
    private let save = DSUIButton(title: "Save", variant: .primary)

    override func viewDidLoad() {
        super.viewDidLoad()
        // …add subviews…
        subscription = store.observe(self)          // applies now and on every theme change
    }

    func apply(theme: DSTheme) {
        view.backgroundColor = .ds(.background, theme: theme)   // dynamic: follows light/dark
        titleLabel.apply(theme: theme)
        save.apply(theme: theme)
    }
}

// In your scene delegate, so the app's light/dark choice wins over the system setting:
appearanceSubscription = store.bindAppearance(to: window)

Prefer NotificationCenter? Use store.observe(self, delivery: .notificationCenter()), or listen for .dsThemeDidChange yourself.

Mixed apps

  • SwiftUI inside UIKit: DSHostingController(store: store) { MySwiftUIView() } applies the theme for you.
  • UIKit inside SwiftUI: wrap the view controller in UIViewControllerRepresentable, and read the store from @Environment(\.dsThemeStore).

Themes

Four themes are built in: standard, forest, sunset (Poppins, pill buttons, filled fields) and midnight. Make your own in code:

var brand = DSTheme.standard
brand.id = "acme"
brand.name = "Acme"
brand.light[.primary] = "#D9480F"
brand.dark[.primary] = "#FFA94D"
brand.components.buttonShape = .pill
store.apply(brand)      // validated; refused (returns false) if it has errors

Or load a JSON file. Anything the file leaves out comes from the standard theme:

{ "id": "acme", "name": "Acme", "light": { "primary": "#D9480F" }, "components": { "buttonShape": "pill" } }
let theme = try DSTheme.decode(from: data)

See Docs/ThemeAuthoring.md for every field, the precedence rules and contrast validation.

Sample app

Examples/DesignSystemDemo has four tabs:

  • the component catalog;
  • a SwiftUI-only sign-up screen;
  • a UIKit-only profile screen;
  • settings, with theme, appearance and tenant switching.

It also shows mixed navigation in both directions. Open Examples/DesignSystemDemo/DesignSystemDemo.xcodeproj and run.

Testing

swift test                                    # Core, Assets and SwiftUI logic on macOS
xcodebuild test -scheme DesignSystemKit-Package \
  -destination 'platform=iOS Simulator,name=iPhone 15 Pro'     # everything, including UIKit and snapshots

The suites cover:

  • token values;
  • contrast of every built-in palette;
  • theme JSON;
  • theme resolution and persistence;
  • font registration;
  • localization and plurals;
  • Dynamic Type scaling;
  • UIKit observation;
  • snapshots in light and dark.

The sample app's UI tests cover:

  • theme switching;
  • tenants;
  • form validation;
  • accessibility identifiers;
  • mixed navigation;
  • the largest Dynamic Type size.

Documentation

Licence

The code is MIT licensed (see LICENSE). The bundled Poppins fonts are © The Poppins Project Authors, under the SIL Open Font License 1.1 (Sources/DesignSystemAssets/Resources/Fonts/Poppins-OFL.txt). The fonts may be redistributed with your app. They may not be sold on their own. Icons are SF Symbols, usable in apps on Apple platforms under Apple's terms, plus two original vector icons.

About

Native design system for SwiftUI & UIKit via Swift Package Manager: tokens, typography, components, assets and runtime multi-tenant theming.

Topics

Resources

Accessibility

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages