AssetCatalogKit

A Swift package for programmatically generating Xcode Asset Catalogs (.xcassets bundles). Build complete asset catalogs with images, colors, and data files in code -- useful for tooling, code generation, and build-time asset pipelines.

Usage

Creating an Asset Catalog

import AssetCatalogKit

let catalog = AssetCatalog(name: "MyAssets", children: [
    // Add image sets, color sets, data sets, and groups here
])

try catalog.write(to: "/path/to/output")
// Creates: /path/to/output/MyAssets.xcassets/

Image Sets

Create image sets with variants for different scales, devices, and traits:

let imageSet = ImageSet(
    name: "AppIcon",
    properties: ImageProperties(),
    images: [
        Image(filename: "icon.png", data: .data(pngData), scale: .unscaled),
        Image(filename: "icon@2x.png", data: .data(pngData2x), scale: .retina),
        Image(filename: "icon@3x.png", data: .data(pngData3x), scale: .retinaPlus),
    ]
)

Images support a wide range of device traits:

let image = Image(
    filename: "hero.png",
    data: .url(fileURL),          // Load from a file URL instead of in-memory data
    idiom: .iphone,               // Target device family
    scale: .retina,               // Display scale
    widthClass: .regular,         // Horizontal size class
    heightClass: .compact,        // Vertical size class
    colorSpace: .displayP3,       // Color space
    languageDirection: .leftToRight
)

Configure vector preservation and template rendering:

let properties = ImageProperties(
    preservesVectorRepresentation: true,
    templateRenderingIntent: .template
)

Color Sets

Define colors with support for dark mode and other appearance variations:

let colorSet = ColorSet(name: "AccentColor", colors: [
    // Default (light) color
    ColorEntry(
        color: Color(components: ColorComponents(red: 0.0, green: 0.478, blue: 1.0, alpha: 1.0))
    ),
    // Dark mode variant
    ColorEntry(
        color: Color(components: ColorComponents(red: 0.188, green: 0.557, blue: 1.0, alpha: 1.0)),
        appearances: [Appearance(appearance: .luminosity, value: .dark)]
    ),
])

Colors support Display P3 wide gamut:

let wideGamutColor = ColorEntry(
    color: Color(
        colorSpace: .displayP3,
        components: ColorComponents(red: 1.0, green: 0.0, blue: 0.0, alpha: 1.0)
    ),
    displayGamut: .displayP3
)

Data Sets

Bundle arbitrary data files that can be loaded at runtime via NSDataAsset:

let dataSet = DataSet(
    name: "LevelData",
    properties: DataProperties(),
    data: [
        DataItem(
            filename: "level1.json",
            universalTypeIdentifier: "public.json",
            data: .data(jsonData)
        )
    ]
)

Groups

Organize assets into groups, optionally using namespaces:

let group = Group(
    name: "Buttons",
    properties: GroupProperties(providesNamespace: true),
    children: [
        ImageSet(name: "Primary", properties: ImageProperties(), images: [...]),
        ImageSet(name: "Secondary", properties: ImageProperties(), images: [...]),
    ]
)

With providesNamespace: true, assets are referenced as "Buttons/Primary" in code.

Putting It All Together

let catalog = AssetCatalog(name: "GeneratedAssets", children: [
    Group(
        name: "Colors",
        properties: GroupProperties(),
        children: [
            ColorSet(name: "Background", colors: [...]),
            ColorSet(name: "TextPrimary", colors: [...]),
        ]
    ),
    Group(
        name: "Icons",
        properties: GroupProperties(providesNamespace: true),
        children: [
            ImageSet(name: "Search", properties: ImageProperties(templateRenderingIntent: .template), images: [...]),
            ImageSet(name: "Settings", properties: ImageProperties(templateRenderingIntent: .template), images: [...]),
        ]
    ),
    DataSet(name: "DefaultConfig", properties: DataProperties(), data: [...]),
])

try catalog.write(to: "/path/to/project")

Data Sources

Asset data (images and data files) can come from two sources:

// In-memory data
let image = Image(filename: "icon.png", data: .data(pngData))

// File URL (read at write time)
let image = Image(filename: "icon.png", data: .url(fileURL))

Supported Asset Catalog Features

Feature	Types
Image sets	ImageSet, Image, ImageProperties
Color sets	ColorSet, ColorEntry, Color, ColorComponents
Data sets	DataSet, DataItem, DataProperties
Groups	Group, GroupProperties
Device targeting	Idiom, DisplayScale, WidthClass, HeightClass
Appearance	Appearance, AppearanceType, AppearanceValue
Color management	ColorSpace, DisplayGamut
GPU requirements	GraphicsFeatureSet, Memory
Internationalization	LanguageDirection
Watch support	WatchScreenWidth
Image resizing	ImageResizing, ImageResizingMode, ImageCapInsets, ImageCenter
Compression	ImageCompressionType
Template rendering	ImageTemplateRenderingIntent
On-demand resources	Via onDemandResourceTags on properties types

License

BSD Zero Clause License. See LICENSE for details.