Xcode 11 Themes

by Toine Heuvelmans

June 15th, 2020

Last year we took a closer look at Xcode Themes and proposed a selection of colors and fonts that not merely looks pretty, but also conveys information that supports understanding your code more easily. With the introduction of Xcode version 11 a few new syntax identifiers have been made available to themes. In this short update we will go through these new identifiers and review our Touchwonders Xcode Theme. But we begin with a typographic change to an existing identifier.

Documentation Markup

If you use documentation markup ( /// for single line or /** for multiline) instead of regular comments for adding inline documentation, it is very likely you will have noticed that Apple have changed the font for this to a proportional (non-monospaced) font. They’ve selected Helvetica for some themes, and Helvetica Neue for others. The use of these font families still is widely used throughout macOS.

Though there’s no documentation on the rationale behind this decision, using a proportional font does support differentiating between code and documentation. Using a font like Helvetica also makes inline documentation visually more similar to its parsed representation in the Quick Help.

A nice detail that most likely was introduced with the font change, is that code in documentation markup (within Markdown single or triple backticks) is now also formatted as code inline. The font used for this inline code formatting is the font specified in the Plain Text syntax identifier. The color is not directly derived from another syntax identifier; rather it is a lighter shade of the color of documentation markup.

Documentation markup

In short, we like this change. In our updated theme, we’ve chosen Helvetica Neue Light at point size 12. Helvetica Neue provides (amongst others) improved legibility over Helvetica. Its light variant is still crisp and readable while reducing the weight of documentation markup opposed to code.

Documentation Markup #868686 Helvetica Neue Light 12pt

Marks

The introduction of a separate syntax identifier for marks comes with two other visual additions to Xcode. 

Most visible is the Minimap, which shows an overview of your code through which you can quickly navigate to any part of the current file. Most code is represented by something that might best be described as syntax-colored Morse code, but what stands out as the only thing readable is marks. This allows you to label discrete sections of your file as if adding a header title above it.

Another improvement to marks is a horizontal separation line across the entire code editor that is added above separating marks (starting with a dash). For this kind of marks Xcode already inserted a separator in the Jump Bar. Now this has been extended to the editor and the minimap as well

To enhance the visibility of marks even further, they are now given a separate syntax identifier. Inspired by how marks are now displayed on the Minimap, we chose a font setting that stands out through use of different face, larger point size and heavier weight: Helvetica Neue Medium at 14 points echos the (relatively) large and heavy display of marks on the minimap, while through its font face associating it more to documentation markup. This at a lighter shade of gray allows it to be clearly visible while scrolling through a file, while not distracting too much when reading code. This new appearance now is applied to comment (//) marks in Swift files as well as #pragma marks in Objective-C files, unifying the appearance of the mark label. The // MARK and #pragma mark bits still retain their respective comment / preprocessor statement appearance.

Marks
Marks #A9A9A9 Helvetica Neue Medium 14pt

Type Declarations / Other Declarations

Two new identifiers that can add considerable color to your code are Type Declarations and Other Declarations. The majority of an Xcode theme consists of syntax identifiers (12 in total) for usage of classes, functions, methods, constants, types, variables and globals, separated further into “project” and “other” (simply put these can be regarded as “yours'' versus “someone else’s” respectively, but for more info read “Project versus Other” in the original post). Whenever you see one of these syntax identifiers applied, that means you see something being referenced that is declared elsewhere. This is where the new identifiers will be applied. When you declare a struct, class, protocol, enum, typealias, associatedtype or any other type, this is now regarded as a Type Declaration. For declarations of functions, methods, enum cases, constants, instance variables and globals the Other Declarations identifier is applied. Contrary to aforementioned “project” and “other” identifiers, there is no distinction between source of Type and Other Declarations; you see them applied in the file containing the declaration, whether it is part of your project, a framework or a library.

Again, this can add considerable color, but a note of caution is in order. Declarations used to be themed as Plain Text. Nothing exists without it being declared somewhere, so declarations are quite numerous. Selecting a bright color will have a severe effect on the appearance of your code.

A color that is not too different from white yet distinct from both the green hue used for “project” identifiers and the blue hue used for “other” identifiers,  we chose yellow for these two new identifiers. Not too saturated as to avoid slapping you in the face with a rainbow, but just enough to make it stand out next to plain text. 

Of the two identifiers, type declarations can be considered more important, as most other declarations only exist within the scope of a type – type declarations hence are also less numerous. For both reasons, we use a more saturated yellow for type declarations.

Declarations are further emphasized by a medium font weight which – as with marks – serves as visual signpost demarcating the declaration site of your type or function. For Objective-C method declarations this heavier font face works especially well, visually tying together the disjointed method arguments.

Declarations
Type Declarations #FFF666 Source Code Pro Medium 12pt
Other Declarations #FFFAAA Source Code Pro Medium 12pt

We have updated the color of the “Project Preprocessor Macros” as this was a yellowish hue that now looked very similar to “Other Declarations”. Following the original rationale to let preprocessor macros stick out (handle with care), the hue has been shifted more towards the other side of greenish, retaining both the association to the “project” group of identifiers and the same brightness and saturation of the original color.

Project Preprocessor Macros #8DD99E Source Code Pro 12pt

Heading

Last but perhaps also least: Heading! No clue as to why Apple have called this identifier “heading”. It took a while to find out where this identifier is applied, but became more apparent after looking at the raw contents of the theme file (thanks Duncan Holm), in which this identifier is defined with the key xcode.syntax.markup.code. Thus far we’ve found that “Heading” will be applied to code blocks in Markdown files (one or more lines captured within triple backticks). Perhaps in a future version of Xcode they’ll add syntax highlighting for fenced code blocks in Markdown files, but for now there’s at least… headings!

If you load a Markdown file in Xcode, most content will be styled by using the color of “Plain Text” and a font that always seems to be Helvetica Neue, but with a point size larger to what you’ve set for “Plain Text”, with a line spacing that seems to be influenced by the font that you’ve chosen for “Plain Text”. Fascinating, but it doesn’t stop there: inline code (in single backticks) is styled according to “Project Class Names”, but always with Menlo as font, no matter what other fonts have been configured in the theme. In the Touchwonders theme, this is a green tint.

It is already a bit arbitrary to give an entire code block a single color. To let code blocks stick out against plain text while associating it to inline code, we give it a shade of green in the same hue as used for “Project Class Names”. The saturation is reduced to avoid big bright blocks of color.

Heading
Heading  #D0D998 Source Code Pro 12pt

Concluding

So there you have it: four new identifiers and a font change, most of which aid in navigating throughout a file and discerning documentation from code. It is good to see that Xcode keeps receiving improvements like this – small and large. We’ve updated the Touchwonders theme that is available on GitHub. For your pleasure we’ve also added a reference table linking syntax identifiers to theme keys, which includes some mysterious ones. Perhaps in a future update we will be able to discuss these!