Category: Apple Developer News

A good document icon aids in the identification of your file on the Desktop, in a Finder window, or in an open dialog, especially when previews aren’t available. These icons may be displayed on screen as small as 16pt or large enough to showcase every glorious design detail.

Depending on the file type and personal preference, document icons can also display document previews. If someone has chosen not to show document extensions in System Preferences, these icons can additionally provide additional context in deciphering their file type and native program.

With macOS Big Sur, you can customize and control how your app’s document icons display across the system. We’ll show you how to design a great icon, integrate it into your Xcode project, and assign document types and type identifiers.

Design a document icon for your app

By default, if you don’t specify a document icon for a file type in your app, macOS will automatically create one for you by compositing your app’s icon together with the correct extension name. This is a common pattern for imported document types or non-proprietary file formats that your application can open such as MP3, JPG or PNG.

You can additionally create a custom document icon if your app supports multiple file types and you’d like to visually distinguish between them. For example, a drawing application may open a jpg file, a project file, a library of drawing components, a plugin or a color swatch.

When creating a custom icon, we recommend keeping its design simple. Try to depict what your icon represents as closely as possible and with as few details as possible. Additionally, think of other document types that your document may commonly be next to, and use distinct shapes and colors that are identifiable even at smaller sizes.

If you plan to create multiple custom icons for different file types, it’s important to make each design distinct and understandable to help people know what to expect when they open them.

The elements of a custom document icon
Beginning with macOS Big Sur, you can generate a new custom document icon with a set of images and a text string.

To create a new custom document icon, you can provide a background fill, center image, or text string. Each of these three elements is optional, allowing you to use just one element or any combination of the three to customize your icon. From there, macOS will automatically layer, position, and mask these elements, then composite them into a page icon with a right corner fold.

---

You can download Sketch and Photoshop templates on Apple Design Resources to assist in the generation of the image assets in all their required sizes.

Apple Design Resources

---

Fill in the background
The background image allows you to customize the background of your icon. The art should fill the entire drawing area, as shown below, and the system will automatically mask it to the document shape in all sizes.

Background images can not only be used to change the background of your document, but you can also use them to create custom designs that fill the entire page.

The background image should be drawn in the following sizes:

• 512×512
• 512×512@2x
• 256×256
• 256×256@2x
• 128×128
• 128×128@2x
• 32×32
• 32×32@2x
• 16×16
• 16×16@2x

Add a center image
The center image is always half the size of the document canvas. For example, the center image displays at 16pt on a 32pt icon size.

The bulk of the artwork for the center image should be drawn at ~80% of the canvas size. For example, on the 256×256 version, the drawing should be inside a 205×205 area, as shown in the image below. Curves and points can extend into the margin to adjust for optical alignment.

The shape of the artwork should be simple to make it easily identifiable in smaller sizes. The rendering, however, can be as simple or as rich as you’d like.

The center image can be specified in the following sizes:

• 256×256
• 256×256@2x
• 128×128
• 128×128@2x
• 32×32
• 32×32@2x
• 16×16
• 16×16@2x

Add some textual context
The icon’s text string will often be your document’s extension, but can also be something more descriptive. For example, “SCENE” is more descriptive — and easier for someone to understand — than “scn.”

The system will capitalize and scale the text to fit inside the icon, so it’s important to keep the length of your string as short of possible to prevent it from getting too small. The text will also automatically change its color to remain legible against flat colored backgrounds.

Build document icons in your app

To create your document icon types, you’ll need to integrate these elements into your Xcode project.

Bring images into the asset catalog
First, add your background fill image and/or center image into the Asset Catalog as Generic Icons.

1. In Xcode, click the + button within your Asset Catalog.
2. Choose macOS > macOS Generic Icon.
3. Drag your assets into their respective size slots.

If your assets are named using the format icon_[size]x[size][@resolution].png (e.g. icon_32x32@2x.png or icon_32x32.png), they can all be dragged at once and will automatically be assigned to their appropriate size slots.

Configure the Document Type Identifier
Click the Imported/Exported Type Identifier disclosure triangle to add a new Document Type Identifier or open an existing one.

• Icon Image (optional): Select a Center Image from your app’s Asset Catalog.
• Icon Fill (optional): Select a Background Fill Image from your app’s Asset Catalog
• Icon Text (optional): Input the text you want displayed on the bottom of the document icon. This can be the same as the extension or something more descriptive. For example, the scn extension can use scene as its text.
• Legacy Icon (optional): This is either an .icns file or a Generic Icon in your Asset Catalog which will be used if you deploy your application to macOS 10.15 and below or in macOS 11 if Icon Image, Icon Fill and Icon Text are left blank. If a Legacy Icon was specified in the Document Type section, it will override this.

