meshing-guidelines — Claude Code skill for SwiftUI gradients
The meshing-guidelines skill guides work with MeshingKit to build, animate, and export SwiftUI mesh gradients. Use it when adding gradient-based visuals to an Apple-platform app.
MIT 1 installs ★ 226 updated 2026-08-31
npx skills add rryam/MeshingKit --skill meshing-guidelines -a claude-codeWhat meshing-guidelines does
The skill covers MeshingKit, a Swift package for mesh gradients in SwiftUI. It describes ready-made 2×2, 3×3, and 4×4 grid templates, plus custom templates defined by their points, colors, and background. Gradients can be static or animated, and Metal shader noise can add texture.
Template lookup uses NaturalLanguage and matches searches against gradient names. Export options vary by platform: iOS can save gradients and videos to the photo library, while macOS can write images and videos to disk. Building requires Swift 6.2+, Xcode 16.0+, and a supported OS version: iOS 18.0+, macOS 15.0+, tvOS 18.0+, watchOS 11.0+, or visionOS 2.0+. A project without the required Swift and Xcode versions will not build.
What it helps with
- add a mesh gradient to a SwiftUI screen
- find a predefined gradient by name
- define a template with custom points and colors
- animate a gradient or apply Metal noise
- export a gradient to the photo library or disk
Example prompts for the agent
- Add a static MeshingKit mesh gradient based on the aurora template to this SwiftUI screen.
- Find gradient templates matching sunset and show me how to use one.
- Explain how to animate a gradient and save it to the iOS photo library.
How to install meshing-guidelines
1Skills CLI (Vercel)
npx skills add rryam/MeshingKit --skill meshing-guidelines -a claude-code2Manually: put the files in place
~/.claude/skills/meshing-guidelines/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/meshing-guidelines/
1Skills CLI (Vercel)
npx skills add rryam/MeshingKit --skill meshing-guidelines -a codex2Manually: put the files in place
.agents/skills/meshing-guidelines/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rryam/MeshingKit --skill meshing-guidelines -a cursor2Manually: put the files in place
.cursor/skills/meshing-guidelines/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rryam/MeshingKit meshing-guidelines2Manually: put the files in place
.github/skills/meshing-guidelines/SKILL.md1Skills CLI (Vercel)
npx skills add rryam/MeshingKit --skill meshing-guidelines -a gemini-cli2Platform CLI
gemini skills install https://github.com/rryam/MeshingKit --path meshing-guidelinesManually: put the files in place
.devin/skills/meshing-guidelines/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add rryam/MeshingKit --skill meshing-guidelines -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about meshing-guidelines
How do I install meshing-guidelines in Claude Code?
Run npx skills add rryam/MeshingKit --skill meshing-guidelines -a claude-code. The skill file is at ~/.claude/skills/meshing-guidelines/SKILL.md.
What does meshing-guidelines do?
It guides Claude Code through using MeshingKit to create and animate SwiftUI mesh gradients, define templates, and export images or video.
What does MeshingKit require?
It requires Swift 6.2+, Xcode 16.0+, and a supported OS: iOS 18.0+, macOS 15.0+, tvOS 18.0+, watchOS 11.0+, or visionOS 2.0+.
Source text
SKILL.md · MIT
---
name: meshing-guidelines
description: Mesh gradient library for SwiftUI. Use for creating, animating, and exporting mesh gradients. Supports 2x2, 3x3, and 4x4 grid templates, animated gradients, Metal shaders, and platform-specific export to photo library or disk.
license: MIT
compatibility: Requires Swift 6.2+, Xcode 16.0+, iOS 18.0+, macOS 15.0+, tvOS 18.0+, watchOS 11.0+, visionOS 2.0+.
metadata:
author: rryam
version: "2.4.0"
allowed-tools: Read Grep Glob Edit Write Bash
---
# MeshingKit
MeshingKit is a Swift package for creating mesh gradients in SwiftUI. It provides 68 predefined gradient templates, animated gradients, Metal shader noise effects, and platform-specific export functionality.
## Build Commands
```bash
# Swift Package Manager build
swift build
# Build for a specific target
swift build --target MeshingKit
# Xcode build for iOS Simulator
xcodebuild build -project Sources/Meshin/Meshin.xcodeproj -scheme Meshin -destination "generic/platform=iOS Simulator"
```
## Test Commands
```bash
# Run tests with verbose output
swift test --verbose
# Run tests with code coverage
swift test --enable-code-coverage
```
## Lint
```bash
# Run SwiftLint with strict mode
swiftlint --strict
# Pre-commit hook runs on staged files
# Setup: scripts/setup-hooks.sh
```
## Architecture
### Main API
`MeshingKit.swift` exposes static methods for creating gradients:
```swift
// Create a static mesh gradient
MeshingKit.gradient(template: myTemplate)
// Create an animated mesh gradient view
MeshingKit.animatedGradient(template: myTemplate)
// Create with custom animation pattern
MeshingKit.animatedGradient(template: template, animationPattern: .fluid)
```
### Template System
**GradientTemplate Protocol:**
```swift
public protocol GradientTemplate: Sendable {
var size: Int { get }
var points: [SIMD2<Float>] { get }
var colors: [Color] { get }
var background: Color { get }
}
```
**Custom Template Example:**
```swift
struct MyGradient: GradientTemplate {
var size: Int { 3 }
var points: [SIMD2<Float>] {
[
SIMD2(0, 0), SIMD2(0.5, 0), SIMD2(1, 0),
SIMD2(0, 0.5), SIMD2(0.5, 0.5), SIMD2(1, 0.5),
SIMD2(0, 1), SIMD2(0.5, 1), SIMD2(1, 1)
]
}
var colors: [Color] {
[.red, .green, .blue, .yellow, .purple, .orange, .pink, .cyan, .mint]
}
var background: Color { .black }
}
```
**PredefinedTemplate Enum:**
```swift
// All 68 templates
let allTemplates = PredefinedTemplate.allCases
// Search by name (uses NaturalLanguage)
let sunsetTemplates = PredefinedTemplate.find(by: "sunset")
// Access base template
let base = PredefinedTemplate.aurora.baseTemplate
```
Templates are organized by grid size:
- `GradientTemplateSize2` - 2x2 grids (4 points)
- `GradientTemplateSize3` - 3x3 grids (9 points)
- `GradientTemplateSize4` - 4x4 grids (16 points)
### Key Views
**AnimatedMeshGradientView:** SwiftUI view for animated gradients with configurable speed.
**ParameterizedNoiseView:** Metal shader-based noise effect for textures and visual effects.
### Search
`PredefinedTemplate.find(by: token)` uses:
- NaturalLanguage framework for lemmatization
- CamelCase splitting for method-style queries
- Semantic matching for gradient names
## Export APIs
### ExportFormat Enum
```swift
public enum ExportFormat: String, CaseIterable, Identifiable, Sendable {
case png, jpg, mp4
public var id: Self { self }
public var fileExtension: String { rawValue }
}
```
### VideoExportError Enum
```swift
public enum VideoExportError: Error, Sendable {
case frameRenderingFailed
case failedToStartWriting
case pixelBufferPoolCreationFailed
case pixelBufferCreationFailed
case failedToAppendPixelBuffer
case failedToAddInput
case failedToCreateOutputURL
case fileNotAccessible
case unsupportedFormat
case photosPermissionDenied
}
```
### iOS - Photo Library
**saveGradientToPhotoAlbum:**
```swift
@MainActor
static func saveGradientToPhotoAlbum(
template: any GradientTemplate,
size: CGSize,
scale: CGFloat = 1.0,
blurRadius: CGFloat = 0,
showDots: Bool = false,
smoothsColors: Bool = true,
completion: @escaping (Result<Void, Error>) -> Void
)
```
**exportVideoToPhotoLibrary:**
```swift
static func exportVideoToPhotoLibrary(
template: any GradientTemplate,
size: CGSize,
duration: TimeInterval = 5.0,
frameRate: Int32 = 30,
blurRadius: CGFloat = 0,
showDots: Bool = false,
animate: Bool = true,
smoothsColors: Bool = true,
completion: @escaping (Result<URL, Error>) -> Void
)
```
**PhotoLibraryError:**
```swift
public enum PhotoLibraryError: Error, Sendable {
case permissionDenied
case saveFailed(Error)
}
```
### macOS - Disk Save
**saveToDisk:**
```swift
@MainActor
static func saveToDisk(
image: NSImage,
fileName: String = "gradient",
format: ExportFormat = .png,
completion: @escaping (Result<URL, Error>) -> Void
)
```
**saveGradientToDisk:**
```swift
@MainActor
static func saveGradientToDisk(
template: any GradientTemplate,
size: CGSize,
scale: CGFloat = 1.0,
blurRadius: CGFloat = 0,
showDots: Bool = false,
smoothsColors: Bool = true,
fileName: String = "gradient",
format: ExportFormat = .png,
completion: @escaping (Result<URL, Error>) -> Void
)
```
**exportVideo (macOS):**
```swift
@MainActor
static func exportVideo(
template: any GradientTemplate,
size: CGSize,
duration: TimeInterval = 5.0,
frameRate: Int32 = 30,
blurRadius: CGFloat = 0,
showDots: Bool = false,
animate: Bool = true,
smoothsColors: Bool = true
) async throws -> URL
```
**SaveToDiskError:**
```swift
public enum SaveToDiskError: Error, Sendable {
case userCancelled
case cgImageCreationFailed
case imageEncodingFailed(Error)
}
```
### Export Examples
**iOS - Save to Photo Library:**
```swift
MeshingKit.saveGradientToPhotoAlbum(
template: .aurora,
size: CGSize(width: 1080, height: 1920)
) { result in
switch result {
case .success:
print("Saved to photo library!")
case .failure(let error):
print("Error: \(error)")
}
}
```
**iOS - Export Video to Photo Library:**
```swift
MeshingKit.exportVideoToPhotoLibrary(
template: .midnightDreams,
size: CGSize(width: 1080, height: 1920),
duration: 5.0,
frameRate: 30
) { result in
switch result {
case .success(let url):
print("Video saved: \(url)")
case .failure(let error):
print("Error: \(error)")
}
}
```
**macOS - Save to Disk:**
```swift
MeshingKit.saveGradientToDisk(
template: .sunsetWave,
size: CGSize(width: 1920, height: 1080),
blurRadius: 10,
fileName: "my-gradient",
format: .png
) { result in
switch result {
case .success(let url):
print("Saved to: \(url)")
case .failure(let error):
print("Error: \(error)")
}
}
```
**macOS - Export Video:**
```swift
let videoURL = try await MeshingKit.exportVideo(
template: .aurora,
size: CGSize(width: 1920, height: 1080),
duration: 5.0,
frameRate: 30,
animate: true
)
print("Video exported to: \(videoURL)")
```
## Animation
### AnimatedMeshGradientView
```swift
struct AnimatedMeshGradientView: View {
public let template: any GradientTemplate
public let animationSpeed: Double
public init(
template: any GradientTemplate,
animationSpeed: Double = 1.0
)
}
```
### AnimationPattern
```swift
public enum AnimationPattern: String, CaseIterable, Identifiable, Sendable {
case fluid, waves, ripples, pulse, none
}
```
### Animated Positions
The `GradientAnimation.swift` module provides animation functions for video export:
```swift
static func animatedPositions(
for date: Double,
positions: [SIMD2<Float>],
animate: Bool
) -> [SIMD2<Float>]
```
## Metal Shaders
**ParameterizedNoiseView:**
Uses Metal shaders to generate procedural noise textures:
```swift
struct ParameterizedNoiseView: View {
@State private var noiseParameter: Float = 0.5
public init(parameter: Float = 0.5)
public var body: some View { ... }
}
```
## Source Structure
```
Sources/MeshingKit/
├── MeshingKit.swift # Main API
├── GradientTemplate.swift # Protocol
├── PredefinedTemplate.swift # 68 templates + search
├── GradientExport.swift # ExportFormat, VideoExportError
├── GradientExport+iOS.swift # iOS photo library
├── GradientExport+macOS.swift # macOS disk save
├── GradientAnimation.swift # Animation functions
├── GradientVideoExport.swift # Video export public API
├── GradientVideoExportHelper.swift # Video export implementation
├── Color+Hex.swift # Color utilities
├── AnimatedMeshGradientView.swift # Animated view
├── AnimationPattern.swift # Animation patterns
├── ParameterizedNoiseView.swift # Metal shader noise
├── GradientTemplateSize2.swift # 2x2 templates
├── GradientTemplateSize3.swift # 3x3 templates
└── GradientTemplateSize4.swift # 4x4 templates
Sources/Meshin/ # Demo app (SwiftUI)
├── MeshinApp.swift # App entry point
├── MeshinViewModel.swift # Export state management
└── GradientSamplesView.swift # Template list + export UI
Tests/MeshingKitTests/ # Swift Testing suite
scripts/ # Git hooks
codemagic.yaml # CI configuration
.swiftlint.yml # SwiftLint config
```
## Meshin Demo App
The Meshin app demonstrates how to use MeshingKit in a real SwiftUI application:
### Running Meshin
```bash
# macOS
xcodebuild build -project Sources/Meshin/Meshin.xcodeproj -scheme Meshin -destination "generic/platform=macOS"
# iOS Simulator
xcodebuild build -project Sources/Meshin/Meshin.xcodeproj -scheme Meshin -destination "generic/platform=iOS Simulator"
```
### Features
- **Template Browser**: Browse all 68 predefined gradients by size (2x2, 3x3, 4x4)
- **Full-Screen Preview**: Tap any template to view it full-screen
- **Animation Toggle**: Enable/disable gradient animation
- **Export Options**:
- iOS: Save to Photo Library, Export Video to Photo Library
- macOS: Save to Disk (PNG/JPG), Export Video to Disk
### Key Files
- `MeshinViewModel.swift` - Demonstrates proper usage of MeshingKit export APIs
- `GradientSamplesView.swift` - Shows how to integrate gradients with UI
### Example: Using MeshinViewModel
```swift
@MainActor
final class MyViewModel: ObservableObject {
@Published var selectedTemplate: PredefinedTemplate?
@Published var isExporting = false
func saveToPhotoLibrary() {
guard let template = selectedTemplate else { return }
MeshingKit.saveGradientToPhotoAlbum(
template: template,
size: CGSize(width: 1080, height: 1920)
) { result in
switch result {
case .success: print("Saved!")
case .failure(let error): print("Error: \(error)")
}
}
}
}
```
## Important Conventions
- All public types conform to `Sendable` for concurrency safety
- Tests use Swift Testing framework with `#expect` macro
- Template files are excluded from SwiftLint (see `.swiftlint.yml`) due to size
- CI runs on Codemagic (see `codemagic.yaml`)
- Video export uses streaming approach (memory-efficient)
- PredefinedTemplate uses NaturalLanguage for smart search
## Common Patterns
### Creating a Gradient View
```swift
let template = PredefinedTemplate.aurora
let gradientView = MeshingKit.gradient(template: template)
```
### Creating an Animated Gradient
```swift
let animatedView = MeshingKit.animatedGradient(
template: PredefinedTemplate.midnightDreams,
animationSpeed: 1.5
)
```
### Custom Animation Pattern
```swift
MeshingKit.animatedGradient(
template: template,
animationPattern: .waves
)
```
### Export with Customization
```swift
// iOS with blur
MeshingKit.saveGradientToPhotoAlbum(
template: template,
size: CGSize(width: 1080, height: 1920),
blurRadius: 15,
smoothsColors: true
) { /* ... */ }
// macOS with corner radius
MeshingKit.saveGradientToDisk(
template: template,
size: size,
showDots: false
) { /* ... */ }
```
## Notes
- Grid sizes: 2x2 (4 points), 3x3 (9 points), 4x4 (16 points)
- Video export supports MP4 (H.264 codec)
- Image export supports PNG and JPG
- All async APIs properly handle MainActor isolation
- Error enums provide type-safe error handling
© rryam · MIT · rryam/MeshingKit