README.md

Cyborg

Cyborg is a partial port of Android's VectorDrawable to iOS. It is intended as a replacement for UIImages, Icon Fonts, and Apple's PDF vector image option. The VectorDrawable format provides a number of advantages:

• Full theming support of individual elements of an illustration, beyond simple image tinting or changing the text color in an Icon Font
• Ability to use one asset for both platforms, simplifying the design -> engineering pipeline
• Assets are resolution independent
• RTL support
• Easily convertible from SVG using Android Studio or third-party tools

Cyborg also supports MacOS (AppKit), TvOS, and can be used from SwiftUI. However, be aware that these implementations are currently less mature than the iOS version.

Performance Comparisons

We benchmarked Cyborg against a number of alternatives, loading the 50+ icons contained in our Driver app's icon set.

• Cyborg's parser is faster than the iOS SVG libraries we could find
• It tends to be a tiny bit slower than UIImage. The differences should be in the fractions of milliseconds in practice
• An icon font with ~50 icons can be loaded in the time that it takes to load around 2-3 drawables of similar complexity.

If parsing performance becomes an issue, you may wish to implement either a caching mechanism appropriate for your application, or take advantage of Cyborg's thread safety to perform parsing off the main thread.

With that said, many performance improvement opportunities currently exist, so performance should improve in the future. As of this writing, Swift is a young language, and performance improvements to it, particularly in String creation, closures, and ownership should also have a positive impact on Cyborg's performance.

The full list of features is enumerated in the Android Documentation.

Installing Cyborg

Cyborg supports Swift Package Manager and Carthage.

To install using Carthage:

1. Get Carthage.
2. Add the following to your CartFile: github "uber/cyborg" ~> [desired version]

To add Cyborg to an Xcode project using Swift Package Manager, follow the instructions provided by Apple.

Using Cyborg

After following the integration steps below, using Cyborg requires only slightly more code than using a UIImage:

let vectorView = VectorView(theme: myTheme)
vectorView.drawable = VectorDrawable.named("MyDrawable")

Integration

Cyborg is made to scale up to complex uses cases, and as such require a bit of configuration to get the clean code sample above.

Let's see how to write the minimal integration to get started:

Implementing Themes and Resources

One of the best features of VectorDrawables is the ability to swap in arbitrary values at runtime. Well authored VectorDrawable assets can change their colors in response to changes in app state, such as a night mode.

However, gaining access to these powerful features requires us to write our own Theme and Resource providers:

class Theme: Cyborg.ThemeProviding {

    func colorFromTheme(named _: String) -> UIColor {
        return .black
    }

}

class Resources: ResourceProviding {

    func colorFromResources(named _: String) -> UIColor {
        return .black
    }

}

Assuming that resources never change, we can now write the convenience initializer depicted in the first code sample:

fileprivate let resources = Resources()

extension VectorDrawable {
    public convenience init(theme: Theme) {
        self.init(theme: theme, resources: resources()
    }
}

Reporting Drawable Parse Errors:

If, for some reason, you provide an invalid VectorDrawable to Cyborg, the standard creation function in Cyborg will give you a detailed error message that you can report as a nonfatal to the crash reporting service of your choice and use to debug locally. This can be handled at your app's "platform" level, allowing you to write code that assumes that the parsing always succeeds, just like with UIImage:

extension VectorDrawable {
    public static func named(_ name: String) -> VectorDrawable? {
        return Bundle.main.url(forResource: name, withExtension: "xml").flatMap { url in
        switch VectorDrawable.create(from: url) {
            case .ok(let drawable):
                return drawable
            case .error(let error):
               myAssertionFailureThatAlsoReportsToBackend("Could not create a vectordrawable named \(name); the error was \(error)")
               return nil
        }
    }
}

Best Practices

Lint VectorDrawable Assets

As you may already have noticed, the Theme and Resource objects you wrote in an earlier section are stringly typed. To prevent issues with assets that reference nonexistent theme or resource colors, you may want to lint the xml files to ensure that they are valid.

Store Your VectorDrawables in a Single Repo

You may find it convenient to allow designers to commit new assets directly to a repo that can be pulled into your Android and iOS repos by designers.

Snapshot Test Your VectorDrawables

The easiest way to ensure correctness of your UIs that use static vector drawables is to snapshot test the UIs that use them using a tool like iOSSnapshotTestCase. This will ensure that any code that isn't compiler-verified matches your expectations.