Declaring New Uniform Type Identifiers

Configure your document icons

Here’s how to indicate whether you want to display a legacy document icon, a custom icon, a programmatic option.

1. In Xcode’s Project navigator, select the project file.
2. Select your app’s target from the target list.
3. Choose the Info tab.

Click the Document Type disclosure triangle to add a new Document Type or open an existing one.

You’ll have two options here for iconography:

• Legacy Icon (optional): This is either an .icns file or a Generic Icon in your Asset Catalog. macOS uses legacy icons if you deploy your app to macOS 10.15 or earlier, or if you don’t provide any custom elements for your icon. If you’ve specified a Legacy Icon in the Document Type Identifier, the one in the Document Type will override it.
• Use system generated icons: Check this box if you’ve defined an Icon Fill, Image or Text in the Document Type Identifier for use in macOS 11 and above, or you want the system to use your App’s icon and extension name as your icon. If you leave this box unchecked, macOS will use your Legacy Icon for that document type even when running macOS 11 and above.

Developing a Document-Based App

Validate your app document icons

You can test your new document icons in your app by building and running your app. Here’s what you need to do.

1. Remove all other versions of your app from your test system and empty the Trash.
2. Open your app project in Xcode
3. Build and run your app
4. Gather test assets by creating a new folder and adding one of each document type.
5. Open the test asset folder in Finder.
6. In Finder, go to View > Show View Options to open the “View Options” window for your test asset folder.
7. Make sure that “Show icon preview” is unchecked.

Bring some life into your documents

Document icons in macOS Big Sur are an excellent way to further refine your app’s design on Mac and help people identify the correct file at a glance. For more support on creating these icons, be sure to check out the Apple Design Resources and developer documentation.

Resources

Apple Design Resources

Developing a Document-Based App

Uniform Type Identifier Concepts

Declaring New Uniform Type Identifiers

Adopting Uniform Type Identifiers

Introduction to Uniform Type Identifiers

People expect apps to be secure and their data to be protected. You may need to perform cryptographic operations to implement features such as authentication, message encryption, or to meet regulatory requirements. CryptoKit is a Swift framework that makes it easier and safer to perform common cryptographic operations, whether you simply need to compute a hash or are implementing a more advanced authentication protocol. This year, CryptoKit adds new APIs for HMAC-based Extract-and-Expand Key Derivation Functions (HKDF), support for PEM and DER formats, and with Swift Crypto your code can now run everywhere Swift runs.

HKDF

Key derivation functions allow you to derive one or more secrets of the size of your choice from a master key or passcode. Starting in iOS 14, you can now use standalone APIs for HKDF. Integrate the easy to use one-shot variant for quick tasks such as deriving multiple keys from a master secret, or the two-step extract and expand API with fine-grained control over the key derivation process. In prior versions of iOS, HKDF was supported only when deriving a symmetric key from an elliptic curve key agreement protocol.

HKDF

PEM and DER formats for encoding elliptic curve keys

PEM and DER formats are now supported directly in CryptoKit. You can now directly pass a PEM string or DER-encoded data to initialize CryptoKit public and private keys, without using another library to perform the conversion.

Portability

With Swift Crypto you can create cross-platform solutions using the CryptoKit APIs on all platforms that Swift supports, including Linux and servers. Portability is important when you need to run the same code on your client and server, such as supporting two-factor authentication using a One-Time Password.

Resources

Introducing Swift Crypto

Watch “Cryptography in Swift” from dotSwift 2020

At Apple, we believe that privacy is a fundamental human right. As announced at WWDC20, App Store product pages will feature a new privacy information section to help users understand an app’s privacy practices. Today we are publishing more details for developers on what will be covered in this new privacy section. By the end of next month, you will be able to submit your information via App Store Connect to prepare for this feature rolling out to users by the end of the year.

Learn more about providing app privacy information

In addition, on iOS 14, iPadOS 14, and tvOS 14, apps will be required to receive user permission to track users across apps or websites owned by other companies, or to access the device’s advertising identifier. We are committed to ensuring users can choose whether or not they allow an app to track them. To give developers time to make necessary changes, apps will be required to obtain permission to track users starting early next year. More information, including an update to the App Store Review Guidelines, will follow this fall.

Learn more about asking permission to track

August 31, 2020

You can now watch the Special Event Keynote, Platforms State of the Union, and over 200 sessions from this year’s Apple Worldwide Developers Conference with Japanese and Simplified Chinese subtitles. Available on the web, iPhone, iPad, Mac, and Apple TV.

View WWDC20 videos

Safari Web Extensions can add custom functionality to Safari 14 beta using the same WebExtensions API used in other browsers, such as Chrome, Firefox, and Edge. And with a new conversion tool in Xcode 12 beta, you can quickly bring your existing extensions to Safari and make them available on the Mac App Store this fall.

