Imported from componentskit/ComponentsKit (AGENTS.md). Install upstream with npx skills add componentskit/ComponentsKit. Copyright stays with the author.

ComponentsKit Agent Guide

Project Overview

ComponentsKit is a Swift Package for iOS 15+ that provides reusable UIKit and SwiftUI components for building app interfaces faster. The package product is ComponentsKit, implemented in Sources/ComponentsKit, with an example demos app under Examples/DemosApp.

The library uses a consistent component model:

• *VM structs define configurable appearance, state, and content.
• SU* types are SwiftUI views.
• UK* types are UIKit views or view controllers.
• UIKit components usually conform to UKComponent and update when their model changes.
• Shared styling comes from Theme.current, Palette, Layout, ComponentColor, UniversalColor, UniversalImage, and common size/style enums in Sources/ComponentsKit/Shared.

Repository Layout

• Package.swift: Swift Package manifest for the ComponentsKit library.
• Sources/ComponentsKit/Components: Component implementations.
• Sources/ComponentsKit/Shared: Shared protocols, colors, images, fonts, and reusable value types.
• Sources/ComponentsKit/Theme: Global theme, palette, and layout definitions.
• Sources/ComponentsKit/Helpers: UIKit, SwiftUI, and Swift helpers.
• Sources/ComponentsKit/Resources: Package resources and privacy manifest.
• Examples/DemosApp: iOS demo app with previews for each component.

Components

How to Use Components

Import the package and create a view model for the component you need:

import ComponentsKit

let model = ButtonVM {
  $0.title = "Continue"
  $0.style = .filled
  $0.size = .large
}

In SwiftUI, pass the model into the matching SU* view:

SUButton(model: model) {
  // Handle tap.
}

In UIKit, instantiate the matching UK* view or controller and update its model when state changes:

let button = UKButton(model: model) {
  // Handle tap.
}

button.model = ButtonVM {
  $0.title = "Loading"
  $0.isLoading = true
}

Use Theme.current to customize global colors and layout. Components that observe theme changes will restyle themselves when the theme changes.

Working Guidelines

• Follow the existing component pattern: model in Models, SwiftUI surface as SU*, UIKit surface as UK*, and shared helpers only when needed.
• Keep public APIs documented with concise doc comments.
• Prefer existing shared types for sizes, colors, radii, shadows, paddings, images, and fonts.
• Add or update the matching demo preview in Examples/DemosApp/DemosApp/ComponentsPreview/PreviewPages when changing component behavior.
• Build with Swift Package Manager or the Xcode workspace before handing off substantial changes.