Swift Code Style Guidelines

Core Style

Indentation: 4 spaces
Braces: Opening brace on same line
Spacing: Single space around operators and commas
Naming: PascalCase for types, camelCase for properties/methods

File Organization

Logical directory grouping
PascalCase files for types,
```
+
```
for extensions
Modular design with extensions

Modern Swift Features

@Observable macro: Replace
```
ObservableObject
```
/
```
@Published
```
Swift concurrency:
```
async/await
```
,
```
Task
```
,
```
actor
```
,
```
@MainActor
```
Result builders: Declarative APIs
Property wrappers: Use line breaks for long declarations
Opaque types:
```
some
```
for protocol returns

Code Structure

Early returns to reduce nesting
Guard statements for optional unwrapping
Single responsibility per type/extension
Value types over reference types

Error Handling

```
Result
```
enum for typed errors
```
throws
```
/
```
try
```
for propagation
Optional chaining with
```
guard let
```
/
```
if let
```
Typed error definitions

Architecture

Avoid using protocol-oriented design unless necessary
Dependency injection over singletons
Composition over inheritance
Factory/Repository patterns

Debug Assertions

Use
```
assert()
```
for development-time invariant checking
Use
```
assertionFailure()
```
for unreachable code paths
Assertions removed in release builds for performance
Precondition checking with
```
precondition()
```
for fatal errors

Memory Management

```
weak
```
references for cycles
```
unowned
```
when guaranteed non-nil
Capture lists in closures
```
deinit
```
for cleanup

ColorfulX is a Metal-backed gradient renderer for Apple platforms that combines LAB color interpolation, spring-based animation, and a configurable compute pipeline to produce vivid multicolor backgrounds. It supports SwiftUI, UIKit, and AppKit with both animated and static gradient rendering.

Architecture

Core Components

Main Classes:

```
ColorfulView
```
(Sources/ColorfulX/ColorfulView.swift:11) - SwiftUI wrapper for animated gradients
```
AnimatedMulticolorGradientView
```
(Sources/ColorfulX/AnimatedMulticolorGradientView.swift:22) - Core animated gradient view with Metal rendering
```
MulticolorGradientView
```
(Sources/ColorfulX/MulticolorGradientView.swift:17) - Base Metal-backed gradient view
```
MetalLink
```
(Sources/ColorfulX/MetalLink.swift:15) - Metal rendering abstraction
```
MetalProgram
```
(Sources/ColorfulX/MetalProgram.swift:14) - Metal shader program management

Animation System:

```
SpeckleAnimationDirector
```
(Sources/ColorfulX/SpeckleAnimationDirector.swift:8) - Abstract animation director protocol
```
SpeckleAnimationRandomDirector
```
(Sources/ColorfulX/SpeckleAnimationRandomDirector.swift:8) - Default random animation director
```
animationDirector
```
property in
```
AnimatedMulticolorGradientView
```
(Sources/ColorfulX/AnimatedMulticolorGradientView.swift:35) - Immutable animation behavior set at initialization

Color System:

```
ColorfulPreset
```
(Sources/ColorfulX/ColorfulPreset.swift:10) - Built-in color presets
```
ColorfulColors
```
(Sources/ColorfulX/ColorfulColors.swift:8) - Protocol for custom palettes
Uses ColorVector dependency for LAB color interpolation

Platform Support:

```
MetalView+UIKit.swift
```
(Sources/ColorfulX/MetalView+UIKit.swift:9) - UIKit extensions
```
MetalView+AppKit.swift
```
(Sources/ColorfulX/MetalView+AppKit.swift:9) - AppKit extensions
SwiftUI integration via
```
ColorfulView
```
and
```
MulticolorGradient
```

Build & Development

Prerequisites

Swift 5.9+
Xcode 15+
Apple platforms: iOS 13+, macOS 11+, macCatalyst 13+, tvOS 13+, visionOS 1+
Metal support required

Building

./Scripts/test.build.sh

