Themes

Themes let you completely change how Cocoon looks and sounds. Colors, wallpapers, sound effects, background music, smart folder artwork, icon overlays, display settings like icon roundness and hover scale… all of it. You can apply a single theme that changes everything, or mix and match pieces from different themes and asset packs.

Themes vs Asset Packs

Cocoon splits customization into two things:

Themes control the visual identity: your color scheme, theme mode (Light/Dark/OLED), wallpapers, and display settings (icon roundness, icon scale, hover scale, hero display style). A theme can also bundle or reference asset packs.

Asset packs are standalone collections of a single type of content: icon overlays, smart folder artwork, sound effects, or music. They live in their own assets/ directory and can be shared across multiple themes.

When you download a theme from Silk Pod that references specific asset packs, Cocoon automatically downloads those packs too. But you can also install asset packs on their own without any theme, or swap them out independently.

Silk Pod

Silk Pod is Cocoon’s community theme and asset store. You can browse, download, and install themes and asset packs made by other users, or submit your own.

Browsing In-App

Open Settings > Appearance > Silk Pod to launch the in-app store. You’ll see:

• Featured — a carousel of highlighted themes picked by the Cocoon team.
• Popular — most downloaded themes and assets.
• New — recently added.
• Updated — recently updated.

There are two tabs at the top: Themes and Assets. The Assets tab has categories for Icon Overlays, Smart Folders, Sounds, and Music, so you can find exactly the type of content you’re after.

Selecting any item opens a detail view with a gallery of screenshots, the description, download count, version, and a like button. Hit download and it gets installed straight to your device.

Browsing on the Web

You can also browse at cocoon-shell.com/themes. The web version has the same sorting (Popular, New, Updated), category filters (All, Themes, Icon Overlays, Smart Folders, Sounds, Music), and a search bar. Click any item for its detail page with gallery, stats, and download.

Downloading

When you download a theme from Silk Pod:

1. The theme ZIP is downloaded and extracted to your themes/ folder.
2. If the theme references asset packs (via asset_refs in its theme.json), Cocoon checks if those packs are already installed and up to date.
3. Any missing or outdated packs are automatically downloaded to assets/{category}/{pack-id}/.
4. The theme is ready to use in the Theme Picker.

Asset packs download the same way but go straight to the assets/ directory.

Submitting Your Own

Want to share something you’ve made?

1. Head to cocoon-shell.com/themes and log in with your Discord account.
2. Use the Theme Builder to create your theme or asset pack (see the Theme Builder wiki page for details).
3. Submit it for review. The Cocoon team will approve it and it shows up in the store.

Installing Themes Manually

If you have a theme that’s not on Silk Pod (maybe someone shared it directly, or you built it yourself):

1. Copy the theme folder into your Cocoon directory > themes/:

Cocoon/
└── themes/
    └── my-theme/
        ├── theme.json
        ├── preview.png
        └── (other theme files)

2. Restart Cocoon so it picks up the new folder.
3. Open Settings > Appearance > Choose Themes.
4. Your theme shows up in the picker, ready to apply.

Importing a ZIP

The fastest way to install a theme you’ve downloaded or created in the Theme Builder is with Import ZIP in the Theme Picker.

1. Open Settings > Appearance > Choose Themes.
2. Select Import ZIP from the actions at the bottom.
3. Pick the .zip file from your device’s file picker.
4. Cocoon extracts everything automatically — themes go into themes/, asset packs go into assets/.
5. The picker refreshes and your new theme is ready to use.

The importer handles two types of ZIPs:

• Bundle ZIPs (from the Theme Builder’s Download ZIP) — these contain a themes/ folder and optionally an assets/ folder. Everything gets extracted to the right place.
• Plain theme ZIPs — a single theme folder with a theme.json inside. Gets extracted to themes/.

If you already have a theme with the same name, it gets replaced.

The Theme Picker

The Theme Picker is where you manage what’s active. Open it from Settings > Appearance > Choose Themes.

It has 6 rows, each controlling a different part of your setup:

Each row has a dropdown that cycles through your options: the built-in defaults, any custom themes you’ve installed, and any downloaded asset packs for that category. Use Left/Right to cycle through options, or press A to open the full dropdown.

Changes are buffered. Nothing takes effect until you press Y (Apply). This lets you preview different combinations before committing.

Built-in Themes

Cocoon comes with 4 built-in theme modes:

• Light — bright, clean look
• Dark — darker backgrounds, easier on the eyes
• OLED — true black backgrounds, saves battery on OLED screens
• System — follows your device’s light/dark mode setting

Selecting a Custom Theme

When you select a custom theme (not one of the 4 built-ins), an options dialog pops up asking which components you want to apply and in which mode.

Mix and Match

Every row in the picker is independent. You can have:

• Colors from one theme
• Sound effects from a completely different asset pack
• Smart folder art from another
• Music from yet another

This is what makes the separation between themes and asset packs useful. You’re not locked into an all-or-nothing choice.

How Themes Apply

When you select a custom theme, its assets are loaded dynamically at runtime. Nothing gets permanently copied into your files. Switch to a different theme and the old one swaps out cleanly. This means you can experiment freely without worrying about leftover files cluttering your setup.

Clearing

The Clear Assets action at the bottom of the Theme Picker lets you selectively wipe components. You’ll see toggles for each category (colors, sounds, smart folders, icon overlays, wallpapers, music) so you can clear just the ones you want without touching the rest.

Exporting Your Setup

Happy with how Cocoon looks and sounds? You can export your current customization as a shareable theme folder. The export grabs your wallpapers, sounds, music, colors, theme mode, volume settings, and other assets and bundles them into a theme.json + folder structure that someone else can drop into their themes/ directory.

The exporter pulls from your setup in this order:

1. User custom preferences — things you’ve set manually (like a custom sound file for a specific slot)
2. User root directory files — files in your sounds/, icon_overlays/, music/ folders
3. Active theme fallback — whatever the active composite theme provides for anything you haven’t overridden

Creating Themes

The recommended way to create themes is with the Theme Builder, a web app with a live dual-screen preview. See the Theme Builder wiki page for a full walkthrough.

If you prefer editing files by hand, the Theme JSON Reference documents every field in theme.json and the full folder structure.

Asset Precedence

When Cocoon needs a sound, icon overlay, or other asset, it checks in this order:

1. User custom asset — set manually via settings (e.g. a custom sound file you picked in Sound Settings)
2. Active theme or asset pack — from the currently applied composite theme
3. Built-in default — bundled with the app

Good to Know

• Restart Cocoon after adding a new theme folder so it gets detected.
• A preview.png in the theme folder shows up as its thumbnail in the picker.
• If a wallpaper causes crashes, Cocoon automatically resets wallpapers after 3 rapid crashes. You won’t get stuck.
• All color scheme fields are optional. Only include the ones you want to change; everything else keeps the user’s existing value.
• Themes are forward-compatible. Unknown fields are ignored, so older themes still work after app updates.