xcassets

xcassets is Apple’s asset catalog system used in Xcode to manage visual resources for iOS, macOS, watchOS, and tvOS applications. An asset catalog is a directory with the .xcassets extension that contains definitions for images, colors, data, and other resources. The assets are described with JSON files (Contents.json) and are compiled by Xcode into a binary asset file (Assets.car) included in the app bundle at build time. This enables platform- and device-specific resource selection at runtime.

The catalog centralizes resources to simplify maintenance and ensure correct variants are used on the target device. Asset catalogs support multiple appearances (such as Any/Light/Dark) and device scales (1x, 2x, 3x) for images, as well as different color appearances. They also provide specialized asset types such as AppIcon, launch images, image sets, color sets, and data sets. Image sets can include vector assets (PDF) with an option to preserve vector data, and they can be organized by device family.

Contents.json entries define the structure and variants of each asset, including the names, appearances, and scales. AppIcon assets define icons for various platforms and contexts (e.g., iPhone, iPad, Apple Watch) and are required for app submission. Colors in color sets can be adaptive, responding to light or dark mode, by selecting the appropriate color variant automatically.

Using xcassets enables predictable resource loading, reduces bundle errors, and simplifies localization and theme adaptation. It is common practice to create separate catalogs for distinct targets or platforms, and to follow consistent naming and scaling conventions to ensure correct resource resolution across devices.