Troubleshooting

Troubleshooting

Components show system colors / fonts instead of the design system

You haven't applied the theme. Add .themeKit() at the root of your scene:

WindowGroup { ContentView().themeKit() }

Dark mode looks wrong in tests or previews

Components read their palette from the Theme.shared singleton, not the SwiftUI \.colorScheme environment. Drive it explicitly:

Theme.shared.setColorScheme(dark: true)

In previews, wrap content in .themeKit() so the palette is installed.

swift build fails with "package requires tools version 6.2"

The package targets Swift 6.2. Install/select Xcode 26 (or newer):

sudo xcode-select -s /Applications/Xcode_26.app

Published DocC on Pages loads with no CSS (everything 404s)

The --hosting-base-path is wrong. For a project site (user.github.io/<repo>/) it must equal the repo name:

--hosting-base-path ThemeKit

For a user/custom-domain site, drop the flag entirely.

Montserrat font isn't rendering

The bundled font is loaded via .themeKit(). If you render components without it, type falls back to the system font (by design). Make sure the theme is applied above the views that use .textStyle(_:).

Visual-regression (snapshot) tests are all skipped

They're opt-in. Set RUN_SNAPSHOTS=1 on the test scheme's Test action (shell env vars don't cross into the Simulator). See the project's docs/SNAPSHOT-TESTING.md.

Still stuck? Open an issue — see Contributing.