Key Parameters

Animated Views:

```
speed
```
- Animation speed factor
```
bias
```
- Gradient spread control (0.00001-0.01 typical)
```
noise
```
- Procedural noise amount
```
transitionSpeed
```
- Color transition speed
```
frameLimit
```
- FPS cap (0=unlimited)
```
renderScale
```
- Resolution scaling for performance

Static Views:

```
power
```
- Falloff curve shaping
```
bias
```
- Gradient spread control

Development Workflow

Make changes to Sources/ColorfulX/
Test with Example app (Example/Workspace.xcworkspace)
Run
```
./Scripts/test.build.sh
```
to verify builds for all platforms
Commit changes

File Organization

Sources/ColorfulX/
├── AnimatedMulticolorGradientView*.swift - Animated gradient core
├── ColorfulView.swift - SwiftUI integration
├── ColorfulPreset.swift - Color presets
├── ColorfulColors.swift - Color palette protocol
├── Metal*.swift - Metal rendering
├── MulticolorGradientView*.swift - Static gradients
└── Various extensions and utilities

Performance Tips

Use lower
```
frameLimit
```
or
```
renderScale
```
on battery-constrained devices
Keep colors ≤ 8 to avoid truncation
Set
```
speed = 0
```
for frozen animation instead of static view
Lower
```
noise
```
for better performance

Architecture

Main Classes:

ColorfulView

(Sources/ColorfulX/ColorfulView.swift:11) - SwiftUI wrapper for animated gradients

AnimatedMulticolorGradientView

(Sources/ColorfulX/AnimatedMulticolorGradientView.swift:22) - Core animated gradient view with Metal rendering

MulticolorGradientView

(Sources/ColorfulX/MulticolorGradientView.swift:17) - Base Metal-backed gradient view

MetalLink

(Sources/ColorfulX/MetalLink.swift:15) - Metal rendering abstraction

MetalProgram

(Sources/ColorfulX/MetalProgram.swift:14) - Metal shader program management

Animation System:

SpeckleAnimationDirector

(Sources/ColorfulX/SpeckleAnimationDirector.swift:8) - Abstract animation director protocol

SpeckleAnimationRandomDirector

(Sources/ColorfulX/SpeckleAnimationRandomDirector.swift:8) - Default random animation director

animationDirector

property in

AnimatedMulticolorGradientView

(Sources/ColorfulX/AnimatedMulticolorGradientView.swift:35) - Immutable animation behavior set at initialization

Color System:

ColorfulPreset

(Sources/ColorfulX/ColorfulPreset.swift:10) - Built-in color presets

ColorfulColors

(Sources/ColorfulX/ColorfulColors.swift:8) - Protocol for custom palettes

Uses ColorVector dependency for LAB color interpolation

Platform Support:

MetalView+UIKit.swift

(Sources/ColorfulX/MetalView+UIKit.swift:9) - UIKit extensions

MetalView+AppKit.swift

(Sources/ColorfulX/MetalView+AppKit.swift:9) - AppKit extensions

SwiftUI integration via

ColorfulView

and

MulticolorGradient

Key Parameters

Animated Views:

speed

- Animation speed factor

bias

- Gradient spread control (0.00001-0.01 typical)

noise

- Procedural noise amount

transitionSpeed

- Color transition speed

frameLimit

- FPS cap (0=unlimited)

renderScale

- Resolution scaling for performance

Static Views:

power

- Falloff curve shaping

bias

- Gradient spread control

File Organization

Sources/ColorfulX/
├── AnimatedMulticolorGradientView*.swift - Animated gradient core
├── ColorfulView.swift - SwiftUI integration
├── ColorfulPreset.swift - Color presets
├── ColorfulColors.swift - Color palette protocol
├── Metal*.swift - Metal rendering
├── MulticolorGradientView*.swift - Static gradients
└── Various extensions and utilities

Swift Code Style Guidelines

Related Skills

Markdown Converter

Nano Banana Pro

1password