ThemePark

A Swift library for working with syntax highlighting/IDE themes

This package aims to solve two problems: reading theme definitions and making those definitions semantically-addressable.

Supports:

• TextMate .tmTheme with UTType.textMateTheme
• Xcode .xccolortheme with UTType.xcodeColorTheme
• BBEdit .bbColorScheme with UTType.bbeditColorScheme
• Loading themes from known installation sources
• Uniform, structed semantic naming of style defintions

Installation

dependencies: [
    .package(url: "https://github.com/ChimeHQ/ThemePark", branch: "main")
],

Usage

Working with themes

TextMate themes:

import ThemePark

let url = URL(...)
let data = try Data(contentsOf: url, options: [])
let theme = try TextMateTheme(with: data)

let urls = TextMateTheme.all

Xcode Themes:

import ThemePark

let url = URL(...)
let data = try Data(contentsOf: url, options: [])
let theme = try XcodeTheme(with: data)

let urls = XcodeTheme.all

BBEdit themes:

import ThemePark

let url = URL(...)
let data = try Data(contentsOf: url, options: [])
let theme = try BBEditTheme(with: data)

let urls = BBEditTheme.all

Resolving styles

ThemePark's Styling protocol can make use of the SwiftUI environment to adjust for color scheme, contrast, and hover state. You can expose this to your view heirarchy with a modifier:

import SwiftUI
import ThemePark

struct ThemedView: View {
    var body: some View {
        Text("themed")
            .themeSensitive()
    }
}

Executing queries on a theme:

let styler: any Styling = TextMateTheme.all.randomElement()!
let query = Query(key: .editorBackground, context: .init(colorScheme: .dark))

let style = styler.style(for: query)
print(style.color)
print(style.font)

Color schemes

The Variant type captures information about color scheme and contrast. But, do you want the theme to fully customize the UI, or would you like the user's preferences to customize the theme? This is up the the client and the capabilities of the underlying Styling conformance. Many themes also do not support more than one variant, so it can be necessary to query that as well:

let variants = theme.supportedVariants

Syntax element indentification

Most theming systems use strings to provide semantic labels for syntax elements. Eventually, this string->semantic meaning needs to be resolved. Instead of leaving this up to the client/theme designer, ThemePark uses a enum-based system for syntax element indentification. This removes all ambiguity, but can potentially expose mismatches.

This is a very common problem with tree-sitter highlight queries, which have no specification and are often completely ad-hoc.

let specifier = SyntaxSpecifier(highlightsQueryCapture: captureName)

Contributing and Collaboration

I would love to hear from you! Issues or pull requests work great. Both a Matrix space and Discord are available for live help, but I have a strong bias towards answering in the form of documentation. You can also find me on mastodon.

I prefer collaboration, and would love to find ways to work together if you have a similar project.

I prefer indentation with tabs for improved accessibility. But, I'd rather you use the system you want and make a PR than hesitate because of whitespace.

By participating in this project you agree to abide by the Contributor Code of Conduct.