Installation

How the design system is organized and how to add it to your project.

Add swiftui-flx to this project. It's a set of SwiftUI components that live in the app's own source, installed with the shadcn CLI.

Components I want: Button, Card, Text Field

1. Read https://swiftui.flexnative.com/llms.txt and follow the docs it links to. If the app already has screens and its own styles, follow https://swiftui.flexnative.com/docs/existing-projects.md instead.
2. Look at the project first: the platforms it targets (iOS, iPadOS, macOS), the folder Xcode compiles, whether the project was created before Xcode 16, and whether shared code lives in Swift packages.
3. Add the foundation, then the components above. Use the ios- items for iOS and iPadOS, the mac- items for macOS, and both for an app that runs on both.
4. If Node isn't available, copy the files by hand from each component's page.
5. Build the app for every platform it targets and fix any errors.
6. Tell me what you added and show a short example of one component in use.

Use the FLX tokens and theme instead of hardcoded colors, spacing or fonts. Don't edit project.pbxproj by hand: if files need adding to the target, tell me how to do it in Xcode.

Prefer to do it yourself? The steps below use the CLI, or copy the files by hand.

Requirements

• iOS 16.4 or later, or macOS 13.3 or later.
• For the CLI: Node.js and a project created with Xcode 16 or later.

How it's organized

Every component pulls its values from a DesignSystem folder that lives in your own project, laid out like this:

DesignSystem├── Tokens│ ├── FLXSpacing│ ├── FLXRadius│ ├── FLXBorderWidth│ ├── FLXOpacity│ ├── FLXTypography│ └── FLXColors├── Theme│ ├── Color+Dynamic│ ├── FLXTheme│ ├── FLXThemeEnvironment│ └── Presets│ ├── FLXTheme+Default│ └── FLXTheme+Sienna (optional)└── Components

Tokens and Theme are the foundation every component needs. FLXTheme+Sienna is optional, see Presets. Components is where the pieces you grab from the components page end up.

Where to run the CLI

Run CLI commands from your app's source folder, the one Xcode compiles, or point to it with --cwd:

MyApp├── MyApp.xcodeproj└── MyApp ← run here, or pass --cwd MyApp

From the folder that holds MyApp.xcodeproj, the files land outside your target and won't compile.

• Projects created before Xcode 16 list their files one by one. After the CLI adds files, add them to your target in Xcode with File > Add Files to "MyApp".
• Extensions, such as a widget, need the files in their target too. Or keep DesignSystem in a Swift package and import it from both.
• Your changes are safe. If a file you edited already exists, the CLI asks before overwriting it. Answer No to keep your version.

Add the foundation

Add it once, before any component.

pnpm dlx shadcn@latest add https://swiftui.flexnative.com/r/foundation.json

That's all the setup. Components use FLXTheme.default automatically, so there's nothing to configure. Grab any component from the components page and it's ready to use.

Use it in your views

Use the tokens for spacing and fonts, and read colors from the theme:

struct ProjectRow: View {    @Environment(\.flxTheme) private var theme    var body: some View {        Text("Q3 roadmap")            .flxFont(.headline)            .foregroundStyle(theme.colors.foreground)            .padding(FLXSpacing.lg)            .background(theme.colors.card)    }}

.flxFont(_:) scales with Dynamic Type, and so do control heights. Titles work like native SwiftUI: a string literal such as FLXButton("Save") is a LocalizedStringKey and gets translated, a String Catalog symbol such as FLXButton(.save) works too, and a String variable is shown as is.

To use a different theme, see Presets.