Theme Builder

The Theme Builder is a web app for creating themes and asset packs. It gives you a live dual-screen preview while you work, and exports ready-to-use ZIPs that you can drop into your Cocoon directory or submit to Silk Pod.

Getting Started

Head to the Theme Builder and you’ll see a creation prompt with different starting points:

New Theme — a full theme with colors, wallpapers, and display settings.
Icon Overlays — decorative frames drawn on top of game art, organized by platform.
Smart Folders — custom artwork for smart folders (Favorites, Recent, etc.).
Sound Effects — replace any of Cocoon’s UI sounds.
Music — background tracks with time-based scheduling or playlist mode.
Import ZIP — open an existing theme ZIP to edit it.

You can work on multiple tabs at once. Click the + button in the tab bar to add more, so you could have a theme and a separate icon overlay pack open side by side.

The Theme Tab

When you create a new theme, the left side is your editor and the right side shows a live preview of both screens (top and bottom) as they’d look on a dual-screen device.

Colors

The color section lets you set every color in Cocoon’s UI. Each field has a color picker and updates in the live preview as you change it.

Fields cover backgrounds, cards, text, icons, tiles, toggles, shadows, accents, dividers, and status colors. You don’t have to set every one — anything left empty keeps the user’s existing value. See the Theme JSON Reference for the full list.

Theme Mode

Choose Light, Dark, OLED, or System as the base mode. This determines the overall feel before your custom colors are applied on top.

Hero Display

The hero area is the large image/logo on the top screen when a game or folder is selected. Two settings control it:

Hero Display Style:

Vignette — the hero image fades out at the edges with a soft radial blur, showing the wallpaper behind it. Classic 3DS-style look.
Fullscreen — the hero image fills the entire top screen edge-to-edge with no fade.
None — no hero image at all.

Hero Gradient:

None — no gradient overlay.
Black Gradient — a dark gradient from the bottom of the hero area, helping text readability.

Display Settings

Three sliders fine-tune the look:

Icon Roundness (0–0.5) — how rounded the corners on game icons are. 0 is square, 0.5 is fully rounded.
Icon Scale (0.5–1.0) — how big game icons appear on the grid.
Hover Scale (0.5–1.0) — how much game icons grow when selected/hovered.

Two more sliders control hero logo sizes:

Game Logo Scale (0.1–1.0) — how big the game logo appears on the top screen.
Folder Logo Scale (0.1–1.0) — how big the folder logo appears on the top screen.

Wallpapers

Drag and drop images, GIFs, or videos onto the wallpaper drop zones:

Main Wallpaper (top screen) — the background behind the hero area.
External Wallpaper (bottom screen) — the background behind the game grid.

Supports PNG, JPG, WEBP, GIF, MP4, and WEBM. Video wallpapers loop automatically.

Preview

The live preview on the right updates as you make changes. It shows the dual-screen layout with your colors, wallpapers, and hero settings applied. Click on folder tiles in the bottom screen to preview smart folder navigation.

Asset Tabs

Asset tabs (Icon Overlays, Smart Folders, Sounds, Music) use a three-pane layout:

Left pane — platform or category list.
Center pane — live preview of the asset applied.
Right pane — upload area for your files.

Icon Overlays

Icon overlays are per-platform. Select a platform on the left, then upload:

Overlay — a PNG image drawn on top of the game art (borders, frames, console shapes).
Mask — a PNG where white areas are visible and transparent areas are cut away. Controls which parts of the game art show through. Must be PNG format (transparency is required).

The preview shows your overlay applied to a sample game tile in real time.

Smart Folders

Smart folder assets customize how folders look. Select a folder type on the left (Favorites, Recent, Most Played, etc.) — you can also add per-platform folder art. For each folder, upload:

Icon — the folder icon shown on the bottom screen grid.
Hero — a background image for the top screen when the folder is selected.
Logo — a logo/wordmark overlaid on the top screen hero area.

Sound Effects

Upload replacement audio files for Cocoon’s 22 sound slots. The builder shows the full list with upload buttons for each. Supported formats include WAV, MP3, OGG, and FLAC.

The available sound slots are: Navigate, Select, Back, Folder Open, Folder Close, Launch, Error, Notification, Discord Open, Discord Close, Screen Swap, Grid Zoom In, Grid Zoom Out, Reorder Pickup, Reorder Place, Open Edit, Pop, Slider Increase, Slider Decrease, Saving, Saving End, and RetroAchievements.

Music

Set up background music with either time-based scheduling or playlist mode. Upload tracks and assign them to time slots, or add them to a playlist.

Exporting

Click Download ZIP (or File > Download ZIP…, or ⌘S) to package everything into a single ZIP file. The ZIP contains:

Your theme in a themes/ folder with theme.json, wallpapers, and music.
Any asset packs from your asset tabs in an assets/ folder, each with its own metadata.json.
Asset references linking the theme to its bundled asset packs via local IDs.

Installing on Your Device

The easiest way to install a downloaded ZIP is with the Import ZIP action in Cocoon’s Theme Picker:

Transfer the .zip to your device.
Open Settings > Appearance > Choose Themes > Import ZIP.
Pick the file — Cocoon extracts themes and asset packs to the right directories automatically.

You can also manually unzip it and copy the themes/ and assets/ folders into your Cocoon data directory.

Importing

Got an existing theme ZIP to tweak? Use File > Import ZIP (or drag a ZIP onto the builder) to load it. The builder reads the theme.json, loads all assets, and lets you edit and re-export.

Submitting to Silk Pod

To share your creation with the community:

Log in with your Discord account on cocoon-shell.com/themes.
Export your theme/asset pack from the builder.
Submit it for review.
Once approved, it appears in the Silk Pod store for everyone to download.