Learn more about the WebExtensions API

When designing games, Philipp Stollenmayer has a confession to make. “I’m easily bored,” he says. “And I just don’t want the player to be bored when I am.”

The German developer’s aversion to monotony has fueled a prolific number of creative and off-kilter titles over the years, including Sometimes You Die, Sticky Terms, and Bacon — The Game. 2019’s Song of Bloom goes further still. The Apple Design Award-winning puzzle game is enigmatic and ever-shifting, with a series of layered and intertwined levels that invite people to tap, shake, draw, and explore their device.

“It’s an abstract game [that develops] into something more understandable with time,” says Stollenmayer. “The more you get in the story, the more you discover and the more the interaction changes.”

This concept is a core part of his philosophy around game design: create an instantly graspable idea, then keep thinking, pushing, and inviting players go further. There’s no true ‘goal’ beyond the exploration of the narrative and the puzzles — in Stollenmayer’s words, the game is “user experience in its truest form.”

Song of Bloom grew from one of Stollenmayer’s vacation experiments. Having taken a looping video of waves on the beach while in Italy, he decided to try and add a new aspect to it with device rotation: when the video flipped, the water would fall out of frame. From there, “it just became a process of triggering new ideas and new experiments,” he says.

Unlike Stollenmayer’s other games, nothing is constant in Song of Bloom. “Not the elements, not the interaction, and not even remotely the style,” he says. One puzzle might look like a rough sketch, while others include hyper-realistic popcorn kernels. His favorite puzzle of the series? A stop-motion risograph-inspired milk carton.

There is always this doubt in the back of the mind if what you are seeing is real. This contributes a lot to the mood I am trying to convey.

Philipp Stollenmayer

Every image in Song of Bloom is computer-generated, the result of experimenting with code — sometimes with unintended results. “As a designer who isn’t the greatest programmer, my code usually creates visual errors,” says Stollenmayer. “On the way, I would let myself [be inspired] by my own faults.”

That included manipulating items to make them look more like how they might in a real-world setting. For example, one puzzle, which requires someone to virtually knit an item, includes the sort of stray holes and tiny offshoots that you might expect from a newer knitter. “Making digital versions without these faults is much easier,” Stollenmayer says. “But copying the faults creates moments where you ask yourself: Could this be real?”

He drew inspiration from immersive installations and puzzle games alike, including multimedia artists Laure Prouvost and Franz West and games like Blackbox, Device6, and Prune. “I look at a lot of art to get a sense for color, composition — but also how to control and transform surroundings,” he says.

I am interested in the between, where it all comes together, because in our world, nothing exists without context.

Philipp Stollenmayer

Each visual, haptic, motion, and verbal cue within the game is designed to get the player to explore that space and interact with its imagery. Because the puzzles are often highly abstracted, Stollenmayer used haptics to help guide people through the game — using them to signify mood in higher- or lower-stakes scenes or aid someone in evaluating potential solves. “Like in the real world, the player expects a reaction from every action,” Stollenmayer says.

One of his earliest concepts for transitioning between puzzles in Song of Bloom was that of someone blinking their eyes: Solve the puzzle or move to the main screen, and the entire screen blinks in and out.

Stollenmayer experimented with several multitouch gestures around that concept, including a pinch gesture, before settling on a button — a single curved line — in the corner. “I had to get it into the player’s mind,” he says. That meant creating something easily findable and understandable, and not adding gestures that might get triggered by chance during the exploration of a puzzle.

That thin curved line is one of the only pieces of consistent, persistent interface amidst Song of Bloom’s many artistic changes. “Like the home bar on full screen iPhones, it’s just there to remind you that [it] exists, without disturbing the running scene with any content or contrasting style,” Stollenmayer says.

On tap, it allows people to return to the game’s main screen and view the branching tree of puzzles they’ve helped grow. This tree also serves as the game’s sole hint mechanism, letting people use long presses to peek at possible areas to focus on within the game. The more you play around with it, the more the story (and tree) grows and the more hints you discover. Along with original music, it’s this fertile combination of forces that earns the game its name.

With so many different art styles and creative influences, it’s amazing how effortlessly they all blend together in Song of Bloom. The story is important, of course, but for Philipp design is really about how it feels. Call Song of Bloom what you will — a game of personal discovery, a provocative tale of art and clues — for Philipp Stollenmayer, the goal is simply to play; to make people feel at once captivated and liberated all in the same hour-long session.

In Song of Bloom, you just play for the sake of playing. And this is what I was trying to achieve — to help the player get lost in his own interpretation.

Philipp Stollenmayer

Learn more about Song of Bloom

Learn more about Song of Bloom on the App Store

Download Song of Bloom