ContrastKit

ContrastKit is a Swift library designed to facilitate colour contrast handling within iOS, iPadOS, macOS, and tvOS applications.

It provides developers with tools to automatically generate colour shades from any base colour and determine the most readable contrast colours according to established accessibility standards (AA Large, AA, and AAA).

This package is particularly useful for UI/UX designers and developers focusing on accessibility and readability in their applications.

• Installation
• Usage
  • Basic Usage
  • In-app Usage
    • SwiftUI
    • UIKit
    • AppKit
• Provided Levels
  • Colour Range
  • Contrast
  • Dark Mode
• UITesting folder
  • Debugging and Visualisation
  • Usage in Xcode
  • Integration with SwiftUI
  • Why Use PreviewTesting?
• Contributing
• License

The ContrastKit package uses Swift Package Manager (SPM) for easy addition. Follow these steps to add it to your project:

1. In Xcode, click File -> Swift Packages -> Add Package Dependency.
2. In the search bar, type https://github.com/markbattistella/ContrastKit and click Next.
3. Specify the version you want to use. You can select the exact version, use the latest one, or set a version range, and then click Next.
4. Finally, select the target in which you want to use ContrastKit and click Finish.

Remember to import the ContrastKit module:

import ContrastKit

The default usage of the ContrastKit package is quite straightforward. Here's an example:

import ContrastKit

// Example usage in SwiftUI
let baseColor = Color.purple
let shadeColor = baseColor.level(.level100)
let contrastColor = shadeColor.highestRatedContrastLevel
let fixedContrastColor = shadeColor.aaLargeContrastLevel

// Example usage in UIKit
let uiColor = UIColor(contrastColor)  // Convert from SwiftUI Color to UIColor

The main call sites are designed for SwiftUI - but you can call UIColor(color:) too.

import SwiftUI
import ContrastKit

struct ContentView: View {
  private let baseColor = Color.green
  private let contrastColor = baseColor.highestRatedContrastLevel
  var body: some View {
    Text("High Contrast Text")
      .foregroundColor(contrastColor)
      .background(baseColor)
  }
}

Or if you want to select a specific shade in the UI (suppose you've built a consistent theme):

import SwiftUI
import ContrastKit

struct ContentView: View {
  private let baseColor = Color.green
  var body: some View {
    Text("Set themed text")
      .foregroundColor(baseColor)
      .background(baseColor.level50)
  }
}

import UIKit
import ContrastKit

class ViewController: UIViewController {
  override func viewDidLoad() {
    super.viewDidLoad()
    let baseUIColor = UIColor.systemBlue
    let contrastKitColor = Color(baseUIColor)
    let highContrastUIColor = UIColor(contrastKitColor.highestRatedContrastLevel)

    let label = UILabel()
    label.text = "High Contrast Label"
    label.textColor = highContrastUIColor
    label.backgroundColor = baseUIColor
    label.frame = CGRect(x: 20, y: 100, width: 300, height: 50)
    label.textAlignment = .center

    self.view.addSubview(label)
  }
}

import AppKit
import ContrastKit

class ViewController: NSViewController {
  override func loadView() {
    self.view = NSView()
    let baseNSColor = NSColor.systemRed
    let contrastKitColor = Color(baseNSColor)
    let highContrastNSColor = NSColor(contrastKitColor.highestRatedContrastLevel)

    let textField = NSTextField(labelWithString: "High Contrast Text")
    textField.textColor = highContrastNSColor
    textField.backgroundColor = baseNSColor
    textField.frame = CGRect(x: 20, y: 20, width: 300, height: 50)
    textField.isBezeled = false
    textField.drawsBackground = true

    self.view.addSubview(textField)
  }
}

ContrastKit provides two core enums to assist in designing UIs with appropriate colour contrast: ColorLevel and ContrastLevel. These enums help developers standardise the visual accessibility of their applications.

The ColorLevel enum defines different levels of lightness for colours, which can be used to generate various shades from a single base colour. These shades range from very light (near white) to very dark (near black), suitable for different UI elements like backgrounds, text, and interactive elements.

Light mode	Dark mode

The ContrastLevel enum specifies minimum and maximum contrast ratios for three accessibility standards: AA Large, AA, and AAA. These levels are based on the WCAG guidelines to ensure that text and interactive elements are readable and accessible.

ContrastKit also provides an optional dark mode (as pictured above) if you need the colours to adapt dynamically with your UI.

You can do this by passing the @Environment(\.colorScheme) directly into the level(_:scheme:) function.

struct EnvironmentShadeView: View {
  @Environment(\.colorScheme) private var colorScheme
  var body: some View {
    VStack {
      Color.red.level(.level100, scheme: colorScheme)
      Color.red.level(.level900, scheme: colorScheme)
    }
  }
}

When the device switches colour schemes, the ColorLevel will flip:

The PreviewTesting file is a vital part of the ContrastKit package, designed exclusively for debugging and visual inspection purposes during the development process.

It allows developers to quickly view and evaluate the contrast levels and colour shades generated by the library directly within the SwiftUI Preview environment.

This file contains sample views and configurations that demonstrate the practical application of ContrastKit.

The file includes an Example+SwiftUI file that utilises ContrastKit functionalities to display a series of colours with varying levels of contrast. This visual representation helps in understanding how different colours and their respective contrast levels appear in a UI context.

There are two previews available - StandardShadeView and EnvironmentShadeView.

The first is an example, where the shades of colours and their contrast colours are fixed regardless of the device colour scheme.

In the EnvironmentShadeView example, you can see how to pass in the @Environment(\.colorScheme) to the level(_:scheme:) function and it will update the colours automatically for you.

To use this file effectively:

1. Open your Xcode project containing the ContrastKit.
2. Navigate to the PreviewTesting file.
3. Ensure your environment is set to Debug mode to activate the #if DEBUG condition.
4. Open the SwiftUI Preview pane to see the results.

It provides a straightforward and effective way to visually inspect the accessibility features provided by ContrastKit, ensuring that the colour contrasts meet the required standards before the application is deployed.

The PreviewTesting file demonstrates the integration of ContrastKit with SwiftUI, showing how easily developers can implement and test colour contrasts in their UI designs.

By modifying the baseColor or the ColorLevel, developers can experiment with different combinations to find the optimal settings for their specific needs.

• Immediate Feedback: Allows developers to see how changes in colour levels affect accessibility and readability in real-time.
• Accessibility Testing: Helps in ensuring that the UI meets accessibility standards, particularly when creating inclusive applications.
• Ease of Use: Simplifies the process of testing multiple colour schemes without needing to deploy the app or navigate through different screens.

The PreviewTesting file is a crucial tool for developers who are serious about integrating effective contrast handling in their applications, making ContrastKit a practical choice for enhancing UI accessibility.

iOS	iPadOS

tvOS	visionOS

Contributions are highly encouraged, as they help make ContrastKit even more useful to the developer community. Feel free to fork the project, submit pull requests, or send suggestions via GitHub issues.

ContrastKit is available under the MIT license, allowing for widespread use and modification in both personal and commercial projects. See the LICENSE file included in the repository for full details.