Theme JSON Reference

Fields and folders used by Cocoon theme.json files.

Theme JSON Reference

Use this reference when building a theme by hand. The Theme Builder is easier for most authors and exports the same structure.

Folder Structure

Place each theme inside the themes/ folder of the Cocoon data directory:

themes/my-theme/
├── theme.json
├── preview.png
├── wallpapers/
│   ├── main.webp
│   └── external.mp4
├── sounds/
│   ├── navigate.ogg
│   └── ...
├── music/
│   └── ...
├── icon_overlays/
│   └── gba/
│       ├── mask.png
│       └── overlay.png
└── smart_folders/
    ├── favorites/
    │   ├── icon.png
    │   ├── hero.png
    │   └── logo.png
    └── by_platform/gba/
        ├── icon.png
        ├── hero.png
        └── logo.png

Use lowercase folder names for consistency.

Example File

Every field except name is optional. Omitted colors and settings leave the user’s current values unchanged.

{
  "name": "My Theme",
  "author": "Your Name",
  "version": "1.0.0",
  "description": "Short description",
  "credits": "Optional asset credits",
  "website": "https://example.com",
  "theme_mode": "DARK",
  "wallpaper_main": "main",
  "wallpaper_external": "external",
  "color_scheme": {},
  "settings": {},
  "music_mode": "PLAYLIST",
  "music_playlist": "music/one.mp3||music/two.mp3",
  "music_playback_mode": "SHUFFLE",
  "sfx_volume": 0.8,
  "music_volume": 0.5,
  "jingle_volume": 0.7,
  "asset_refs": []
}

Metadata and Theme Mode

Field	Type	Notes
`name`	string	Required display name
`author`	string	Author or handle
`version`	string	Theme version
`description`	string	Short store/picker description
`credits`	string	Asset and collaborator credits
`website`	string	Optional project URL
`theme_mode`	string	`LIGHT` or `DARK`. `OLED` and `SYSTEM` are also valid

Enum values are case-insensitive.

Colors

Put colors in color_scheme. Use #RRGGBB or #AARRGGBB.

Field	Purpose
`background_gradient_start`, `background_gradient_end`	Main background gradient
`card_gradient_start`, `card_gradient_end`	Cards and dialogs, plus panels
`text_primary`, `text_secondary`	Main and supporting text
`icon_tint`	Default flat icon tint
`tile_background`, `tile_border`	Game and app tiles
`toggle_off_gradient_start`, `toggle_off_gradient_end`	Toggle off track
`toggle_thumb_gradient_start`, `toggle_thumb_gradient_end`	Toggle thumb
`drop_shadow`, `inner_shadow_light`, `inner_shadow_dark`	Depth effects
`success`, `warning`, `divider`	Semantic and divider colors
`accent_gradient_start`, `accent_gradient_end`, `accent_glow`	Accent override
`selection_gradient_start`, `selection_gradient_end`	Optional cursor-only gradient

When selection colors are omitted, the cursor follows the effective accent. If only one endpoint is supplied, the other falls back to its accent endpoint.

Wallpapers

Field	Description
`wallpaper_main`	Main/bottom display wallpaper name or relative reference
`wallpaper_external`	External/top display wallpaper name or relative reference

Wallpaper files normally live under wallpapers/. References may omit the extension. Cocoon checks image and GIF formats, plus video. Without explicit fields, it checks names such as main or bottom. The names external and top also work.

Display and Behavior Settings

Put these snake-case fields inside settings. They apply once when the user chooses to apply Theme Settings and remain editable afterward.

Field	Type / values	Purpose
`icon_roundness`	`0.0-0.5`	Tile corner roundness
`icon_scale`	`0.5-1.0`	Artwork size inside tiles
`hover_scale`	`0.5-1.0`	Non-selected/selected scale relationship
`hero_display_style`	`VIGNETTE`, `FULLSCREEN`, `NONE`	Hero image treatment
`hero_logo_scale`	`0.1-1.0`	Game logo size
`hero_folder_logo_scale`	`0.1-1.0`	Folder logo size
`hero_gradient_style`	`NONE`, `BLACK_GRADIENT`	Hero overlay
`hero_vignette_size`	`0.3-1.0`	Vignette area
`icon_style`	`COLORED`, `ACCENT`, `FLAT`	Cocoon icon rendering
`surface_material`	`SOLID`, `GLASS`	Panel material
`glass_blur`	`0.0-10.0`	Glass blur
`glass_refraction`	`0.0-1.0`	Refraction strength
`glass_highlight`	boolean	Bright glass rim
`glass_rim_strength`	`0.0-1.0`	Rim intensity
`glass_on_tiles`	boolean	Extend Glass to tiles
`glass_tint`	`0.0-1.0`	Surface tint
`cursor_style`	`ANIMATED`, `OUTLINED`, `ALTERNATIVE_ANIMATED`, `ALTERNATIVE`	Outlined or corner cursor, animated or static
`highlight_thickness`	`0.5-1.0`	Selection border thickness
`dock_icon_shape`	`CIRCLE`, `SQUIRCLE`, `ROUNDED_SQUARE`, `SQUARE`	Dock app shape
`hide_dock_background`	boolean	Hide the dock panel
`dock_on_top`	boolean	Place the dock at the top
`corner_hints`	boolean	Always show button hints

Music and Volume

Field	Values / format
`music_mode`	`TIME`, `PLAYLIST` or `DISABLED`
`music_time_schedule`	`hour:minute\|relative-file
`music_playlist`	Relative files separated with `
`music_playback_mode`	`IN ORDER` or `SHUFFLE`
`sfx_volume`, `music_volume`, `jingle_volume`	`0.0-1.0`

Sound Files

Put sound files in sounds/ and use these base names:

The sound names are listed below:

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
retroachievements

WAV and MP3 files are supported. OGG and M4A also work, as does FLAC.

Icon Overlays

Use icon_overlays/{platform}/mask.png and/or overlay.png.

mask.png defines the visible game-art shape.
overlay.png is drawn above the game art.
The platform folder uses Cocoon’s platform ID, such as gba or snes.

See Icon Overlays for authoring advice.

Smart-Folder Assets

Use smart_folders/{type}/icon for the icon. The hero and logo names add the other images. Common keys include favorites and recent. Other keys are most_played, unplayed, newly_added, android_games and emulators.

Platform folders go under smart_folders/by_platform/{platform}/. Missing components fall back independently, so a pack can provide only icons or only heroes.

Asset References

Silk themes can depend on shared asset packs:

"asset_refs": [
  {
    "id": "pack-id",
    "name": "Pack Name",
    "category": "icon_overlays",
    "version": "1.0"
  }
]

Supported categories include icon_overlays and smart_folders. The sounds and music categories are also valid. Cocoon downloads missing linked packs when a theme comes from Silk.

Validation Tips

Keep theme.json valid JSON with no comments or trailing commas.
Test Light and Dark themes, plus OLED.
Check single-screen and dual-screen layouts.
Check text contrast and selection visibility.
Increment version when publishing an update.
Check that every file named in the theme exists.